a

api_update_plan.md

@@ -244,9 +244,9 @@ Before finalizing documentation, verify:
 [x] 23. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/datatypes.py` - Core API datatypes and enums
 [x] 24. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/content_types.py` - Content type definitions for multimedia
 [x] 25. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/job_types.py` - Job status and management types
-[ ] 26. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/training_types.py` - Training metrics and checkpoint types
+[x] 26. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/training_types.py` - Training metrics and checkpoint types
-[ ] 27. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/responses.py` - Generic response types (well documented)
+[x] 27. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/responses.py` - Generic response types (well documented)
-[ ] 28. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/type_system.py` - Parameter type system definitions
+[x] 28. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/type_system.py` - Parameter type system definitions
 
 **NOTE:** `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/errors.py` contains only Python exception classes (no @json_schema_type), so it's not included in the documentation update scope.
 

docs/_static/llama-stack-spec.html

@@ -10616,14 +10616,16 @@
                     "type": {
                         "type": "string",
                         "const": "agent_turn_input",
-                        "default": "agent_turn_input"
+                        "default": "agent_turn_input",
+                        "description": "Discriminator type. Always \"agent_turn_input\""
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "type"
                 ],
-                "title": "AgentTurnInputType"
+                "title": "AgentTurnInputType",
+                "description": "Parameter type for agent turn input."
             },
             "ArrayType": {
                 "type": "object",
@@ -10631,14 +10633,16 @@
                     "type": {
                         "type": "string",
                         "const": "array",
-                        "default": "array"
+                        "default": "array",
+                        "description": "Discriminator type. Always \"array\""
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "type"
                 ],
-                "title": "ArrayType"
+                "title": "ArrayType",
+                "description": "Parameter type for array values."
             },
             "BooleanType": {
                 "type": "object",
@@ -10646,14 +10650,16 @@
                     "type": {
                         "type": "string",
                         "const": "boolean",
-                        "default": "boolean"
+                        "default": "boolean",
+                        "description": "Discriminator type. Always \"boolean\""
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "type"
                 ],
-                "title": "BooleanType"
+                "title": "BooleanType",
+                "description": "Parameter type for boolean values."
             },
             "ChatCompletionInputType": {
                 "type": "object",
@@ -10661,14 +10667,16 @@
                     "type": {
                         "type": "string",
                         "const": "chat_completion_input",
-                        "default": "chat_completion_input"
+                        "default": "chat_completion_input",
+                        "description": "Discriminator type. Always \"chat_completion_input\""
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "type"
                 ],
-                "title": "ChatCompletionInputType"
+                "title": "ChatCompletionInputType",
+                "description": "Parameter type for chat completion input."
             },
             "CompletionInputType": {
                 "type": "object",
@@ -10676,14 +10684,16 @@
                     "type": {
                         "type": "string",
                         "const": "completion_input",
-                        "default": "completion_input"
+                        "default": "completion_input",
+                        "description": "Discriminator type. Always \"completion_input\""
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "type"
                 ],
-                "title": "CompletionInputType"
+                "title": "CompletionInputType",
+                "description": "Parameter type for completion input."
             },
             "JsonType": {
                 "type": "object",
@@ -10691,14 +10701,16 @@
                     "type": {
                         "type": "string",
                         "const": "json",
-                        "default": "json"
+                        "default": "json",
+                        "description": "Discriminator type. Always \"json\""
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "type"
                 ],
-                "title": "JsonType"
+                "title": "JsonType",
+                "description": "Parameter type for JSON values."
             },
             "NumberType": {
                 "type": "object",
@@ -10706,14 +10718,16 @@
                     "type": {
                         "type": "string",
                         "const": "number",
-                        "default": "number"
+                        "default": "number",
+                        "description": "Discriminator type. Always \"number\""
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "type"
                 ],
-                "title": "NumberType"
+                "title": "NumberType",
+                "description": "Parameter type for numeric values."
             },
             "ObjectType": {
                 "type": "object",
@@ -10721,14 +10735,16 @@
                     "type": {
                         "type": "string",
                         "const": "object",
-                        "default": "object"
+                        "default": "object",
+                        "description": "Discriminator type. Always \"object\""
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "type"
                 ],
-                "title": "ObjectType"
+                "title": "ObjectType",
+                "description": "Parameter type for object values."
             },
             "ParamType": {
                 "oneOf": [
@@ -10859,14 +10875,16 @@
                     "type": {
                         "type": "string",
                         "const": "string",
-                        "default": "string"
+                        "default": "string",
+                        "description": "Discriminator type. Always \"string\""
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "type"
                 ],
-                "title": "StringType"
+                "title": "StringType",
+                "description": "Parameter type for string values."
             },
             "UnionType": {
                 "type": "object",
@@ -10874,14 +10892,16 @@
                     "type": {
                         "type": "string",
                         "const": "union",
-                        "default": "union"
+                        "default": "union",
+                        "description": "Discriminator type. Always \"union\""
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "type"
                 ],
-                "title": "UnionType"
+                "title": "UnionType",
+                "description": "Parameter type for union values."
             },
             "Shield": {
                 "type": "object",
@@ -11310,7 +11330,7 @@
                 "description": "A trace representing the complete execution path of a request across multiple operations."
             },
             "Checkpoint": {
-                "description": "Checkpoint created during training runs",
+                "description": "Checkpoint created during training runs.",
                 "title": "Checkpoint"
             },
             "PostTrainingJobArtifactsResponse": {
@@ -11999,7 +12019,8 @@
                     "asc",
                     "desc"
                 ],
-                "title": "Order"
+                "title": "Order",
+                "description": "Sort order for paginated responses."
             },
             "ListOpenAIChatCompletionResponse": {
                 "type": "object",

docs/_static/llama-stack-spec.yaml

@@ -7692,10 +7692,13 @@ components:
           type: string
           const: agent_turn_input
           default: agent_turn_input
+          description: >-
+            Discriminator type. Always "agent_turn_input"
       additionalProperties: false
       required:
         - type
       title: AgentTurnInputType
+      description: Parameter type for agent turn input.
     ArrayType:
       type: object
       properties:
@@ -7703,10 +7706,12 @@ components:
           type: string
           const: array
           default: array
+          description: Discriminator type. Always "array"
       additionalProperties: false
       required:
         - type
       title: ArrayType
+      description: Parameter type for array values.
     BooleanType:
       type: object
       properties:
@@ -7714,10 +7719,12 @@ components:
           type: string
           const: boolean
           default: boolean
+          description: Discriminator type. Always "boolean"
       additionalProperties: false
       required:
         - type
       title: BooleanType
+      description: Parameter type for boolean values.
     ChatCompletionInputType:
       type: object
       properties:
@@ -7725,10 +7732,14 @@ components:
           type: string
           const: chat_completion_input
           default: chat_completion_input
+          description: >-
+            Discriminator type. Always "chat_completion_input"
       additionalProperties: false
       required:
         - type
       title: ChatCompletionInputType
+      description: >-
+        Parameter type for chat completion input.
     CompletionInputType:
       type: object
       properties:
@@ -7736,10 +7747,13 @@ components:
           type: string
           const: completion_input
           default: completion_input
+          description: >-
+            Discriminator type. Always "completion_input"
       additionalProperties: false
       required:
         - type
       title: CompletionInputType
+      description: Parameter type for completion input.
     JsonType:
       type: object
       properties:
@@ -7747,10 +7761,12 @@ components:
           type: string
           const: json
           default: json
+          description: Discriminator type. Always "json"
       additionalProperties: false
       required:
         - type
       title: JsonType
+      description: Parameter type for JSON values.
     NumberType:
       type: object
       properties:
@@ -7758,10 +7774,12 @@ components:
           type: string
           const: number
           default: number
+          description: Discriminator type. Always "number"
       additionalProperties: false
       required:
         - type
       title: NumberType
+      description: Parameter type for numeric values.
     ObjectType:
       type: object
       properties:
@@ -7769,10 +7787,12 @@ components:
           type: string
           const: object
           default: object
+          description: Discriminator type. Always "object"
       additionalProperties: false
       required:
         - type
       title: ObjectType
+      description: Parameter type for object values.
     ParamType:
       oneOf:
         - $ref: '#/components/schemas/StringType'
@@ -7855,10 +7875,12 @@ components:
           type: string
           const: string
           default: string
+          description: Discriminator type. Always "string"
       additionalProperties: false
       required:
         - type
       title: StringType
+      description: Parameter type for string values.
     UnionType:
       type: object
       properties:
@@ -7866,10 +7888,12 @@ components:
           type: string
           const: union
           default: union
+          description: Discriminator type. Always "union"
       additionalProperties: false
       required:
         - type
       title: UnionType
+      description: Parameter type for union values.
     Shield:
       type: object
       properties:
@@ -8183,7 +8207,7 @@ components:
         A trace representing the complete execution path of a request across multiple
         operations.
     Checkpoint:
-      description: Checkpoint created during training runs
+      description: Checkpoint created during training runs.
       title: Checkpoint
     PostTrainingJobArtifactsResponse:
       type: object
@@ -8688,6 +8712,7 @@ components:
         - asc
         - desc
       title: Order
+      description: Sort order for paginated responses.
     ListOpenAIChatCompletionResponse:
       type: object
       properties:

llama_stack/apis/common/responses.py

@@ -13,6 +13,11 @@ from llama_stack.schema_utils import json_schema_type
 
 
 class Order(Enum):
+    """Sort order for paginated responses.
+    
+    :cvar asc: Ascending order
+    :cvar desc: Descending order
+    """
     asc = "asc"
     desc = "desc"
 

llama_stack/apis/common/training_types.py

@@ -13,6 +13,13 @@ from llama_stack.schema_utils import json_schema_type
 
 @json_schema_type
 class PostTrainingMetric(BaseModel):
+    """Training metrics captured during post-training jobs.
+
+    :param epoch: Training epoch number
+    :param train_loss: Loss value on the training dataset
+    :param validation_loss: Loss value on the validation dataset
+    :param perplexity: Perplexity metric indicating model confidence
+    """
     epoch: int
     train_loss: float
     validation_loss: float
@@ -21,6 +28,15 @@ class PostTrainingMetric(BaseModel):
 
 @json_schema_type(schema={"description": "Checkpoint created during training runs"})
 class Checkpoint(BaseModel):
+    """Checkpoint created during training runs.
+
+    :param identifier: Unique identifier for the checkpoint
+    :param created_at: Timestamp when the checkpoint was created
+    :param epoch: Training epoch when the checkpoint was saved
+    :param post_training_job_id: Identifier of the training job that created this checkpoint
+    :param path: File system path where the checkpoint is stored
+    :param training_metrics: (Optional) Training metrics associated with this checkpoint
+    """
     identifier: str
     created_at: datetime
     epoch: int

llama_stack/apis/common/type_system.py

@@ -13,59 +13,103 @@ from llama_stack.schema_utils import json_schema_type, register_schema
 
 @json_schema_type
 class StringType(BaseModel):
+    """Parameter type for string values.
+
+    :param type: Discriminator type. Always "string"
+    """
     type: Literal["string"] = "string"
 
 
 @json_schema_type
 class NumberType(BaseModel):
+    """Parameter type for numeric values.
+
+    :param type: Discriminator type. Always "number"
+    """
     type: Literal["number"] = "number"
 
 
 @json_schema_type
 class BooleanType(BaseModel):
+    """Parameter type for boolean values.
+
+    :param type: Discriminator type. Always "boolean"
+    """
     type: Literal["boolean"] = "boolean"
 
 
 @json_schema_type
 class ArrayType(BaseModel):
+    """Parameter type for array values.
+
+    :param type: Discriminator type. Always "array"
+    """
     type: Literal["array"] = "array"
 
 
 @json_schema_type
 class ObjectType(BaseModel):
+    """Parameter type for object values.
+
+    :param type: Discriminator type. Always "object"
+    """
     type: Literal["object"] = "object"
 
 
 @json_schema_type
 class JsonType(BaseModel):
+    """Parameter type for JSON values.
+
+    :param type: Discriminator type. Always "json"
+    """
     type: Literal["json"] = "json"
 
 
 @json_schema_type
 class UnionType(BaseModel):
+    """Parameter type for union values.
+
+    :param type: Discriminator type. Always "union"
+    """
     type: Literal["union"] = "union"
 
 
 @json_schema_type
 class ChatCompletionInputType(BaseModel):
+    """Parameter type for chat completion input.
+
+    :param type: Discriminator type. Always "chat_completion_input"
+    """
     # expects List[Message] for messages
     type: Literal["chat_completion_input"] = "chat_completion_input"
 
 
 @json_schema_type
 class CompletionInputType(BaseModel):
+    """Parameter type for completion input.
+
+    :param type: Discriminator type. Always "completion_input"
+    """
     # expects InterleavedTextMedia for content
     type: Literal["completion_input"] = "completion_input"
 
 
 @json_schema_type
 class AgentTurnInputType(BaseModel):
+    """Parameter type for agent turn input.
+
+    :param type: Discriminator type. Always "agent_turn_input"
+    """
     # expects List[Message] for messages (may also include attachments?)
     type: Literal["agent_turn_input"] = "agent_turn_input"
 
 
 @json_schema_type
 class DialogType(BaseModel):
+    """Parameter type for dialog data with semantic output labels.
+
+    :param type: Discriminator type. Always "dialog"
+    """
     # expects List[Message] for messages
     # this type semantically contains the output label whereas ChatCompletionInputType does not
     type: Literal["dialog"] = "dialog"