a

api_update_plan.md

@@ -241,6 +241,14 @@ Before finalizing documentation, verify:
 [x] 20. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/providers/providers.py` - Provider management
 [x] 21. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/inspect/inspect.py` - System inspection
 [x] 22. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/telemetry/telemetry.py` - Telemetry and monitoring
+[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
+[ ] 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
+
+**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.
 
 **Step 1: Existing Documentation Assessment**
 - **Priority**: Review all @json_schema_type classes and @webmethod functions for docstring completeness

docs/_static/llama-stack-spec.html

@@ -5724,14 +5724,16 @@
                 "type": "object",
                 "properties": {
                     "uri": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "The URL string pointing to the resource"
                     }
                 },
                 "additionalProperties": false,
                 "required": [
                     "uri"
                 ],
-                "title": "URL"
+                "title": "URL",
+                "description": "A URL reference to external content."
             },
             "UserMessage": {
                 "type": "object",
@@ -6189,11 +6191,13 @@
                     "type": {
                         "type": "string",
                         "const": "image",
-                        "default": "image"
+                        "default": "image",
+                        "description": "Discriminator type of the delta. Always \"image\""
                     },
                     "image": {
                         "type": "string",
-                        "contentEncoding": "base64"
+                        "contentEncoding": "base64",
+                        "description": "The incremental image data as bytes"
                     }
                 },
                 "additionalProperties": false,
@@ -6201,7 +6205,8 @@
                     "type",
                     "image"
                 ],
-                "title": "ImageDelta"
+                "title": "ImageDelta",
+                "description": "An image content delta for streaming responses."
             },
             "TextDelta": {
                 "type": "object",
@@ -6209,10 +6214,12 @@
                     "type": {
                         "type": "string",
                         "const": "text",
-                        "default": "text"
+                        "default": "text",
+                        "description": "Discriminator type of the delta. Always \"text\""
                     },
                     "text": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "The incremental text content"
                     }
                 },
                 "additionalProperties": false,
@@ -6220,7 +6227,8 @@
                     "type",
                     "text"
                 ],
-                "title": "TextDelta"
+                "title": "TextDelta",
+                "description": "A text content delta for streaming responses."
             },
             "ToolCallDelta": {
                 "type": "object",
@@ -6228,7 +6236,8 @@
                     "type": {
                         "type": "string",
                         "const": "tool_call",
-                        "default": "tool_call"
+                        "default": "tool_call",
+                        "description": "Discriminator type of the delta. Always \"tool_call\""
                     },
                     "tool_call": {
                         "oneOf": [
@@ -6238,7 +6247,8 @@
                             {
                                 "$ref": "#/components/schemas/ToolCall"
                             }
-                        ]
+                        ],
+                        "description": "Either an in-progress tool call string or the final parsed tool call"
                     },
                     "parse_status": {
                         "type": "string",
@@ -6248,7 +6258,7 @@
                             "failed",
                             "succeeded"
                         ],
-                        "title": "ToolCallParseStatus"
+                        "description": "Current parsing status of the tool call"
                     }
                 },
                 "additionalProperties": false,
@@ -6257,7 +6267,8 @@
                     "tool_call",
                     "parse_status"
                 ],
-                "title": "ToolCallDelta"
+                "title": "ToolCallDelta",
+                "description": "A tool call content delta for streaming responses."
             },
             "CompletionRequest": {
                 "type": "object",
@@ -11943,7 +11954,8 @@
                 "type": "object",
                 "properties": {
                     "job_id": {
-                        "type": "string"
+                        "type": "string",
+                        "description": "Unique identifier for the job"
                     },
                     "status": {
                         "type": "string",
@@ -11954,7 +11966,7 @@
                             "scheduled",
                             "cancelled"
                         ],
-                        "title": "JobStatus"
+                        "description": "Current execution status of the job"
                     }
                 },
                 "additionalProperties": false,
@@ -11962,7 +11974,8 @@
                     "job_id",
                     "status"
                 ],
-                "title": "Job"
+                "title": "Job",
+                "description": "A job execution instance with status tracking."
             },
             "ListBenchmarksResponse": {
                 "type": "object",

docs/_static/llama-stack-spec.yaml

@@ -4068,10 +4068,12 @@ components:
       properties:
         uri:
           type: string
+          description: The URL string pointing to the resource
       additionalProperties: false
       required:
         - uri
       title: URL
+      description: A URL reference to external content.
     UserMessage:
       type: object
       properties:
@@ -4465,14 +4467,19 @@ components:
           type: string
           const: image
           default: image
+          description: >-
+            Discriminator type of the delta. Always "image"
         image:
           type: string
           contentEncoding: base64
+          description: The incremental image data as bytes
       additionalProperties: false
       required:
         - type
         - image
       title: ImageDelta
+      description: >-
+        An image content delta for streaming responses.
     TextDelta:
       type: object
       properties:
@@ -4480,13 +4487,18 @@ components:
           type: string
           const: text
           default: text
+          description: >-
+            Discriminator type of the delta. Always "text"
         text:
           type: string
+          description: The incremental text content
       additionalProperties: false
       required:
         - type
         - text
       title: TextDelta
+      description: >-
+        A text content delta for streaming responses.
     ToolCallDelta:
       type: object
       properties:
@@ -4494,10 +4506,14 @@ components:
           type: string
           const: tool_call
           default: tool_call
+          description: >-
+            Discriminator type of the delta. Always "tool_call"
         tool_call:
           oneOf:
             - type: string
             - $ref: '#/components/schemas/ToolCall'
+          description: >-
+            Either an in-progress tool call string or the final parsed tool call
         parse_status:
           type: string
           enum:
@@ -4505,13 +4521,15 @@ components:
             - in_progress
             - failed
             - succeeded
-          title: ToolCallParseStatus
+          description: Current parsing status of the tool call
       additionalProperties: false
       required:
         - type
         - tool_call
         - parse_status
       title: ToolCallDelta
+      description: >-
+        A tool call content delta for streaming responses.
     CompletionRequest:
       type: object
       properties:
@@ -8636,6 +8654,7 @@ components:
       properties:
         job_id:
           type: string
+          description: Unique identifier for the job
         status:
           type: string
           enum:
@@ -8644,12 +8663,14 @@ components:
             - failed
             - scheduled
             - cancelled
-          title: JobStatus
+          description: Current execution status of the job
       additionalProperties: false
       required:
         - job_id
         - status
       title: Job
+      description: >-
+        A job execution instance with status tracking.
     ListBenchmarksResponse:
       type: object
       properties:

llama_stack/apis/common/content_types.py

@@ -15,6 +15,10 @@ from llama_stack.schema_utils import json_schema_type, register_schema
 
 @json_schema_type
 class URL(BaseModel):
+    """A URL reference to external content.
+
+    :param uri: The URL string pointing to the resource
+    """
     uri: str
 
 
@@ -76,17 +80,34 @@ register_schema(InterleavedContent, name="InterleavedContent")
 
 @json_schema_type
 class TextDelta(BaseModel):
+    """A text content delta for streaming responses.
+
+    :param type: Discriminator type of the delta. Always "text"
+    :param text: The incremental text content
+    """
     type: Literal["text"] = "text"
     text: str
 
 
 @json_schema_type
 class ImageDelta(BaseModel):
+    """An image content delta for streaming responses.
+
+    :param type: Discriminator type of the delta. Always "image"
+    :param image: The incremental image data as bytes
+    """
     type: Literal["image"] = "image"
     image: bytes
 
 
 class ToolCallParseStatus(Enum):
+    """Status of tool call parsing during streaming.
+    
+    :cvar started: Tool call parsing has begun
+    :cvar in_progress: Tool call parsing is ongoing
+    :cvar failed: Tool call parsing failed
+    :cvar succeeded: Tool call parsing completed successfully
+    """
     started = "started"
     in_progress = "in_progress"
     failed = "failed"
@@ -95,6 +116,12 @@ class ToolCallParseStatus(Enum):
 
 @json_schema_type
 class ToolCallDelta(BaseModel):
+    """A tool call content delta for streaming responses.
+
+    :param type: Discriminator type of the delta. Always "tool_call"
+    :param tool_call: Either an in-progress tool call string or the final parsed tool call
+    :param parse_status: Current parsing status of the tool call
+    """
     type: Literal["tool_call"] = "tool_call"
 
     # you either send an in-progress tool call so the client can stream a long

llama_stack/apis/common/job_types.py

@@ -11,6 +11,14 @@ from llama_stack.schema_utils import json_schema_type
 
 
 class JobStatus(Enum):
+    """Status of a job execution.
+    
+    :cvar completed: Job has finished successfully
+    :cvar in_progress: Job is currently running
+    :cvar failed: Job has failed during execution
+    :cvar scheduled: Job is scheduled but not yet started
+    :cvar cancelled: Job was cancelled before completion
+    """
     completed = "completed"
     in_progress = "in_progress"
     failed = "failed"
@@ -20,5 +28,10 @@ class JobStatus(Enum):
 
 @json_schema_type
 class Job(BaseModel):
+    """A job execution instance with status tracking.
+
+    :param job_id: Unique identifier for the job
+    :param status: Current execution status of the job
+    """
     job_id: str
     status: JobStatus

llama_stack/apis/datatypes.py

@@ -13,6 +13,29 @@ from llama_stack.schema_utils import json_schema_type
 
 @json_schema_type
 class Api(Enum):
+    """Enumeration of all available APIs in the Llama Stack system.
+    
+    :cvar providers: Provider management and configuration
+    :cvar inference: Text generation, chat completions, and embeddings
+    :cvar safety: Content moderation and safety shields
+    :cvar agents: Agent orchestration and execution
+    :cvar vector_io: Vector database operations and queries
+    :cvar datasetio: Dataset input/output operations
+    :cvar scoring: Model output evaluation and scoring
+    :cvar eval: Model evaluation and benchmarking framework
+    :cvar post_training: Fine-tuning and model training
+    :cvar tool_runtime: Tool execution and management
+    :cvar telemetry: Observability and system monitoring
+    :cvar models: Model metadata and management
+    :cvar shields: Safety shield implementations
+    :cvar vector_dbs: Vector database management
+    :cvar datasets: Dataset creation and management
+    :cvar scoring_functions: Scoring function definitions
+    :cvar benchmarks: Benchmark suite management
+    :cvar tool_groups: Tool group organization
+    :cvar files: File storage and management
+    :cvar inspect: Built-in system inspection and introspection
+    """
     providers = "providers"
     inference = "inference"
     safety = "safety"