openapi: 3.0.3
info:
  title: remediation.proto Audio RL API
  version: version not set
servers:
- url: https://api.together.xyz/v1
security:
- bearerAuth: []
tags:
- name: RL
paths:
  /rl/training-sessions:
    get:
      summary: List training sessions
      description: Lists all training sessions.
      operationId: listTrainingSessions
      tags:
      - RL
      responses:
        '200':
          description: List of training sessions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.TrainingSessionsListResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: status
        in: query
        required: false
        schema:
          description: Status of the training sessions to list
          $ref: '#/components/schemas/RL.TrainingSessionStatus'
      - name: limit
        in: query
        required: false
        schema:
          description: Maximum number of sessions to return (1-100)
          type: integer
          format: int32
          default: '20'
      - name: after
        in: query
        required: false
        schema:
          description: Cursor for pagination (ID of the last session from the previous page)
          type: string
    post:
      summary: Create training session
      description: Creates a training session and returns its details.
      operationId: startTrainingSession
      tags:
      - RL
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RL.StartTrainingSessionRequest'
        required: true
      responses:
        '200':
          description: Training session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.TrainingSession'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
  /rl/training-sessions/{session_id}:
    get:
      summary: Get training session
      description: Gets a training session by its ID and returns its details.
      operationId: getTrainingSession
      tags:
      - RL
      responses:
        '200':
          description: Training session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.TrainingSession'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: ID of the training session
          type: string
  /rl/training-sessions/{session_id}/stop:
    post:
      summary: Stop training session
      description: Stops a training session.
      operationId: stopTrainingSession
      tags:
      - RL
      responses:
        '200':
          description: Training session details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.TrainingSession'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: ID of the training session
          type: string
  /rl/training-sessions/{session_id}/operations/forward-backward/{operation_id}:
    get:
      summary: Get forward-backward operation
      description: Retrieves the current status and result of a forward-backward operation.
      operationId: getForwardBackwardOperation
      tags:
      - RL
      responses:
        '200':
          description: Forward-backward operation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.ForwardBackwardOperation'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: Training session ID
          type: string
      - name: operation_id
        in: path
        required: true
        schema:
          description: Operation ID
          type: string
  /rl/training-sessions/{session_id}/operations/optim-step/{operation_id}:
    get:
      summary: Get optim-step operation
      description: Retrieves the current status and result of an optim-step operation.
      operationId: getOptimStepOperation
      tags:
      - RL
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.OptimStepOperation'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: Training session ID
          type: string
      - name: operation_id
        in: path
        required: true
        schema:
          description: Operation ID
          type: string
  /rl/training-sessions/{session_id}/operations/sample/{operation_id}:
    get:
      summary: Get sample operation
      description: Retrieves the current status and result of a sample operation.
      operationId: GetSample
      tags:
      - RL
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.SampleOperation'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: Training session ID
          type: string
      - name: operation_id
        in: path
        required: true
        schema:
          description: Operation ID
          type: string
  /rl/training-sessions/{session_id}/operations/forward-backward:
    post:
      summary: Forward-backward pass
      description: Submits a forward-backward pass operation that will asynchronously compute gradients via backpropagation.
      operationId: forwardBackward
      tags:
      - RL
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RL.ForwardBackwardBody'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.ForwardBackwardOperation'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: Training session ID
          type: string
  /rl/training-sessions/{session_id}/operations/optim-step:
    post:
      summary: Optimizer step
      description: Submits an optimizer step operation that will asynchronously apply accumulated gradients to update model parameters.
      operationId: OptimStep
      tags:
      - RL
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RL.OptimStepBody'
        required: true
      responses:
        '200':
          description: Optimizer step operation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.OptimStepOperation'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: Training session ID
          type: string
  /rl/training-sessions/{session_id}/operations/sample:
    post:
      summary: Sample
      description: Submits a sample operation that will asynchronously generate text completions with logprobs.
      operationId: Sample
      tags:
      - RL
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RL.SampleBody'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.SampleOperation'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: Training session ID
          type: string
  /rl/training-sessions/{session_id}/operations/inference-checkpoint:
    post:
      summary: Create inference checkpoint
      description: Submits an operation that will asynchronously save the current LoRA adapter as an inference checkpoint and upload it to object storage.
      operationId: createInferenceCheckpoint
      tags:
      - RL
      responses:
        '200':
          description: Inference checkpoint operation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.InferenceCheckpointOperation'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: Training session ID
          type: string
  /rl/training-sessions/{session_id}/operations/inference-checkpoint/{operation_id}:
    get:
      summary: Get inference checkpoint operation
      description: Retrieves the current status and result of an inference checkpoint operation.
      operationId: getInferenceCheckpointOperation
      tags:
      - RL
      responses:
        '200':
          description: Inference checkpoint operation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.InferenceCheckpointOperation'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: Training session ID
          type: string
      - name: operation_id
        in: path
        required: true
        schema:
          description: Operation ID
          type: string
  /rl/training-sessions/{session_id}/operations/training-checkpoint:
    post:
      summary: Save training checkpoint
      description: Submits an operation that will asynchronously save the full training state (adapter + optimizer + step).
      operationId: createTrainingCheckpoint
      tags:
      - RL
      responses:
        '200':
          description: Save training checkpoint operation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.TrainingCheckpointOperation'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: Training session ID
          type: string
  /rl/training-sessions/{session_id}/operations/training-checkpoint/{operation_id}:
    get:
      summary: Get save training checkpoint operation
      description: Retrieves the current status and result of a save training checkpoint operation.
      operationId: getTrainingCheckpointOperation
      tags:
      - RL
      responses:
        '200':
          description: Save training checkpoint operation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.TrainingCheckpointOperation'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: session_id
        in: path
        required: true
        schema:
          description: Training session ID
          type: string
      - name: operation_id
        in: path
        required: true
        schema:
          description: Operation ID
          type: string
  /rl/checkpoints/{id}/download:
    get:
      summary: Download checkpoint
      description: Returns presigned URLs for downloading a checkpoint's model files. Only inference checkpoints support downloading.
      operationId: downloadCheckpoint
      tags:
      - RL
      responses:
        '200':
          description: Checkpoint download URLs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RL.CheckpointDownloadResponse'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorData'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          description: ID of the checkpoint
          type: string
      - name: variant
        in: query
        required: true
        schema:
          description: 'Checkpoint variant to download: merged (full model) or adapter (LoRA weights only)'
          $ref: '#/components/schemas/RL.CheckpointVariant'
