Update API docs

llama_stack/apis/common/content_types.py

@@ -15,6 +15,11 @@ 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 +81,36 @@ 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 +119,13 @@ 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,11 @@ 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/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,14 @@ 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 +29,16 @@ 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,114 @@ 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"