From 88af03829ca51a9a709f4edf28529f804e0213f0 Mon Sep 17 00:00:00 2001 From: Sai Soundararaj Date: Tue, 1 Jul 2025 17:59:18 -0700 Subject: [PATCH] a --- api_update_plan.md | 6 +-- docs/_static/llama-stack-spec.html | 65 +++++++++++++++-------- docs/_static/llama-stack-spec.yaml | 27 +++++++++- llama_stack/apis/common/responses.py | 5 ++ llama_stack/apis/common/training_types.py | 16 ++++++ llama_stack/apis/common/type_system.py | 44 +++++++++++++++ 6 files changed, 137 insertions(+), 26 deletions(-) diff --git a/api_update_plan.md b/api_update_plan.md index ff048f8de..e653ac566 100644 --- a/api_update_plan.md +++ b/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 -[ ] 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] 26. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/training_types.py` - Training metrics and checkpoint types +[x] 27. `/Users/saip/Documents/GitHub/llama-stack-sai/llama_stack/apis/common/responses.py` - Generic response types (well documented) +[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. diff --git a/docs/_static/llama-stack-spec.html b/docs/_static/llama-stack-spec.html index 3b7662f83..9a8b92b15 100644 --- a/docs/_static/llama-stack-spec.html +++ b/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", diff --git a/docs/_static/llama-stack-spec.yaml b/docs/_static/llama-stack-spec.yaml index 73a74cf6f..ea306f120 100644 --- a/docs/_static/llama-stack-spec.yaml +++ b/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: diff --git a/llama_stack/apis/common/responses.py b/llama_stack/apis/common/responses.py index e4cf21a54..ab2b3f13a 100644 --- a/llama_stack/apis/common/responses.py +++ b/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" diff --git a/llama_stack/apis/common/training_types.py b/llama_stack/apis/common/training_types.py index 46cd101af..b97947e78 100644 --- a/llama_stack/apis/common/training_types.py +++ b/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 diff --git a/llama_stack/apis/common/type_system.py b/llama_stack/apis/common/type_system.py index db4aab4c5..3f93e4c69 100644 --- a/llama_stack/apis/common/type_system.py +++ b/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"