components:
  schemas:
    RL.TrainingOperationError:
      type: object
      description: Error details for a failed training operation
      properties:
        code:
          description: Application error code
          $ref: '#/components/schemas/RL.TrainingOperationErrorCode'
          example: TRAINING_OPERATION_ERROR_CODE_TIMEOUT
        message:
          description: Human-readable error message
          type: string
          example: Operation timed out
    RL.LossConfig:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/RL.LossType'
          description: Type of loss function to use
          example: LOSS_TYPE_GRPO
        cross_entropy_params:
          $ref: '#/components/schemas/RL.CrossEntropyLossParams'
        grpo_params:
          $ref: '#/components/schemas/RL.GRPOLossParams'
    RL.LossMask:
      type: object
      required:
      - data
      description: Per-token loss mask (1=compute loss, 0=ignore)
      properties:
        data:
          description: Integer array of per-token mask values (0s and 1s)
          type: array
          example:
          - 0
          - 0
          - 1
          items:
            oneOf:
            - type: string
            - type: integer
        dtype:
          description: Data type of the integer array (must be D_TYPE_INT64)
          $ref: '#/components/schemas/RL.DType'
          example: D_TYPE_INT64
    RL.TrainingCheckpoint:
      type: object
      description: Saved training checkpoint
      required:
      - id
      - step
      - created_at
      properties:
        id:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Unique identifier for the checkpoint
        step:
          oneOf:
          - type: string
          - type: integer
          example: '42'
          description: Training step at time of save
        created_at:
          type: string
          format: date-time
          example: '2026-01-02T00:00:00Z'
          description: Timestamp when the checkpoint was created
    RL.OptimStepOperation:
      type: object
      description: Async optimizer step operation
      required:
      - id
      - status
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: Operation ID
        status:
          $ref: '#/components/schemas/RL.TrainingOperationStatus'
          description: Operation status
        output:
          $ref: '#/components/schemas/RL.OptimStepResult'
          description: Result on success
        error:
          $ref: '#/components/schemas/RL.TrainingOperationError'
          description: Error details on failure
    RL.GRPOLossAggregationType:
      type: string
      enum:
      - GRPO_LOSS_AGGREGATION_TYPE_UNSPECIFIED
      - GRPO_LOSS_AGGREGATION_TYPE_FIXED_HORIZON
      - GRPO_LOSS_AGGREGATION_TYPE_TOKEN_MEAN
      - GRPO_LOSS_AGGREGATION_TYPE_SEQUENCE_MEAN
      default: GRPO_LOSS_AGGREGATION_TYPE_UNSPECIFIED
    RL.DType:
      type: string
      enum:
      - D_TYPE_UNSPECIFIED
      - D_TYPE_INT64
      - D_TYPE_FLOAT32
      - D_TYPE_BFLOAT16
      default: D_TYPE_UNSPECIFIED
    RL.GRPOLossParams:
      type: object
      properties:
        clip_low:
          type: number
          format: float
          example: 0.2
          default: '0.2'
          description: Lower clip bound for importance ratio
        clip_high:
          type: number
          format: float
          example: 0.28
          default: '0.28'
          description: Upper clip bound for importance ratio
        beta:
          type: number
          format: float
          example: 0.1
          default: '0.0'
          description: KL penalty coefficient
        agg_type:
          $ref: '#/components/schemas/RL.GRPOLossAggregationType'
          example: GRPO_LOSS_AGGREGATION_TYPE_FIXED_HORIZON
          default: GRPO_LOSS_AGGREGATION_TYPE_FIXED_HORIZON
          description: Aggregation type for loss computation
    RL.SessionType:
      description: Type of a training session. TRAINER_AND_GENERATOR provisions both trainer and generator; TRAINER_ONLY provisions only the trainer and rejects generator-dependent operations such as sample.
      default: SESSION_TYPE_UNSPECIFIED
      type: string
      enum:
      - SESSION_TYPE_UNSPECIFIED
      - SESSION_TYPE_TRAINER_AND_GENERATOR
      - SESSION_TYPE_TRAINER_ONLY
    RL.SampleRollout:
      type: object
      description: Completions generated for a single prompt
      required:
      - sequences
      properties:
        sequences:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/RL.SampleSequence'
          description: Completions generated for one prompt
    RL.SampleResult:
      type: object
      description: Result of a sample operation
      required:
      - rollouts
      properties:
        rollouts:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/RL.SampleRollout'
          description: Completions grouped by prompt
    RL.GRPOLossInputs:
      type: object
      required:
      - advantages
      - generator_logprobs
      properties:
        advantages:
          $ref: '#/components/schemas/RL.LossAdvantages'
          description: Per-token advantages for GRPO
        generator_logprobs:
          $ref: '#/components/schemas/RL.LossLogprobs'
          description: Generator log probabilities for GRPO
        reference_logprobs:
          $ref: '#/components/schemas/RL.LossLogprobs'
          description: Reference model log probabilities (required if beta > 0)
    RL.TrainingOperationErrorCode:
      type: string
      enum:
      - TRAINING_OPERATION_ERROR_CODE_UNSPECIFIED
      - TRAINING_OPERATION_ERROR_CODE_RESOURCE_EXHAUSTED
      - TRAINING_OPERATION_ERROR_CODE_TIMEOUT
      - TRAINING_OPERATION_ERROR_CODE_INTERNAL_ERROR
      - TRAINING_OPERATION_ERROR_CODE_SESSION_NOT_ACTIVE
      - TRAINING_OPERATION_ERROR_CODE_INVALID_INPUT
      default: TRAINING_OPERATION_ERROR_CODE_UNSPECIFIED
    RL.TrainingCheckpointOperation:
      type: object
      description: Async save training checkpoint operation
      required:
      - id
      - status
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: Operation ID
        status:
          $ref: '#/components/schemas/RL.TrainingOperationStatus'
          example: TRAINING_OPERATION_STATUS_PENDING
          description: Operation status
        output:
          $ref: '#/components/schemas/RL.TrainingCheckpointResult'
          description: Result on success
        error:
          $ref: '#/components/schemas/RL.TrainingOperationError'
          description: Error details on failure
    RL.CheckpointFile:
      type: object
      description: A downloadable file within a checkpoint
      required:
      - filename
      - url
      - size
      properties:
        filename:
          type: string
          example: model-00001-of-00002.safetensors
          description: Name of the file
        url:
          type: string
          example: https://...
          description: Presigned URL for downloading the file
        size:
          oneOf:
          - type: string
          - type: integer
          example: '123456789'
          description: File size in bytes
    RL.InputChunk:
      type: object
      properties:
        encoded_text:
          $ref: '#/components/schemas/RL.EncodedText'
    RL.SampleOperation:
      type: object
      description: Async sample operation
      required:
      - id
      - status
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: Operation ID
        status:
          $ref: '#/components/schemas/RL.TrainingOperationStatus'
          example: TRAINING_OPERATION_STATUS_PENDING
          description: Operation status
        output:
          $ref: '#/components/schemas/RL.SampleResult'
          description: Result on success
        error:
          $ref: '#/components/schemas/RL.TrainingOperationError'
          description: Error details on failure
    RL.ForwardBackwardBody:
      type: object
      required:
      - samples
      - loss
      properties:
        samples:
          description: Batch of training samples to process
          type: array
          items:
            type: object
            $ref: '#/components/schemas/RL.TrainingSample'
        loss:
          description: Loss function configuration
          $ref: '#/components/schemas/RL.LossConfig'
    RL.AdamWOptimizerParams:
      description: AdamW optimizer parameters
      type: object
      properties:
        beta1:
          description: First moment decay rate
          type: number
          format: float
          example: 0.9
          default: '0.9'
        beta2:
          description: Second moment decay rate
          type: number
          format: float
          example: 0.95
          default: '0.95'
        eps:
          description: Epsilon for numerical stability
          type: number
          format: float
          example: 1.0e-08
          default: 1e-8
        weight_decay:
          description: Weight decay coefficient
          type: number
          format: float
          example: 0.1
          default: '0.1'
    RL.ForwardBackwardResult:
      type: object
      description: Result of a forward-backward pass operation
      required:
      - loss
      properties:
        loss:
          type: number
          format: double
          example: 2.345
          description: Loss value
        metrics:
          type: object
          description: Loss-specific metrics (e.g., KL divergence, clip fraction for GRPO)
          example:
            loss/clip/high_fraction: 0.1
            loss/kl_ref/mean: 0.05
          additionalProperties:
            type: number
            format: double
    RL.ForwardBackwardOperation:
      type: object
      description: Async forward-backward pass operation
      required:
      - id
      - status
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: Operation ID
        status:
          $ref: '#/components/schemas/RL.TrainingOperationStatus'
          example: TRAINING_OPERATION_STATUS_PENDING
          description: Operation status
        output:
          $ref: '#/components/schemas/RL.ForwardBackwardResult'
          description: Result on success
        error:
          $ref: '#/components/schemas/RL.TrainingOperationError'
          description: Error details on failure
    RL.SampleBody:
      type: object
      required:
      - prompts
      properties:
        prompts:
          description: Input prompts as tokenized chunks
          type: array
          items:
            type: object
            $ref: '#/components/schemas/RL.ModelInput'
        sampling_params:
          $ref: '#/components/schemas/RL.SamplingParams'
          description: Optional sampling parameters
        num_samples:
          type: integer
          format: int64
          example: 1
          default: '1'
          description: Number of completions to generate per prompt
    RL.StartTrainingSessionRequest:
      type: object
      required:
      - base_model
      properties:
        base_model:
          description: Base model to use for the training session
          type: string
          example: meta-llama/Meta-Llama-3-8B-Instruct
        resume_from_checkpoint_id:
          description: Checkpoint ID to resume from
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
        type:
          $ref: '#/components/schemas/RL.SessionType'
          default: SESSION_TYPE_TRAINER_AND_GENERATOR
          example: SESSION_TYPE_TRAINER_ONLY
          description: Type of the training session. Defaults to TRAINER_AND_GENERATOR when unspecified. TRAINER_ONLY provisions only the trainer and rejects sample requests.
        lora_config:
          $ref: '#/components/schemas/RL.LoraConfig'
    RL.LossInputs:
      type: object
      properties:
        target_tokens:
          $ref: '#/components/schemas/RL.LossTargetTokens'
          description: Target tokens for loss computation
        loss_mask:
          $ref: '#/components/schemas/RL.LossMask'
          description: Per-token loss mask (1=compute loss, 0=ignore)
        grpo_inputs:
          $ref: '#/components/schemas/RL.GRPOLossInputs'
      required:
      - target_tokens
    RL.EncodedText:
      type: object
      required:
      - tokens
      properties:
        tokens:
          description: Pre-tokenized text input
          type: array
          example:
          - 123
          - 456
          - 789
          items:
            oneOf:
            - type: string
            - type: integer
    RL.LossAdvantages:
      type: object
      required:
      - data
      properties:
        data:
          description: Float array of per-token advantages
          type: array
          example:
          - 0.5
          - 0.5
          items:
            type: number
            format: float
        dtype:
          description: Data type of the float array (D_TYPE_FLOAT32 or D_TYPE_BFLOAT16)
          $ref: '#/components/schemas/RL.DType'
          example: D_TYPE_FLOAT32
    ErrorData:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              nullable: false
            type:
              type: string
              nullable: false
            param:
              type: string
              nullable: true
              default: null
            code:
              type: string
              nullable: true
              default: null
          required:
          - type
          - message
    RL.InferenceCheckpoint:
      type: object
      description: Saved inference checkpoint
      required:
      - id
      - step
      - created_at
      properties:
        id:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Unique identifier for the checkpoint
        step:
          oneOf:
          - type: string
          - type: integer
          example: '42'
          description: Training step at time of save
        created_at:
          type: string
          format: date-time
          example: '2026-01-02T00:00:00Z'
          description: Timestamp when the checkpoint was created
        registration:
          $ref: '#/components/schemas/RL.InferenceCheckpointRegistration'
          description: Model registration details
    RL.OptimStepResult:
      type: object
      description: Result of an optimizer step operation
      required:
      - step
      properties:
        step:
          description: Step number
          oneOf:
          - type: string
          - type: integer
          example: '100'
    RL.TrainingSample:
      type: object
      required:
      - model_input
      - loss_inputs
      properties:
        model_input:
          description: Model input
          $ref: '#/components/schemas/RL.ModelInput'
        loss_inputs:
          description: Loss function inputs
          $ref: '#/components/schemas/RL.LossInputs'
    RL.InferenceCheckpointRegistration:
      type: object
      description: Model registration details for an inference checkpoint
      required:
      - model_name
      - registered_at
      properties:
        model_name:
          type: string
          example: username/Meta-Llama-3-8B-rl-step-42-20260216
          description: Registered model name for downloading the checkpoint
        registered_at:
          type: string
          format: date-time
          example: '2026-01-02T00:00:00Z'
          description: Timestamp when the model was registered
    RL.InferenceCheckpointOperation:
      type: object
      description: Async inference checkpoint operation
      required:
      - id
      - status
      properties:
        id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: Operation ID
        status:
          $ref: '#/components/schemas/RL.TrainingOperationStatus'
          example: TRAINING_OPERATION_STATUS_PENDING
          description: Operation status
        output:
          $ref: '#/components/schemas/RL.InferenceCheckpointResult'
          description: Result on success
        error:
          $ref: '#/components/schemas/RL.TrainingOperationError'
          description: Error details on failure
    RL.SamplingParams:
      type: object
      properties:
        max_tokens:
          type: integer
          format: int32
          example: 100
          default: '100'
          description: Maximum number of tokens to generate per completion
        temperature:
          type: number
          example: 1
          format: float
          default: '1.0'
          description: Sampling temperature
        top_p:
          type: number
          example: 1
          format: float
          default: '1.0'
          description: Nucleus sampling probability threshold
        top_k:
          type: integer
          format: int32
          example: -1
          default: '-1'
          description: Top-k sampling limit
        stop:
          type: array
          example:
          - '

            '
          - END
          items:
            type: string
          description: Generation stops when any of these strings is produced
        seed:
          oneOf:
          - type: string
          - type: integer
          example: '42'
          description: Random seed for reproducibility
    RL.LossType:
      type: string
      enum:
      - LOSS_TYPE_UNSPECIFIED
      - LOSS_TYPE_CROSS_ENTROPY
      - LOSS_TYPE_GRPO
      default: LOSS_TYPE_UNSPECIFIED
    RL.InferenceCheckpointResult:
      type: object
      description: Result of an inference checkpoint operation
      required:
      - model_name
      properties:
        model_name:
          type: string
          example: username/Meta-Llama-3-8B-rl-step-42-20260216
          description: Registered model name for downloading the checkpoint
    RL.CrossEntropyLossParams:
      type: object
      description: Cross-entropy loss parameters (currently empty).
      properties: {}
    RL.TrainingSession:
      type: object
      description: A training session and its current state
      required:
      - id
      - status
      - base_model
      - inference_checkpoints
      - training_checkpoints
      - step
      - created_at
      - updated_at
      - lora_config
      - type
      properties:
        id:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
          description: ID of the training session
        status:
          $ref: '#/components/schemas/RL.TrainingSessionStatus'
          example: TRAINING_SESSION_STATUS_RUNNING
          description: Status of the training session
        base_model:
          type: string
          example: meta-llama/Meta-Llama-3-8B-Instruct
          description: Base model used for the training session
        inference_checkpoints:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/RL.InferenceCheckpoint'
          description: List of saved inference checkpoints for this session
        training_checkpoints:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/RL.TrainingCheckpoint'
          description: List of saved training checkpoints for this session
        resume_from_checkpoint_id:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Checkpoint ID this session was resumed from
        step:
          description: Current training step
          oneOf:
          - type: string
          - type: integer
          example: '100'
          default: '0'
        created_at:
          type: string
          format: date-time
          example: '2026-01-02T00:00:00Z'
          description: Timestamp when the training session was created
        updated_at:
          type: string
          format: date-time
          example: '2026-01-02T00:00:05Z'
          description: Timestamp when the training session was last updated
        lora_config:
          $ref: '#/components/schemas/RL.LoraConfig'
        type:
          $ref: '#/components/schemas/RL.SessionType'
          example: SESSION_TYPE_TRAINER_AND_GENERATOR
          description: Type of the training session. TRAINER_AND_GENERATOR provisions both trainer and generator; TRAINER_ONLY provisions only the trainer and rejects generator-dependent operations such as sample.
    RL.LoraConfig:
      type: object
      description: LoRA adapter configuration
      properties:
        rank:
          type: integer
          format: int64
          example: 8
          default: '8'
          description: Rank of the LoRA adapter
        alpha:
          type: integer
          format: int64
          example: 16
          default: '16'
          description: Alpha of the LoRA adapter
        dropout:
          type: number
          format: float
          example: 0.05
          default: '0.05'
          description: Dropout of the LoRA adapter
    RL.LossTargetTokens:
      type: object
      required:
      - data
      properties:
        data:
          description: Integer array of target tokens
          type: array
          example:
          - 123
          - 456
          - 789
          items:
            oneOf:
            - type: string
            - type: integer
        dtype:
          description: Data type of the integer array
          $ref: '#/components/schemas/RL.DType'
          example: D_TYPE_INT64
    RL.ModelInput:
      type: object
      required:
      - chunks
      properties:
        chunks:
          description: Input chunks for the model
          type: array
          items:
            type: object
            $ref: '#/components/schemas/RL.InputChunk'
    RL.SampleSequence:
      type: object
      description: A single generated completion sequence with tokens and logprobs
      required:
      - tokens
      properties:
        tokens:
          type: array
          example:
          - '123'
          - '456'
          - '789'
          items:
            oneOf:
            - type: string
            - type: integer
          description: Generated token IDs
        logprobs:
          type: array
          example:
          - -0.5
          - -1.2
          - -0.3
          items:
            type: number
            format: double
          description: Log probabilities for each generated token
        stop_reason:
          type: string
          example: length
          description: Reason for stopping generation
    RL.TrainingCheckpointResult:
      type: object
      description: Result of a save training checkpoint operation
      required:
      - checkpoint_id
      properties:
        checkpoint_id:
          type: string
          example: 550e8400-e29b-41d4-a716-446655440000
          description: ID of the saved training checkpoint (use for resume via Start)
    RL.TrainingSessionStatus:
      description: Status of the training session
      default: TRAINING_SESSION_STATUS_UNSPECIFIED
      type: string
      enum:
      - TRAINING_SESSION_STATUS_UNSPECIFIED
      - TRAINING_SESSION_STATUS_CREATING
      - TRAINING_SESSION_STATUS_RUNNING
      - TRAINING_SESSION_STATUS_STOPPED
      - TRAINING_SESSION_STATUS_STOPPING
      - TRAINING_SESSION_STATUS_ERROR
      - TRAINING_SESSION_STATUS_EXPIRED
    RL.LossLogprobs:
      type: object
      required:
      - data
      properties:
        data:
          description: Float array of per-token log probabilities
          type: array
          example:
          - -1.2
          - -0.8
          items:
            type: number
            format: float
        dtype:
          description: Data type of the float array (D_TYPE_FLOAT32 or D_TYPE_BFLOAT16)
          $ref: '#/components/schemas/RL.DType'
          example: D_TYPE_FLOAT32
    RL.CheckpointDownloadResponse:
      type: object
      description: Presigned download URLs for a checkpoint's files
      required:
      - data
      properties:
        data:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/RL.CheckpointFile'
          description: List of files with presigned download URLs
    RL.TrainingOperationStatus:
      type: string
      enum:
      - TRAINING_OPERATION_STATUS_UNSPECIFIED
      - TRAINING_OPERATION_STATUS_PENDING
      - TRAINING_OPERATION_STATUS_RUNNING
      - TRAINING_OPERATION_STATUS_COMPLETED
      - TRAINING_OPERATION_STATUS_FAILED
      default: TRAINING_OPERATION_STATUS_UNSPECIFIED
    RL.TrainingSessionsListResponse:
      type: object
      description: Paginated list of training sessions
      properties:
        data:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/RL.TrainingSession'
          description: List of training sessions
        meta:
          $ref: '#/components/schemas/RL.ListMeta'
          description: Pagination metadata
    RL.CheckpointVariant:
      type: string
      enum:
      - CHECKPOINT_VARIANT_UNSPECIFIED
      - CHECKPOINT_VARIANT_MERGED
      - CHECKPOINT_VARIANT_ADAPTER
      default: CHECKPOINT_VARIANT_UNSPECIFIED
      description: 'Checkpoint variant: merged (full model) or adapter (LoRA weights only)'
    RL.OptimStepBody:
      type: object
      properties:
        learning_rate:
          description: Learning rate for this step.
          type: number
          format: float
          example: 0.0001
          default: '0.0001'
        adamw_params:
          $ref: '#/components/schemas/RL.AdamWOptimizerParams'
    RL.ListMeta:
      type: object
      description: Pagination metadata for list responses
      properties:
        limit:
          type: integer
          format: int32
          example: 20
          description: Maximum number of items returned per page
        has_more:
          type: boolean
          example: true
          description: Whether more items exist beyond this page
        next_cursor:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Cursor to use as the 'after' parameter for the next page. Empty when has_more is false.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      x-bearer-format: bearer
      x-default: default