diff --git a/api_update_plan.md b/api_update_plan.md index a0dd7b95a..ff048f8de 100644 --- a/api_update_plan.md +++ b/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 diff --git a/docs/_static/llama-stack-spec.html b/docs/_static/llama-stack-spec.html index 6419d369a..3b7662f83 100644 --- a/docs/_static/llama-stack-spec.html +++ b/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", diff --git a/docs/_static/llama-stack-spec.yaml b/docs/_static/llama-stack-spec.yaml index 564ea3bbc..73a74cf6f 100644 --- a/docs/_static/llama-stack-spec.yaml +++ b/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: diff --git a/llama_stack/apis/common/content_types.py b/llama_stack/apis/common/content_types.py index 8bcb781f7..24d06062c 100644 --- a/llama_stack/apis/common/content_types.py +++ b/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 diff --git a/llama_stack/apis/common/job_types.py b/llama_stack/apis/common/job_types.py index ca6bcaf63..4e1b11cb1 100644 --- a/llama_stack/apis/common/job_types.py +++ b/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 diff --git a/llama_stack/apis/datatypes.py b/llama_stack/apis/datatypes.py index 63a764725..8bc8991a7 100644 --- a/llama_stack/apis/datatypes.py +++ b/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"