docs: Add detailed docstrings to API models and update OpenAPI spec (#2889)

This PR focuses on improving the developer experience by adding
comprehensive docstrings to the API data models across the Llama Stack.
These docstrings provide detailed explanations for each model and its
fields, making the API easier to understand and use.

**Key changes:**
- **Added Docstrings:** Added reST formatted docstrings to Pydantic
models in the `llama_stack/apis/` directory. This includes models for:
  - Agents (`agents.py`)
  - Benchmarks (`benchmarks.py`)
  - Datasets (`datasets.py`)
  - Inference (`inference.py`)
  - And many other API modules.
- **OpenAPI Spec Update:** Regenerated the OpenAPI specification
(`docs/_static/llama-stack-spec.yaml` and
`docs/_static/llama-stack-spec.html`) to include the new docstrings.
This will be reflected in the API documentation, providing richer
information to users.

**Impact:**
- Developers using the Llama Stack API will have a better understanding
of the data structures.
- The auto-generated API documentation is now more informative.

---------

Co-authored-by: Ashwin Bharambe <ashwin.bharambe@gmail.com>

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,7 +29,15 @@ class PostTrainingMetric(BaseModel):
 
 @json_schema_type
 class Checkpoint(BaseModel):
-    """Checkpoint created during training runs"""
+    """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

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"