Merge pull request #233 from togethercomputer/gleb-khaykin/mosh-2087-configure-stainless-shared-models-and-named-enums-for-rl-api

MOSH-2087: Update RL OpenAPI fields to generate better SDKs

Author: khaykingleb

openapi.yaml

@@ -7707,6 +7707,7 @@ components:
           $ref: '#/components/schemas/RL.EncodedText'
     RL.ListMeta:
       type: object
+      description: Pagination metadata for list responses
       properties:
         limit:
           type: integer
@@ -7723,6 +7724,8 @@ components:
           description: Cursor to use as the 'after' parameter for the next page. Empty when has_more is false.
     RL.EncodedText:
       type: object
+      required:
+        - tokens
       properties:
         tokens:
           description: Pre-tokenized text input
@@ -7732,8 +7735,9 @@ components:
             - 456
             - 789
           items:
-            type: string
-            format: int64
+            oneOf:
+              - type: string
+              - type: integer
     RL.DType:
       type: string
       enum:
@@ -7812,8 +7816,9 @@ components:
             - 456
             - 789
           items:
-            type: string
-            format: int64
+            oneOf:
+              - type: string
+              - type: integer
         dtype:
           description: Data type of the integer array
           $ref: '#/components/schemas/RL.DType'
@@ -7832,8 +7837,9 @@ components:
             - 0
             - 1
           items:
-            type: string
-            format: int64
+            oneOf:
+              - type: string
+              - type: integer
         dtype:
           description: Data type of the integer array (must be D_TYPE_INT64)
           $ref: '#/components/schemas/RL.DType'
@@ -7914,6 +7920,10 @@ components:
           $ref: '#/components/schemas/RL.LossInputs'
     RL.OptimStepOperation:
       type: object
+      description: Async optimizer step operation
+      required:
+        - id
+        - status
       properties:
         id:
           type: string
@@ -7924,10 +7934,16 @@ components:
           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.SampleOperation:
       type: object
+      description: Async sample operation
+      required:
+        - id
+        - status
       properties:
         id:
           type: string
@@ -7939,10 +7955,15 @@ components:
           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.OptimStepResult:
       type: object
+      description: Result of an optimizer step operation
+      required:
+        - step
       properties:
         step:
           description: Step number
@@ -7951,6 +7972,9 @@ components:
           example: 100
     RL.SampleResult:
       type: object
+      description: Result of a sample operation
+      required:
+        - rollouts
       properties:
         rollouts:
           type: array
@@ -7960,6 +7984,9 @@ components:
           description: Completions grouped by prompt
     RL.SampleRollout:
       type: object
+      description: Completions generated for a single prompt
+      required:
+        - sequences
       properties:
         sequences:
           type: array
@@ -7969,6 +7996,9 @@ components:
           description: Completions generated for one prompt
     RL.SampleSequence:
       type: object
+      description: A single generated completion sequence with tokens and logprobs
+      required:
+        - tokens
       properties:
         tokens:
           type: array
@@ -7996,6 +8026,10 @@ components:
           description: Reason for stopping generation
     RL.ForwardBackwardOperation:
       type: object
+      description: Async forward-backward pass operation
+      required:
+        - id
+        - status
       properties:
         id:
           type: string
@@ -8007,10 +8041,15 @@ components:
           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.ForwardBackwardResult:
       type: object
+      description: Result of a forward-backward pass operation
+      required:
+        - loss
       properties:
         loss:
           type: number
@@ -8028,6 +8067,7 @@ components:
             format: double
     RL.TrainingOperationError:
       type: object
+      description: Error details for a failed training operation
       properties:
         code:
           description: Application error code
@@ -8085,6 +8125,17 @@ components:
         - TRAINING_SESSION_STATUS_EXPIRED
     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
       properties:
         id:
           type: string
@@ -8134,6 +8185,7 @@ components:
           $ref: '#/components/schemas/RL.LoraConfig'
     RL.TrainingSessionsListResponse:
       type: object
+      description: Paginated list of training sessions
       properties:
         data:
           type: array
@@ -8196,6 +8248,10 @@ components:
           default: "0.1"
     RL.InferenceCheckpointOperation:
       type: object
+      description: Async inference checkpoint operation
+      required:
+        - id
+        - status
       properties:
         id:
           type: string
@@ -8207,10 +8263,15 @@ components:
           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.InferenceCheckpointResult:
       type: object
+      description: Result of an inference checkpoint operation
+      required:
+        - model_name
       properties:
         model_name:
           type: string
@@ -8219,6 +8280,10 @@ components:
     RL.InferenceCheckpoint:
       type: object
       description: Saved inference checkpoint
+      required:
+        - id
+        - step
+        - created_at
       properties:
         id:
           type: string
@@ -8240,6 +8305,9 @@ components:
     RL.InferenceCheckpointRegistration:
       type: object
       description: Model registration details for an inference checkpoint
+      required:
+        - model_name
+        - registered_at
       properties:
         model_name:
           type: string
@@ -8253,6 +8321,10 @@ components:
     RL.TrainingCheckpoint:
       type: object
       description: Saved training checkpoint
+      required:
+        - id
+        - step
+        - created_at
       properties:
         id:
           type: string
@@ -8270,13 +8342,20 @@ components:
           description: Timestamp when the checkpoint was created
     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.TrainingCheckpointOperation:
       type: object
+      description: Async save training checkpoint operation
+      required:
+        - id
+        - status
       properties:
         id:
           type: string
@@ -8288,8 +8367,10 @@ components:
           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.CheckpointVariant:
       type: string
       enum:
@@ -8301,6 +8382,10 @@ components:
     RL.CheckpointFile:
       type: object
       description: A downloadable file within a checkpoint
+      required:
+        - filename
+        - url
+        - size
       properties:
         filename:
           type: string
@@ -8317,6 +8402,9 @@ components:
           description: File size in bytes
     RL.CheckpointDownloadResponse:
       type: object
+      description: Presigned download URLs for a checkpoint's files
+      required:
+        - data
       properties:
         data:
           type: array