From cb7354a9cebad943c6a88b9d2ff4c12a00b36155 Mon Sep 17 00:00:00 2001 From: Sai Prashanth S <6779603+saiprashanths@users.noreply.github.com> Date: Wed, 30 Jul 2025 16:32:59 -0700 Subject: [PATCH] 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 --- docs/_static/llama-stack-spec.html | 2147 +++++++++++------ docs/_static/llama-stack-spec.yaml | 1309 +++++++++- llama_stack/apis/agents/agents.py | 114 +- llama_stack/apis/agents/openai_responses.py | 287 +++ llama_stack/apis/benchmarks/benchmarks.py | 8 + llama_stack/apis/common/content_types.py | 31 + llama_stack/apis/common/job_types.py | 14 + llama_stack/apis/common/responses.py | 5 + llama_stack/apis/common/training_types.py | 18 +- llama_stack/apis/common/type_system.py | 55 + llama_stack/apis/datasets/datasets.py | 19 + llama_stack/apis/datatypes.py | 23 + llama_stack/apis/files/files.py | 3 + llama_stack/apis/inference/inference.py | 111 + llama_stack/apis/inspect/inspect.py | 32 +- llama_stack/apis/models/models.py | 15 + .../apis/post_training/post_training.py | 124 +- llama_stack/apis/providers/providers.py | 14 + llama_stack/apis/safety/safety.py | 19 + llama_stack/apis/scoring/scoring.py | 6 + .../scoring_functions/scoring_functions.py | 37 + llama_stack/apis/shields/shields.py | 6 +- .../synthetic_data_generation.py | 33 +- llama_stack/apis/telemetry/telemetry.py | 163 ++ llama_stack/apis/tools/rag_tool.py | 43 +- llama_stack/apis/tools/tools.py | 69 + llama_stack/apis/vector_dbs/vector_dbs.py | 20 + llama_stack/apis/vector_io/vector_io.py | 166 +- 28 files changed, 4079 insertions(+), 812 deletions(-) diff --git a/docs/_static/llama-stack-spec.html b/docs/_static/llama-stack-spec.html index 65b515ef4..6a8945bd1 100644 --- a/docs/_static/llama-stack-spec.html +++ b/docs/_static/llama-stack-spec.html @@ -1922,7 +1922,7 @@ "get": { "responses": { "200": { - "description": "A HealthInfo.", + "description": "Health information indicating if the service is operational.", "content": { "application/json": { "schema": { @@ -1947,7 +1947,7 @@ "tags": [ "Inspect" ], - "description": "Get the health of the service.", + "description": "Get the current health status of the service.", "parameters": [] } }, @@ -1973,7 +1973,7 @@ "tags": [ "ToolRuntime" ], - "description": "Index documents so they can be used by the RAG system", + "description": "Index documents so they can be used by the RAG system.", "parameters": [], "requestBody": { "content": { @@ -2839,7 +2839,7 @@ "get": { "responses": { "200": { - "description": "A ListRoutesResponse.", + "description": "Response containing information about all available routes.", "content": { "application/json": { "schema": { @@ -2864,7 +2864,7 @@ "tags": [ "Inspect" ], - "description": "List all routes.", + "description": "List all available API routes with their methods and implementing providers.", "parameters": [] } }, @@ -3324,6 +3324,7 @@ { "name": "limit", "in": "query", + "description": "(Optional) A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.", "required": false, "schema": { "type": "integer" @@ -3332,6 +3333,7 @@ { "name": "order", "in": "query", + "description": "(Optional) Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.", "required": false, "schema": { "type": "string" @@ -3340,6 +3342,7 @@ { "name": "after", "in": "query", + "description": "(Optional) A cursor for use in pagination. `after` is an object ID that defines your place in the list.", "required": false, "schema": { "type": "string" @@ -3348,6 +3351,7 @@ { "name": "before", "in": "query", + "description": "(Optional) A cursor for use in pagination. `before` is an object ID that defines your place in the list.", "required": false, "schema": { "type": "string" @@ -3356,6 +3360,7 @@ { "name": "filter", "in": "query", + "description": "(Optional) Filter by file status to only return files with the specified status.", "required": false, "schema": { "$ref": "#/components/schemas/VectorStoreFileStatus" @@ -4345,7 +4350,7 @@ "post": { "responses": { "200": { - "description": "OK", + "description": "RAGQueryResult containing the retrieved content and metadata", "content": { "application/json": { "schema": { @@ -4370,7 +4375,7 @@ "tags": [ "ToolRuntime" ], - "description": "Query the RAG system for context; typically invoked by the agent", + "description": "Query the RAG system for context; typically invoked by the agent.", "parameters": [], "requestBody": { "content": { @@ -4907,7 +4912,7 @@ "post": { "responses": { "200": { - "description": "OK", + "description": "Response containing filtered synthetic data samples and optional statistics", "content": { "application/json": { "schema": { @@ -4932,7 +4937,7 @@ "tags": [ "SyntheticDataGeneration (Coming Soon)" ], - "description": "", + "description": "Generate synthetic data based on input dialogs and apply filtering.", "parameters": [], "requestBody": { "content": { @@ -4950,7 +4955,7 @@ "get": { "responses": { "200": { - "description": "A VersionInfo.", + "description": "Version information containing the service version number.", "content": { "application/json": { "schema": { @@ -5144,14 +5149,16 @@ "type": { "type": "string", "const": "greedy", - "default": "greedy" + "default": "greedy", + "description": "Must be \"greedy\" to identify this sampling strategy" } }, "additionalProperties": false, "required": [ "type" ], - "title": "GreedySamplingStrategy" + "title": "GreedySamplingStrategy", + "description": "Greedy sampling strategy that selects the highest probability token at each step." }, "ImageContentItem": { "type": "object", @@ -5671,10 +5678,12 @@ "type": { "type": "string", "const": "top_k", - "default": "top_k" + "default": "top_k", + "description": "Must be \"top_k\" to identify this sampling strategy" }, "top_k": { - "type": "integer" + "type": "integer", + "description": "Number of top tokens to consider for sampling. Must be at least 1" } }, "additionalProperties": false, @@ -5682,7 +5691,8 @@ "type", "top_k" ], - "title": "TopKSamplingStrategy" + "title": "TopKSamplingStrategy", + "description": "Top-k sampling strategy that restricts sampling to the k most likely tokens." }, "TopPSamplingStrategy": { "type": "object", @@ -5690,34 +5700,40 @@ "type": { "type": "string", "const": "top_p", - "default": "top_p" + "default": "top_p", + "description": "Must be \"top_p\" to identify this sampling strategy" }, "temperature": { - "type": "number" + "type": "number", + "description": "Controls randomness in sampling. Higher values increase randomness" }, "top_p": { "type": "number", - "default": 0.95 + "default": 0.95, + "description": "Cumulative probability threshold for nucleus sampling. Defaults to 0.95" } }, "additionalProperties": false, "required": [ "type" ], - "title": "TopPSamplingStrategy" + "title": "TopPSamplingStrategy", + "description": "Top-p (nucleus) sampling strategy that samples from the smallest set of tokens with cumulative probability >= p." }, "URL": { "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", @@ -5808,14 +5824,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/ChatCompletionResponse" - } + }, + "description": "List of chat completion responses, one for each conversation in the batch" } }, "additionalProperties": false, "required": [ "batch" ], - "title": "BatchChatCompletionResponse" + "title": "BatchChatCompletionResponse", + "description": "Response from a batch chat completion request." }, "ChatCompletionResponse": { "type": "object", @@ -5824,7 +5842,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/MetricInResponse" - } + }, + "description": "(Optional) List of metrics associated with the API response" }, "completion_message": { "$ref": "#/components/schemas/CompletionMessage", @@ -5849,7 +5868,8 @@ "type": "object", "properties": { "metric": { - "type": "string" + "type": "string", + "description": "The name of the metric" }, "value": { "oneOf": [ @@ -5859,10 +5879,12 @@ { "type": "number" } - ] + ], + "description": "The numeric value of the metric" }, "unit": { - "type": "string" + "type": "string", + "description": "(Optional) The unit of measurement for the metric value" } }, "additionalProperties": false, @@ -5870,7 +5892,8 @@ "metric", "value" ], - "title": "MetricInResponse" + "title": "MetricInResponse", + "description": "A metric value included in API responses." }, "TokenLogProbs": { "type": "object", @@ -5939,14 +5962,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/CompletionResponse" - } + }, + "description": "List of completion responses, one for each input in the batch" } }, "additionalProperties": false, "required": [ "batch" ], - "title": "BatchCompletionResponse" + "title": "BatchCompletionResponse", + "description": "Response from a batch completion request." }, "CompletionResponse": { "type": "object", @@ -5955,7 +5980,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/MetricInResponse" - } + }, + "description": "(Optional) List of metrics associated with the API response" }, "content": { "type": "string", @@ -6123,7 +6149,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/MetricInResponse" - } + }, + "description": "(Optional) List of metrics associated with the API response" }, "event": { "$ref": "#/components/schemas/ChatCompletionResponseEvent", @@ -6164,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, @@ -6176,7 +6205,8 @@ "type", "image" ], - "title": "ImageDelta" + "title": "ImageDelta", + "description": "An image content delta for streaming responses." }, "TextDelta": { "type": "object", @@ -6184,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, @@ -6195,7 +6227,8 @@ "type", "text" ], - "title": "TextDelta" + "title": "TextDelta", + "description": "A text content delta for streaming responses." }, "ToolCallDelta": { "type": "object", @@ -6203,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": [ @@ -6213,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", @@ -6223,7 +6258,7 @@ "failed", "succeeded" ], - "title": "ToolCallParseStatus" + "description": "Current parsing status of the tool call" } }, "additionalProperties": false, @@ -6232,7 +6267,8 @@ "tool_call", "parse_status" ], - "title": "ToolCallDelta" + "title": "ToolCallDelta", + "description": "A tool call content delta for streaming responses." }, "CompletionRequest": { "type": "object", @@ -6284,7 +6320,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/MetricInResponse" - } + }, + "description": "(Optional) List of metrics associated with the API response" }, "delta": { "type": "string", @@ -6453,16 +6490,19 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the tool" }, "description": { - "type": "string" + "type": "string", + "description": "(Optional) Human-readable description of what the tool does" }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/ToolParameter" - } + }, + "description": "(Optional) List of parameters this tool accepts" }, "metadata": { "type": "object", @@ -6487,30 +6527,36 @@ "type": "object" } ] - } + }, + "description": "(Optional) Additional metadata about the tool" } }, "additionalProperties": false, "required": [ "name" ], - "title": "ToolDef" + "title": "ToolDef", + "description": "Tool definition used in runtime contexts." }, "ToolParameter": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the parameter" }, "parameter_type": { - "type": "string" + "type": "string", + "description": "Type of the parameter (e.g., string, integer)" }, "description": { - "type": "string" + "type": "string", + "description": "Human-readable description of what the parameter does" }, "required": { "type": "boolean", - "default": true + "default": true, + "description": "Whether this parameter is required for tool invocation" }, "default": { "oneOf": [ @@ -6532,7 +6578,8 @@ { "type": "object" } - ] + ], + "description": "(Optional) Default value for the parameter if not provided" } }, "additionalProperties": false, @@ -6542,7 +6589,8 @@ "description", "required" ], - "title": "ToolParameter" + "title": "ToolParameter", + "description": "Parameter definition for a tool." }, "CreateAgentRequest": { "type": "object", @@ -6562,14 +6610,16 @@ "type": "object", "properties": { "agent_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the created agent" } }, "additionalProperties": false, "required": [ "agent_id" ], - "title": "AgentCreateResponse" + "title": "AgentCreateResponse", + "description": "Response returned when creating a new agent." }, "CreateAgentSessionRequest": { "type": "object", @@ -6589,14 +6639,16 @@ "type": "object", "properties": { "session_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the created session" } }, "additionalProperties": false, "required": [ "session_id" ], - "title": "AgentSessionCreateResponse" + "title": "AgentSessionCreateResponse", + "description": "Response returned when creating a new agent session." }, "CreateAgentTurnRequest": { "type": "object", @@ -6784,10 +6836,12 @@ "type": "object", "properties": { "violation_level": { - "$ref": "#/components/schemas/ViolationLevel" + "$ref": "#/components/schemas/ViolationLevel", + "description": "Severity level of the violation" }, "user_message": { - "type": "string" + "type": "string", + "description": "(Optional) Message to convey to the user about the violation" }, "metadata": { "type": "object", @@ -6812,7 +6866,8 @@ "type": "object" } ] - } + }, + "description": "Additional metadata including specific violation codes for debugging and telemetry" } }, "additionalProperties": false, @@ -6820,7 +6875,8 @@ "violation_level", "metadata" ], - "title": "SafetyViolation" + "title": "SafetyViolation", + "description": "Details of a safety violation detected by content moderation." }, "ShieldCallStep": { "type": "object", @@ -6934,7 +6990,8 @@ "type": "object", "properties": { "call_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the tool call this response is for" }, "tool_name": { "oneOf": [ @@ -6951,10 +7008,12 @@ { "type": "string" } - ] + ], + "description": "Name of the tool that was invoked" }, "content": { - "$ref": "#/components/schemas/InterleavedContent" + "$ref": "#/components/schemas/InterleavedContent", + "description": "The response content from the tool" }, "metadata": { "type": "object", @@ -6979,7 +7038,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) Additional metadata about the tool response" } }, "additionalProperties": false, @@ -6988,16 +7048,19 @@ "tool_name", "content" ], - "title": "ToolResponse" + "title": "ToolResponse", + "description": "Response from a tool invocation." }, "Turn": { "type": "object", "properties": { "turn_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the turn within a session" }, "session_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the conversation session" }, "input_messages": { "type": "array", @@ -7010,7 +7073,8 @@ "$ref": "#/components/schemas/ToolResponseMessage" } ] - } + }, + "description": "List of messages that initiated this turn" }, "steps": { "type": "array", @@ -7038,10 +7102,12 @@ "memory_retrieval": "#/components/schemas/MemoryRetrievalStep" } } - } + }, + "description": "Ordered list of processing steps executed during this turn" }, "output_message": { - "$ref": "#/components/schemas/CompletionMessage" + "$ref": "#/components/schemas/CompletionMessage", + "description": "The model's generated response containing content and metadata" }, "output_attachments": { "type": "array", @@ -7080,15 +7146,18 @@ ], "title": "Attachment", "description": "An attachment to an agent turn." - } + }, + "description": "(Optional) Files or media attached to the agent's response" }, "started_at": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the turn began" }, "completed_at": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "(Optional) Timestamp when the turn finished, if completed" } }, "additionalProperties": false, @@ -7110,20 +7179,23 @@ "warn", "error" ], - "title": "ViolationLevel" + "title": "ViolationLevel", + "description": "Severity level of a safety violation." }, "AgentTurnResponseEvent": { "type": "object", "properties": { "payload": { - "$ref": "#/components/schemas/AgentTurnResponseEventPayload" + "$ref": "#/components/schemas/AgentTurnResponseEventPayload", + "description": "Event-specific payload containing event data" } }, "additionalProperties": false, "required": [ "payload" ], - "title": "AgentTurnResponseEvent" + "title": "AgentTurnResponseEvent", + "description": "An event in an agent turn response stream." }, "AgentTurnResponseEventPayload": { "oneOf": [ @@ -7171,9 +7243,9 @@ "turn_complete", "turn_awaiting_input" ], - "title": "AgentTurnResponseEventType", "const": "step_complete", - "default": "step_complete" + "default": "step_complete", + "description": "Type of event being reported" }, "step_type": { "type": "string", @@ -7183,11 +7255,11 @@ "shield_call", "memory_retrieval" ], - "title": "StepType", - "description": "Type of the step in an agent turn." + "description": "Type of step being executed" }, "step_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the step within a turn" }, "step_details": { "oneOf": [ @@ -7212,7 +7284,8 @@ "shield_call": "#/components/schemas/ShieldCallStep", "memory_retrieval": "#/components/schemas/MemoryRetrievalStep" } - } + }, + "description": "Complete details of the executed step" } }, "additionalProperties": false, @@ -7222,7 +7295,8 @@ "step_id", "step_details" ], - "title": "AgentTurnResponseStepCompletePayload" + "title": "AgentTurnResponseStepCompletePayload", + "description": "Payload for step completion events in agent turn responses." }, "AgentTurnResponseStepProgressPayload": { "type": "object", @@ -7237,9 +7311,9 @@ "turn_complete", "turn_awaiting_input" ], - "title": "AgentTurnResponseEventType", "const": "step_progress", - "default": "step_progress" + "default": "step_progress", + "description": "Type of event being reported" }, "step_type": { "type": "string", @@ -7249,14 +7323,15 @@ "shield_call", "memory_retrieval" ], - "title": "StepType", - "description": "Type of the step in an agent turn." + "description": "Type of step being executed" }, "step_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the step within a turn" }, "delta": { - "$ref": "#/components/schemas/ContentDelta" + "$ref": "#/components/schemas/ContentDelta", + "description": "Incremental content changes during step execution" } }, "additionalProperties": false, @@ -7266,7 +7341,8 @@ "step_id", "delta" ], - "title": "AgentTurnResponseStepProgressPayload" + "title": "AgentTurnResponseStepProgressPayload", + "description": "Payload for step progress events in agent turn responses." }, "AgentTurnResponseStepStartPayload": { "type": "object", @@ -7281,9 +7357,9 @@ "turn_complete", "turn_awaiting_input" ], - "title": "AgentTurnResponseEventType", "const": "step_start", - "default": "step_start" + "default": "step_start", + "description": "Type of event being reported" }, "step_type": { "type": "string", @@ -7293,11 +7369,11 @@ "shield_call", "memory_retrieval" ], - "title": "StepType", - "description": "Type of the step in an agent turn." + "description": "Type of step being executed" }, "step_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the step within a turn" }, "metadata": { "type": "object", @@ -7322,7 +7398,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) Additional metadata for the step" } }, "additionalProperties": false, @@ -7331,13 +7408,15 @@ "step_type", "step_id" ], - "title": "AgentTurnResponseStepStartPayload" + "title": "AgentTurnResponseStepStartPayload", + "description": "Payload for step start events in agent turn responses." }, "AgentTurnResponseStreamChunk": { "type": "object", "properties": { "event": { - "$ref": "#/components/schemas/AgentTurnResponseEvent" + "$ref": "#/components/schemas/AgentTurnResponseEvent", + "description": "Individual event in the agent turn response stream" } }, "additionalProperties": false, @@ -7345,7 +7424,7 @@ "event" ], "title": "AgentTurnResponseStreamChunk", - "description": "streamed agent turn completion response." + "description": "Streamed agent turn completion response." }, "AgentTurnResponseTurnAwaitingInputPayload": { "type": "object", @@ -7360,12 +7439,13 @@ "turn_complete", "turn_awaiting_input" ], - "title": "AgentTurnResponseEventType", "const": "turn_awaiting_input", - "default": "turn_awaiting_input" + "default": "turn_awaiting_input", + "description": "Type of event being reported" }, "turn": { - "$ref": "#/components/schemas/Turn" + "$ref": "#/components/schemas/Turn", + "description": "Turn data when waiting for external tool responses" } }, "additionalProperties": false, @@ -7373,7 +7453,8 @@ "event_type", "turn" ], - "title": "AgentTurnResponseTurnAwaitingInputPayload" + "title": "AgentTurnResponseTurnAwaitingInputPayload", + "description": "Payload for turn awaiting input events in agent turn responses." }, "AgentTurnResponseTurnCompletePayload": { "type": "object", @@ -7388,12 +7469,13 @@ "turn_complete", "turn_awaiting_input" ], - "title": "AgentTurnResponseEventType", "const": "turn_complete", - "default": "turn_complete" + "default": "turn_complete", + "description": "Type of event being reported" }, "turn": { - "$ref": "#/components/schemas/Turn" + "$ref": "#/components/schemas/Turn", + "description": "Complete turn data including all steps and results" } }, "additionalProperties": false, @@ -7401,7 +7483,8 @@ "event_type", "turn" ], - "title": "AgentTurnResponseTurnCompletePayload" + "title": "AgentTurnResponseTurnCompletePayload", + "description": "Payload for turn completion events in agent turn responses." }, "AgentTurnResponseTurnStartPayload": { "type": "object", @@ -7416,12 +7499,13 @@ "turn_complete", "turn_awaiting_input" ], - "title": "AgentTurnResponseEventType", "const": "turn_start", - "default": "turn_start" + "default": "turn_start", + "description": "Type of event being reported" }, "turn_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the turn within a session" } }, "additionalProperties": false, @@ -7429,7 +7513,8 @@ "event_type", "turn_id" ], - "title": "AgentTurnResponseTurnStartPayload" + "title": "AgentTurnResponseTurnStartPayload", + "description": "Payload for turn start events in agent turn responses." }, "OpenAIResponseAnnotationCitation": { "type": "object", @@ -7437,19 +7522,24 @@ "type": { "type": "string", "const": "url_citation", - "default": "url_citation" + "default": "url_citation", + "description": "Annotation type identifier, always \"url_citation\"" }, "end_index": { - "type": "integer" + "type": "integer", + "description": "End position of the citation span in the content" }, "start_index": { - "type": "integer" + "type": "integer", + "description": "Start position of the citation span in the content" }, "title": { - "type": "string" + "type": "string", + "description": "Title of the referenced web resource" }, "url": { - "type": "string" + "type": "string", + "description": "URL of the referenced web resource" } }, "additionalProperties": false, @@ -7460,7 +7550,8 @@ "title", "url" ], - "title": "OpenAIResponseAnnotationCitation" + "title": "OpenAIResponseAnnotationCitation", + "description": "URL citation annotation for referencing external web resources." }, "OpenAIResponseAnnotationContainerFileCitation": { "type": "object", @@ -7503,16 +7594,20 @@ "type": { "type": "string", "const": "file_citation", - "default": "file_citation" + "default": "file_citation", + "description": "Annotation type identifier, always \"file_citation\"" }, "file_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the referenced file" }, "filename": { - "type": "string" + "type": "string", + "description": "Name of the referenced file" }, "index": { - "type": "integer" + "type": "integer", + "description": "Position index of the citation within the content" } }, "additionalProperties": false, @@ -7522,7 +7617,8 @@ "filename", "index" ], - "title": "OpenAIResponseAnnotationFileCitation" + "title": "OpenAIResponseAnnotationFileCitation", + "description": "File citation annotation for referencing specific files in response content." }, "OpenAIResponseAnnotationFilePath": { "type": "object", @@ -7656,15 +7752,18 @@ "const": "auto" } ], - "default": "auto" + "default": "auto", + "description": "Level of detail for image processing, can be \"low\", \"high\", or \"auto\"" }, "type": { "type": "string", "const": "input_image", - "default": "input_image" + "default": "input_image", + "description": "Content type identifier, always \"input_image\"" }, "image_url": { - "type": "string" + "type": "string", + "description": "(Optional) URL of the image content" } }, "additionalProperties": false, @@ -7672,18 +7771,21 @@ "detail", "type" ], - "title": "OpenAIResponseInputMessageContentImage" + "title": "OpenAIResponseInputMessageContentImage", + "description": "Image content for input messages in OpenAI response format." }, "OpenAIResponseInputMessageContentText": { "type": "object", "properties": { "text": { - "type": "string" + "type": "string", + "description": "The text content of the input message" }, "type": { "type": "string", "const": "input_text", - "default": "input_text" + "default": "input_text", + "description": "Content type identifier, always \"input_text\"" } }, "additionalProperties": false, @@ -7691,7 +7793,8 @@ "text", "type" ], - "title": "OpenAIResponseInputMessageContentText" + "title": "OpenAIResponseInputMessageContentText", + "description": "Text content for input messages in OpenAI response format." }, "OpenAIResponseInputTool": { "oneOf": [ @@ -7724,13 +7827,15 @@ "type": { "type": "string", "const": "file_search", - "default": "file_search" + "default": "file_search", + "description": "Tool type identifier, always \"file_search\"" }, "vector_store_ids": { "type": "array", "items": { "type": "string" - } + }, + "description": "List of vector store identifiers to search within" }, "filters": { "type": "object", @@ -7755,25 +7860,29 @@ "type": "object" } ] - } + }, + "description": "(Optional) Additional filters to apply to the search" }, "max_num_results": { "type": "integer", - "default": 10 + "default": 10, + "description": "(Optional) Maximum number of search results to return (1-50)" }, "ranking_options": { "type": "object", "properties": { "ranker": { - "type": "string" + "type": "string", + "description": "(Optional) Name of the ranking algorithm to use" }, "score_threshold": { "type": "number", - "default": 0.0 + "default": 0.0, + "description": "(Optional) Minimum relevance score threshold for results" } }, "additionalProperties": false, - "title": "SearchRankingOptions" + "description": "(Optional) Options for ranking and scoring search results" } }, "additionalProperties": false, @@ -7781,7 +7890,8 @@ "type", "vector_store_ids" ], - "title": "OpenAIResponseInputToolFileSearch" + "title": "OpenAIResponseInputToolFileSearch", + "description": "File search tool configuration for OpenAI response inputs." }, "OpenAIResponseInputToolFunction": { "type": "object", @@ -7789,13 +7899,16 @@ "type": { "type": "string", "const": "function", - "default": "function" + "default": "function", + "description": "Tool type identifier, always \"function\"" }, "name": { - "type": "string" + "type": "string", + "description": "Name of the function that can be called" }, "description": { - "type": "string" + "type": "string", + "description": "(Optional) Description of what the function does" }, "parameters": { "type": "object", @@ -7820,10 +7933,12 @@ "type": "object" } ] - } + }, + "description": "(Optional) JSON schema defining the function's parameters" }, "strict": { - "type": "boolean" + "type": "boolean", + "description": "(Optional) Whether to enforce strict parameter validation" } }, "additionalProperties": false, @@ -7831,7 +7946,8 @@ "type", "name" ], - "title": "OpenAIResponseInputToolFunction" + "title": "OpenAIResponseInputToolFunction", + "description": "Function tool configuration for OpenAI response inputs." }, "OpenAIResponseInputToolMCP": { "type": "object", @@ -7839,13 +7955,16 @@ "type": { "type": "string", "const": "mcp", - "default": "mcp" + "default": "mcp", + "description": "Tool type identifier, always \"mcp\"" }, "server_label": { - "type": "string" + "type": "string", + "description": "Label to identify this MCP server" }, "server_url": { - "type": "string" + "type": "string", + "description": "URL endpoint of the MCP server" }, "headers": { "type": "object", @@ -7870,7 +7989,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) HTTP headers to include when connecting to the server" }, "require_approval": { "oneOf": [ @@ -7889,20 +8009,24 @@ "type": "array", "items": { "type": "string" - } + }, + "description": "(Optional) List of tool names that always require approval" }, "never": { "type": "array", "items": { "type": "string" - } + }, + "description": "(Optional) List of tool names that never require approval" } }, "additionalProperties": false, - "title": "ApprovalFilter" + "title": "ApprovalFilter", + "description": "Filter configuration for MCP tool approval requirements." } ], - "default": "never" + "default": "never", + "description": "Approval requirement for tool calls (\"always\", \"never\", or filter)" }, "allowed_tools": { "oneOf": [ @@ -7919,13 +8043,16 @@ "type": "array", "items": { "type": "string" - } + }, + "description": "(Optional) List of specific tool names that are allowed" } }, "additionalProperties": false, - "title": "AllowedToolsFilter" + "title": "AllowedToolsFilter", + "description": "Filter configuration for restricting which MCP tools can be used." } - ] + ], + "description": "(Optional) Restriction on which tools can be used from this server" } }, "additionalProperties": false, @@ -7935,7 +8062,8 @@ "server_url", "require_approval" ], - "title": "OpenAIResponseInputToolMCP" + "title": "OpenAIResponseInputToolMCP", + "description": "Model Context Protocol (MCP) tool configuration for OpenAI response inputs." }, "OpenAIResponseInputToolWebSearch": { "type": "object", @@ -7955,18 +8083,21 @@ "const": "web_search_preview_2025_03_11" } ], - "default": "web_search" + "default": "web_search", + "description": "Web search tool type variant to use" }, "search_context_size": { "type": "string", - "default": "medium" + "default": "medium", + "description": "(Optional) Size of search context, must be \"low\", \"medium\", or \"high\"" } }, "additionalProperties": false, "required": [ "type" ], - "title": "OpenAIResponseInputToolWebSearch" + "title": "OpenAIResponseInputToolWebSearch", + "description": "Web search tool configuration for OpenAI response inputs." }, "OpenAIResponseMessage": { "type": "object", @@ -8061,21 +8192,25 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier for this tool call" }, "queries": { "type": "array", "items": { "type": "string" - } + }, + "description": "List of search queries executed" }, "status": { - "type": "string" + "type": "string", + "description": "Current status of the file search operation" }, "type": { "type": "string", "const": "file_search_call", - "default": "file_search_call" + "default": "file_search_call", + "description": "Tool call type identifier, always \"file_search_call\"" }, "results": { "type": "array", @@ -8103,7 +8238,8 @@ } ] } - } + }, + "description": "(Optional) Search results returned by the file search operation" } }, "additionalProperties": false, @@ -8113,30 +8249,37 @@ "status", "type" ], - "title": "OpenAIResponseOutputMessageFileSearchToolCall" + "title": "OpenAIResponseOutputMessageFileSearchToolCall", + "description": "File search tool call output message for OpenAI responses." }, "OpenAIResponseOutputMessageFunctionToolCall": { "type": "object", "properties": { "call_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the function call" }, "name": { - "type": "string" + "type": "string", + "description": "Name of the function being called" }, "arguments": { - "type": "string" + "type": "string", + "description": "JSON string containing the function arguments" }, "type": { "type": "string", "const": "function_call", - "default": "function_call" + "default": "function_call", + "description": "Tool call type identifier, always \"function_call\"" }, "id": { - "type": "string" + "type": "string", + "description": "(Optional) Additional identifier for the tool call" }, "status": { - "type": "string" + "type": "string", + "description": "(Optional) Current status of the function call execution" } }, "additionalProperties": false, @@ -8146,21 +8289,25 @@ "arguments", "type" ], - "title": "OpenAIResponseOutputMessageFunctionToolCall" + "title": "OpenAIResponseOutputMessageFunctionToolCall", + "description": "Function tool call output message for OpenAI responses." }, "OpenAIResponseOutputMessageWebSearchToolCall": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier for this tool call" }, "status": { - "type": "string" + "type": "string", + "description": "Current status of the web search operation" }, "type": { "type": "string", "const": "web_search_call", - "default": "web_search_call" + "default": "web_search_call", + "description": "Tool call type identifier, always \"web_search_call\"" } }, "additionalProperties": false, @@ -8169,7 +8316,8 @@ "status", "type" ], - "title": "OpenAIResponseOutputMessageWebSearchToolCall" + "title": "OpenAIResponseOutputMessageWebSearchToolCall", + "description": "Web search tool call output message for OpenAI responses." }, "OpenAIResponseText": { "type": "object", @@ -8237,12 +8385,12 @@ "required": [ "type" ], - "title": "OpenAIResponseTextFormat", - "description": "Configuration for Responses API text format." + "description": "(Optional) Text format configuration specifying output format requirements" } }, "additionalProperties": false, - "title": "OpenAIResponseText" + "title": "OpenAIResponseText", + "description": "Text response configuration for OpenAI responses." }, "CreateOpenaiResponseRequest": { "type": "object", @@ -8305,10 +8453,12 @@ "type": "object", "properties": { "code": { - "type": "string" + "type": "string", + "description": "Error code identifying the type of failure" }, "message": { - "type": "string" + "type": "string", + "description": "Human-readable error message describing the failure" } }, "additionalProperties": false, @@ -8316,58 +8466,73 @@ "code", "message" ], - "title": "OpenAIResponseError" + "title": "OpenAIResponseError", + "description": "Error details for failed OpenAI response requests." }, "OpenAIResponseObject": { "type": "object", "properties": { "created_at": { - "type": "integer" + "type": "integer", + "description": "Unix timestamp when the response was created" }, "error": { - "$ref": "#/components/schemas/OpenAIResponseError" + "$ref": "#/components/schemas/OpenAIResponseError", + "description": "(Optional) Error details if the response generation failed" }, "id": { - "type": "string" + "type": "string", + "description": "Unique identifier for this response" }, "model": { - "type": "string" + "type": "string", + "description": "Model identifier used for generation" }, "object": { "type": "string", "const": "response", - "default": "response" + "default": "response", + "description": "Object type identifier, always \"response\"" }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/OpenAIResponseOutput" - } + }, + "description": "List of generated output items (messages, tool calls, etc.)" }, "parallel_tool_calls": { "type": "boolean", - "default": false + "default": false, + "description": "Whether tool calls can be executed in parallel" }, "previous_response_id": { - "type": "string" + "type": "string", + "description": "(Optional) ID of the previous response in a conversation" }, "status": { - "type": "string" + "type": "string", + "description": "Current status of the response generation" }, "temperature": { - "type": "number" + "type": "number", + "description": "(Optional) Sampling temperature used for generation" }, "text": { - "$ref": "#/components/schemas/OpenAIResponseText" + "$ref": "#/components/schemas/OpenAIResponseText", + "description": "Text formatting configuration for the response" }, "top_p": { - "type": "number" + "type": "number", + "description": "(Optional) Nucleus sampling parameter used for generation" }, "truncation": { - "type": "string" + "type": "string", + "description": "(Optional) Truncation strategy applied to the response" }, "user": { - "type": "string" + "type": "string", + "description": "(Optional) User identifier associated with the request" } }, "additionalProperties": false, @@ -8381,7 +8546,8 @@ "status", "text" ], - "title": "OpenAIResponseObject" + "title": "OpenAIResponseObject", + "description": "Complete OpenAI response object containing generation results and metadata." }, "OpenAIResponseOutput": { "oneOf": [ @@ -8420,27 +8586,34 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier for this MCP call" }, "type": { "type": "string", "const": "mcp_call", - "default": "mcp_call" + "default": "mcp_call", + "description": "Tool call type identifier, always \"mcp_call\"" }, "arguments": { - "type": "string" + "type": "string", + "description": "JSON string containing the MCP call arguments" }, "name": { - "type": "string" + "type": "string", + "description": "Name of the MCP method being called" }, "server_label": { - "type": "string" + "type": "string", + "description": "Label identifying the MCP server handling the call" }, "error": { - "type": "string" + "type": "string", + "description": "(Optional) Error message if the MCP call failed" }, "output": { - "type": "string" + "type": "string", + "description": "(Optional) Output result from the successful MCP call" } }, "additionalProperties": false, @@ -8451,21 +8624,25 @@ "name", "server_label" ], - "title": "OpenAIResponseOutputMessageMCPCall" + "title": "OpenAIResponseOutputMessageMCPCall", + "description": "Model Context Protocol (MCP) call output message for OpenAI responses." }, "OpenAIResponseOutputMessageMCPListTools": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier for this MCP list tools operation" }, "type": { "type": "string", "const": "mcp_list_tools", - "default": "mcp_list_tools" + "default": "mcp_list_tools", + "description": "Tool call type identifier, always \"mcp_list_tools\"" }, "server_label": { - "type": "string" + "type": "string", + "description": "Label identifying the MCP server providing the tools" }, "tools": { "type": "array", @@ -8495,13 +8672,16 @@ "type": "object" } ] - } + }, + "description": "JSON schema defining the tool's input parameters" }, "name": { - "type": "string" + "type": "string", + "description": "Name of the tool" }, "description": { - "type": "string" + "type": "string", + "description": "(Optional) Description of what the tool does" } }, "additionalProperties": false, @@ -8509,8 +8689,10 @@ "input_schema", "name" ], - "title": "MCPListToolsTool" - } + "title": "MCPListToolsTool", + "description": "Tool definition returned by MCP list tools operation." + }, + "description": "List of available tools provided by the MCP server" } }, "additionalProperties": false, @@ -8520,7 +8702,8 @@ "server_label", "tools" ], - "title": "OpenAIResponseOutputMessageMCPListTools" + "title": "OpenAIResponseOutputMessageMCPListTools", + "description": "MCP list tools output message containing available tools from an MCP server." }, "OpenAIResponseObjectStream": { "oneOf": [ @@ -8611,12 +8794,14 @@ "type": "object", "properties": { "response": { - "$ref": "#/components/schemas/OpenAIResponseObject" + "$ref": "#/components/schemas/OpenAIResponseObject", + "description": "The completed response object" }, "type": { "type": "string", "const": "response.completed", - "default": "response.completed" + "default": "response.completed", + "description": "Event type identifier, always \"response.completed\"" } }, "additionalProperties": false, @@ -8624,18 +8809,21 @@ "response", "type" ], - "title": "OpenAIResponseObjectStreamResponseCompleted" + "title": "OpenAIResponseObjectStreamResponseCompleted", + "description": "Streaming event indicating a response has been completed." }, "OpenAIResponseObjectStreamResponseCreated": { "type": "object", "properties": { "response": { - "$ref": "#/components/schemas/OpenAIResponseObject" + "$ref": "#/components/schemas/OpenAIResponseObject", + "description": "The newly created response object" }, "type": { "type": "string", "const": "response.created", - "default": "response.created" + "default": "response.created", + "description": "Event type identifier, always \"response.created\"" } }, "additionalProperties": false, @@ -8643,27 +8831,33 @@ "response", "type" ], - "title": "OpenAIResponseObjectStreamResponseCreated" + "title": "OpenAIResponseObjectStreamResponseCreated", + "description": "Streaming event indicating a new response has been created." }, "OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta": { "type": "object", "properties": { "delta": { - "type": "string" + "type": "string", + "description": "Incremental function call arguments being added" }, "item_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the function call being updated" }, "output_index": { - "type": "integer" + "type": "integer", + "description": "Index position of the item in the output list" }, "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.function_call_arguments.delta", - "default": "response.function_call_arguments.delta" + "default": "response.function_call_arguments.delta", + "description": "Event type identifier, always \"response.function_call_arguments.delta\"" } }, "additionalProperties": false, @@ -8674,27 +8868,33 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta" + "title": "OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta", + "description": "Streaming event for incremental function call argument updates." }, "OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone": { "type": "object", "properties": { "arguments": { - "type": "string" + "type": "string", + "description": "Final complete arguments JSON string for the function call" }, "item_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the completed function call" }, "output_index": { - "type": "integer" + "type": "integer", + "description": "Index position of the item in the output list" }, "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.function_call_arguments.done", - "default": "response.function_call_arguments.done" + "default": "response.function_call_arguments.done", + "description": "Event type identifier, always \"response.function_call_arguments.done\"" } }, "additionalProperties": false, @@ -8705,7 +8905,8 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone" + "title": "OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone", + "description": "Streaming event for when function call arguments are completed." }, "OpenAIResponseObjectStreamResponseMcpCallArgumentsDelta": { "type": "object", @@ -8773,12 +8974,14 @@ "type": "object", "properties": { "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.mcp_call.completed", - "default": "response.mcp_call.completed" + "default": "response.mcp_call.completed", + "description": "Event type identifier, always \"response.mcp_call.completed\"" } }, "additionalProperties": false, @@ -8786,18 +8989,21 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseMcpCallCompleted" + "title": "OpenAIResponseObjectStreamResponseMcpCallCompleted", + "description": "Streaming event for completed MCP calls." }, "OpenAIResponseObjectStreamResponseMcpCallFailed": { "type": "object", "properties": { "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.mcp_call.failed", - "default": "response.mcp_call.failed" + "default": "response.mcp_call.failed", + "description": "Event type identifier, always \"response.mcp_call.failed\"" } }, "additionalProperties": false, @@ -8805,24 +9011,29 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseMcpCallFailed" + "title": "OpenAIResponseObjectStreamResponseMcpCallFailed", + "description": "Streaming event for failed MCP calls." }, "OpenAIResponseObjectStreamResponseMcpCallInProgress": { "type": "object", "properties": { "item_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the MCP call" }, "output_index": { - "type": "integer" + "type": "integer", + "description": "Index position of the item in the output list" }, "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.mcp_call.in_progress", - "default": "response.mcp_call.in_progress" + "default": "response.mcp_call.in_progress", + "description": "Event type identifier, always \"response.mcp_call.in_progress\"" } }, "additionalProperties": false, @@ -8832,7 +9043,8 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseMcpCallInProgress" + "title": "OpenAIResponseObjectStreamResponseMcpCallInProgress", + "description": "Streaming event for MCP calls in progress." }, "OpenAIResponseObjectStreamResponseMcpListToolsCompleted": { "type": "object", @@ -8895,21 +9107,26 @@ "type": "object", "properties": { "response_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the response containing this output" }, "item": { - "$ref": "#/components/schemas/OpenAIResponseOutput" + "$ref": "#/components/schemas/OpenAIResponseOutput", + "description": "The output item that was added (message, tool call, etc.)" }, "output_index": { - "type": "integer" + "type": "integer", + "description": "Index position of this item in the output list" }, "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.output_item.added", - "default": "response.output_item.added" + "default": "response.output_item.added", + "description": "Event type identifier, always \"response.output_item.added\"" } }, "additionalProperties": false, @@ -8920,27 +9137,33 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseOutputItemAdded" + "title": "OpenAIResponseObjectStreamResponseOutputItemAdded", + "description": "Streaming event for when a new output item is added to the response." }, "OpenAIResponseObjectStreamResponseOutputItemDone": { "type": "object", "properties": { "response_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the response containing this output" }, "item": { - "$ref": "#/components/schemas/OpenAIResponseOutput" + "$ref": "#/components/schemas/OpenAIResponseOutput", + "description": "The completed output item (message, tool call, etc.)" }, "output_index": { - "type": "integer" + "type": "integer", + "description": "Index position of this item in the output list" }, "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.output_item.done", - "default": "response.output_item.done" + "default": "response.output_item.done", + "description": "Event type identifier, always \"response.output_item.done\"" } }, "additionalProperties": false, @@ -8951,30 +9174,37 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseOutputItemDone" + "title": "OpenAIResponseObjectStreamResponseOutputItemDone", + "description": "Streaming event for when an output item is completed." }, "OpenAIResponseObjectStreamResponseOutputTextDelta": { "type": "object", "properties": { "content_index": { - "type": "integer" + "type": "integer", + "description": "Index position within the text content" }, "delta": { - "type": "string" + "type": "string", + "description": "Incremental text content being added" }, "item_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the output item being updated" }, "output_index": { - "type": "integer" + "type": "integer", + "description": "Index position of the item in the output list" }, "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.output_text.delta", - "default": "response.output_text.delta" + "default": "response.output_text.delta", + "description": "Event type identifier, always \"response.output_text.delta\"" } }, "additionalProperties": false, @@ -8986,30 +9216,37 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseOutputTextDelta" + "title": "OpenAIResponseObjectStreamResponseOutputTextDelta", + "description": "Streaming event for incremental text content updates." }, "OpenAIResponseObjectStreamResponseOutputTextDone": { "type": "object", "properties": { "content_index": { - "type": "integer" + "type": "integer", + "description": "Index position within the text content" }, "text": { - "type": "string" + "type": "string", + "description": "Final complete text content of the output item" }, "item_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the completed output item" }, "output_index": { - "type": "integer" + "type": "integer", + "description": "Index position of the item in the output list" }, "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.output_text.done", - "default": "response.output_text.done" + "default": "response.output_text.done", + "description": "Event type identifier, always \"response.output_text.done\"" } }, "additionalProperties": false, @@ -9021,24 +9258,29 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseOutputTextDone" + "title": "OpenAIResponseObjectStreamResponseOutputTextDone", + "description": "Streaming event for when text output is completed." }, "OpenAIResponseObjectStreamResponseWebSearchCallCompleted": { "type": "object", "properties": { "item_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the completed web search call" }, "output_index": { - "type": "integer" + "type": "integer", + "description": "Index position of the item in the output list" }, "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.web_search_call.completed", - "default": "response.web_search_call.completed" + "default": "response.web_search_call.completed", + "description": "Event type identifier, always \"response.web_search_call.completed\"" } }, "additionalProperties": false, @@ -9048,24 +9290,29 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseWebSearchCallCompleted" + "title": "OpenAIResponseObjectStreamResponseWebSearchCallCompleted", + "description": "Streaming event for completed web search calls." }, "OpenAIResponseObjectStreamResponseWebSearchCallInProgress": { "type": "object", "properties": { "item_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the web search call" }, "output_index": { - "type": "integer" + "type": "integer", + "description": "Index position of the item in the output list" }, "sequence_number": { - "type": "integer" + "type": "integer", + "description": "Sequential number for ordering streaming events" }, "type": { "type": "string", "const": "response.web_search_call.in_progress", - "default": "response.web_search_call.in_progress" + "default": "response.web_search_call.in_progress", + "description": "Event type identifier, always \"response.web_search_call.in_progress\"" } }, "additionalProperties": false, @@ -9075,7 +9322,8 @@ "sequence_number", "type" ], - "title": "OpenAIResponseObjectStreamResponseWebSearchCallInProgress" + "title": "OpenAIResponseObjectStreamResponseWebSearchCallInProgress", + "description": "Streaming event for web search calls in progress." }, "OpenAIResponseObjectStreamResponseWebSearchCallSearching": { "type": "object", @@ -9108,16 +9356,19 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the deleted response" }, "object": { "type": "string", "const": "response", - "default": "response" + "default": "response", + "description": "Object type identifier, always \"response\"" }, "deleted": { "type": "boolean", - "default": true + "default": true, + "description": "Deletion confirmation flag, always True" } }, "additionalProperties": false, @@ -9126,7 +9377,8 @@ "object", "deleted" ], - "title": "OpenAIDeleteResponseObject" + "title": "OpenAIDeleteResponseObject", + "description": "Response object confirming deletion of an OpenAI response." }, "EmbeddingsRequest": { "type": "object", @@ -9232,7 +9484,8 @@ "categorical_count", "accuracy" ], - "title": "AggregationFunctionType" + "title": "AggregationFunctionType", + "description": "Types of aggregation functions for scoring results." }, "BasicScoringFnParams": { "type": "object", @@ -9240,13 +9493,15 @@ "type": { "$ref": "#/components/schemas/ScoringFnParamsType", "const": "basic", - "default": "basic" + "default": "basic", + "description": "The type of scoring function parameters, always basic" }, "aggregation_functions": { "type": "array", "items": { "$ref": "#/components/schemas/AggregationFunctionType" - } + }, + "description": "Aggregation functions to apply to the scores of each row" } }, "additionalProperties": false, @@ -9254,7 +9509,8 @@ "type", "aggregation_functions" ], - "title": "BasicScoringFnParams" + "title": "BasicScoringFnParams", + "description": "Parameters for basic scoring function configuration." }, "BenchmarkConfig": { "type": "object", @@ -9306,25 +9562,30 @@ "type": { "$ref": "#/components/schemas/ScoringFnParamsType", "const": "llm_as_judge", - "default": "llm_as_judge" + "default": "llm_as_judge", + "description": "The type of scoring function parameters, always llm_as_judge" }, "judge_model": { - "type": "string" + "type": "string", + "description": "Identifier of the LLM model to use as a judge for scoring" }, "prompt_template": { - "type": "string" + "type": "string", + "description": "(Optional) Custom prompt template for the judge model" }, "judge_score_regexes": { "type": "array", "items": { "type": "string" - } + }, + "description": "Regexes to extract the answer from generated response" }, "aggregation_functions": { "type": "array", "items": { "$ref": "#/components/schemas/AggregationFunctionType" - } + }, + "description": "Aggregation functions to apply to the scores of each row" } }, "additionalProperties": false, @@ -9334,7 +9595,8 @@ "judge_score_regexes", "aggregation_functions" ], - "title": "LLMAsJudgeScoringFnParams" + "title": "LLMAsJudgeScoringFnParams", + "description": "Parameters for LLM-as-judge scoring function configuration." }, "ModelCandidate": { "type": "object", @@ -9372,19 +9634,22 @@ "type": { "$ref": "#/components/schemas/ScoringFnParamsType", "const": "regex_parser", - "default": "regex_parser" + "default": "regex_parser", + "description": "The type of scoring function parameters, always regex_parser" }, "parsing_regexes": { "type": "array", "items": { "type": "string" - } + }, + "description": "Regex to extract the answer from generated response" }, "aggregation_functions": { "type": "array", "items": { "$ref": "#/components/schemas/AggregationFunctionType" - } + }, + "description": "Aggregation functions to apply to the scores of each row" } }, "additionalProperties": false, @@ -9393,7 +9658,8 @@ "parsing_regexes", "aggregation_functions" ], - "title": "RegexParserScoringFnParams" + "title": "RegexParserScoringFnParams", + "description": "Parameters for regex parser scoring function configuration." }, "ScoringFnParams": { "oneOf": [ @@ -9423,7 +9689,8 @@ "regex_parser", "basic" ], - "title": "ScoringFnParamsType" + "title": "ScoringFnParamsType", + "description": "Types of scoring function parameter configurations." }, "EvaluateRowsRequest": { "type": "object", @@ -9596,14 +9863,17 @@ "type": "object", "properties": { "agent_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the agent" }, "agent_config": { - "$ref": "#/components/schemas/AgentConfig" + "$ref": "#/components/schemas/AgentConfig", + "description": "Configuration settings for the agent" }, "created_at": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the agent was created" } }, "additionalProperties": false, @@ -9612,26 +9882,31 @@ "agent_config", "created_at" ], - "title": "Agent" + "title": "Agent", + "description": "An agent instance with configuration and metadata." }, "Session": { "type": "object", "properties": { "session_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the conversation session" }, "session_name": { - "type": "string" + "type": "string", + "description": "Human-readable name for the session" }, "turns": { "type": "array", "items": { "$ref": "#/components/schemas/Turn" - } + }, + "description": "List of all turns that have occurred in this session" }, "started_at": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the session was created" } }, "additionalProperties": false, @@ -9670,14 +9945,16 @@ "shield_call": "#/components/schemas/ShieldCallStep", "memory_retrieval": "#/components/schemas/MemoryRetrievalStep" } - } + }, + "description": "The complete step data and execution details" } }, "additionalProperties": false, "required": [ "step" ], - "title": "AgentStepResponse" + "title": "AgentStepResponse", + "description": "Response containing details of a specific agent step." }, "Benchmark": { "type": "object", @@ -9703,18 +9980,20 @@ "tool", "tool_group" ], - "title": "ResourceType", "const": "benchmark", - "default": "benchmark" + "default": "benchmark", + "description": "The resource type, always benchmark" }, "dataset_id": { - "type": "string" + "type": "string", + "description": "Identifier of the dataset to use for the benchmark evaluation" }, "scoring_functions": { "type": "array", "items": { "type": "string" - } + }, + "description": "List of scoring function identifiers to apply during evaluation" }, "metadata": { "type": "object", @@ -9739,7 +10018,8 @@ "type": "object" } ] - } + }, + "description": "Metadata for this evaluation task" } }, "additionalProperties": false, @@ -9751,7 +10031,8 @@ "scoring_functions", "metadata" ], - "title": "Benchmark" + "title": "Benchmark", + "description": "A benchmark resource for evaluating model performance." }, "OpenAIAssistantMessageParam": { "type": "object", @@ -9801,10 +10082,12 @@ "type": { "type": "string", "const": "image_url", - "default": "image_url" + "default": "image_url", + "description": "Must be \"image_url\" to identify this as image content" }, "image_url": { - "$ref": "#/components/schemas/OpenAIImageURL" + "$ref": "#/components/schemas/OpenAIImageURL", + "description": "Image URL specification and processing details" } }, "additionalProperties": false, @@ -9812,7 +10095,8 @@ "type", "image_url" ], - "title": "OpenAIChatCompletionContentPartImageParam" + "title": "OpenAIChatCompletionContentPartImageParam", + "description": "Image content part for OpenAI-compatible chat completion messages." }, "OpenAIChatCompletionContentPartParam": { "oneOf": [ @@ -9841,10 +10125,12 @@ "type": { "type": "string", "const": "text", - "default": "text" + "default": "text", + "description": "Must be \"text\" to identify this as text content" }, "text": { - "type": "string" + "type": "string", + "description": "The text content of the message" } }, "additionalProperties": false, @@ -9852,44 +10138,53 @@ "type", "text" ], - "title": "OpenAIChatCompletionContentPartTextParam" + "title": "OpenAIChatCompletionContentPartTextParam", + "description": "Text content part for OpenAI-compatible chat completion messages." }, "OpenAIChatCompletionToolCall": { "type": "object", "properties": { "index": { - "type": "integer" + "type": "integer", + "description": "(Optional) Index of the tool call in the list" }, "id": { - "type": "string" + "type": "string", + "description": "(Optional) Unique identifier for the tool call" }, "type": { "type": "string", "const": "function", - "default": "function" + "default": "function", + "description": "Must be \"function\" to identify this as a function call" }, "function": { - "$ref": "#/components/schemas/OpenAIChatCompletionToolCallFunction" + "$ref": "#/components/schemas/OpenAIChatCompletionToolCallFunction", + "description": "(Optional) Function call details" } }, "additionalProperties": false, "required": [ "type" ], - "title": "OpenAIChatCompletionToolCall" + "title": "OpenAIChatCompletionToolCall", + "description": "Tool call specification for OpenAI-compatible chat completion responses." }, "OpenAIChatCompletionToolCallFunction": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "(Optional) Name of the function to call" }, "arguments": { - "type": "string" + "type": "string", + "description": "(Optional) Arguments to pass to the function as a JSON string" } }, "additionalProperties": false, - "title": "OpenAIChatCompletionToolCallFunction" + "title": "OpenAIChatCompletionToolCallFunction", + "description": "Function call details for OpenAI-compatible tool calls." }, "OpenAIChoice": { "type": "object", @@ -10017,17 +10312,20 @@ "type": "object", "properties": { "url": { - "type": "string" + "type": "string", + "description": "URL of the image to include in the message" }, "detail": { - "type": "string" + "type": "string", + "description": "(Optional) Level of detail for image processing. Can be \"low\", \"high\", or \"auto\"" } }, "additionalProperties": false, "required": [ "url" ], - "title": "OpenAIImageURL" + "title": "OpenAIImageURL", + "description": "Image URL specification for OpenAI-compatible chat completion messages." }, "OpenAIMessageParam": { "oneOf": [ @@ -10309,9 +10607,9 @@ "tool", "tool_group" ], - "title": "ResourceType", "const": "dataset", - "default": "dataset" + "default": "dataset", + "description": "Type of resource, always 'dataset' for datasets" }, "purpose": { "type": "string", @@ -10320,11 +10618,11 @@ "eval/question-answer", "eval/messages-answer" ], - "title": "DatasetPurpose", - "description": "Purpose of the dataset. Each purpose has a required input data schema." + "description": "Purpose of the dataset indicating its intended use" }, "source": { - "$ref": "#/components/schemas/DataSource" + "$ref": "#/components/schemas/DataSource", + "description": "Data source configuration for the dataset" }, "metadata": { "type": "object", @@ -10349,7 +10647,8 @@ "type": "object" } ] - } + }, + "description": "Additional metadata for the dataset" } }, "additionalProperties": false, @@ -10361,7 +10660,8 @@ "source", "metadata" ], - "title": "Dataset" + "title": "Dataset", + "description": "Dataset resource for storing and accessing training or evaluation data." }, "RowsDataSource": { "type": "object", @@ -10434,13 +10734,16 @@ "type": "object", "properties": { "identifier": { - "type": "string" + "type": "string", + "description": "Unique identifier for this resource in llama stack" }, "provider_resource_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for this resource in the provider" }, "provider_id": { - "type": "string" + "type": "string", + "description": "ID of the provider that owns this resource" }, "type": { "type": "string", @@ -10454,9 +10757,9 @@ "tool", "tool_group" ], - "title": "ResourceType", "const": "model", - "default": "model" + "default": "model", + "description": "The resource type, always 'model' for model resources" }, "metadata": { "type": "object", @@ -10481,11 +10784,13 @@ "type": "object" } ] - } + }, + "description": "Any additional metadata for this model" }, "model_type": { "$ref": "#/components/schemas/ModelType", - "default": "llm" + "default": "llm", + "description": "The type of model (LLM or embedding model)" } }, "additionalProperties": false, @@ -10496,7 +10801,8 @@ "metadata", "model_type" ], - "title": "Model" + "title": "Model", + "description": "A model resource representing an AI model registered in Llama Stack." }, "ModelType": { "type": "string", @@ -10504,7 +10810,8 @@ "llm", "embedding" ], - "title": "ModelType" + "title": "ModelType", + "description": "Enumeration of supported model types in Llama Stack." }, "AgentTurnInputType": { "type": "object", @@ -10512,14 +10819,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", @@ -10527,14 +10836,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", @@ -10542,14 +10853,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", @@ -10557,14 +10870,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", @@ -10572,14 +10887,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", @@ -10587,14 +10904,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", @@ -10602,14 +10921,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", @@ -10617,14 +10938,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": [ @@ -10699,9 +11022,9 @@ "tool", "tool_group" ], - "title": "ResourceType", "const": "scoring_function", - "default": "scoring_function" + "default": "scoring_function", + "description": "The resource type, always scoring_function" }, "description": { "type": "string" @@ -10746,7 +11069,8 @@ "metadata", "return_type" ], - "title": "ScoringFn" + "title": "ScoringFn", + "description": "A scoring function resource for evaluating model outputs." }, "StringType": { "type": "object", @@ -10754,14 +11078,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", @@ -10769,14 +11095,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", @@ -10802,9 +11130,9 @@ "tool", "tool_group" ], - "title": "ResourceType", "const": "shield", - "default": "shield" + "default": "shield", + "description": "The resource type, always shield" }, "params": { "type": "object", @@ -10829,7 +11157,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) Configuration parameters for the shield" } }, "additionalProperties": false, @@ -10839,30 +11168,36 @@ "type" ], "title": "Shield", - "description": "A safety shield resource that can be used to check content" + "description": "A safety shield resource that can be used to check content." }, "Span": { "type": "object", "properties": { "span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the span" }, "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace this span belongs to" }, "parent_span_id": { - "type": "string" + "type": "string", + "description": "(Optional) Unique identifier for the parent span, if this is a child span" }, "name": { - "type": "string" + "type": "string", + "description": "Human-readable name describing the operation this span represents" }, "start_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the operation began" }, "end_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "(Optional) Timestamp when the operation finished, if completed" }, "attributes": { "type": "object", @@ -10887,7 +11222,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) Key-value pairs containing additional metadata about the span" } }, "additionalProperties": false, @@ -10897,7 +11233,8 @@ "name", "start_time" ], - "title": "Span" + "title": "Span", + "description": "A span representing a single operation within a trace." }, "GetSpanTreeRequest": { "type": "object", @@ -10923,30 +11260,37 @@ "ok", "error" ], - "title": "SpanStatus" + "title": "SpanStatus", + "description": "The status of a span indicating whether it completed successfully or with an error." }, "SpanWithStatus": { "type": "object", "properties": { "span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the span" }, "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace this span belongs to" }, "parent_span_id": { - "type": "string" + "type": "string", + "description": "(Optional) Unique identifier for the parent span, if this is a child span" }, "name": { - "type": "string" + "type": "string", + "description": "Human-readable name describing the operation this span represents" }, "start_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the operation began" }, "end_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "(Optional) Timestamp when the operation finished, if completed" }, "attributes": { "type": "object", @@ -10971,10 +11315,12 @@ "type": "object" } ] - } + }, + "description": "(Optional) Key-value pairs containing additional metadata about the span" }, "status": { - "$ref": "#/components/schemas/SpanStatus" + "$ref": "#/components/schemas/SpanStatus", + "description": "(Optional) The current status of the span" } }, "additionalProperties": false, @@ -10984,7 +11330,8 @@ "name", "start_time" ], - "title": "SpanWithStatus" + "title": "SpanWithStatus", + "description": "A span that includes status information." }, "QuerySpanTreeResponse": { "type": "object", @@ -10993,14 +11340,16 @@ "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SpanWithStatus" - } + }, + "description": "Dictionary mapping span IDs to spans with status information" } }, "additionalProperties": false, "required": [ "data" ], - "title": "QuerySpanTreeResponse" + "title": "QuerySpanTreeResponse", + "description": "Response containing a tree structure of spans." }, "Tool": { "type": "object", @@ -11026,21 +11375,24 @@ "tool", "tool_group" ], - "title": "ResourceType", "const": "tool", - "default": "tool" + "default": "tool", + "description": "Type of resource, always 'tool'" }, "toolgroup_id": { - "type": "string" + "type": "string", + "description": "ID of the tool group this tool belongs to" }, "description": { - "type": "string" + "type": "string", + "description": "Human-readable description of what the tool does" }, "parameters": { "type": "array", "items": { "$ref": "#/components/schemas/ToolParameter" - } + }, + "description": "List of parameters this tool accepts" }, "metadata": { "type": "object", @@ -11065,7 +11417,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) Additional metadata about the tool" } }, "additionalProperties": false, @@ -11077,7 +11430,8 @@ "description", "parameters" ], - "title": "Tool" + "title": "Tool", + "description": "A tool that can be invoked by agents." }, "ToolGroup": { "type": "object", @@ -11103,12 +11457,13 @@ "tool", "tool_group" ], - "title": "ResourceType", "const": "tool_group", - "default": "tool_group" + "default": "tool_group", + "description": "Type of resource, always 'tool_group'" }, "mcp_endpoint": { - "$ref": "#/components/schemas/URL" + "$ref": "#/components/schemas/URL", + "description": "(Optional) Model Context Protocol endpoint for remote tools" }, "args": { "type": "object", @@ -11133,7 +11488,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) Additional arguments for the tool group" } }, "additionalProperties": false, @@ -11142,24 +11498,29 @@ "provider_id", "type" ], - "title": "ToolGroup" + "title": "ToolGroup", + "description": "A group of related tools managed together." }, "Trace": { "type": "object", "properties": { "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace" }, "root_span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the root span that started this trace" }, "start_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the trace began" }, "end_time": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "(Optional) Timestamp when the trace finished, if completed" } }, "additionalProperties": false, @@ -11168,29 +11529,36 @@ "root_span_id", "start_time" ], - "title": "Trace" + "title": "Trace", + "description": "A trace representing the complete execution path of a request across multiple operations." }, "Checkpoint": { "type": "object", "properties": { "identifier": { - "type": "string" + "type": "string", + "description": "Unique identifier for the checkpoint" }, "created_at": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the checkpoint was created" }, "epoch": { - "type": "integer" + "type": "integer", + "description": "Training epoch when the checkpoint was saved" }, "post_training_job_id": { - "type": "string" + "type": "string", + "description": "Identifier of the training job that created this checkpoint" }, "path": { - "type": "string" + "type": "string", + "description": "File system path where the checkpoint is stored" }, "training_metrics": { - "$ref": "#/components/schemas/PostTrainingMetric" + "$ref": "#/components/schemas/PostTrainingMetric", + "description": "(Optional) Training metrics associated with this checkpoint" } }, "additionalProperties": false, @@ -11202,19 +11570,21 @@ "path" ], "title": "Checkpoint", - "description": "Checkpoint created during training runs" + "description": "Checkpoint created during training runs." }, "PostTrainingJobArtifactsResponse": { "type": "object", "properties": { "job_uuid": { - "type": "string" + "type": "string", + "description": "Unique identifier for the training job" }, "checkpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Checkpoint" - } + }, + "description": "List of model checkpoints created during training" } }, "additionalProperties": false, @@ -11229,16 +11599,20 @@ "type": "object", "properties": { "epoch": { - "type": "integer" + "type": "integer", + "description": "Training epoch number" }, "train_loss": { - "type": "number" + "type": "number", + "description": "Loss value on the training dataset" }, "validation_loss": { - "type": "number" + "type": "number", + "description": "Loss value on the validation dataset" }, "perplexity": { - "type": "number" + "type": "number", + "description": "Perplexity metric indicating model confidence" } }, "additionalProperties": false, @@ -11248,13 +11622,15 @@ "validation_loss", "perplexity" ], - "title": "PostTrainingMetric" + "title": "PostTrainingMetric", + "description": "Training metrics captured during post-training jobs." }, "PostTrainingJobStatusResponse": { "type": "object", "properties": { "job_uuid": { - "type": "string" + "type": "string", + "description": "Unique identifier for the training job" }, "status": { "type": "string", @@ -11265,19 +11641,22 @@ "scheduled", "cancelled" ], - "title": "JobStatus" + "description": "Current status of the training job" }, "scheduled_at": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "(Optional) Timestamp when the job was scheduled" }, "started_at": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "(Optional) Timestamp when the job execution began" }, "completed_at": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "(Optional) Timestamp when the job finished, if completed" }, "resources_allocated": { "type": "object", @@ -11302,13 +11681,15 @@ "type": "object" } ] - } + }, + "description": "(Optional) Information about computational resources allocated to the job" }, "checkpoints": { "type": "array", "items": { "$ref": "#/components/schemas/Checkpoint" - } + }, + "description": "List of model checkpoints created during training" } }, "additionalProperties": false, @@ -11370,15 +11751,17 @@ "tool", "tool_group" ], - "title": "ResourceType", "const": "vector_db", - "default": "vector_db" + "default": "vector_db", + "description": "Type of resource, always 'vector_db' for vector databases" }, "embedding_model": { - "type": "string" + "type": "string", + "description": "Name of the embedding model to use for vector generation" }, "embedding_dimension": { - "type": "integer" + "type": "integer", + "description": "Dimension of the embedding vectors" }, "vector_db_name": { "type": "string" @@ -11392,7 +11775,8 @@ "embedding_model", "embedding_dimension" ], - "title": "VectorDB" + "title": "VectorDB", + "description": "Vector database resource for storing and querying vector embeddings." }, "HealthInfo": { "type": "object", @@ -11404,14 +11788,15 @@ "Error", "Not Implemented" ], - "title": "HealthStatus" + "description": "Current health status of the service" } }, "additionalProperties": false, "required": [ "status" ], - "title": "HealthInfo" + "title": "HealthInfo", + "description": "Health status information for the service." }, "RAGDocument": { "type": "object", @@ -11487,13 +11872,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/RAGDocument" - } + }, + "description": "List of documents to index in the RAG system" }, "vector_db_id": { - "type": "string" + "type": "string", + "description": "ID of the vector database to store the document embeddings" }, "chunk_size_in_tokens": { - "type": "integer" + "type": "integer", + "description": "(Optional) Size in tokens for document chunking during indexing" } }, "additionalProperties": false, @@ -11643,13 +12031,16 @@ "type": "object", "properties": { "api": { - "type": "string" + "type": "string", + "description": "The API name this provider implements" }, "provider_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the provider" }, "provider_type": { - "type": "string" + "type": "string", + "description": "The type of provider implementation" }, "config": { "type": "object", @@ -11674,7 +12065,8 @@ "type": "object" } ] - } + }, + "description": "Configuration parameters for the provider" }, "health": { "type": "object", @@ -11699,7 +12091,8 @@ "type": "object" } ] - } + }, + "description": "Current health status of the provider" } }, "additionalProperties": false, @@ -11710,7 +12103,8 @@ "config", "health" ], - "title": "ProviderInfo" + "title": "ProviderInfo", + "description": "Information about a registered provider including its configuration and health status." }, "InvokeToolRequest": { "type": "object", @@ -11757,13 +12151,16 @@ "type": "object", "properties": { "content": { - "$ref": "#/components/schemas/InterleavedContent" + "$ref": "#/components/schemas/InterleavedContent", + "description": "(Optional) The output content from the tool execution" }, "error_message": { - "type": "string" + "type": "string", + "description": "(Optional) Error message if the tool execution failed" }, "error_code": { - "type": "integer" + "type": "integer", + "description": "(Optional) Numeric error code if the tool execution failed" }, "metadata": { "type": "object", @@ -11788,11 +12185,13 @@ "type": "object" } ] - } + }, + "description": "(Optional) Additional metadata about the tool execution" } }, "additionalProperties": false, - "title": "ToolInvocationResult" + "title": "ToolInvocationResult", + "description": "Result of a tool invocation." }, "PaginatedResponse": { "type": "object", @@ -11847,7 +12246,8 @@ "type": "object", "properties": { "job_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the job" }, "status": { "type": "string", @@ -11858,7 +12258,7 @@ "scheduled", "cancelled" ], - "title": "JobStatus" + "description": "Current execution status of the job" } }, "additionalProperties": false, @@ -11866,7 +12266,8 @@ "job_id", "status" ], - "title": "Job" + "title": "Job", + "description": "A job execution instance with status tracking." }, "ListBenchmarksResponse": { "type": "object", @@ -11890,7 +12291,8 @@ "asc", "desc" ], - "title": "Order" + "title": "Order", + "description": "Sort order for paginated responses." }, "ListOpenAIChatCompletionResponse": { "type": "object", @@ -11942,21 +12344,26 @@ "input_messages" ], "title": "OpenAICompletionWithInputMessages" - } + }, + "description": "List of chat completion objects with their input messages" }, "has_more": { - "type": "boolean" + "type": "boolean", + "description": "Whether there are more completions available beyond this list" }, "first_id": { - "type": "string" + "type": "string", + "description": "ID of the first completion in this list" }, "last_id": { - "type": "string" + "type": "string", + "description": "ID of the last completion in this list" }, "object": { "type": "string", "const": "list", - "default": "list" + "default": "list", + "description": "Must be \"list\" to identify this as a list response" } }, "additionalProperties": false, @@ -11967,7 +12374,8 @@ "last_id", "object" ], - "title": "ListOpenAIChatCompletionResponse" + "title": "ListOpenAIChatCompletionResponse", + "description": "Response from listing OpenAI-compatible chat completions." }, "ListDatasetsResponse": { "type": "object", @@ -11976,14 +12384,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/Dataset" - } + }, + "description": "List of datasets" } }, "additionalProperties": false, "required": [ "data" ], - "title": "ListDatasetsResponse" + "title": "ListDatasetsResponse", + "description": "Response from listing datasets." }, "ListModelsResponse": { "type": "object", @@ -12008,12 +12418,14 @@ "type": "array", "items": { "$ref": "#/components/schemas/OpenAIResponseInput" - } + }, + "description": "List of input items" }, "object": { "type": "string", "const": "list", - "default": "list" + "default": "list", + "description": "Object type identifier, always \"list\"" } }, "additionalProperties": false, @@ -12021,7 +12433,8 @@ "data", "object" ], - "title": "ListOpenAIResponseInputItem" + "title": "ListOpenAIResponseInputItem", + "description": "List container for OpenAI response input items." }, "ListOpenAIResponseObject": { "type": "object", @@ -12030,21 +12443,26 @@ "type": "array", "items": { "$ref": "#/components/schemas/OpenAIResponseObjectWithInput" - } + }, + "description": "List of response objects with their input context" }, "has_more": { - "type": "boolean" + "type": "boolean", + "description": "Whether there are more results available beyond this page" }, "first_id": { - "type": "string" + "type": "string", + "description": "Identifier of the first item in this page" }, "last_id": { - "type": "string" + "type": "string", + "description": "Identifier of the last item in this page" }, "object": { "type": "string", "const": "list", - "default": "list" + "default": "list", + "description": "Object type identifier, always \"list\"" } }, "additionalProperties": false, @@ -12055,64 +12473,80 @@ "last_id", "object" ], - "title": "ListOpenAIResponseObject" + "title": "ListOpenAIResponseObject", + "description": "Paginated list of OpenAI response objects with navigation metadata." }, "OpenAIResponseObjectWithInput": { "type": "object", "properties": { "created_at": { - "type": "integer" + "type": "integer", + "description": "Unix timestamp when the response was created" }, "error": { - "$ref": "#/components/schemas/OpenAIResponseError" + "$ref": "#/components/schemas/OpenAIResponseError", + "description": "(Optional) Error details if the response generation failed" }, "id": { - "type": "string" + "type": "string", + "description": "Unique identifier for this response" }, "model": { - "type": "string" + "type": "string", + "description": "Model identifier used for generation" }, "object": { "type": "string", "const": "response", - "default": "response" + "default": "response", + "description": "Object type identifier, always \"response\"" }, "output": { "type": "array", "items": { "$ref": "#/components/schemas/OpenAIResponseOutput" - } + }, + "description": "List of generated output items (messages, tool calls, etc.)" }, "parallel_tool_calls": { "type": "boolean", - "default": false + "default": false, + "description": "Whether tool calls can be executed in parallel" }, "previous_response_id": { - "type": "string" + "type": "string", + "description": "(Optional) ID of the previous response in a conversation" }, "status": { - "type": "string" + "type": "string", + "description": "Current status of the response generation" }, "temperature": { - "type": "number" + "type": "number", + "description": "(Optional) Sampling temperature used for generation" }, "text": { - "$ref": "#/components/schemas/OpenAIResponseText" + "$ref": "#/components/schemas/OpenAIResponseText", + "description": "Text formatting configuration for the response" }, "top_p": { - "type": "number" + "type": "number", + "description": "(Optional) Nucleus sampling parameter used for generation" }, "truncation": { - "type": "string" + "type": "string", + "description": "(Optional) Truncation strategy applied to the response" }, "user": { - "type": "string" + "type": "string", + "description": "(Optional) User identifier associated with the request" }, "input": { "type": "array", "items": { "$ref": "#/components/schemas/OpenAIResponseInput" - } + }, + "description": "List of input items that led to this response" } }, "additionalProperties": false, @@ -12127,7 +12561,8 @@ "text", "input" ], - "title": "OpenAIResponseObjectWithInput" + "title": "OpenAIResponseObjectWithInput", + "description": "OpenAI response object extended with input context information." }, "ListProvidersResponse": { "type": "object", @@ -12136,29 +12571,34 @@ "type": "array", "items": { "$ref": "#/components/schemas/ProviderInfo" - } + }, + "description": "List of provider information objects" } }, "additionalProperties": false, "required": [ "data" ], - "title": "ListProvidersResponse" + "title": "ListProvidersResponse", + "description": "Response containing a list of all available providers." }, "RouteInfo": { "type": "object", "properties": { "route": { - "type": "string" + "type": "string", + "description": "The API endpoint path" }, "method": { - "type": "string" + "type": "string", + "description": "HTTP method for the route" }, "provider_types": { "type": "array", "items": { "type": "string" - } + }, + "description": "List of provider types that implement this route" } }, "additionalProperties": false, @@ -12167,7 +12607,8 @@ "method", "provider_types" ], - "title": "RouteInfo" + "title": "RouteInfo", + "description": "Information about an API route including its path, method, and implementing providers." }, "ListRoutesResponse": { "type": "object", @@ -12176,14 +12617,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/RouteInfo" - } + }, + "description": "List of available route information objects" } }, "additionalProperties": false, "required": [ "data" ], - "title": "ListRoutesResponse" + "title": "ListRoutesResponse", + "description": "Response containing a list of all available API routes." }, "ListToolDefsResponse": { "type": "object", @@ -12192,14 +12635,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/ToolDef" - } + }, + "description": "List of tool definitions" } }, "additionalProperties": false, "required": [ "data" ], - "title": "ListToolDefsResponse" + "title": "ListToolDefsResponse", + "description": "Response containing a list of tool definitions." }, "ListScoringFunctionsResponse": { "type": "object", @@ -12240,14 +12685,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/ToolGroup" - } + }, + "description": "List of tool groups" } }, "additionalProperties": false, "required": [ "data" ], - "title": "ListToolGroupsResponse" + "title": "ListToolGroupsResponse", + "description": "Response containing a list of tool groups." }, "ListToolsResponse": { "type": "object", @@ -12256,14 +12703,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/Tool" - } + }, + "description": "List of tools" } }, "additionalProperties": false, "required": [ "data" ], - "title": "ListToolsResponse" + "title": "ListToolsResponse", + "description": "Response containing a list of tools." }, "ListVectorDBsResponse": { "type": "object", @@ -12272,14 +12721,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/VectorDB" - } + }, + "description": "List of vector databases" } }, "additionalProperties": false, "required": [ "data" ], - "title": "ListVectorDBsResponse" + "title": "ListVectorDBsResponse", + "description": "Response from listing vector databases." }, "Event": { "oneOf": [ @@ -12309,7 +12760,8 @@ "structured_log", "metric" ], - "title": "EventType" + "title": "EventType", + "description": "The type of telemetry event being logged." }, "LogSeverity": { "type": "string", @@ -12321,20 +12773,24 @@ "error", "critical" ], - "title": "LogSeverity" + "title": "LogSeverity", + "description": "The severity level of a log message." }, "MetricEvent": { "type": "object", "properties": { "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace this event belongs to" }, "span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the span this event belongs to" }, "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the event occurred" }, "attributes": { "type": "object", @@ -12356,15 +12812,18 @@ "type": "null" } ] - } + }, + "description": "(Optional) Key-value pairs containing additional metadata about the event" }, "type": { "$ref": "#/components/schemas/EventType", "const": "metric", - "default": "metric" + "default": "metric", + "description": "Event type identifier set to METRIC" }, "metric": { - "type": "string" + "type": "string", + "description": "The name of the metric being measured" }, "value": { "oneOf": [ @@ -12374,10 +12833,12 @@ { "type": "number" } - ] + ], + "description": "The numeric value of the metric measurement" }, "unit": { - "type": "string" + "type": "string", + "description": "The unit of measurement for the metric value" } }, "additionalProperties": false, @@ -12390,7 +12851,8 @@ "value", "unit" ], - "title": "MetricEvent" + "title": "MetricEvent", + "description": "A metric event containing a measured value." }, "SpanEndPayload": { "type": "object", @@ -12398,10 +12860,12 @@ "type": { "$ref": "#/components/schemas/StructuredLogType", "const": "span_end", - "default": "span_end" + "default": "span_end", + "description": "Payload type identifier set to SPAN_END" }, "status": { - "$ref": "#/components/schemas/SpanStatus" + "$ref": "#/components/schemas/SpanStatus", + "description": "The final status of the span indicating success or failure" } }, "additionalProperties": false, @@ -12409,7 +12873,8 @@ "type", "status" ], - "title": "SpanEndPayload" + "title": "SpanEndPayload", + "description": "Payload for a span end event." }, "SpanStartPayload": { "type": "object", @@ -12417,13 +12882,16 @@ "type": { "$ref": "#/components/schemas/StructuredLogType", "const": "span_start", - "default": "span_start" + "default": "span_start", + "description": "Payload type identifier set to SPAN_START" }, "name": { - "type": "string" + "type": "string", + "description": "Human-readable name describing the operation this span represents" }, "parent_span_id": { - "type": "string" + "type": "string", + "description": "(Optional) Unique identifier for the parent span, if this is a child span" } }, "additionalProperties": false, @@ -12431,20 +12899,24 @@ "type", "name" ], - "title": "SpanStartPayload" + "title": "SpanStartPayload", + "description": "Payload for a span start event." }, "StructuredLogEvent": { "type": "object", "properties": { "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace this event belongs to" }, "span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the span this event belongs to" }, "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the event occurred" }, "attributes": { "type": "object", @@ -12466,15 +12938,18 @@ "type": "null" } ] - } + }, + "description": "(Optional) Key-value pairs containing additional metadata about the event" }, "type": { "$ref": "#/components/schemas/EventType", "const": "structured_log", - "default": "structured_log" + "default": "structured_log", + "description": "Event type identifier set to STRUCTURED_LOG" }, "payload": { - "$ref": "#/components/schemas/StructuredLogPayload" + "$ref": "#/components/schemas/StructuredLogPayload", + "description": "The structured payload data for the log event" } }, "additionalProperties": false, @@ -12485,7 +12960,8 @@ "type", "payload" ], - "title": "StructuredLogEvent" + "title": "StructuredLogEvent", + "description": "A structured log event containing typed payload data." }, "StructuredLogPayload": { "oneOf": [ @@ -12510,20 +12986,24 @@ "span_start", "span_end" ], - "title": "StructuredLogType" + "title": "StructuredLogType", + "description": "The type of structured log event payload." }, "UnstructuredLogEvent": { "type": "object", "properties": { "trace_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the trace this event belongs to" }, "span_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the span this event belongs to" }, "timestamp": { "type": "string", - "format": "date-time" + "format": "date-time", + "description": "Timestamp when the event occurred" }, "attributes": { "type": "object", @@ -12545,18 +13025,22 @@ "type": "null" } ] - } + }, + "description": "(Optional) Key-value pairs containing additional metadata about the event" }, "type": { "$ref": "#/components/schemas/EventType", "const": "unstructured_log", - "default": "unstructured_log" + "default": "unstructured_log", + "description": "Event type identifier set to UNSTRUCTURED_LOG" }, "message": { - "type": "string" + "type": "string", + "description": "The log message text" }, "severity": { - "$ref": "#/components/schemas/LogSeverity" + "$ref": "#/components/schemas/LogSeverity", + "description": "The severity level of the log message" } }, "additionalProperties": false, @@ -12568,7 +13052,8 @@ "message", "severity" ], - "title": "UnstructuredLogEvent" + "title": "UnstructuredLogEvent", + "description": "An unstructured log event containing a simple text message." }, "LogEventRequest": { "type": "object", @@ -12612,14 +13097,16 @@ "type": { "type": "string", "const": "auto", - "default": "auto" + "default": "auto", + "description": "Strategy type, always \"auto\" for automatic chunking" } }, "additionalProperties": false, "required": [ "type" ], - "title": "VectorStoreChunkingStrategyAuto" + "title": "VectorStoreChunkingStrategyAuto", + "description": "Automatic chunking strategy for vector store files." }, "VectorStoreChunkingStrategyStatic": { "type": "object", @@ -12627,10 +13114,12 @@ "type": { "type": "string", "const": "static", - "default": "static" + "default": "static", + "description": "Strategy type, always \"static\" for static chunking" }, "static": { - "$ref": "#/components/schemas/VectorStoreChunkingStrategyStaticConfig" + "$ref": "#/components/schemas/VectorStoreChunkingStrategyStaticConfig", + "description": "Configuration parameters for the static chunking strategy" } }, "additionalProperties": false, @@ -12638,18 +13127,21 @@ "type", "static" ], - "title": "VectorStoreChunkingStrategyStatic" + "title": "VectorStoreChunkingStrategyStatic", + "description": "Static chunking strategy with configurable parameters." }, "VectorStoreChunkingStrategyStaticConfig": { "type": "object", "properties": { "chunk_overlap_tokens": { "type": "integer", - "default": 400 + "default": 400, + "description": "Number of tokens to overlap between adjacent chunks" }, "max_chunk_size_tokens": { "type": "integer", - "default": 800 + "default": 800, + "description": "Maximum number of tokens per chunk, must be between 100 and 4096" } }, "additionalProperties": false, @@ -12657,7 +13149,8 @@ "chunk_overlap_tokens", "max_chunk_size_tokens" ], - "title": "VectorStoreChunkingStrategyStaticConfig" + "title": "VectorStoreChunkingStrategyStaticConfig", + "description": "Configuration for static chunking strategy." }, "OpenaiAttachFileToVectorStoreRequest": { "type": "object", @@ -12716,10 +13209,12 @@ "type": "string", "const": "rate_limit_exceeded" } - ] + ], + "description": "Error code indicating the type of failure" }, "message": { - "type": "string" + "type": "string", + "description": "Human-readable error message describing the failure" } }, "additionalProperties": false, @@ -12727,17 +13222,20 @@ "code", "message" ], - "title": "VectorStoreFileLastError" + "title": "VectorStoreFileLastError", + "description": "Error information for failed vector store file processing." }, "VectorStoreFileObject": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the file" }, "object": { "type": "string", - "default": "vector_store.file" + "default": "vector_store.file", + "description": "Object type identifier, always \"vector_store.file\"" }, "attributes": { "type": "object", @@ -12762,26 +13260,33 @@ "type": "object" } ] - } + }, + "description": "Key-value attributes associated with the file" }, "chunking_strategy": { - "$ref": "#/components/schemas/VectorStoreChunkingStrategy" + "$ref": "#/components/schemas/VectorStoreChunkingStrategy", + "description": "Strategy used for splitting the file into chunks" }, "created_at": { - "type": "integer" + "type": "integer", + "description": "Timestamp when the file was added to the vector store" }, "last_error": { - "$ref": "#/components/schemas/VectorStoreFileLastError" + "$ref": "#/components/schemas/VectorStoreFileLastError", + "description": "(Optional) Error information if file processing failed" }, "status": { - "$ref": "#/components/schemas/VectorStoreFileStatus" + "$ref": "#/components/schemas/VectorStoreFileStatus", + "description": "Current processing status of the file" }, "usage_bytes": { "type": "integer", - "default": 0 + "default": 0, + "description": "Storage space used by this file in bytes" }, "vector_store_id": { - "type": "string" + "type": "string", + "description": "ID of the vector store containing this file" } }, "additionalProperties": false, @@ -12822,13 +13327,16 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name of the schema" }, "description": { - "type": "string" + "type": "string", + "description": "(Optional) Description of the schema" }, "strict": { - "type": "boolean" + "type": "boolean", + "description": "(Optional) Whether to enforce strict adherence to the schema" }, "schema": { "type": "object", @@ -12853,14 +13361,16 @@ "type": "object" } ] - } + }, + "description": "(Optional) The JSON schema definition" } }, "additionalProperties": false, "required": [ "name" ], - "title": "OpenAIJSONSchema" + "title": "OpenAIJSONSchema", + "description": "JSON schema specification for OpenAI-compatible structured response format." }, "OpenAIResponseFormatJSONObject": { "type": "object", @@ -12868,14 +13378,16 @@ "type": { "type": "string", "const": "json_object", - "default": "json_object" + "default": "json_object", + "description": "Must be \"json_object\" to indicate generic JSON object response format" } }, "additionalProperties": false, "required": [ "type" ], - "title": "OpenAIResponseFormatJSONObject" + "title": "OpenAIResponseFormatJSONObject", + "description": "JSON object response format for OpenAI-compatible chat completion requests." }, "OpenAIResponseFormatJSONSchema": { "type": "object", @@ -12883,10 +13395,12 @@ "type": { "type": "string", "const": "json_schema", - "default": "json_schema" + "default": "json_schema", + "description": "Must be \"json_schema\" to indicate structured JSON response format" }, "json_schema": { - "$ref": "#/components/schemas/OpenAIJSONSchema" + "$ref": "#/components/schemas/OpenAIJSONSchema", + "description": "The JSON schema specification for the response" } }, "additionalProperties": false, @@ -12894,7 +13408,8 @@ "type", "json_schema" ], - "title": "OpenAIResponseFormatJSONSchema" + "title": "OpenAIResponseFormatJSONSchema", + "description": "JSON schema response format for OpenAI-compatible chat completion requests." }, "OpenAIResponseFormatParam": { "oneOf": [ @@ -12923,14 +13438,16 @@ "type": { "type": "string", "const": "text", - "default": "text" + "default": "text", + "description": "Must be \"text\" to indicate plain text response format" } }, "additionalProperties": false, "required": [ "type" ], - "title": "OpenAIResponseFormatText" + "title": "OpenAIResponseFormatText", + "description": "Text response format for OpenAI-compatible chat completion requests." }, "OpenaiChatCompletionRequest": { "type": "object", @@ -13641,19 +14158,24 @@ "type": "object", "properties": { "completed": { - "type": "integer" + "type": "integer", + "description": "Number of files that have been successfully processed" }, "cancelled": { - "type": "integer" + "type": "integer", + "description": "Number of files that had their processing cancelled" }, "failed": { - "type": "integer" + "type": "integer", + "description": "Number of files that failed to process" }, "in_progress": { - "type": "integer" + "type": "integer", + "description": "Number of files currently being processed" }, "total": { - "type": "integer" + "type": "integer", + "description": "Total number of files in the vector store" } }, "additionalProperties": false, @@ -13664,34 +14186,42 @@ "in_progress", "total" ], - "title": "VectorStoreFileCounts" + "title": "VectorStoreFileCounts", + "description": "File processing status counts for a vector store." }, "VectorStoreObject": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the vector store" }, "object": { "type": "string", - "default": "vector_store" + "default": "vector_store", + "description": "Object type identifier, always \"vector_store\"" }, "created_at": { - "type": "integer" + "type": "integer", + "description": "Timestamp when the vector store was created" }, "name": { - "type": "string" + "type": "string", + "description": "(Optional) Name of the vector store" }, "usage_bytes": { "type": "integer", - "default": 0 + "default": 0, + "description": "Storage space used by the vector store in bytes" }, "file_counts": { - "$ref": "#/components/schemas/VectorStoreFileCounts" + "$ref": "#/components/schemas/VectorStoreFileCounts", + "description": "File processing status counts for the vector store" }, "status": { "type": "string", - "default": "completed" + "default": "completed", + "description": "Current status of the vector store" }, "expires_after": { "type": "object", @@ -13716,13 +14246,16 @@ "type": "object" } ] - } + }, + "description": "(Optional) Expiration policy for the vector store" }, "expires_at": { - "type": "integer" + "type": "integer", + "description": "(Optional) Timestamp when the vector store will expire" }, "last_active_at": { - "type": "integer" + "type": "integer", + "description": "(Optional) Timestamp of last activity on the vector store" }, "metadata": { "type": "object", @@ -13747,7 +14280,8 @@ "type": "object" } ] - } + }, + "description": "Set of key-value pairs that can be attached to the vector store" } }, "additionalProperties": false, @@ -13794,15 +14328,18 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the deleted vector store" }, "object": { "type": "string", - "default": "vector_store.deleted" + "default": "vector_store.deleted", + "description": "Object type identifier for the deletion response" }, "deleted": { "type": "boolean", - "default": true + "default": true, + "description": "Whether the deletion operation was successful" } }, "additionalProperties": false, @@ -13818,15 +14355,18 @@ "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the deleted file" }, "object": { "type": "string", - "default": "vector_store.file.deleted" + "default": "vector_store.file.deleted", + "description": "Object type identifier for the deletion response" }, "deleted": { "type": "boolean", - "default": true + "default": true, + "description": "Whether the deletion operation was successful" } }, "additionalProperties": false, @@ -13990,13 +14530,16 @@ "description": "List of file objects" }, "has_more": { - "type": "boolean" + "type": "boolean", + "description": "Whether there are more files available beyond this page" }, "first_id": { - "type": "string" + "type": "string", + "description": "ID of the first file in the list for pagination" }, "last_id": { - "type": "string" + "type": "string", + "description": "ID of the last file in the list for pagination" }, "object": { "type": "string", @@ -14071,23 +14614,28 @@ "properties": { "object": { "type": "string", - "default": "list" + "default": "list", + "description": "Object type identifier, always \"list\"" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VectorStoreFileObject" - } + }, + "description": "List of vector store file objects" }, "first_id": { - "type": "string" + "type": "string", + "description": "(Optional) ID of the first file in the list for pagination" }, "last_id": { - "type": "string" + "type": "string", + "description": "(Optional) ID of the last file in the list for pagination" }, "has_more": { "type": "boolean", - "default": false + "default": false, + "description": "Whether there are more files available beyond this page" } }, "additionalProperties": false, @@ -14097,7 +14645,7 @@ "has_more" ], "title": "VectorStoreListFilesResponse", - "description": "Response from listing vector stores." + "description": "Response from listing files in a vector store." }, "OpenAIModel": { "type": "object", @@ -14148,23 +14696,28 @@ "properties": { "object": { "type": "string", - "default": "list" + "default": "list", + "description": "Object type identifier, always \"list\"" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VectorStoreObject" - } + }, + "description": "List of vector store objects" }, "first_id": { - "type": "string" + "type": "string", + "description": "(Optional) ID of the first vector store in the list for pagination" }, "last_id": { - "type": "string" + "type": "string", + "description": "(Optional) ID of the last vector store in the list for pagination" }, "has_more": { "type": "boolean", - "default": false + "default": false, + "description": "Whether there are more vector stores available beyond this page" } }, "additionalProperties": false, @@ -14185,10 +14738,12 @@ "properties": { "type": { "type": "string", - "const": "text" + "const": "text", + "description": "Content type, currently only \"text\" is supported" }, "text": { - "type": "string" + "type": "string", + "description": "The actual text content" } }, "additionalProperties": false, @@ -14196,16 +14751,19 @@ "type", "text" ], - "title": "VectorStoreContent" + "title": "VectorStoreContent", + "description": "Content item from a vector store file or search result." }, "VectorStoreFileContentsResponse": { "type": "object", "properties": { "file_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the file" }, "filename": { - "type": "string" + "type": "string", + "description": "Name of the file" }, "attributes": { "type": "object", @@ -14230,13 +14788,15 @@ "type": "object" } ] - } + }, + "description": "Key-value attributes associated with the file" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/VectorStoreContent" - } + }, + "description": "List of content items from the file" } }, "additionalProperties": false, @@ -14300,11 +14860,13 @@ "type": "object", "properties": { "ranker": { - "type": "string" + "type": "string", + "description": "(Optional) Name of the ranking algorithm to use" }, "score_threshold": { "type": "number", - "default": 0.0 + "default": 0.0, + "description": "(Optional) Minimum relevance score threshold for results" } }, "additionalProperties": false, @@ -14329,13 +14891,16 @@ "type": "object", "properties": { "file_id": { - "type": "string" + "type": "string", + "description": "Unique identifier of the file containing the result" }, "filename": { - "type": "string" + "type": "string", + "description": "Name of the file containing the result" }, "score": { - "type": "number" + "type": "number", + "description": "Relevance score for this search result" }, "attributes": { "type": "object", @@ -14351,13 +14916,15 @@ "type": "boolean" } ] - } + }, + "description": "(Optional) Key-value attributes associated with the file" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/VectorStoreContent" - } + }, + "description": "List of content items matching the search query" } }, "additionalProperties": false, @@ -14375,23 +14942,28 @@ "properties": { "object": { "type": "string", - "default": "vector_store.search_results.page" + "default": "vector_store.search_results.page", + "description": "Object type identifier for the search results page" }, "search_query": { - "type": "string" + "type": "string", + "description": "The original search query that was executed" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/VectorStoreSearchResponse" - } + }, + "description": "List of search result objects" }, "has_more": { "type": "boolean", - "default": false + "default": false, + "description": "Whether there are more results available beyond this page" }, "next_page": { - "type": "string" + "type": "string", + "description": "(Optional) Token for retrieving the next page of results" } }, "additionalProperties": false, @@ -14402,7 +14974,7 @@ "has_more" ], "title": "VectorStoreSearchResponsePage", - "description": "Response from searching a vector store." + "description": "Paginated response from searching a vector store." }, "OpenaiUpdateVectorStoreRequest": { "type": "object", @@ -14506,20 +15078,43 @@ "DPOAlignmentConfig": { "type": "object", "properties": { + "reward_scale": { + "type": "number", + "description": "Scaling factor for the reward signal" + }, + "reward_clip": { + "type": "number", + "description": "Maximum absolute value for reward clipping" + }, + "epsilon": { + "type": "number", + "description": "Small value added for numerical stability" + }, + "gamma": { + "type": "number", + "description": "Discount factor for future rewards" + }, "beta": { - "type": "number" + "type": "number", + "description": "Temperature parameter for the DPO loss" }, "loss_type": { "$ref": "#/components/schemas/DPOLossType", - "default": "sigmoid" + "default": "sigmoid", + "description": "The type of loss function to use for DPO" } }, "additionalProperties": false, "required": [ + "reward_scale", + "reward_clip", + "epsilon", + "gamma", "beta", "loss_type" ], - "title": "DPOAlignmentConfig" + "title": "DPOAlignmentConfig", + "description": "Configuration for Direct Preference Optimization (DPO) alignment." }, "DPOLossType": { "type": "string", @@ -14535,27 +15130,34 @@ "type": "object", "properties": { "dataset_id": { - "type": "string" + "type": "string", + "description": "Unique identifier for the training dataset" }, "batch_size": { - "type": "integer" + "type": "integer", + "description": "Number of samples per training batch" }, "shuffle": { - "type": "boolean" + "type": "boolean", + "description": "Whether to shuffle the dataset during training" }, "data_format": { - "$ref": "#/components/schemas/DatasetFormat" + "$ref": "#/components/schemas/DatasetFormat", + "description": "Format of the dataset (instruct or dialog)" }, "validation_dataset_id": { - "type": "string" + "type": "string", + "description": "(Optional) Unique identifier for the validation dataset" }, "packed": { "type": "boolean", - "default": false + "default": false, + "description": "(Optional) Whether to pack multiple samples into a single sequence for efficiency" }, "train_on_input": { "type": "boolean", - "default": false + "default": false, + "description": "(Optional) Whether to compute loss on input tokens as well as output tokens" } }, "additionalProperties": false, @@ -14565,7 +15167,8 @@ "shuffle", "data_format" ], - "title": "DataConfig" + "title": "DataConfig", + "description": "Configuration for training data and data loading." }, "DatasetFormat": { "type": "string", @@ -14573,45 +15176,55 @@ "instruct", "dialog" ], - "title": "DatasetFormat" + "title": "DatasetFormat", + "description": "Format of the training dataset." }, "EfficiencyConfig": { "type": "object", "properties": { "enable_activation_checkpointing": { "type": "boolean", - "default": false + "default": false, + "description": "(Optional) Whether to use activation checkpointing to reduce memory usage" }, "enable_activation_offloading": { "type": "boolean", - "default": false + "default": false, + "description": "(Optional) Whether to offload activations to CPU to save GPU memory" }, "memory_efficient_fsdp_wrap": { "type": "boolean", - "default": false + "default": false, + "description": "(Optional) Whether to use memory-efficient FSDP wrapping" }, "fsdp_cpu_offload": { "type": "boolean", - "default": false + "default": false, + "description": "(Optional) Whether to offload FSDP parameters to CPU" } }, "additionalProperties": false, - "title": "EfficiencyConfig" + "title": "EfficiencyConfig", + "description": "Configuration for memory and compute efficiency optimizations." }, "OptimizerConfig": { "type": "object", "properties": { "optimizer_type": { - "$ref": "#/components/schemas/OptimizerType" + "$ref": "#/components/schemas/OptimizerType", + "description": "Type of optimizer to use (adam, adamw, or sgd)" }, "lr": { - "type": "number" + "type": "number", + "description": "Learning rate for the optimizer" }, "weight_decay": { - "type": "number" + "type": "number", + "description": "Weight decay coefficient for regularization" }, "num_warmup_steps": { - "type": "integer" + "type": "integer", + "description": "Number of steps for learning rate warmup" } }, "additionalProperties": false, @@ -14621,7 +15234,8 @@ "weight_decay", "num_warmup_steps" ], - "title": "OptimizerConfig" + "title": "OptimizerConfig", + "description": "Configuration parameters for the optimization algorithm." }, "OptimizerType": { "type": "string", @@ -14630,38 +15244,47 @@ "adamw", "sgd" ], - "title": "OptimizerType" + "title": "OptimizerType", + "description": "Available optimizer algorithms for training." }, "TrainingConfig": { "type": "object", "properties": { "n_epochs": { - "type": "integer" + "type": "integer", + "description": "Number of training epochs to run" }, "max_steps_per_epoch": { "type": "integer", - "default": 1 + "default": 1, + "description": "Maximum number of steps to run per epoch" }, "gradient_accumulation_steps": { "type": "integer", - "default": 1 + "default": 1, + "description": "Number of steps to accumulate gradients before updating" }, "max_validation_steps": { "type": "integer", - "default": 1 + "default": 1, + "description": "(Optional) Maximum number of validation steps per epoch" }, "data_config": { - "$ref": "#/components/schemas/DataConfig" + "$ref": "#/components/schemas/DataConfig", + "description": "(Optional) Configuration for data loading and formatting" }, "optimizer_config": { - "$ref": "#/components/schemas/OptimizerConfig" + "$ref": "#/components/schemas/OptimizerConfig", + "description": "(Optional) Configuration for the optimization algorithm" }, "efficiency_config": { - "$ref": "#/components/schemas/EfficiencyConfig" + "$ref": "#/components/schemas/EfficiencyConfig", + "description": "(Optional) Configuration for memory and compute optimizations" }, "dtype": { "type": "string", - "default": "bf16" + "default": "bf16", + "description": "(Optional) Data type for model parameters (bf16, fp16, fp32)" } }, "additionalProperties": false, @@ -14670,7 +15293,8 @@ "max_steps_per_epoch", "gradient_accumulation_steps" ], - "title": "TrainingConfig" + "title": "TrainingConfig", + "description": "Comprehensive configuration for the training process." }, "PreferenceOptimizeRequest": { "type": "object", @@ -14774,11 +15398,13 @@ "type": { "type": "string", "const": "default", - "default": "default" + "default": "default", + "description": "Type of query generator, always 'default'" }, "separator": { "type": "string", - "default": " " + "default": " ", + "description": "String separator used to join query terms" } }, "additionalProperties": false, @@ -14786,7 +15412,8 @@ "type", "separator" ], - "title": "DefaultRAGQueryGeneratorConfig" + "title": "DefaultRAGQueryGeneratorConfig", + "description": "Configuration for the default RAG query generator." }, "LLMRAGQueryGeneratorConfig": { "type": "object", @@ -14794,13 +15421,16 @@ "type": { "type": "string", "const": "llm", - "default": "llm" + "default": "llm", + "description": "Type of query generator, always 'llm'" }, "model": { - "type": "string" + "type": "string", + "description": "Name of the language model to use for query generation" }, "template": { - "type": "string" + "type": "string", + "description": "Template string for formatting the query generation prompt" } }, "additionalProperties": false, @@ -14809,7 +15439,8 @@ "model", "template" ], - "title": "LLMRAGQueryGeneratorConfig" + "title": "LLMRAGQueryGeneratorConfig", + "description": "Configuration for the LLM-based RAG query generator." }, "RAGQueryConfig": { "type": "object", @@ -14892,7 +15523,7 @@ "impact_factor": { "type": "number", "default": 60.0, - "description": "The impact factor for RRF scoring. Higher values give more weight to higher-ranked results. Must be greater than 0. Default of 60 is from the original RRF paper (Cormack et al., 2009)." + "description": "The impact factor for RRF scoring. Higher values give more weight to higher-ranked results. Must be greater than 0" } }, "additionalProperties": false, @@ -14947,16 +15578,19 @@ "type": "object", "properties": { "content": { - "$ref": "#/components/schemas/InterleavedContent" + "$ref": "#/components/schemas/InterleavedContent", + "description": "The query content to search for in the indexed documents" }, "vector_db_ids": { "type": "array", "items": { "type": "string" - } + }, + "description": "List of vector database IDs to search within" }, "query_config": { - "$ref": "#/components/schemas/RAGQueryConfig" + "$ref": "#/components/schemas/RAGQueryConfig", + "description": "(Optional) Configuration parameters for the query operation" } }, "additionalProperties": false, @@ -14970,7 +15604,8 @@ "type": "object", "properties": { "content": { - "$ref": "#/components/schemas/InterleavedContent" + "$ref": "#/components/schemas/InterleavedContent", + "description": "(Optional) The retrieved content from the query" }, "metadata": { "type": "object", @@ -14995,14 +15630,16 @@ "type": "object" } ] - } + }, + "description": "Additional metadata about the query result" } }, "additionalProperties": false, "required": [ "metadata" ], - "title": "RAGQueryResult" + "title": "RAGQueryResult", + "description": "Result of a RAG query containing retrieved content and metadata." }, "QueryChunksRequest": { "type": "object", @@ -15056,13 +15693,15 @@ "type": "array", "items": { "$ref": "#/components/schemas/Chunk" - } + }, + "description": "List of content chunks returned from the query" }, "scores": { "type": "array", "items": { "type": "number" - } + }, + "description": "Relevance scores corresponding to each returned chunk" } }, "additionalProperties": false, @@ -15070,7 +15709,8 @@ "chunks", "scores" ], - "title": "QueryChunksResponse" + "title": "QueryChunksResponse", + "description": "Response from querying chunks in a vector database." }, "QueryMetricsRequest": { "type": "object", @@ -15101,10 +15741,12 @@ "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name of the label to match" }, "value": { - "type": "string" + "type": "string", + "description": "The value to match against" }, "operator": { "type": "string", @@ -15114,7 +15756,7 @@ "=~", "!~" ], - "title": "MetricLabelOperator", + "description": "The comparison operator to use for matching", "default": "=" } }, @@ -15124,7 +15766,8 @@ "value", "operator" ], - "title": "MetricLabelMatcher" + "title": "MetricLabelMatcher", + "description": "A matcher for filtering metrics by label values." }, "description": "The label matchers to apply to the metric." } @@ -15140,10 +15783,12 @@ "type": "object", "properties": { "timestamp": { - "type": "integer" + "type": "integer", + "description": "Unix timestamp when the metric value was recorded" }, "value": { - "type": "number" + "type": "number", + "description": "The numeric value of the metric at this timestamp" } }, "additionalProperties": false, @@ -15151,16 +15796,19 @@ "timestamp", "value" ], - "title": "MetricDataPoint" + "title": "MetricDataPoint", + "description": "A single data point in a metric time series." }, "MetricLabel": { "type": "object", "properties": { "name": { - "type": "string" + "type": "string", + "description": "The name of the label" }, "value": { - "type": "string" + "type": "string", + "description": "The value of the label" } }, "additionalProperties": false, @@ -15168,25 +15816,29 @@ "name", "value" ], - "title": "MetricLabel" + "title": "MetricLabel", + "description": "A label associated with a metric." }, "MetricSeries": { "type": "object", "properties": { "metric": { - "type": "string" + "type": "string", + "description": "The name of the metric" }, "labels": { "type": "array", "items": { "$ref": "#/components/schemas/MetricLabel" - } + }, + "description": "List of labels associated with this metric series" }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/MetricDataPoint" - } + }, + "description": "List of data points in chronological order" } }, "additionalProperties": false, @@ -15195,7 +15847,8 @@ "labels", "values" ], - "title": "MetricSeries" + "title": "MetricSeries", + "description": "A time series of metric data points." }, "QueryMetricsResponse": { "type": "object", @@ -15204,23 +15857,27 @@ "type": "array", "items": { "$ref": "#/components/schemas/MetricSeries" - } + }, + "description": "List of metric series matching the query criteria" } }, "additionalProperties": false, "required": [ "data" ], - "title": "QueryMetricsResponse" + "title": "QueryMetricsResponse", + "description": "Response containing metric time series data." }, "QueryCondition": { "type": "object", "properties": { "key": { - "type": "string" + "type": "string", + "description": "The attribute key to filter on" }, "op": { - "$ref": "#/components/schemas/QueryConditionOp" + "$ref": "#/components/schemas/QueryConditionOp", + "description": "The comparison operator to apply" }, "value": { "oneOf": [ @@ -15242,7 +15899,8 @@ { "type": "object" } - ] + ], + "description": "The value to compare against" } }, "additionalProperties": false, @@ -15251,7 +15909,8 @@ "op", "value" ], - "title": "QueryCondition" + "title": "QueryCondition", + "description": "A condition for filtering query results." }, "QueryConditionOp": { "type": "string", @@ -15261,7 +15920,8 @@ "gt", "lt" ], - "title": "QueryConditionOp" + "title": "QueryConditionOp", + "description": "Comparison operators for query conditions." }, "QuerySpansRequest": { "type": "object", @@ -15299,14 +15959,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/Span" - } + }, + "description": "List of spans matching the query criteria" } }, "additionalProperties": false, "required": [ "data" ], - "title": "QuerySpansResponse" + "title": "QuerySpansResponse", + "description": "Response containing a list of spans." }, "QueryTracesRequest": { "type": "object", @@ -15344,14 +16006,16 @@ "type": "array", "items": { "$ref": "#/components/schemas/Trace" - } + }, + "description": "List of traces matching the query criteria" } }, "additionalProperties": false, "required": [ "data" ], - "title": "QueryTracesResponse" + "title": "QueryTracesResponse", + "description": "Response containing a list of traces." }, "RegisterBenchmarkRequest": { "type": "object", @@ -15776,11 +16440,13 @@ "type": "object", "properties": { "violation": { - "$ref": "#/components/schemas/SafetyViolation" + "$ref": "#/components/schemas/SafetyViolation", + "description": "(Optional) Safety violation detected by the shield, if any" } }, "additionalProperties": false, - "title": "RunShieldResponse" + "title": "RunShieldResponse", + "description": "Response from running a safety shield." }, "SaveSpansToDatasetRequest": { "type": "object", @@ -15926,20 +16592,23 @@ "type": "object", "properties": { "dataset_id": { - "type": "string" + "type": "string", + "description": "(Optional) The identifier of the dataset that was scored" }, "results": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ScoringResult" - } + }, + "description": "A map of scoring function name to ScoringResult" } }, "additionalProperties": false, "required": [ "results" ], - "title": "ScoreBatchResponse" + "title": "ScoreBatchResponse", + "description": "Response from batch scoring operations on datasets." }, "AlgorithmConfig": { "oneOf": [ @@ -15964,33 +16633,41 @@ "type": { "type": "string", "const": "LoRA", - "default": "LoRA" + "default": "LoRA", + "description": "Algorithm type identifier, always \"LoRA\"" }, "lora_attn_modules": { "type": "array", "items": { "type": "string" - } + }, + "description": "List of attention module names to apply LoRA to" }, "apply_lora_to_mlp": { - "type": "boolean" + "type": "boolean", + "description": "Whether to apply LoRA to MLP layers" }, "apply_lora_to_output": { - "type": "boolean" + "type": "boolean", + "description": "Whether to apply LoRA to output projection layers" }, "rank": { - "type": "integer" + "type": "integer", + "description": "Rank of the LoRA adaptation (lower rank = fewer parameters)" }, "alpha": { - "type": "integer" + "type": "integer", + "description": "LoRA scaling parameter that controls adaptation strength" }, "use_dora": { "type": "boolean", - "default": false + "default": false, + "description": "(Optional) Whether to use DoRA (Weight-Decomposed Low-Rank Adaptation)" }, "quantize_base": { "type": "boolean", - "default": false + "default": false, + "description": "(Optional) Whether to quantize the base model weights" } }, "additionalProperties": false, @@ -16002,7 +16679,8 @@ "rank", "alpha" ], - "title": "LoraFinetuningConfig" + "title": "LoraFinetuningConfig", + "description": "Configuration for Low-Rank Adaptation (LoRA) fine-tuning." }, "QATFinetuningConfig": { "type": "object", @@ -16010,13 +16688,16 @@ "type": { "type": "string", "const": "QAT", - "default": "QAT" + "default": "QAT", + "description": "Algorithm type identifier, always \"QAT\"" }, "quantizer_name": { - "type": "string" + "type": "string", + "description": "Name of the quantization algorithm to use" }, "group_size": { - "type": "integer" + "type": "integer", + "description": "Size of groups for grouped quantization" } }, "additionalProperties": false, @@ -16025,7 +16706,8 @@ "quantizer_name", "group_size" ], - "title": "QATFinetuningConfig" + "title": "QATFinetuningConfig", + "description": "Configuration for Quantization-Aware Training (QAT) fine-tuning." }, "SupervisedFineTuneRequest": { "type": "object", @@ -16119,7 +16801,8 @@ "type": "array", "items": { "$ref": "#/components/schemas/Message" - } + }, + "description": "List of conversation messages to use as input for synthetic data generation" }, "filtering_function": { "type": "string", @@ -16131,11 +16814,11 @@ "top_k_top_p", "sigmoid" ], - "title": "FilteringFunction", - "description": "The type of filtering function." + "description": "Type of filtering to apply to generated synthetic data samples" }, "model": { - "type": "string" + "type": "string", + "description": "(Optional) The identifier of the model to use. The model must be registered with Llama Stack and available via the /models endpoint" } }, "additionalProperties": false, @@ -16174,7 +16857,8 @@ } ] } - } + }, + "description": "List of generated synthetic data samples that passed the filtering criteria" }, "statistics": { "type": "object", @@ -16199,7 +16883,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) Statistical information about the generation process and filtering results" } }, "additionalProperties": false, @@ -16213,14 +16898,16 @@ "type": "object", "properties": { "version": { - "type": "string" + "type": "string", + "description": "Version number of the service" } }, "additionalProperties": false, "required": [ "version" ], - "title": "VersionInfo" + "title": "VersionInfo", + "description": "Version information for the service." } }, "responses": { diff --git a/docs/_static/llama-stack-spec.yaml b/docs/_static/llama-stack-spec.yaml index 9ac29034d..f1bb40dc1 100644 --- a/docs/_static/llama-stack-spec.yaml +++ b/docs/_static/llama-stack-spec.yaml @@ -1323,7 +1323,8 @@ paths: get: responses: '200': - description: A HealthInfo. + description: >- + Health information indicating if the service is operational. content: application/json: schema: @@ -1340,7 +1341,8 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Inspect - description: Get the health of the service. + description: >- + Get the current health status of the service. parameters: [] /v1/tool-runtime/rag-tool/insert: post: @@ -1360,7 +1362,7 @@ paths: tags: - ToolRuntime description: >- - Index documents so they can be used by the RAG system + Index documents so they can be used by the RAG system. parameters: [] requestBody: content: @@ -1984,7 +1986,8 @@ paths: get: responses: '200': - description: A ListRoutesResponse. + description: >- + Response containing information about all available routes. content: application/json: schema: @@ -2001,7 +2004,8 @@ paths: $ref: '#/components/responses/DefaultError' tags: - Inspect - description: List all routes. + description: >- + List all available API routes with their methods and implementing providers. parameters: [] /v1/tool-runtime/list-tools: get: @@ -2324,26 +2328,41 @@ paths: type: string - name: limit in: query + description: >- + (Optional) A limit on the number of objects to be returned. Limit can + range between 1 and 100, and the default is 20. required: false schema: type: integer - name: order in: query + description: >- + (Optional) Sort order by the `created_at` timestamp of the objects. `asc` + for ascending order and `desc` for descending order. required: false schema: type: string - name: after in: query + description: >- + (Optional) A cursor for use in pagination. `after` is an object ID that + defines your place in the list. required: false schema: type: string - name: before in: query + description: >- + (Optional) A cursor for use in pagination. `before` is an object ID that + defines your place in the list. required: false schema: type: string - name: filter in: query + description: >- + (Optional) Filter by file status to only return files with the specified + status. required: false schema: $ref: '#/components/schemas/VectorStoreFileStatus' @@ -3071,7 +3090,8 @@ paths: post: responses: '200': - description: OK + description: >- + RAGQueryResult containing the retrieved content and metadata content: application/json: schema: @@ -3089,7 +3109,7 @@ paths: tags: - ToolRuntime description: >- - Query the RAG system for context; typically invoked by the agent + Query the RAG system for context; typically invoked by the agent. parameters: [] requestBody: content: @@ -3459,7 +3479,8 @@ paths: post: responses: '200': - description: OK + description: >- + Response containing filtered synthetic data samples and optional statistics content: application/json: schema: @@ -3476,7 +3497,8 @@ paths: $ref: '#/components/responses/DefaultError' tags: - SyntheticDataGeneration (Coming Soon) - description: '' + description: >- + Generate synthetic data based on input dialogs and apply filtering. parameters: [] requestBody: content: @@ -3488,7 +3510,8 @@ paths: get: responses: '200': - description: A VersionInfo. + description: >- + Version information containing the service version number. content: application/json: schema: @@ -3636,10 +3659,15 @@ components: type: string const: greedy default: greedy + description: >- + Must be "greedy" to identify this sampling strategy additionalProperties: false required: - type title: GreedySamplingStrategy + description: >- + Greedy sampling strategy that selects the highest probability token at each + step. ImageContentItem: type: object properties: @@ -3997,13 +4025,19 @@ components: type: string const: top_k default: top_k + description: >- + Must be "top_k" to identify this sampling strategy top_k: type: integer + description: >- + Number of top tokens to consider for sampling. Must be at least 1 additionalProperties: false required: - type - top_k title: TopKSamplingStrategy + description: >- + Top-k sampling strategy that restricts sampling to the k most likely tokens. TopPSamplingStrategy: type: object properties: @@ -4011,24 +4045,35 @@ components: type: string const: top_p default: top_p + description: >- + Must be "top_p" to identify this sampling strategy temperature: type: number + description: >- + Controls randomness in sampling. Higher values increase randomness top_p: type: number default: 0.95 + description: >- + Cumulative probability threshold for nucleus sampling. Defaults to 0.95 additionalProperties: false required: - type title: TopPSamplingStrategy + description: >- + Top-p (nucleus) sampling strategy that samples from the smallest set of tokens + with cumulative probability >= p. URL: type: object 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: @@ -4111,10 +4156,14 @@ components: type: array items: $ref: '#/components/schemas/ChatCompletionResponse' + description: >- + List of chat completion responses, one for each conversation in the batch additionalProperties: false required: - batch title: BatchChatCompletionResponse + description: >- + Response from a batch chat completion request. ChatCompletionResponse: type: object properties: @@ -4122,6 +4171,8 @@ components: type: array items: $ref: '#/components/schemas/MetricInResponse' + description: >- + (Optional) List of metrics associated with the API response completion_message: $ref: '#/components/schemas/CompletionMessage' description: The complete response message @@ -4141,17 +4192,23 @@ components: properties: metric: type: string + description: The name of the metric value: oneOf: - type: integer - type: number + description: The numeric value of the metric unit: type: string + description: >- + (Optional) The unit of measurement for the metric value additionalProperties: false required: - metric - value title: MetricInResponse + description: >- + A metric value included in API responses. TokenLogProbs: type: object properties: @@ -4211,10 +4268,14 @@ components: type: array items: $ref: '#/components/schemas/CompletionResponse' + description: >- + List of completion responses, one for each input in the batch additionalProperties: false required: - batch title: BatchCompletionResponse + description: >- + Response from a batch completion request. CompletionResponse: type: object properties: @@ -4222,6 +4283,8 @@ components: type: array items: $ref: '#/components/schemas/MetricInResponse' + description: >- + (Optional) List of metrics associated with the API response content: type: string description: The generated completion text @@ -4375,6 +4438,8 @@ components: type: array items: $ref: '#/components/schemas/MetricInResponse' + description: >- + (Optional) List of metrics associated with the API response event: $ref: '#/components/schemas/ChatCompletionResponseEvent' description: The event containing the new content @@ -4402,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: @@ -4417,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: @@ -4431,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: @@ -4442,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: @@ -4498,6 +4579,8 @@ components: type: array items: $ref: '#/components/schemas/MetricInResponse' + description: >- + (Optional) List of metrics associated with the API response delta: type: string description: >- @@ -4622,12 +4705,17 @@ components: properties: name: type: string + description: Name of the tool description: type: string + description: >- + (Optional) Human-readable description of what the tool does parameters: type: array items: $ref: '#/components/schemas/ToolParameter' + description: >- + (Optional) List of parameters this tool accepts metadata: type: object additionalProperties: @@ -4638,22 +4726,33 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Additional metadata about the tool additionalProperties: false required: - name title: ToolDef + description: >- + Tool definition used in runtime contexts. ToolParameter: type: object properties: name: type: string + description: Name of the parameter parameter_type: type: string + description: >- + Type of the parameter (e.g., string, integer) description: type: string + description: >- + Human-readable description of what the parameter does required: type: boolean default: true + description: >- + Whether this parameter is required for tool invocation default: oneOf: - type: 'null' @@ -4662,6 +4761,8 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Default value for the parameter if not provided additionalProperties: false required: - name @@ -4669,6 +4770,7 @@ components: - description - required title: ToolParameter + description: Parameter definition for a tool. CreateAgentRequest: type: object properties: @@ -4684,10 +4786,13 @@ components: properties: agent_id: type: string + description: Unique identifier for the created agent additionalProperties: false required: - agent_id title: AgentCreateResponse + description: >- + Response returned when creating a new agent. CreateAgentSessionRequest: type: object properties: @@ -4703,10 +4808,14 @@ components: properties: session_id: type: string + description: >- + Unique identifier for the created session additionalProperties: false required: - session_id title: AgentSessionCreateResponse + description: >- + Response returned when creating a new agent session. CreateAgentTurnRequest: type: object properties: @@ -4853,8 +4962,11 @@ components: properties: violation_level: $ref: '#/components/schemas/ViolationLevel' + description: Severity level of the violation user_message: type: string + description: >- + (Optional) Message to convey to the user about the violation metadata: type: object additionalProperties: @@ -4865,11 +4977,16 @@ components: - type: string - type: array - type: object + description: >- + Additional metadata including specific violation codes for debugging and + telemetry additionalProperties: false required: - violation_level - metadata title: SafetyViolation + description: >- + Details of a safety violation detected by content moderation. ShieldCallStep: type: object properties: @@ -4960,6 +5077,8 @@ components: properties: call_id: type: string + description: >- + Unique identifier for the tool call this response is for tool_name: oneOf: - type: string @@ -4970,8 +5089,10 @@ components: - code_interpreter title: BuiltinTool - type: string + description: Name of the tool that was invoked content: $ref: '#/components/schemas/InterleavedContent' + description: The response content from the tool metadata: type: object additionalProperties: @@ -4982,25 +5103,34 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Additional metadata about the tool response additionalProperties: false required: - call_id - tool_name - content title: ToolResponse + description: Response from a tool invocation. Turn: type: object properties: turn_id: type: string + description: >- + Unique identifier for the turn within a session session_id: type: string + description: >- + Unique identifier for the conversation session input_messages: type: array items: oneOf: - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/ToolResponseMessage' + description: >- + List of messages that initiated this turn steps: type: array items: @@ -5016,8 +5146,12 @@ components: tool_execution: '#/components/schemas/ToolExecutionStep' shield_call: '#/components/schemas/ShieldCallStep' memory_retrieval: '#/components/schemas/MemoryRetrievalStep' + description: >- + Ordered list of processing steps executed during this turn output_message: $ref: '#/components/schemas/CompletionMessage' + description: >- + The model's generated response containing content and metadata output_attachments: type: array items: @@ -5041,12 +5175,17 @@ components: - mime_type title: Attachment description: An attachment to an agent turn. + description: >- + (Optional) Files or media attached to the agent's response started_at: type: string format: date-time + description: Timestamp when the turn began completed_at: type: string format: date-time + description: >- + (Optional) Timestamp when the turn finished, if completed additionalProperties: false required: - turn_id @@ -5065,15 +5204,20 @@ components: - warn - error title: ViolationLevel + description: Severity level of a safety violation. AgentTurnResponseEvent: type: object properties: payload: $ref: '#/components/schemas/AgentTurnResponseEventPayload' + description: >- + Event-specific payload containing event data additionalProperties: false required: - payload title: AgentTurnResponseEvent + description: >- + An event in an agent turn response stream. AgentTurnResponseEventPayload: oneOf: - $ref: '#/components/schemas/AgentTurnResponseStepStartPayload' @@ -5103,9 +5247,9 @@ components: - turn_start - turn_complete - turn_awaiting_input - title: AgentTurnResponseEventType const: step_complete default: step_complete + description: Type of event being reported step_type: type: string enum: @@ -5113,10 +5257,11 @@ components: - tool_execution - shield_call - memory_retrieval - title: StepType - description: Type of the step in an agent turn. + description: Type of step being executed step_id: type: string + description: >- + Unique identifier for the step within a turn step_details: oneOf: - $ref: '#/components/schemas/InferenceStep' @@ -5130,6 +5275,7 @@ components: tool_execution: '#/components/schemas/ToolExecutionStep' shield_call: '#/components/schemas/ShieldCallStep' memory_retrieval: '#/components/schemas/MemoryRetrievalStep' + description: Complete details of the executed step additionalProperties: false required: - event_type @@ -5137,6 +5283,8 @@ components: - step_id - step_details title: AgentTurnResponseStepCompletePayload + description: >- + Payload for step completion events in agent turn responses. AgentTurnResponseStepProgressPayload: type: object properties: @@ -5149,9 +5297,9 @@ components: - turn_start - turn_complete - turn_awaiting_input - title: AgentTurnResponseEventType const: step_progress default: step_progress + description: Type of event being reported step_type: type: string enum: @@ -5159,12 +5307,15 @@ components: - tool_execution - shield_call - memory_retrieval - title: StepType - description: Type of the step in an agent turn. + description: Type of step being executed step_id: type: string + description: >- + Unique identifier for the step within a turn delta: $ref: '#/components/schemas/ContentDelta' + description: >- + Incremental content changes during step execution additionalProperties: false required: - event_type @@ -5172,6 +5323,8 @@ components: - step_id - delta title: AgentTurnResponseStepProgressPayload + description: >- + Payload for step progress events in agent turn responses. AgentTurnResponseStepStartPayload: type: object properties: @@ -5184,9 +5337,9 @@ components: - turn_start - turn_complete - turn_awaiting_input - title: AgentTurnResponseEventType const: step_start default: step_start + description: Type of event being reported step_type: type: string enum: @@ -5194,10 +5347,11 @@ components: - tool_execution - shield_call - memory_retrieval - title: StepType - description: Type of the step in an agent turn. + description: Type of step being executed step_id: type: string + description: >- + Unique identifier for the step within a turn metadata: type: object additionalProperties: @@ -5208,22 +5362,28 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Additional metadata for the step additionalProperties: false required: - event_type - step_type - step_id title: AgentTurnResponseStepStartPayload + description: >- + Payload for step start events in agent turn responses. AgentTurnResponseStreamChunk: type: object properties: event: $ref: '#/components/schemas/AgentTurnResponseEvent' + description: >- + Individual event in the agent turn response stream additionalProperties: false required: - event title: AgentTurnResponseStreamChunk - description: streamed agent turn completion response. + description: Streamed agent turn completion response. "AgentTurnResponseTurnAwaitingInputPayload": type: object properties: @@ -5236,17 +5396,21 @@ components: - turn_start - turn_complete - turn_awaiting_input - title: AgentTurnResponseEventType const: turn_awaiting_input default: turn_awaiting_input + description: Type of event being reported turn: $ref: '#/components/schemas/Turn' + description: >- + Turn data when waiting for external tool responses additionalProperties: false required: - event_type - turn title: >- AgentTurnResponseTurnAwaitingInputPayload + description: >- + Payload for turn awaiting input events in agent turn responses. AgentTurnResponseTurnCompletePayload: type: object properties: @@ -5259,16 +5423,20 @@ components: - turn_start - turn_complete - turn_awaiting_input - title: AgentTurnResponseEventType const: turn_complete default: turn_complete + description: Type of event being reported turn: $ref: '#/components/schemas/Turn' + description: >- + Complete turn data including all steps and results additionalProperties: false required: - event_type - turn title: AgentTurnResponseTurnCompletePayload + description: >- + Payload for turn completion events in agent turn responses. AgentTurnResponseTurnStartPayload: type: object properties: @@ -5281,16 +5449,20 @@ components: - turn_start - turn_complete - turn_awaiting_input - title: AgentTurnResponseEventType const: turn_start default: turn_start + description: Type of event being reported turn_id: type: string + description: >- + Unique identifier for the turn within a session additionalProperties: false required: - event_type - turn_id title: AgentTurnResponseTurnStartPayload + description: >- + Payload for turn start events in agent turn responses. OpenAIResponseAnnotationCitation: type: object properties: @@ -5298,14 +5470,22 @@ components: type: string const: url_citation default: url_citation + description: >- + Annotation type identifier, always "url_citation" end_index: type: integer + description: >- + End position of the citation span in the content start_index: type: integer + description: >- + Start position of the citation span in the content title: type: string + description: Title of the referenced web resource url: type: string + description: URL of the referenced web resource additionalProperties: false required: - type @@ -5314,6 +5494,8 @@ components: - title - url title: OpenAIResponseAnnotationCitation + description: >- + URL citation annotation for referencing external web resources. "OpenAIResponseAnnotationContainerFileCitation": type: object properties: @@ -5348,12 +5530,18 @@ components: type: string const: file_citation default: file_citation + description: >- + Annotation type identifier, always "file_citation" file_id: type: string + description: Unique identifier of the referenced file filename: type: string + description: Name of the referenced file index: type: integer + description: >- + Position index of the citation within the content additionalProperties: false required: - type @@ -5361,6 +5549,8 @@ components: - filename - index title: OpenAIResponseAnnotationFileCitation + description: >- + File citation annotation for referencing specific files in response content. OpenAIResponseAnnotationFilePath: type: object properties: @@ -5444,31 +5634,43 @@ components: - type: string const: auto default: auto + description: >- + Level of detail for image processing, can be "low", "high", or "auto" type: type: string const: input_image default: input_image + description: >- + Content type identifier, always "input_image" image_url: type: string + description: (Optional) URL of the image content additionalProperties: false required: - detail - type title: OpenAIResponseInputMessageContentImage + description: >- + Image content for input messages in OpenAI response format. OpenAIResponseInputMessageContentText: type: object properties: text: type: string + description: The text content of the input message type: type: string const: input_text default: input_text + description: >- + Content type identifier, always "input_text" additionalProperties: false required: - text - type title: OpenAIResponseInputMessageContentText + description: >- + Text content for input messages in OpenAI response format. OpenAIResponseInputTool: oneOf: - $ref: '#/components/schemas/OpenAIResponseInputToolWebSearch' @@ -5489,10 +5691,14 @@ components: type: string const: file_search default: file_search + description: >- + Tool type identifier, always "file_search" vector_store_ids: type: array items: type: string + description: >- + List of vector store identifiers to search within filters: type: object additionalProperties: @@ -5503,24 +5709,35 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Additional filters to apply to the search max_num_results: type: integer default: 10 + description: >- + (Optional) Maximum number of search results to return (1-50) ranking_options: type: object properties: ranker: type: string + description: >- + (Optional) Name of the ranking algorithm to use score_threshold: type: number default: 0.0 + description: >- + (Optional) Minimum relevance score threshold for results additionalProperties: false - title: SearchRankingOptions + description: >- + (Optional) Options for ranking and scoring search results additionalProperties: false required: - type - vector_store_ids title: OpenAIResponseInputToolFileSearch + description: >- + File search tool configuration for OpenAI response inputs. OpenAIResponseInputToolFunction: type: object properties: @@ -5528,10 +5745,14 @@ components: type: string const: function default: function + description: Tool type identifier, always "function" name: type: string + description: Name of the function that can be called description: type: string + description: >- + (Optional) Description of what the function does parameters: type: object additionalProperties: @@ -5542,13 +5763,19 @@ components: - type: string - type: array - type: object + description: >- + (Optional) JSON schema defining the function's parameters strict: type: boolean + description: >- + (Optional) Whether to enforce strict parameter validation additionalProperties: false required: - type - name title: OpenAIResponseInputToolFunction + description: >- + Function tool configuration for OpenAI response inputs. OpenAIResponseInputToolMCP: type: object properties: @@ -5556,10 +5783,13 @@ components: type: string const: mcp default: mcp + description: Tool type identifier, always "mcp" server_label: type: string + description: Label to identify this MCP server server_url: type: string + description: URL endpoint of the MCP server headers: type: object additionalProperties: @@ -5570,6 +5800,8 @@ components: - type: string - type: array - type: object + description: >- + (Optional) HTTP headers to include when connecting to the server require_approval: oneOf: - type: string @@ -5582,13 +5814,21 @@ components: type: array items: type: string + description: >- + (Optional) List of tool names that always require approval never: type: array items: type: string + description: >- + (Optional) List of tool names that never require approval additionalProperties: false title: ApprovalFilter + description: >- + Filter configuration for MCP tool approval requirements. default: never + description: >- + Approval requirement for tool calls ("always", "never", or filter) allowed_tools: oneOf: - type: array @@ -5600,8 +5840,14 @@ components: type: array items: type: string + description: >- + (Optional) List of specific tool names that are allowed additionalProperties: false title: AllowedToolsFilter + description: >- + Filter configuration for restricting which MCP tools can be used. + description: >- + (Optional) Restriction on which tools can be used from this server additionalProperties: false required: - type @@ -5609,6 +5855,8 @@ components: - server_url - require_approval title: OpenAIResponseInputToolMCP + description: >- + Model Context Protocol (MCP) tool configuration for OpenAI response inputs. OpenAIResponseInputToolWebSearch: type: object properties: @@ -5621,13 +5869,18 @@ components: - type: string const: web_search_preview_2025_03_11 default: web_search + description: Web search tool type variant to use search_context_size: type: string default: medium + description: >- + (Optional) Size of search context, must be "low", "medium", or "high" additionalProperties: false required: - type title: OpenAIResponseInputToolWebSearch + description: >- + Web search tool configuration for OpenAI response inputs. OpenAIResponseMessage: type: object properties: @@ -5693,16 +5946,22 @@ components: properties: id: type: string + description: Unique identifier for this tool call queries: type: array items: type: string + description: List of search queries executed status: type: string + description: >- + Current status of the file search operation type: type: string const: file_search_call default: file_search_call + description: >- + Tool call type identifier, always "file_search_call" results: type: array items: @@ -5715,6 +5974,8 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Search results returned by the file search operation additionalProperties: false required: - id @@ -5723,23 +5984,35 @@ components: - type title: >- OpenAIResponseOutputMessageFileSearchToolCall + description: >- + File search tool call output message for OpenAI responses. "OpenAIResponseOutputMessageFunctionToolCall": type: object properties: call_id: type: string + description: Unique identifier for the function call name: type: string + description: Name of the function being called arguments: type: string + description: >- + JSON string containing the function arguments type: type: string const: function_call default: function_call + description: >- + Tool call type identifier, always "function_call" id: type: string + description: >- + (Optional) Additional identifier for the tool call status: type: string + description: >- + (Optional) Current status of the function call execution additionalProperties: false required: - call_id @@ -5748,17 +6021,24 @@ components: - type title: >- OpenAIResponseOutputMessageFunctionToolCall + description: >- + Function tool call output message for OpenAI responses. "OpenAIResponseOutputMessageWebSearchToolCall": type: object properties: id: type: string + description: Unique identifier for this tool call status: type: string + description: >- + Current status of the web search operation type: type: string const: web_search_call default: web_search_call + description: >- + Tool call type identifier, always "web_search_call" additionalProperties: false required: - id @@ -5766,6 +6046,8 @@ components: - type title: >- OpenAIResponseOutputMessageWebSearchToolCall + description: >- + Web search tool call output message for OpenAI responses. OpenAIResponseText: type: object properties: @@ -5812,11 +6094,12 @@ components: additionalProperties: false required: - type - title: OpenAIResponseTextFormat description: >- - Configuration for Responses API text format. + (Optional) Text format configuration specifying output format requirements additionalProperties: false title: OpenAIResponseText + description: >- + Text response configuration for OpenAI responses. CreateOpenaiResponseRequest: type: object properties: @@ -5862,49 +6145,81 @@ components: properties: code: type: string + description: >- + Error code identifying the type of failure message: type: string + description: >- + Human-readable error message describing the failure additionalProperties: false required: - code - message title: OpenAIResponseError + description: >- + Error details for failed OpenAI response requests. OpenAIResponseObject: type: object properties: created_at: type: integer + description: >- + Unix timestamp when the response was created error: $ref: '#/components/schemas/OpenAIResponseError' + description: >- + (Optional) Error details if the response generation failed id: type: string + description: Unique identifier for this response model: type: string + description: Model identifier used for generation object: type: string const: response default: response + description: >- + Object type identifier, always "response" output: type: array items: $ref: '#/components/schemas/OpenAIResponseOutput' + description: >- + List of generated output items (messages, tool calls, etc.) parallel_tool_calls: type: boolean default: false + description: >- + Whether tool calls can be executed in parallel previous_response_id: type: string + description: >- + (Optional) ID of the previous response in a conversation status: type: string + description: >- + Current status of the response generation temperature: type: number + description: >- + (Optional) Sampling temperature used for generation text: $ref: '#/components/schemas/OpenAIResponseText' + description: >- + Text formatting configuration for the response top_p: type: number + description: >- + (Optional) Nucleus sampling parameter used for generation truncation: type: string + description: >- + (Optional) Truncation strategy applied to the response user: type: string + description: >- + (Optional) User identifier associated with the request additionalProperties: false required: - created_at @@ -5916,6 +6231,8 @@ components: - status - text title: OpenAIResponseObject + description: >- + Complete OpenAI response object containing generation results and metadata. OpenAIResponseOutput: oneOf: - $ref: '#/components/schemas/OpenAIResponseMessage' @@ -5938,20 +6255,32 @@ components: properties: id: type: string + description: Unique identifier for this MCP call type: type: string const: mcp_call default: mcp_call + description: >- + Tool call type identifier, always "mcp_call" arguments: type: string + description: >- + JSON string containing the MCP call arguments name: type: string + description: Name of the MCP method being called server_label: type: string + description: >- + Label identifying the MCP server handling the call error: type: string + description: >- + (Optional) Error message if the MCP call failed output: type: string + description: >- + (Optional) Output result from the successful MCP call additionalProperties: false required: - id @@ -5960,17 +6289,25 @@ components: - name - server_label title: OpenAIResponseOutputMessageMCPCall + description: >- + Model Context Protocol (MCP) call output message for OpenAI responses. OpenAIResponseOutputMessageMCPListTools: type: object properties: id: type: string + description: >- + Unique identifier for this MCP list tools operation type: type: string const: mcp_list_tools default: mcp_list_tools + description: >- + Tool call type identifier, always "mcp_list_tools" server_label: type: string + description: >- + Label identifying the MCP server providing the tools tools: type: array items: @@ -5986,15 +6323,24 @@ components: - type: string - type: array - type: object + description: >- + JSON schema defining the tool's input parameters name: type: string + description: Name of the tool description: type: string + description: >- + (Optional) Description of what the tool does additionalProperties: false required: - input_schema - name title: MCPListToolsTool + description: >- + Tool definition returned by MCP list tools operation. + description: >- + List of available tools provided by the MCP server additionalProperties: false required: - id @@ -6002,6 +6348,8 @@ components: - server_label - tools title: OpenAIResponseOutputMessageMCPListTools + description: >- + MCP list tools output message containing available tools from an MCP server. OpenAIResponseObjectStream: oneOf: - $ref: '#/components/schemas/OpenAIResponseObjectStreamResponseCreated' @@ -6050,46 +6398,66 @@ components: properties: response: $ref: '#/components/schemas/OpenAIResponseObject' + description: The completed response object type: type: string const: response.completed default: response.completed + description: >- + Event type identifier, always "response.completed" additionalProperties: false required: - response - type title: >- OpenAIResponseObjectStreamResponseCompleted + description: >- + Streaming event indicating a response has been completed. "OpenAIResponseObjectStreamResponseCreated": type: object properties: response: $ref: '#/components/schemas/OpenAIResponseObject' + description: The newly created response object type: type: string const: response.created default: response.created + description: >- + Event type identifier, always "response.created" additionalProperties: false required: - response - type title: >- OpenAIResponseObjectStreamResponseCreated + description: >- + Streaming event indicating a new response has been created. "OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta": type: object properties: delta: type: string + description: >- + Incremental function call arguments being added item_id: type: string + description: >- + Unique identifier of the function call being updated output_index: type: integer + description: >- + Index position of the item in the output list sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.function_call_arguments.delta default: response.function_call_arguments.delta + description: >- + Event type identifier, always "response.function_call_arguments.delta" additionalProperties: false required: - delta @@ -6099,21 +6467,33 @@ components: - type title: >- OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta + description: >- + Streaming event for incremental function call argument updates. "OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone": type: object properties: arguments: type: string + description: >- + Final complete arguments JSON string for the function call item_id: type: string + description: >- + Unique identifier of the completed function call output_index: type: integer + description: >- + Index position of the item in the output list sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.function_call_arguments.done default: response.function_call_arguments.done + description: >- + Event type identifier, always "response.function_call_arguments.done" additionalProperties: false required: - arguments @@ -6123,6 +6503,8 @@ components: - type title: >- OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone + description: >- + Streaming event for when function call arguments are completed. "OpenAIResponseObjectStreamResponseMcpCallArgumentsDelta": type: object properties: @@ -6176,44 +6558,61 @@ components: properties: sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.mcp_call.completed default: response.mcp_call.completed + description: >- + Event type identifier, always "response.mcp_call.completed" additionalProperties: false required: - sequence_number - type title: >- OpenAIResponseObjectStreamResponseMcpCallCompleted + description: Streaming event for completed MCP calls. "OpenAIResponseObjectStreamResponseMcpCallFailed": type: object properties: sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.mcp_call.failed default: response.mcp_call.failed + description: >- + Event type identifier, always "response.mcp_call.failed" additionalProperties: false required: - sequence_number - type title: >- OpenAIResponseObjectStreamResponseMcpCallFailed + description: Streaming event for failed MCP calls. "OpenAIResponseObjectStreamResponseMcpCallInProgress": type: object properties: item_id: type: string + description: Unique identifier of the MCP call output_index: type: integer + description: >- + Index position of the item in the output list sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.mcp_call.in_progress default: response.mcp_call.in_progress + description: >- + Event type identifier, always "response.mcp_call.in_progress" additionalProperties: false required: - item_id @@ -6222,6 +6621,8 @@ components: - type title: >- OpenAIResponseObjectStreamResponseMcpCallInProgress + description: >- + Streaming event for MCP calls in progress. "OpenAIResponseObjectStreamResponseMcpListToolsCompleted": type: object properties: @@ -6272,16 +6673,26 @@ components: properties: response_id: type: string + description: >- + Unique identifier of the response containing this output item: $ref: '#/components/schemas/OpenAIResponseOutput' + description: >- + The output item that was added (message, tool call, etc.) output_index: type: integer + description: >- + Index position of this item in the output list sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.output_item.added default: response.output_item.added + description: >- + Event type identifier, always "response.output_item.added" additionalProperties: false required: - response_id @@ -6291,21 +6702,33 @@ components: - type title: >- OpenAIResponseObjectStreamResponseOutputItemAdded + description: >- + Streaming event for when a new output item is added to the response. "OpenAIResponseObjectStreamResponseOutputItemDone": type: object properties: response_id: type: string + description: >- + Unique identifier of the response containing this output item: $ref: '#/components/schemas/OpenAIResponseOutput' + description: >- + The completed output item (message, tool call, etc.) output_index: type: integer + description: >- + Index position of this item in the output list sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.output_item.done default: response.output_item.done + description: >- + Event type identifier, always "response.output_item.done" additionalProperties: false required: - response_id @@ -6315,23 +6738,35 @@ components: - type title: >- OpenAIResponseObjectStreamResponseOutputItemDone + description: >- + Streaming event for when an output item is completed. "OpenAIResponseObjectStreamResponseOutputTextDelta": type: object properties: content_index: type: integer + description: Index position within the text content delta: type: string + description: Incremental text content being added item_id: type: string + description: >- + Unique identifier of the output item being updated output_index: type: integer + description: >- + Index position of the item in the output list sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.output_text.delta default: response.output_text.delta + description: >- + Event type identifier, always "response.output_text.delta" additionalProperties: false required: - content_index @@ -6342,23 +6777,36 @@ components: - type title: >- OpenAIResponseObjectStreamResponseOutputTextDelta + description: >- + Streaming event for incremental text content updates. "OpenAIResponseObjectStreamResponseOutputTextDone": type: object properties: content_index: type: integer + description: Index position within the text content text: type: string + description: >- + Final complete text content of the output item item_id: type: string + description: >- + Unique identifier of the completed output item output_index: type: integer + description: >- + Index position of the item in the output list sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.output_text.done default: response.output_text.done + description: >- + Event type identifier, always "response.output_text.done" additionalProperties: false required: - content_index @@ -6369,19 +6817,29 @@ components: - type title: >- OpenAIResponseObjectStreamResponseOutputTextDone + description: >- + Streaming event for when text output is completed. "OpenAIResponseObjectStreamResponseWebSearchCallCompleted": type: object properties: item_id: type: string + description: >- + Unique identifier of the completed web search call output_index: type: integer + description: >- + Index position of the item in the output list sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.web_search_call.completed default: response.web_search_call.completed + description: >- + Event type identifier, always "response.web_search_call.completed" additionalProperties: false required: - item_id @@ -6390,19 +6848,28 @@ components: - type title: >- OpenAIResponseObjectStreamResponseWebSearchCallCompleted + description: >- + Streaming event for completed web search calls. "OpenAIResponseObjectStreamResponseWebSearchCallInProgress": type: object properties: item_id: type: string + description: Unique identifier of the web search call output_index: type: integer + description: >- + Index position of the item in the output list sequence_number: type: integer + description: >- + Sequential number for ordering streaming events type: type: string const: response.web_search_call.in_progress default: response.web_search_call.in_progress + description: >- + Event type identifier, always "response.web_search_call.in_progress" additionalProperties: false required: - item_id @@ -6411,6 +6878,8 @@ components: - type title: >- OpenAIResponseObjectStreamResponseWebSearchCallInProgress + description: >- + Streaming event for web search calls in progress. "OpenAIResponseObjectStreamResponseWebSearchCallSearching": type: object properties: @@ -6437,19 +6906,26 @@ components: properties: id: type: string + description: >- + Unique identifier of the deleted response object: type: string const: response default: response + description: >- + Object type identifier, always "response" deleted: type: boolean default: true + description: Deletion confirmation flag, always True additionalProperties: false required: - id - object - deleted title: OpenAIDeleteResponseObject + description: >- + Response object confirming deletion of an OpenAI response. EmbeddingsRequest: type: object properties: @@ -6542,6 +7018,8 @@ components: - categorical_count - accuracy title: AggregationFunctionType + description: >- + Types of aggregation functions for scoring results. BasicScoringFnParams: type: object properties: @@ -6549,15 +7027,21 @@ components: $ref: '#/components/schemas/ScoringFnParamsType' const: basic default: basic + description: >- + The type of scoring function parameters, always basic aggregation_functions: type: array items: $ref: '#/components/schemas/AggregationFunctionType' + description: >- + Aggregation functions to apply to the scores of each row additionalProperties: false required: - type - aggregation_functions title: BasicScoringFnParams + description: >- + Parameters for basic scoring function configuration. BenchmarkConfig: type: object properties: @@ -6599,18 +7083,28 @@ components: $ref: '#/components/schemas/ScoringFnParamsType' const: llm_as_judge default: llm_as_judge + description: >- + The type of scoring function parameters, always llm_as_judge judge_model: type: string + description: >- + Identifier of the LLM model to use as a judge for scoring prompt_template: type: string + description: >- + (Optional) Custom prompt template for the judge model judge_score_regexes: type: array items: type: string + description: >- + Regexes to extract the answer from generated response aggregation_functions: type: array items: $ref: '#/components/schemas/AggregationFunctionType' + description: >- + Aggregation functions to apply to the scores of each row additionalProperties: false required: - type @@ -6618,6 +7112,8 @@ components: - judge_score_regexes - aggregation_functions title: LLMAsJudgeScoringFnParams + description: >- + Parameters for LLM-as-judge scoring function configuration. ModelCandidate: type: object properties: @@ -6650,20 +7146,28 @@ components: $ref: '#/components/schemas/ScoringFnParamsType' const: regex_parser default: regex_parser + description: >- + The type of scoring function parameters, always regex_parser parsing_regexes: type: array items: type: string + description: >- + Regex to extract the answer from generated response aggregation_functions: type: array items: $ref: '#/components/schemas/AggregationFunctionType' + description: >- + Aggregation functions to apply to the scores of each row additionalProperties: false required: - type - parsing_regexes - aggregation_functions title: RegexParserScoringFnParams + description: >- + Parameters for regex parser scoring function configuration. ScoringFnParams: oneOf: - $ref: '#/components/schemas/LLMAsJudgeScoringFnParams' @@ -6682,6 +7186,8 @@ components: - regex_parser - basic title: ScoringFnParamsType + description: >- + Types of scoring function parameter configurations. EvaluateRowsRequest: type: object properties: @@ -6779,31 +7285,42 @@ components: properties: agent_id: type: string + description: Unique identifier for the agent agent_config: $ref: '#/components/schemas/AgentConfig' + description: Configuration settings for the agent created_at: type: string format: date-time + description: Timestamp when the agent was created additionalProperties: false required: - agent_id - agent_config - created_at title: Agent + description: >- + An agent instance with configuration and metadata. Session: type: object properties: session_id: type: string + description: >- + Unique identifier for the conversation session session_name: type: string + description: Human-readable name for the session turns: type: array items: $ref: '#/components/schemas/Turn' + description: >- + List of all turns that have occurred in this session started_at: type: string format: date-time + description: Timestamp when the session was created additionalProperties: false required: - session_id @@ -6829,10 +7346,14 @@ components: tool_execution: '#/components/schemas/ToolExecutionStep' shield_call: '#/components/schemas/ShieldCallStep' memory_retrieval: '#/components/schemas/MemoryRetrievalStep' + description: >- + The complete step data and execution details additionalProperties: false required: - step title: AgentStepResponse + description: >- + Response containing details of a specific agent step. Benchmark: type: object properties: @@ -6853,15 +7374,19 @@ components: - benchmark - tool - tool_group - title: ResourceType const: benchmark default: benchmark + description: The resource type, always benchmark dataset_id: type: string + description: >- + Identifier of the dataset to use for the benchmark evaluation scoring_functions: type: array items: type: string + description: >- + List of scoring function identifiers to apply during evaluation metadata: type: object additionalProperties: @@ -6872,6 +7397,7 @@ components: - type: string - type: array - type: object + description: Metadata for this evaluation task additionalProperties: false required: - identifier @@ -6881,6 +7407,8 @@ components: - scoring_functions - metadata title: Benchmark + description: >- + A benchmark resource for evaluating model performance. OpenAIAssistantMessageParam: type: object properties: @@ -6922,14 +7450,20 @@ components: type: string const: image_url default: image_url + description: >- + Must be "image_url" to identify this as image content image_url: $ref: '#/components/schemas/OpenAIImageURL' + description: >- + Image URL specification and processing details additionalProperties: false required: - type - image_url title: >- OpenAIChatCompletionContentPartImageParam + description: >- + Image content part for OpenAI-compatible chat completion messages. OpenAIChatCompletionContentPartParam: oneOf: - $ref: '#/components/schemas/OpenAIChatCompletionContentPartTextParam' @@ -6948,39 +7482,58 @@ components: type: string const: text default: text + description: >- + Must be "text" to identify this as text content text: type: string + description: The text content of the message additionalProperties: false required: - type - text title: OpenAIChatCompletionContentPartTextParam + description: >- + Text content part for OpenAI-compatible chat completion messages. OpenAIChatCompletionToolCall: type: object properties: index: type: integer + description: >- + (Optional) Index of the tool call in the list id: type: string + description: >- + (Optional) Unique identifier for the tool call type: type: string const: function default: function + description: >- + Must be "function" to identify this as a function call function: $ref: '#/components/schemas/OpenAIChatCompletionToolCallFunction' + description: (Optional) Function call details additionalProperties: false required: - type title: OpenAIChatCompletionToolCall + description: >- + Tool call specification for OpenAI-compatible chat completion responses. OpenAIChatCompletionToolCallFunction: type: object properties: name: type: string + description: (Optional) Name of the function to call arguments: type: string + description: >- + (Optional) Arguments to pass to the function as a JSON string additionalProperties: false title: OpenAIChatCompletionToolCallFunction + description: >- + Function call details for OpenAI-compatible tool calls. OpenAIChoice: type: object properties: @@ -7082,12 +7635,19 @@ components: properties: url: type: string + description: >- + URL of the image to include in the message detail: type: string + description: >- + (Optional) Level of detail for image processing. Can be "low", "high", + or "auto" additionalProperties: false required: - url title: OpenAIImageURL + description: >- + Image URL specification for OpenAI-compatible chat completion messages. OpenAIMessageParam: oneOf: - $ref: '#/components/schemas/OpenAIUserMessageParam' @@ -7300,20 +7860,22 @@ components: - benchmark - tool - tool_group - title: ResourceType const: dataset default: dataset + description: >- + Type of resource, always 'dataset' for datasets purpose: type: string enum: - post-training/messages - eval/question-answer - eval/messages-answer - title: DatasetPurpose description: >- - Purpose of the dataset. Each purpose has a required input data schema. + Purpose of the dataset indicating its intended use source: $ref: '#/components/schemas/DataSource' + description: >- + Data source configuration for the dataset metadata: type: object additionalProperties: @@ -7324,6 +7886,7 @@ components: - type: string - type: array - type: object + description: Additional metadata for the dataset additionalProperties: false required: - identifier @@ -7333,6 +7896,8 @@ components: - source - metadata title: Dataset + description: >- + Dataset resource for storing and accessing training or evaluation data. RowsDataSource: type: object properties: @@ -7386,10 +7951,16 @@ components: properties: identifier: type: string + description: >- + Unique identifier for this resource in llama stack provider_resource_id: type: string + description: >- + Unique identifier for this resource in the provider provider_id: type: string + description: >- + ID of the provider that owns this resource type: type: string enum: @@ -7401,9 +7972,10 @@ components: - benchmark - tool - tool_group - title: ResourceType const: model default: model + description: >- + The resource type, always 'model' for model resources metadata: type: object additionalProperties: @@ -7414,9 +7986,12 @@ components: - type: string - type: array - type: object + description: Any additional metadata for this model model_type: $ref: '#/components/schemas/ModelType' default: llm + description: >- + The type of model (LLM or embedding model) additionalProperties: false required: - identifier @@ -7425,12 +8000,16 @@ components: - metadata - model_type title: Model + description: >- + A model resource representing an AI model registered in Llama Stack. ModelType: type: string enum: - llm - embedding title: ModelType + description: >- + Enumeration of supported model types in Llama Stack. AgentTurnInputType: type: object properties: @@ -7438,10 +8017,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: @@ -7449,10 +8031,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: @@ -7460,10 +8044,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: @@ -7471,10 +8057,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: @@ -7482,10 +8072,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: @@ -7493,10 +8086,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: @@ -7504,10 +8099,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: @@ -7515,10 +8112,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' @@ -7564,9 +8163,10 @@ components: - benchmark - tool - tool_group - title: ResourceType const: scoring_function default: scoring_function + description: >- + The resource type, always scoring_function description: type: string metadata: @@ -7591,6 +8191,8 @@ components: - metadata - return_type title: ScoringFn + description: >- + A scoring function resource for evaluating model outputs. StringType: type: object properties: @@ -7598,10 +8200,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: @@ -7609,10 +8213,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: @@ -7633,9 +8239,9 @@ components: - benchmark - tool - tool_group - title: ResourceType const: shield default: shield + description: The resource type, always shield params: type: object additionalProperties: @@ -7646,6 +8252,8 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Configuration parameters for the shield additionalProperties: false required: - identifier @@ -7653,24 +8261,34 @@ components: - type title: Shield description: >- - A safety shield resource that can be used to check content + A safety shield resource that can be used to check content. Span: type: object properties: span_id: type: string + description: Unique identifier for the span trace_id: type: string + description: >- + Unique identifier for the trace this span belongs to parent_span_id: type: string + description: >- + (Optional) Unique identifier for the parent span, if this is a child span name: type: string + description: >- + Human-readable name describing the operation this span represents start_time: type: string format: date-time + description: Timestamp when the operation began end_time: type: string format: date-time + description: >- + (Optional) Timestamp when the operation finished, if completed attributes: type: object additionalProperties: @@ -7681,6 +8299,8 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Key-value pairs containing additional metadata about the span additionalProperties: false required: - span_id @@ -7688,6 +8308,8 @@ components: - name - start_time title: Span + description: >- + A span representing a single operation within a trace. GetSpanTreeRequest: type: object properties: @@ -7707,23 +8329,36 @@ components: - ok - error title: SpanStatus + description: >- + The status of a span indicating whether it completed successfully or with + an error. SpanWithStatus: type: object properties: span_id: type: string + description: Unique identifier for the span trace_id: type: string + description: >- + Unique identifier for the trace this span belongs to parent_span_id: type: string + description: >- + (Optional) Unique identifier for the parent span, if this is a child span name: type: string + description: >- + Human-readable name describing the operation this span represents start_time: type: string format: date-time + description: Timestamp when the operation began end_time: type: string format: date-time + description: >- + (Optional) Timestamp when the operation finished, if completed attributes: type: object additionalProperties: @@ -7734,8 +8369,12 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Key-value pairs containing additional metadata about the span status: $ref: '#/components/schemas/SpanStatus' + description: >- + (Optional) The current status of the span additionalProperties: false required: - span_id @@ -7743,6 +8382,7 @@ components: - name - start_time title: SpanWithStatus + description: A span that includes status information. QuerySpanTreeResponse: type: object properties: @@ -7750,10 +8390,14 @@ components: type: object additionalProperties: $ref: '#/components/schemas/SpanWithStatus' + description: >- + Dictionary mapping span IDs to spans with status information additionalProperties: false required: - data title: QuerySpanTreeResponse + description: >- + Response containing a tree structure of spans. Tool: type: object properties: @@ -7774,17 +8418,22 @@ components: - benchmark - tool - tool_group - title: ResourceType const: tool default: tool + description: Type of resource, always 'tool' toolgroup_id: type: string + description: >- + ID of the tool group this tool belongs to description: type: string + description: >- + Human-readable description of what the tool does parameters: type: array items: $ref: '#/components/schemas/ToolParameter' + description: List of parameters this tool accepts metadata: type: object additionalProperties: @@ -7795,6 +8444,8 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Additional metadata about the tool additionalProperties: false required: - identifier @@ -7804,6 +8455,7 @@ components: - description - parameters title: Tool + description: A tool that can be invoked by agents. ToolGroup: type: object properties: @@ -7824,11 +8476,13 @@ components: - benchmark - tool - tool_group - title: ResourceType const: tool_group default: tool_group + description: Type of resource, always 'tool_group' mcp_endpoint: $ref: '#/components/schemas/URL' + description: >- + (Optional) Model Context Protocol endpoint for remote tools args: type: object additionalProperties: @@ -7839,47 +8493,71 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Additional arguments for the tool group additionalProperties: false required: - identifier - provider_id - type title: ToolGroup + description: >- + A group of related tools managed together. Trace: type: object properties: trace_id: type: string + description: Unique identifier for the trace root_span_id: type: string + description: >- + Unique identifier for the root span that started this trace start_time: type: string format: date-time + description: Timestamp when the trace began end_time: type: string format: date-time + description: >- + (Optional) Timestamp when the trace finished, if completed additionalProperties: false required: - trace_id - root_span_id - start_time title: Trace + description: >- + A trace representing the complete execution path of a request across multiple + operations. Checkpoint: type: object properties: identifier: type: string + description: Unique identifier for the checkpoint created_at: type: string format: date-time + description: >- + Timestamp when the checkpoint was created epoch: type: integer + description: >- + Training epoch when the checkpoint was saved post_training_job_id: type: string + description: >- + Identifier of the training job that created this checkpoint path: type: string + description: >- + File system path where the checkpoint is stored training_metrics: $ref: '#/components/schemas/PostTrainingMetric' + description: >- + (Optional) Training metrics associated with this checkpoint additionalProperties: false required: - identifier @@ -7888,16 +8566,19 @@ components: - post_training_job_id - path title: Checkpoint - description: Checkpoint created during training runs + description: Checkpoint created during training runs. PostTrainingJobArtifactsResponse: type: object properties: job_uuid: type: string + description: Unique identifier for the training job checkpoints: type: array items: $ref: '#/components/schemas/Checkpoint' + description: >- + List of model checkpoints created during training additionalProperties: false required: - job_uuid @@ -7909,12 +8590,17 @@ components: properties: epoch: type: integer + description: Training epoch number train_loss: type: number + description: Loss value on the training dataset validation_loss: type: number + description: Loss value on the validation dataset perplexity: type: number + description: >- + Perplexity metric indicating model confidence additionalProperties: false required: - epoch @@ -7922,11 +8608,14 @@ components: - validation_loss - perplexity title: PostTrainingMetric + description: >- + Training metrics captured during post-training jobs. PostTrainingJobStatusResponse: type: object properties: job_uuid: type: string + description: Unique identifier for the training job status: type: string enum: @@ -7935,16 +8624,22 @@ components: - failed - scheduled - cancelled - title: JobStatus + description: Current status of the training job scheduled_at: type: string format: date-time + description: >- + (Optional) Timestamp when the job was scheduled started_at: type: string format: date-time + description: >- + (Optional) Timestamp when the job execution began completed_at: type: string format: date-time + description: >- + (Optional) Timestamp when the job finished, if completed resources_allocated: type: object additionalProperties: @@ -7955,10 +8650,15 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Information about computational resources allocated to the + job checkpoints: type: array items: $ref: '#/components/schemas/Checkpoint' + description: >- + List of model checkpoints created during training additionalProperties: false required: - job_uuid @@ -8004,13 +8704,17 @@ components: - benchmark - tool - tool_group - title: ResourceType const: vector_db default: vector_db + description: >- + Type of resource, always 'vector_db' for vector databases embedding_model: type: string + description: >- + Name of the embedding model to use for vector generation embedding_dimension: type: integer + description: Dimension of the embedding vectors vector_db_name: type: string additionalProperties: false @@ -8021,6 +8725,8 @@ components: - embedding_model - embedding_dimension title: VectorDB + description: >- + Vector database resource for storing and querying vector embeddings. HealthInfo: type: object properties: @@ -8030,11 +8736,13 @@ components: - OK - Error - Not Implemented - title: HealthStatus + description: Current health status of the service additionalProperties: false required: - status title: HealthInfo + description: >- + Health status information for the service. RAGDocument: type: object properties: @@ -8079,10 +8787,16 @@ components: type: array items: $ref: '#/components/schemas/RAGDocument' + description: >- + List of documents to index in the RAG system vector_db_id: type: string + description: >- + ID of the vector database to store the document embeddings chunk_size_in_tokens: type: integer + description: >- + (Optional) Size in tokens for document chunking during indexing additionalProperties: false required: - documents @@ -8220,10 +8934,13 @@ components: properties: api: type: string + description: The API name this provider implements provider_id: type: string + description: Unique identifier for the provider provider_type: type: string + description: The type of provider implementation config: type: object additionalProperties: @@ -8234,6 +8951,8 @@ components: - type: string - type: array - type: object + description: >- + Configuration parameters for the provider health: type: object additionalProperties: @@ -8244,6 +8963,7 @@ components: - type: string - type: array - type: object + description: Current health status of the provider additionalProperties: false required: - api @@ -8252,6 +8972,9 @@ components: - config - health title: ProviderInfo + description: >- + Information about a registered provider including its configuration and health + status. InvokeToolRequest: type: object properties: @@ -8280,10 +9003,16 @@ components: properties: content: $ref: '#/components/schemas/InterleavedContent' + description: >- + (Optional) The output content from the tool execution error_message: type: string + description: >- + (Optional) Error message if the tool execution failed error_code: type: integer + description: >- + (Optional) Numeric error code if the tool execution failed metadata: type: object additionalProperties: @@ -8294,8 +9023,11 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Additional metadata about the tool execution additionalProperties: false title: ToolInvocationResult + description: Result of a tool invocation. PaginatedResponse: type: object properties: @@ -8331,6 +9063,7 @@ components: properties: job_id: type: string + description: Unique identifier for the job status: type: string enum: @@ -8339,12 +9072,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: @@ -8362,6 +9097,7 @@ components: - asc - desc title: Order + description: Sort order for paginated responses. ListOpenAIChatCompletionResponse: type: object properties: @@ -8405,16 +9141,24 @@ components: - model - input_messages title: OpenAICompletionWithInputMessages + description: >- + List of chat completion objects with their input messages has_more: type: boolean + description: >- + Whether there are more completions available beyond this list first_id: type: string + description: ID of the first completion in this list last_id: type: string + description: ID of the last completion in this list object: type: string const: list default: list + description: >- + Must be "list" to identify this as a list response additionalProperties: false required: - data @@ -8423,6 +9167,8 @@ components: - last_id - object title: ListOpenAIChatCompletionResponse + description: >- + Response from listing OpenAI-compatible chat completions. ListDatasetsResponse: type: object properties: @@ -8430,10 +9176,12 @@ components: type: array items: $ref: '#/components/schemas/Dataset' + description: List of datasets additionalProperties: false required: - data title: ListDatasetsResponse + description: Response from listing datasets. ListModelsResponse: type: object properties: @@ -8452,15 +9200,19 @@ components: type: array items: $ref: '#/components/schemas/OpenAIResponseInput' + description: List of input items object: type: string const: list default: list + description: Object type identifier, always "list" additionalProperties: false required: - data - object title: ListOpenAIResponseInputItem + description: >- + List container for OpenAI response input items. ListOpenAIResponseObject: type: object properties: @@ -8468,16 +9220,24 @@ components: type: array items: $ref: '#/components/schemas/OpenAIResponseObjectWithInput' + description: >- + List of response objects with their input context has_more: type: boolean + description: >- + Whether there are more results available beyond this page first_id: type: string + description: >- + Identifier of the first item in this page last_id: type: string + description: Identifier of the last item in this page object: type: string const: list default: list + description: Object type identifier, always "list" additionalProperties: false required: - data @@ -8486,46 +9246,76 @@ components: - last_id - object title: ListOpenAIResponseObject + description: >- + Paginated list of OpenAI response objects with navigation metadata. OpenAIResponseObjectWithInput: type: object properties: created_at: type: integer + description: >- + Unix timestamp when the response was created error: $ref: '#/components/schemas/OpenAIResponseError' + description: >- + (Optional) Error details if the response generation failed id: type: string + description: Unique identifier for this response model: type: string + description: Model identifier used for generation object: type: string const: response default: response + description: >- + Object type identifier, always "response" output: type: array items: $ref: '#/components/schemas/OpenAIResponseOutput' + description: >- + List of generated output items (messages, tool calls, etc.) parallel_tool_calls: type: boolean default: false + description: >- + Whether tool calls can be executed in parallel previous_response_id: type: string + description: >- + (Optional) ID of the previous response in a conversation status: type: string + description: >- + Current status of the response generation temperature: type: number + description: >- + (Optional) Sampling temperature used for generation text: $ref: '#/components/schemas/OpenAIResponseText' + description: >- + Text formatting configuration for the response top_p: type: number + description: >- + (Optional) Nucleus sampling parameter used for generation truncation: type: string + description: >- + (Optional) Truncation strategy applied to the response user: type: string + description: >- + (Optional) User identifier associated with the request input: type: array items: $ref: '#/components/schemas/OpenAIResponseInput' + description: >- + List of input items that led to this response additionalProperties: false required: - created_at @@ -8538,6 +9328,8 @@ components: - text - input title: OpenAIResponseObjectWithInput + description: >- + OpenAI response object extended with input context information. ListProvidersResponse: type: object properties: @@ -8545,27 +9337,37 @@ components: type: array items: $ref: '#/components/schemas/ProviderInfo' + description: List of provider information objects additionalProperties: false required: - data title: ListProvidersResponse + description: >- + Response containing a list of all available providers. RouteInfo: type: object properties: route: type: string + description: The API endpoint path method: type: string + description: HTTP method for the route provider_types: type: array items: type: string + description: >- + List of provider types that implement this route additionalProperties: false required: - route - method - provider_types title: RouteInfo + description: >- + Information about an API route including its path, method, and implementing + providers. ListRoutesResponse: type: object properties: @@ -8573,10 +9375,14 @@ components: type: array items: $ref: '#/components/schemas/RouteInfo' + description: >- + List of available route information objects additionalProperties: false required: - data title: ListRoutesResponse + description: >- + Response containing a list of all available API routes. ListToolDefsResponse: type: object properties: @@ -8584,10 +9390,13 @@ components: type: array items: $ref: '#/components/schemas/ToolDef' + description: List of tool definitions additionalProperties: false required: - data title: ListToolDefsResponse + description: >- + Response containing a list of tool definitions. ListScoringFunctionsResponse: type: object properties: @@ -8617,10 +9426,13 @@ components: type: array items: $ref: '#/components/schemas/ToolGroup' + description: List of tool groups additionalProperties: false required: - data title: ListToolGroupsResponse + description: >- + Response containing a list of tool groups. ListToolsResponse: type: object properties: @@ -8628,10 +9440,12 @@ components: type: array items: $ref: '#/components/schemas/Tool' + description: List of tools additionalProperties: false required: - data title: ListToolsResponse + description: Response containing a list of tools. ListVectorDBsResponse: type: object properties: @@ -8639,10 +9453,12 @@ components: type: array items: $ref: '#/components/schemas/VectorDB' + description: List of vector databases additionalProperties: false required: - data title: ListVectorDBsResponse + description: Response from listing vector databases. Event: oneOf: - $ref: '#/components/schemas/UnstructuredLogEvent' @@ -8661,6 +9477,8 @@ components: - structured_log - metric title: EventType + description: >- + The type of telemetry event being logged. LogSeverity: type: string enum: @@ -8671,16 +9489,22 @@ components: - error - critical title: LogSeverity + description: The severity level of a log message. MetricEvent: type: object properties: trace_id: type: string + description: >- + Unique identifier for the trace this event belongs to span_id: type: string + description: >- + Unique identifier for the span this event belongs to timestamp: type: string format: date-time + description: Timestamp when the event occurred attributes: type: object additionalProperties: @@ -8690,18 +9514,26 @@ components: - type: number - type: boolean - type: 'null' + description: >- + (Optional) Key-value pairs containing additional metadata about the event type: $ref: '#/components/schemas/EventType' const: metric default: metric + description: Event type identifier set to METRIC metric: type: string + description: The name of the metric being measured value: oneOf: - type: integer - type: number + description: >- + The numeric value of the metric measurement unit: type: string + description: >- + The unit of measurement for the metric value additionalProperties: false required: - trace_id @@ -8712,6 +9544,8 @@ components: - value - unit title: MetricEvent + description: >- + A metric event containing a measured value. SpanEndPayload: type: object properties: @@ -8719,13 +9553,17 @@ components: $ref: '#/components/schemas/StructuredLogType' const: span_end default: span_end + description: Payload type identifier set to SPAN_END status: $ref: '#/components/schemas/SpanStatus' + description: >- + The final status of the span indicating success or failure additionalProperties: false required: - type - status title: SpanEndPayload + description: Payload for a span end event. SpanStartPayload: type: object properties: @@ -8733,25 +9571,37 @@ components: $ref: '#/components/schemas/StructuredLogType' const: span_start default: span_start + description: >- + Payload type identifier set to SPAN_START name: type: string + description: >- + Human-readable name describing the operation this span represents parent_span_id: type: string + description: >- + (Optional) Unique identifier for the parent span, if this is a child span additionalProperties: false required: - type - name title: SpanStartPayload + description: Payload for a span start event. StructuredLogEvent: type: object properties: trace_id: type: string + description: >- + Unique identifier for the trace this event belongs to span_id: type: string + description: >- + Unique identifier for the span this event belongs to timestamp: type: string format: date-time + description: Timestamp when the event occurred attributes: type: object additionalProperties: @@ -8761,12 +9611,18 @@ components: - type: number - type: boolean - type: 'null' + description: >- + (Optional) Key-value pairs containing additional metadata about the event type: $ref: '#/components/schemas/EventType' const: structured_log default: structured_log + description: >- + Event type identifier set to STRUCTURED_LOG payload: $ref: '#/components/schemas/StructuredLogPayload' + description: >- + The structured payload data for the log event additionalProperties: false required: - trace_id @@ -8775,6 +9631,8 @@ components: - type - payload title: StructuredLogEvent + description: >- + A structured log event containing typed payload data. StructuredLogPayload: oneOf: - $ref: '#/components/schemas/SpanStartPayload' @@ -8790,16 +9648,23 @@ components: - span_start - span_end title: StructuredLogType + description: >- + The type of structured log event payload. UnstructuredLogEvent: type: object properties: trace_id: type: string + description: >- + Unique identifier for the trace this event belongs to span_id: type: string + description: >- + Unique identifier for the span this event belongs to timestamp: type: string format: date-time + description: Timestamp when the event occurred attributes: type: object additionalProperties: @@ -8809,14 +9674,20 @@ components: - type: number - type: boolean - type: 'null' + description: >- + (Optional) Key-value pairs containing additional metadata about the event type: $ref: '#/components/schemas/EventType' const: unstructured_log default: unstructured_log + description: >- + Event type identifier set to UNSTRUCTURED_LOG message: type: string + description: The log message text severity: $ref: '#/components/schemas/LogSeverity' + description: The severity level of the log message additionalProperties: false required: - trace_id @@ -8826,6 +9697,8 @@ components: - message - severity title: UnstructuredLogEvent + description: >- + An unstructured log event containing a simple text message. LogEventRequest: type: object properties: @@ -8856,10 +9729,14 @@ components: type: string const: auto default: auto + description: >- + Strategy type, always "auto" for automatic chunking additionalProperties: false required: - type title: VectorStoreChunkingStrategyAuto + description: >- + Automatic chunking strategy for vector store files. VectorStoreChunkingStrategyStatic: type: object properties: @@ -8867,27 +9744,39 @@ components: type: string const: static default: static + description: >- + Strategy type, always "static" for static chunking static: $ref: '#/components/schemas/VectorStoreChunkingStrategyStaticConfig' + description: >- + Configuration parameters for the static chunking strategy additionalProperties: false required: - type - static title: VectorStoreChunkingStrategyStatic + description: >- + Static chunking strategy with configurable parameters. VectorStoreChunkingStrategyStaticConfig: type: object properties: chunk_overlap_tokens: type: integer default: 400 + description: >- + Number of tokens to overlap between adjacent chunks max_chunk_size_tokens: type: integer default: 800 + description: >- + Maximum number of tokens per chunk, must be between 100 and 4096 additionalProperties: false required: - chunk_overlap_tokens - max_chunk_size_tokens title: VectorStoreChunkingStrategyStaticConfig + description: >- + Configuration for static chunking strategy. OpenaiAttachFileToVectorStoreRequest: type: object properties: @@ -8924,21 +9813,30 @@ components: const: server_error - type: string const: rate_limit_exceeded + description: >- + Error code indicating the type of failure message: type: string + description: >- + Human-readable error message describing the failure additionalProperties: false required: - code - message title: VectorStoreFileLastError + description: >- + Error information for failed vector store file processing. VectorStoreFileObject: type: object properties: id: type: string + description: Unique identifier for the file object: type: string default: vector_store.file + description: >- + Object type identifier, always "vector_store.file" attributes: type: object additionalProperties: @@ -8949,19 +9847,31 @@ components: - type: string - type: array - type: object + description: >- + Key-value attributes associated with the file chunking_strategy: $ref: '#/components/schemas/VectorStoreChunkingStrategy' + description: >- + Strategy used for splitting the file into chunks created_at: type: integer + description: >- + Timestamp when the file was added to the vector store last_error: $ref: '#/components/schemas/VectorStoreFileLastError' + description: >- + (Optional) Error information if file processing failed status: $ref: '#/components/schemas/VectorStoreFileStatus' + description: Current processing status of the file usage_bytes: type: integer default: 0 + description: Storage space used by this file in bytes vector_store_id: type: string + description: >- + ID of the vector store containing this file additionalProperties: false required: - id @@ -8989,10 +9899,14 @@ components: properties: name: type: string + description: Name of the schema description: type: string + description: (Optional) Description of the schema strict: type: boolean + description: >- + (Optional) Whether to enforce strict adherence to the schema schema: type: object additionalProperties: @@ -9003,10 +9917,13 @@ components: - type: string - type: array - type: object + description: (Optional) The JSON schema definition additionalProperties: false required: - name title: OpenAIJSONSchema + description: >- + JSON schema specification for OpenAI-compatible structured response format. OpenAIResponseFormatJSONObject: type: object properties: @@ -9014,10 +9931,14 @@ components: type: string const: json_object default: json_object + description: >- + Must be "json_object" to indicate generic JSON object response format additionalProperties: false required: - type title: OpenAIResponseFormatJSONObject + description: >- + JSON object response format for OpenAI-compatible chat completion requests. OpenAIResponseFormatJSONSchema: type: object properties: @@ -9025,13 +9946,19 @@ components: type: string const: json_schema default: json_schema + description: >- + Must be "json_schema" to indicate structured JSON response format json_schema: $ref: '#/components/schemas/OpenAIJSONSchema' + description: >- + The JSON schema specification for the response additionalProperties: false required: - type - json_schema title: OpenAIResponseFormatJSONSchema + description: >- + JSON schema response format for OpenAI-compatible chat completion requests. OpenAIResponseFormatParam: oneOf: - $ref: '#/components/schemas/OpenAIResponseFormatText' @@ -9050,10 +9977,14 @@ components: type: string const: text default: text + description: >- + Must be "text" to indicate plain text response format additionalProperties: false required: - type title: OpenAIResponseFormatText + description: >- + Text response format for OpenAI-compatible chat completion requests. OpenaiChatCompletionRequest: type: object properties: @@ -9530,14 +10461,23 @@ components: properties: completed: type: integer + description: >- + Number of files that have been successfully processed cancelled: type: integer + description: >- + Number of files that had their processing cancelled failed: type: integer + description: Number of files that failed to process in_progress: type: integer + description: >- + Number of files currently being processed total: type: integer + description: >- + Total number of files in the vector store additionalProperties: false required: - completed @@ -9546,26 +10486,39 @@ components: - in_progress - total title: VectorStoreFileCounts + description: >- + File processing status counts for a vector store. VectorStoreObject: type: object properties: id: type: string + description: Unique identifier for the vector store object: type: string default: vector_store + description: >- + Object type identifier, always "vector_store" created_at: type: integer + description: >- + Timestamp when the vector store was created name: type: string + description: (Optional) Name of the vector store usage_bytes: type: integer default: 0 + description: >- + Storage space used by the vector store in bytes file_counts: $ref: '#/components/schemas/VectorStoreFileCounts' + description: >- + File processing status counts for the vector store status: type: string default: completed + description: Current status of the vector store expires_after: type: object additionalProperties: @@ -9576,10 +10529,16 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Expiration policy for the vector store expires_at: type: integer + description: >- + (Optional) Timestamp when the vector store will expire last_active_at: type: integer + description: >- + (Optional) Timestamp of last activity on the vector store metadata: type: object additionalProperties: @@ -9590,6 +10549,8 @@ components: - type: string - type: array - type: object + description: >- + Set of key-value pairs that can be attached to the vector store additionalProperties: false required: - id @@ -9629,12 +10590,18 @@ components: properties: id: type: string + description: >- + Unique identifier of the deleted vector store object: type: string default: vector_store.deleted + description: >- + Object type identifier for the deletion response deleted: type: boolean default: true + description: >- + Whether the deletion operation was successful additionalProperties: false required: - id @@ -9647,12 +10614,17 @@ components: properties: id: type: string + description: Unique identifier of the deleted file object: type: string default: vector_store.file.deleted + description: >- + Object type identifier for the deletion response deleted: type: boolean default: true + description: >- + Whether the deletion operation was successful additionalProperties: false required: - id @@ -9790,10 +10762,16 @@ components: description: List of file objects has_more: type: boolean + description: >- + Whether there are more files available beyond this page first_id: type: string + description: >- + ID of the first file in the list for pagination last_id: type: string + description: >- + ID of the last file in the list for pagination object: type: string const: list @@ -9858,24 +10836,33 @@ components: object: type: string default: list + description: Object type identifier, always "list" data: type: array items: $ref: '#/components/schemas/VectorStoreFileObject' + description: List of vector store file objects first_id: type: string + description: >- + (Optional) ID of the first file in the list for pagination last_id: type: string + description: >- + (Optional) ID of the last file in the list for pagination has_more: type: boolean default: false + description: >- + Whether there are more files available beyond this page additionalProperties: false required: - object - data - has_more title: VectorStoreListFilesResponse - description: Response from listing vector stores. + description: >- + Response from listing files in a vector store. OpenAIModel: type: object properties: @@ -9914,17 +10901,25 @@ components: object: type: string default: list + description: Object type identifier, always "list" data: type: array items: $ref: '#/components/schemas/VectorStoreObject' + description: List of vector store objects first_id: type: string + description: >- + (Optional) ID of the first vector store in the list for pagination last_id: type: string + description: >- + (Optional) ID of the last vector store in the list for pagination has_more: type: boolean default: false + description: >- + Whether there are more vector stores available beyond this page additionalProperties: false required: - object @@ -9941,20 +10936,27 @@ components: type: type: string const: text + description: >- + Content type, currently only "text" is supported text: type: string + description: The actual text content additionalProperties: false required: - type - text title: VectorStoreContent + description: >- + Content item from a vector store file or search result. VectorStoreFileContentsResponse: type: object properties: file_id: type: string + description: Unique identifier for the file filename: type: string + description: Name of the file attributes: type: object additionalProperties: @@ -9965,10 +10967,13 @@ components: - type: string - type: array - type: object + description: >- + Key-value attributes associated with the file content: type: array items: $ref: '#/components/schemas/VectorStoreContent' + description: List of content items from the file additionalProperties: false required: - file_id @@ -10010,9 +11015,13 @@ components: properties: ranker: type: string + description: >- + (Optional) Name of the ranking algorithm to use score_threshold: type: number default: 0.0 + description: >- + (Optional) Minimum relevance score threshold for results additionalProperties: false description: >- Ranking options for fine-tuning the search results. @@ -10034,10 +11043,14 @@ components: properties: file_id: type: string + description: >- + Unique identifier of the file containing the result filename: type: string + description: Name of the file containing the result score: type: number + description: Relevance score for this search result attributes: type: object additionalProperties: @@ -10045,10 +11058,14 @@ components: - type: string - type: number - type: boolean + description: >- + (Optional) Key-value attributes associated with the file content: type: array items: $ref: '#/components/schemas/VectorStoreContent' + description: >- + List of content items matching the search query additionalProperties: false required: - file_id @@ -10063,17 +11080,26 @@ components: object: type: string default: vector_store.search_results.page + description: >- + Object type identifier for the search results page search_query: type: string + description: >- + The original search query that was executed data: type: array items: $ref: '#/components/schemas/VectorStoreSearchResponse' + description: List of search result objects has_more: type: boolean default: false + description: >- + Whether there are more results available beyond this page next_page: type: string + description: >- + (Optional) Token for retrieving the next page of results additionalProperties: false required: - object @@ -10081,7 +11107,8 @@ components: - data - has_more title: VectorStoreSearchResponsePage - description: Response from searching a vector store. + description: >- + Paginated response from searching a vector store. OpenaiUpdateVectorStoreRequest: type: object properties: @@ -10136,16 +11163,38 @@ components: DPOAlignmentConfig: type: object properties: + reward_scale: + type: number + description: Scaling factor for the reward signal + reward_clip: + type: number + description: >- + Maximum absolute value for reward clipping + epsilon: + type: number + description: >- + Small value added for numerical stability + gamma: + type: number + description: Discount factor for future rewards beta: type: number + description: Temperature parameter for the DPO loss loss_type: $ref: '#/components/schemas/DPOLossType' default: sigmoid + description: The type of loss function to use for DPO additionalProperties: false required: + - reward_scale + - reward_clip + - epsilon + - gamma - beta - loss_type title: DPOAlignmentConfig + description: >- + Configuration for Direct Preference Optimization (DPO) alignment. DPOLossType: type: string enum: @@ -10159,20 +11208,34 @@ components: properties: dataset_id: type: string + description: >- + Unique identifier for the training dataset batch_size: type: integer + description: Number of samples per training batch shuffle: type: boolean + description: >- + Whether to shuffle the dataset during training data_format: $ref: '#/components/schemas/DatasetFormat' + description: >- + Format of the dataset (instruct or dialog) validation_dataset_id: type: string + description: >- + (Optional) Unique identifier for the validation dataset packed: type: boolean default: false + description: >- + (Optional) Whether to pack multiple samples into a single sequence for + efficiency train_on_input: type: boolean default: false + description: >- + (Optional) Whether to compute loss on input tokens as well as output tokens additionalProperties: false required: - dataset_id @@ -10180,40 +11243,59 @@ components: - shuffle - data_format title: DataConfig + description: >- + Configuration for training data and data loading. DatasetFormat: type: string enum: - instruct - dialog title: DatasetFormat + description: Format of the training dataset. EfficiencyConfig: type: object properties: enable_activation_checkpointing: type: boolean default: false + description: >- + (Optional) Whether to use activation checkpointing to reduce memory usage enable_activation_offloading: type: boolean default: false + description: >- + (Optional) Whether to offload activations to CPU to save GPU memory memory_efficient_fsdp_wrap: type: boolean default: false + description: >- + (Optional) Whether to use memory-efficient FSDP wrapping fsdp_cpu_offload: type: boolean default: false + description: >- + (Optional) Whether to offload FSDP parameters to CPU additionalProperties: false title: EfficiencyConfig + description: >- + Configuration for memory and compute efficiency optimizations. OptimizerConfig: type: object properties: optimizer_type: $ref: '#/components/schemas/OptimizerType' + description: >- + Type of optimizer to use (adam, adamw, or sgd) lr: type: number + description: Learning rate for the optimizer weight_decay: type: number + description: >- + Weight decay coefficient for regularization num_warmup_steps: type: integer + description: Number of steps for learning rate warmup additionalProperties: false required: - optimizer_type @@ -10221,6 +11303,8 @@ components: - weight_decay - num_warmup_steps title: OptimizerConfig + description: >- + Configuration parameters for the optimization algorithm. OptimizerType: type: string enum: @@ -10228,35 +11312,53 @@ components: - adamw - sgd title: OptimizerType + description: >- + Available optimizer algorithms for training. TrainingConfig: type: object properties: n_epochs: type: integer + description: Number of training epochs to run max_steps_per_epoch: type: integer default: 1 + description: Maximum number of steps to run per epoch gradient_accumulation_steps: type: integer default: 1 + description: >- + Number of steps to accumulate gradients before updating max_validation_steps: type: integer default: 1 + description: >- + (Optional) Maximum number of validation steps per epoch data_config: $ref: '#/components/schemas/DataConfig' + description: >- + (Optional) Configuration for data loading and formatting optimizer_config: $ref: '#/components/schemas/OptimizerConfig' + description: >- + (Optional) Configuration for the optimization algorithm efficiency_config: $ref: '#/components/schemas/EfficiencyConfig' + description: >- + (Optional) Configuration for memory and compute optimizations dtype: type: string default: bf16 + description: >- + (Optional) Data type for model parameters (bf16, fp16, fp32) additionalProperties: false required: - n_epochs - max_steps_per_epoch - gradient_accumulation_steps title: TrainingConfig + description: >- + Comprehensive configuration for the training process. PreferenceOptimizeRequest: type: object properties: @@ -10319,14 +11421,20 @@ components: type: string const: default default: default + description: >- + Type of query generator, always 'default' separator: type: string default: ' ' + description: >- + String separator used to join query terms additionalProperties: false required: - type - separator title: DefaultRAGQueryGeneratorConfig + description: >- + Configuration for the default RAG query generator. LLMRAGQueryGeneratorConfig: type: object properties: @@ -10334,16 +11442,23 @@ components: type: string const: llm default: llm + description: Type of query generator, always 'llm' model: type: string + description: >- + Name of the language model to use for query generation template: type: string + description: >- + Template string for formatting the query generation prompt additionalProperties: false required: - type - model - template title: LLMRAGQueryGeneratorConfig + description: >- + Configuration for the LLM-based RAG query generator. RAGQueryConfig: type: object properties: @@ -10424,8 +11539,7 @@ components: default: 60.0 description: >- The impact factor for RRF scoring. Higher values give more weight to higher-ranked - results. Must be greater than 0. Default of 60 is from the original RRF - paper (Cormack et al., 2009). + results. Must be greater than 0 additionalProperties: false required: - type @@ -10468,12 +11582,18 @@ components: properties: content: $ref: '#/components/schemas/InterleavedContent' + description: >- + The query content to search for in the indexed documents vector_db_ids: type: array items: type: string + description: >- + List of vector database IDs to search within query_config: $ref: '#/components/schemas/RAGQueryConfig' + description: >- + (Optional) Configuration parameters for the query operation additionalProperties: false required: - content @@ -10484,6 +11604,8 @@ components: properties: content: $ref: '#/components/schemas/InterleavedContent' + description: >- + (Optional) The retrieved content from the query metadata: type: object additionalProperties: @@ -10494,10 +11616,14 @@ components: - type: string - type: array - type: object + description: >- + Additional metadata about the query result additionalProperties: false required: - metadata title: RAGQueryResult + description: >- + Result of a RAG query containing retrieved content and metadata. QueryChunksRequest: type: object properties: @@ -10531,15 +11657,21 @@ components: type: array items: $ref: '#/components/schemas/Chunk' + description: >- + List of content chunks returned from the query scores: type: array items: type: number + description: >- + Relevance scores corresponding to each returned chunk additionalProperties: false required: - chunks - scores title: QueryChunksResponse + description: >- + Response from querying chunks in a vector database. QueryMetricsRequest: type: object properties: @@ -10565,8 +11697,10 @@ components: properties: name: type: string + description: The name of the label to match value: type: string + description: The value to match against operator: type: string enum: @@ -10574,7 +11708,8 @@ components: - '!=' - =~ - '!~' - title: MetricLabelOperator + description: >- + The comparison operator to use for matching default: '=' additionalProperties: false required: @@ -10582,6 +11717,8 @@ components: - value - operator title: MetricLabelMatcher + description: >- + A matcher for filtering metrics by label values. description: >- The label matchers to apply to the metric. additionalProperties: false @@ -10594,44 +11731,59 @@ components: properties: timestamp: type: integer + description: >- + Unix timestamp when the metric value was recorded value: type: number + description: >- + The numeric value of the metric at this timestamp additionalProperties: false required: - timestamp - value title: MetricDataPoint + description: >- + A single data point in a metric time series. MetricLabel: type: object properties: name: type: string + description: The name of the label value: type: string + description: The value of the label additionalProperties: false required: - name - value title: MetricLabel + description: A label associated with a metric. MetricSeries: type: object properties: metric: type: string + description: The name of the metric labels: type: array items: $ref: '#/components/schemas/MetricLabel' + description: >- + List of labels associated with this metric series values: type: array items: $ref: '#/components/schemas/MetricDataPoint' + description: >- + List of data points in chronological order additionalProperties: false required: - metric - labels - values title: MetricSeries + description: A time series of metric data points. QueryMetricsResponse: type: object properties: @@ -10639,17 +11791,23 @@ components: type: array items: $ref: '#/components/schemas/MetricSeries' + description: >- + List of metric series matching the query criteria additionalProperties: false required: - data title: QueryMetricsResponse + description: >- + Response containing metric time series data. QueryCondition: type: object properties: key: type: string + description: The attribute key to filter on op: $ref: '#/components/schemas/QueryConditionOp' + description: The comparison operator to apply value: oneOf: - type: 'null' @@ -10658,12 +11816,14 @@ components: - type: string - type: array - type: object + description: The value to compare against additionalProperties: false required: - key - op - value title: QueryCondition + description: A condition for filtering query results. QueryConditionOp: type: string enum: @@ -10672,6 +11832,8 @@ components: - gt - lt title: QueryConditionOp + description: >- + Comparison operators for query conditions. QuerySpansRequest: type: object properties: @@ -10701,10 +11863,13 @@ components: type: array items: $ref: '#/components/schemas/Span' + description: >- + List of spans matching the query criteria additionalProperties: false required: - data title: QuerySpansResponse + description: Response containing a list of spans. QueryTracesRequest: type: object properties: @@ -10734,10 +11899,13 @@ components: type: array items: $ref: '#/components/schemas/Trace' + description: >- + List of traces matching the query criteria additionalProperties: false required: - data title: QueryTracesResponse + description: Response containing a list of traces. RegisterBenchmarkRequest: type: object properties: @@ -11042,8 +12210,11 @@ components: properties: violation: $ref: '#/components/schemas/SafetyViolation' + description: >- + (Optional) Safety violation detected by the shield, if any additionalProperties: false title: RunShieldResponse + description: Response from running a safety shield. SaveSpansToDatasetRequest: type: object properties: @@ -11143,14 +12314,20 @@ components: properties: dataset_id: type: string + description: >- + (Optional) The identifier of the dataset that was scored results: type: object additionalProperties: $ref: '#/components/schemas/ScoringResult' + description: >- + A map of scoring function name to ScoringResult additionalProperties: false required: - results title: ScoreBatchResponse + description: >- + Response from batch scoring operations on datasets. AlgorithmConfig: oneOf: - $ref: '#/components/schemas/LoraFinetuningConfig' @@ -11167,24 +12344,38 @@ components: type: string const: LoRA default: LoRA + description: Algorithm type identifier, always "LoRA" lora_attn_modules: type: array items: type: string + description: >- + List of attention module names to apply LoRA to apply_lora_to_mlp: type: boolean + description: Whether to apply LoRA to MLP layers apply_lora_to_output: type: boolean + description: >- + Whether to apply LoRA to output projection layers rank: type: integer + description: >- + Rank of the LoRA adaptation (lower rank = fewer parameters) alpha: type: integer + description: >- + LoRA scaling parameter that controls adaptation strength use_dora: type: boolean default: false + description: >- + (Optional) Whether to use DoRA (Weight-Decomposed Low-Rank Adaptation) quantize_base: type: boolean default: false + description: >- + (Optional) Whether to quantize the base model weights additionalProperties: false required: - type @@ -11194,6 +12385,8 @@ components: - rank - alpha title: LoraFinetuningConfig + description: >- + Configuration for Low-Rank Adaptation (LoRA) fine-tuning. QATFinetuningConfig: type: object properties: @@ -11201,16 +12394,22 @@ components: type: string const: QAT default: QAT + description: Algorithm type identifier, always "QAT" quantizer_name: type: string + description: >- + Name of the quantization algorithm to use group_size: type: integer + description: Size of groups for grouped quantization additionalProperties: false required: - type - quantizer_name - group_size title: QATFinetuningConfig + description: >- + Configuration for Quantization-Aware Training (QAT) fine-tuning. SupervisedFineTuneRequest: type: object properties: @@ -11265,6 +12464,8 @@ components: type: array items: $ref: '#/components/schemas/Message' + description: >- + List of conversation messages to use as input for synthetic data generation filtering_function: type: string enum: @@ -11274,10 +12475,13 @@ components: - top_p - top_k_top_p - sigmoid - title: FilteringFunction - description: The type of filtering function. + description: >- + Type of filtering to apply to generated synthetic data samples model: type: string + description: >- + (Optional) The identifier of the model to use. The model must be registered + with Llama Stack and available via the /models endpoint additionalProperties: false required: - dialogs @@ -11298,6 +12502,8 @@ components: - type: string - type: array - type: object + description: >- + List of generated synthetic data samples that passed the filtering criteria statistics: type: object additionalProperties: @@ -11308,6 +12514,9 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Statistical information about the generation process and filtering + results additionalProperties: false required: - synthetic_data @@ -11320,10 +12529,12 @@ components: properties: version: type: string + description: Version number of the service additionalProperties: false required: - version title: VersionInfo + description: Version information for the service. responses: BadRequest400: description: The request was invalid or malformed diff --git a/llama_stack/apis/agents/agents.py b/llama_stack/apis/agents/agents.py index 64b162e9e..e816da766 100644 --- a/llama_stack/apis/agents/agents.py +++ b/llama_stack/apis/agents/agents.py @@ -152,7 +152,17 @@ Step = Annotated[ @json_schema_type class Turn(BaseModel): - """A single turn in an interaction with an Agentic System.""" + """A single turn in an interaction with an Agentic System. + + :param turn_id: Unique identifier for the turn within a session + :param session_id: Unique identifier for the conversation session + :param input_messages: List of messages that initiated this turn + :param steps: Ordered list of processing steps executed during this turn + :param output_message: The model's generated response containing content and metadata + :param output_attachments: (Optional) Files or media attached to the agent's response + :param started_at: Timestamp when the turn began + :param completed_at: (Optional) Timestamp when the turn finished, if completed + """ turn_id: str session_id: str @@ -167,7 +177,13 @@ class Turn(BaseModel): @json_schema_type class Session(BaseModel): - """A single session of an interaction with an Agentic System.""" + """A single session of an interaction with an Agentic System. + + :param session_id: Unique identifier for the conversation session + :param session_name: Human-readable name for the session + :param turns: List of all turns that have occurred in this session + :param started_at: Timestamp when the session was created + """ session_id: str session_name: str @@ -232,6 +248,13 @@ class AgentConfig(AgentConfigCommon): @json_schema_type class Agent(BaseModel): + """An agent instance with configuration and metadata. + + :param agent_id: Unique identifier for the agent + :param agent_config: Configuration settings for the agent + :param created_at: Timestamp when the agent was created + """ + agent_id: str agent_config: AgentConfig created_at: datetime @@ -253,6 +276,14 @@ class AgentTurnResponseEventType(StrEnum): @json_schema_type class AgentTurnResponseStepStartPayload(BaseModel): + """Payload for step start events in agent turn responses. + + :param event_type: Type of event being reported + :param step_type: Type of step being executed + :param step_id: Unique identifier for the step within a turn + :param metadata: (Optional) Additional metadata for the step + """ + event_type: Literal[AgentTurnResponseEventType.step_start] = AgentTurnResponseEventType.step_start step_type: StepType step_id: str @@ -261,6 +292,14 @@ class AgentTurnResponseStepStartPayload(BaseModel): @json_schema_type class AgentTurnResponseStepCompletePayload(BaseModel): + """Payload for step completion events in agent turn responses. + + :param event_type: Type of event being reported + :param step_type: Type of step being executed + :param step_id: Unique identifier for the step within a turn + :param step_details: Complete details of the executed step + """ + event_type: Literal[AgentTurnResponseEventType.step_complete] = AgentTurnResponseEventType.step_complete step_type: StepType step_id: str @@ -269,6 +308,14 @@ class AgentTurnResponseStepCompletePayload(BaseModel): @json_schema_type class AgentTurnResponseStepProgressPayload(BaseModel): + """Payload for step progress events in agent turn responses. + + :param event_type: Type of event being reported + :param step_type: Type of step being executed + :param step_id: Unique identifier for the step within a turn + :param delta: Incremental content changes during step execution + """ + model_config = ConfigDict(protected_namespaces=()) event_type: Literal[AgentTurnResponseEventType.step_progress] = AgentTurnResponseEventType.step_progress @@ -280,18 +327,36 @@ class AgentTurnResponseStepProgressPayload(BaseModel): @json_schema_type class AgentTurnResponseTurnStartPayload(BaseModel): + """Payload for turn start events in agent turn responses. + + :param event_type: Type of event being reported + :param turn_id: Unique identifier for the turn within a session + """ + event_type: Literal[AgentTurnResponseEventType.turn_start] = AgentTurnResponseEventType.turn_start turn_id: str @json_schema_type class AgentTurnResponseTurnCompletePayload(BaseModel): + """Payload for turn completion events in agent turn responses. + + :param event_type: Type of event being reported + :param turn: Complete turn data including all steps and results + """ + event_type: Literal[AgentTurnResponseEventType.turn_complete] = AgentTurnResponseEventType.turn_complete turn: Turn @json_schema_type class AgentTurnResponseTurnAwaitingInputPayload(BaseModel): + """Payload for turn awaiting input events in agent turn responses. + + :param event_type: Type of event being reported + :param turn: Turn data when waiting for external tool responses + """ + event_type: Literal[AgentTurnResponseEventType.turn_awaiting_input] = AgentTurnResponseEventType.turn_awaiting_input turn: Turn @@ -310,21 +375,47 @@ register_schema(AgentTurnResponseEventPayload, name="AgentTurnResponseEventPaylo @json_schema_type class AgentTurnResponseEvent(BaseModel): + """An event in an agent turn response stream. + + :param payload: Event-specific payload containing event data + """ + payload: AgentTurnResponseEventPayload @json_schema_type class AgentCreateResponse(BaseModel): + """Response returned when creating a new agent. + + :param agent_id: Unique identifier for the created agent + """ + agent_id: str @json_schema_type class AgentSessionCreateResponse(BaseModel): + """Response returned when creating a new agent session. + + :param session_id: Unique identifier for the created session + """ + session_id: str @json_schema_type class AgentTurnCreateRequest(AgentConfigOverridablePerTurn): + """Request to create a new turn for an agent. + + :param agent_id: Unique identifier for the agent + :param session_id: Unique identifier for the conversation session + :param messages: List of messages to start the turn with + :param documents: (Optional) List of documents to provide to the agent + :param toolgroups: (Optional) List of tool groups to make available for this turn + :param stream: (Optional) Whether to stream the response + :param tool_config: (Optional) Tool configuration to override agent defaults + """ + agent_id: str session_id: str @@ -342,6 +433,15 @@ class AgentTurnCreateRequest(AgentConfigOverridablePerTurn): @json_schema_type class AgentTurnResumeRequest(BaseModel): + """Request to resume an agent turn with tool responses. + + :param agent_id: Unique identifier for the agent + :param session_id: Unique identifier for the conversation session + :param turn_id: Unique identifier for the turn within a session + :param tool_responses: List of tool responses to submit to continue the turn + :param stream: (Optional) Whether to stream the response + """ + agent_id: str session_id: str turn_id: str @@ -351,13 +451,21 @@ class AgentTurnResumeRequest(BaseModel): @json_schema_type class AgentTurnResponseStreamChunk(BaseModel): - """streamed agent turn completion response.""" + """Streamed agent turn completion response. + + :param event: Individual event in the agent turn response stream + """ event: AgentTurnResponseEvent @json_schema_type class AgentStepResponse(BaseModel): + """Response containing details of a specific agent step. + + :param step: The complete step data and execution details + """ + step: Step diff --git a/llama_stack/apis/agents/openai_responses.py b/llama_stack/apis/agents/openai_responses.py index 10843a3fe..10cadf38f 100644 --- a/llama_stack/apis/agents/openai_responses.py +++ b/llama_stack/apis/agents/openai_responses.py @@ -18,18 +18,37 @@ from llama_stack.schema_utils import json_schema_type, register_schema @json_schema_type class OpenAIResponseError(BaseModel): + """Error details for failed OpenAI response requests. + + :param code: Error code identifying the type of failure + :param message: Human-readable error message describing the failure + """ + code: str message: str @json_schema_type class OpenAIResponseInputMessageContentText(BaseModel): + """Text content for input messages in OpenAI response format. + + :param text: The text content of the input message + :param type: Content type identifier, always "input_text" + """ + text: str type: Literal["input_text"] = "input_text" @json_schema_type class OpenAIResponseInputMessageContentImage(BaseModel): + """Image content for input messages in OpenAI response format. + + :param detail: Level of detail for image processing, can be "low", "high", or "auto" + :param type: Content type identifier, always "input_image" + :param image_url: (Optional) URL of the image content + """ + detail: Literal["low"] | Literal["high"] | Literal["auto"] = "auto" type: Literal["input_image"] = "input_image" # TODO: handle file_id @@ -46,6 +65,14 @@ register_schema(OpenAIResponseInputMessageContent, name="OpenAIResponseInputMess @json_schema_type class OpenAIResponseAnnotationFileCitation(BaseModel): + """File citation annotation for referencing specific files in response content. + + :param type: Annotation type identifier, always "file_citation" + :param file_id: Unique identifier of the referenced file + :param filename: Name of the referenced file + :param index: Position index of the citation within the content + """ + type: Literal["file_citation"] = "file_citation" file_id: str filename: str @@ -54,6 +81,15 @@ class OpenAIResponseAnnotationFileCitation(BaseModel): @json_schema_type class OpenAIResponseAnnotationCitation(BaseModel): + """URL citation annotation for referencing external web resources. + + :param type: Annotation type identifier, always "url_citation" + :param end_index: End position of the citation span in the content + :param start_index: Start position of the citation span in the content + :param title: Title of the referenced web resource + :param url: URL of the referenced web resource + """ + type: Literal["url_citation"] = "url_citation" end_index: int start_index: int @@ -122,6 +158,13 @@ class OpenAIResponseMessage(BaseModel): @json_schema_type class OpenAIResponseOutputMessageWebSearchToolCall(BaseModel): + """Web search tool call output message for OpenAI responses. + + :param id: Unique identifier for this tool call + :param status: Current status of the web search operation + :param type: Tool call type identifier, always "web_search_call" + """ + id: str status: str type: Literal["web_search_call"] = "web_search_call" @@ -129,6 +172,15 @@ class OpenAIResponseOutputMessageWebSearchToolCall(BaseModel): @json_schema_type class OpenAIResponseOutputMessageFileSearchToolCall(BaseModel): + """File search tool call output message for OpenAI responses. + + :param id: Unique identifier for this tool call + :param queries: List of search queries executed + :param status: Current status of the file search operation + :param type: Tool call type identifier, always "file_search_call" + :param results: (Optional) Search results returned by the file search operation + """ + id: str queries: list[str] status: str @@ -138,6 +190,16 @@ class OpenAIResponseOutputMessageFileSearchToolCall(BaseModel): @json_schema_type class OpenAIResponseOutputMessageFunctionToolCall(BaseModel): + """Function tool call output message for OpenAI responses. + + :param call_id: Unique identifier for the function call + :param name: Name of the function being called + :param arguments: JSON string containing the function arguments + :param type: Tool call type identifier, always "function_call" + :param id: (Optional) Additional identifier for the tool call + :param status: (Optional) Current status of the function call execution + """ + call_id: str name: str arguments: str @@ -148,6 +210,17 @@ class OpenAIResponseOutputMessageFunctionToolCall(BaseModel): @json_schema_type class OpenAIResponseOutputMessageMCPCall(BaseModel): + """Model Context Protocol (MCP) call output message for OpenAI responses. + + :param id: Unique identifier for this MCP call + :param type: Tool call type identifier, always "mcp_call" + :param arguments: JSON string containing the MCP call arguments + :param name: Name of the MCP method being called + :param server_label: Label identifying the MCP server handling the call + :param error: (Optional) Error message if the MCP call failed + :param output: (Optional) Output result from the successful MCP call + """ + id: str type: Literal["mcp_call"] = "mcp_call" arguments: str @@ -158,6 +231,13 @@ class OpenAIResponseOutputMessageMCPCall(BaseModel): class MCPListToolsTool(BaseModel): + """Tool definition returned by MCP list tools operation. + + :param input_schema: JSON schema defining the tool's input parameters + :param name: Name of the tool + :param description: (Optional) Description of what the tool does + """ + input_schema: dict[str, Any] name: str description: str | None = None @@ -165,6 +245,14 @@ class MCPListToolsTool(BaseModel): @json_schema_type class OpenAIResponseOutputMessageMCPListTools(BaseModel): + """MCP list tools output message containing available tools from an MCP server. + + :param id: Unique identifier for this MCP list tools operation + :param type: Tool call type identifier, always "mcp_list_tools" + :param server_label: Label identifying the MCP server providing the tools + :param tools: List of available tools provided by the MCP server + """ + id: str type: Literal["mcp_list_tools"] = "mcp_list_tools" server_label: str @@ -206,11 +294,34 @@ class OpenAIResponseTextFormat(TypedDict, total=False): @json_schema_type class OpenAIResponseText(BaseModel): + """Text response configuration for OpenAI responses. + + :param format: (Optional) Text format configuration specifying output format requirements + """ + format: OpenAIResponseTextFormat | None = None @json_schema_type class OpenAIResponseObject(BaseModel): + """Complete OpenAI response object containing generation results and metadata. + + :param created_at: Unix timestamp when the response was created + :param error: (Optional) Error details if the response generation failed + :param id: Unique identifier for this response + :param model: Model identifier used for generation + :param object: Object type identifier, always "response" + :param output: List of generated output items (messages, tool calls, etc.) + :param parallel_tool_calls: Whether tool calls can be executed in parallel + :param previous_response_id: (Optional) ID of the previous response in a conversation + :param status: Current status of the response generation + :param temperature: (Optional) Sampling temperature used for generation + :param text: Text formatting configuration for the response + :param top_p: (Optional) Nucleus sampling parameter used for generation + :param truncation: (Optional) Truncation strategy applied to the response + :param user: (Optional) User identifier associated with the request + """ + created_at: int error: OpenAIResponseError | None = None id: str @@ -231,6 +342,13 @@ class OpenAIResponseObject(BaseModel): @json_schema_type class OpenAIDeleteResponseObject(BaseModel): + """Response object confirming deletion of an OpenAI response. + + :param id: Unique identifier of the deleted response + :param object: Object type identifier, always "response" + :param deleted: Deletion confirmation flag, always True + """ + id: str object: Literal["response"] = "response" deleted: bool = True @@ -238,18 +356,39 @@ class OpenAIDeleteResponseObject(BaseModel): @json_schema_type class OpenAIResponseObjectStreamResponseCreated(BaseModel): + """Streaming event indicating a new response has been created. + + :param response: The newly created response object + :param type: Event type identifier, always "response.created" + """ + response: OpenAIResponseObject type: Literal["response.created"] = "response.created" @json_schema_type class OpenAIResponseObjectStreamResponseCompleted(BaseModel): + """Streaming event indicating a response has been completed. + + :param response: The completed response object + :param type: Event type identifier, always "response.completed" + """ + response: OpenAIResponseObject type: Literal["response.completed"] = "response.completed" @json_schema_type class OpenAIResponseObjectStreamResponseOutputItemAdded(BaseModel): + """Streaming event for when a new output item is added to the response. + + :param response_id: Unique identifier of the response containing this output + :param item: The output item that was added (message, tool call, etc.) + :param output_index: Index position of this item in the output list + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.output_item.added" + """ + response_id: str item: OpenAIResponseOutput output_index: int @@ -259,6 +398,15 @@ class OpenAIResponseObjectStreamResponseOutputItemAdded(BaseModel): @json_schema_type class OpenAIResponseObjectStreamResponseOutputItemDone(BaseModel): + """Streaming event for when an output item is completed. + + :param response_id: Unique identifier of the response containing this output + :param item: The completed output item (message, tool call, etc.) + :param output_index: Index position of this item in the output list + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.output_item.done" + """ + response_id: str item: OpenAIResponseOutput output_index: int @@ -268,6 +416,16 @@ class OpenAIResponseObjectStreamResponseOutputItemDone(BaseModel): @json_schema_type class OpenAIResponseObjectStreamResponseOutputTextDelta(BaseModel): + """Streaming event for incremental text content updates. + + :param content_index: Index position within the text content + :param delta: Incremental text content being added + :param item_id: Unique identifier of the output item being updated + :param output_index: Index position of the item in the output list + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.output_text.delta" + """ + content_index: int delta: str item_id: str @@ -278,6 +436,16 @@ class OpenAIResponseObjectStreamResponseOutputTextDelta(BaseModel): @json_schema_type class OpenAIResponseObjectStreamResponseOutputTextDone(BaseModel): + """Streaming event for when text output is completed. + + :param content_index: Index position within the text content + :param text: Final complete text content of the output item + :param item_id: Unique identifier of the completed output item + :param output_index: Index position of the item in the output list + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.output_text.done" + """ + content_index: int text: str # final text of the output item item_id: str @@ -288,6 +456,15 @@ class OpenAIResponseObjectStreamResponseOutputTextDone(BaseModel): @json_schema_type class OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta(BaseModel): + """Streaming event for incremental function call argument updates. + + :param delta: Incremental function call arguments being added + :param item_id: Unique identifier of the function call being updated + :param output_index: Index position of the item in the output list + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.function_call_arguments.delta" + """ + delta: str item_id: str output_index: int @@ -297,6 +474,15 @@ class OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta(BaseModel): @json_schema_type class OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone(BaseModel): + """Streaming event for when function call arguments are completed. + + :param arguments: Final complete arguments JSON string for the function call + :param item_id: Unique identifier of the completed function call + :param output_index: Index position of the item in the output list + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.function_call_arguments.done" + """ + arguments: str # final arguments of the function call item_id: str output_index: int @@ -306,6 +492,14 @@ class OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone(BaseModel): @json_schema_type class OpenAIResponseObjectStreamResponseWebSearchCallInProgress(BaseModel): + """Streaming event for web search calls in progress. + + :param item_id: Unique identifier of the web search call + :param output_index: Index position of the item in the output list + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.web_search_call.in_progress" + """ + item_id: str output_index: int sequence_number: int @@ -322,6 +516,14 @@ class OpenAIResponseObjectStreamResponseWebSearchCallSearching(BaseModel): @json_schema_type class OpenAIResponseObjectStreamResponseWebSearchCallCompleted(BaseModel): + """Streaming event for completed web search calls. + + :param item_id: Unique identifier of the completed web search call + :param output_index: Index position of the item in the output list + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.web_search_call.completed" + """ + item_id: str output_index: int sequence_number: int @@ -366,6 +568,14 @@ class OpenAIResponseObjectStreamResponseMcpCallArgumentsDone(BaseModel): @json_schema_type class OpenAIResponseObjectStreamResponseMcpCallInProgress(BaseModel): + """Streaming event for MCP calls in progress. + + :param item_id: Unique identifier of the MCP call + :param output_index: Index position of the item in the output list + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.mcp_call.in_progress" + """ + item_id: str output_index: int sequence_number: int @@ -374,12 +584,24 @@ class OpenAIResponseObjectStreamResponseMcpCallInProgress(BaseModel): @json_schema_type class OpenAIResponseObjectStreamResponseMcpCallFailed(BaseModel): + """Streaming event for failed MCP calls. + + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.mcp_call.failed" + """ + sequence_number: int type: Literal["response.mcp_call.failed"] = "response.mcp_call.failed" @json_schema_type class OpenAIResponseObjectStreamResponseMcpCallCompleted(BaseModel): + """Streaming event for completed MCP calls. + + :param sequence_number: Sequential number for ordering streaming events + :param type: Event type identifier, always "response.mcp_call.completed" + """ + sequence_number: int type: Literal["response.mcp_call.completed"] = "response.mcp_call.completed" @@ -442,6 +664,12 @@ WebSearchToolTypes = ["web_search", "web_search_preview", "web_search_preview_20 @json_schema_type class OpenAIResponseInputToolWebSearch(BaseModel): + """Web search tool configuration for OpenAI response inputs. + + :param type: Web search tool type variant to use + :param search_context_size: (Optional) Size of search context, must be "low", "medium", or "high" + """ + # Must match values of WebSearchToolTypes above type: Literal["web_search"] | Literal["web_search_preview"] | Literal["web_search_preview_2025_03_11"] = ( "web_search" @@ -453,6 +681,15 @@ class OpenAIResponseInputToolWebSearch(BaseModel): @json_schema_type class OpenAIResponseInputToolFunction(BaseModel): + """Function tool configuration for OpenAI response inputs. + + :param type: Tool type identifier, always "function" + :param name: Name of the function that can be called + :param description: (Optional) Description of what the function does + :param parameters: (Optional) JSON schema defining the function's parameters + :param strict: (Optional) Whether to enforce strict parameter validation + """ + type: Literal["function"] = "function" name: str description: str | None = None @@ -462,6 +699,15 @@ class OpenAIResponseInputToolFunction(BaseModel): @json_schema_type class OpenAIResponseInputToolFileSearch(BaseModel): + """File search tool configuration for OpenAI response inputs. + + :param type: Tool type identifier, always "file_search" + :param vector_store_ids: List of vector store identifiers to search within + :param filters: (Optional) Additional filters to apply to the search + :param max_num_results: (Optional) Maximum number of search results to return (1-50) + :param ranking_options: (Optional) Options for ranking and scoring search results + """ + type: Literal["file_search"] = "file_search" vector_store_ids: list[str] filters: dict[str, Any] | None = None @@ -470,16 +716,37 @@ class OpenAIResponseInputToolFileSearch(BaseModel): class ApprovalFilter(BaseModel): + """Filter configuration for MCP tool approval requirements. + + :param always: (Optional) List of tool names that always require approval + :param never: (Optional) List of tool names that never require approval + """ + always: list[str] | None = None never: list[str] | None = None class AllowedToolsFilter(BaseModel): + """Filter configuration for restricting which MCP tools can be used. + + :param tool_names: (Optional) List of specific tool names that are allowed + """ + tool_names: list[str] | None = None @json_schema_type class OpenAIResponseInputToolMCP(BaseModel): + """Model Context Protocol (MCP) tool configuration for OpenAI response inputs. + + :param type: Tool type identifier, always "mcp" + :param server_label: Label to identify this MCP server + :param server_url: URL endpoint of the MCP server + :param headers: (Optional) HTTP headers to include when connecting to the server + :param require_approval: Approval requirement for tool calls ("always", "never", or filter) + :param allowed_tools: (Optional) Restriction on which tools can be used from this server + """ + type: Literal["mcp"] = "mcp" server_label: str server_url: str @@ -500,17 +767,37 @@ register_schema(OpenAIResponseInputTool, name="OpenAIResponseInputTool") class ListOpenAIResponseInputItem(BaseModel): + """List container for OpenAI response input items. + + :param data: List of input items + :param object: Object type identifier, always "list" + """ + data: list[OpenAIResponseInput] object: Literal["list"] = "list" @json_schema_type class OpenAIResponseObjectWithInput(OpenAIResponseObject): + """OpenAI response object extended with input context information. + + :param input: List of input items that led to this response + """ + input: list[OpenAIResponseInput] @json_schema_type class ListOpenAIResponseObject(BaseModel): + """Paginated list of OpenAI response objects with navigation metadata. + + :param data: List of response objects with their input context + :param has_more: Whether there are more results available beyond this page + :param first_id: Identifier of the first item in this page + :param last_id: Identifier of the last item in this page + :param object: Object type identifier, always "list" + """ + data: list[OpenAIResponseObjectWithInput] has_more: bool first_id: str diff --git a/llama_stack/apis/benchmarks/benchmarks.py b/llama_stack/apis/benchmarks/benchmarks.py index d80c767f8..706eaed6c 100644 --- a/llama_stack/apis/benchmarks/benchmarks.py +++ b/llama_stack/apis/benchmarks/benchmarks.py @@ -22,6 +22,14 @@ class CommonBenchmarkFields(BaseModel): @json_schema_type class Benchmark(CommonBenchmarkFields, Resource): + """A benchmark resource for evaluating model performance. + + :param dataset_id: Identifier of the dataset to use for the benchmark evaluation + :param scoring_functions: List of scoring function identifiers to apply during evaluation + :param metadata: Metadata for this evaluation task + :param type: The resource type, always benchmark + """ + type: Literal[ResourceType.benchmark] = ResourceType.benchmark @property diff --git a/llama_stack/apis/common/content_types.py b/llama_stack/apis/common/content_types.py index 8bcb781f7..950dd17ff 100644 --- a/llama_stack/apis/common/content_types.py +++ b/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 diff --git a/llama_stack/apis/common/job_types.py b/llama_stack/apis/common/job_types.py index ca6bcaf63..5da42bfd3 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,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 diff --git a/llama_stack/apis/common/responses.py b/llama_stack/apis/common/responses.py index e4cf21a54..616bee73a 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 a2c3b78f1..5c236a25d 100644 --- a/llama_stack/apis/common/training_types.py +++ b/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 diff --git a/llama_stack/apis/common/type_system.py b/llama_stack/apis/common/type_system.py index db4aab4c5..0e62ee484 100644 --- a/llama_stack/apis/common/type_system.py +++ b/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" diff --git a/llama_stack/apis/datasets/datasets.py b/llama_stack/apis/datasets/datasets.py index 8bf7a48d0..f347e0e29 100644 --- a/llama_stack/apis/datasets/datasets.py +++ b/llama_stack/apis/datasets/datasets.py @@ -94,6 +94,10 @@ register_schema(DataSource, name="DataSource") class CommonDatasetFields(BaseModel): """ Common fields for a dataset. + + :param purpose: Purpose of the dataset indicating its intended use + :param source: Data source configuration for the dataset + :param metadata: Additional metadata for the dataset """ purpose: DatasetPurpose @@ -106,6 +110,11 @@ class CommonDatasetFields(BaseModel): @json_schema_type class Dataset(CommonDatasetFields, Resource): + """Dataset resource for storing and accessing training or evaluation data. + + :param type: Type of resource, always 'dataset' for datasets + """ + type: Literal[ResourceType.dataset] = ResourceType.dataset @property @@ -118,10 +127,20 @@ class Dataset(CommonDatasetFields, Resource): class DatasetInput(CommonDatasetFields, BaseModel): + """Input parameters for dataset operations. + + :param dataset_id: Unique identifier for the dataset + """ + dataset_id: str class ListDatasetsResponse(BaseModel): + """Response from listing datasets. + + :param data: List of datasets + """ + data: list[Dataset] diff --git a/llama_stack/apis/datatypes.py b/llama_stack/apis/datatypes.py index e6628f5d7..cabe46a2f 100644 --- a/llama_stack/apis/datatypes.py +++ b/llama_stack/apis/datatypes.py @@ -81,6 +81,29 @@ class DynamicApiMeta(EnumMeta): @json_schema_type class Api(Enum, metaclass=DynamicApiMeta): + """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" diff --git a/llama_stack/apis/files/files.py b/llama_stack/apis/files/files.py index a72dcd8d4..ba8701e23 100644 --- a/llama_stack/apis/files/files.py +++ b/llama_stack/apis/files/files.py @@ -54,6 +54,9 @@ class ListOpenAIFileResponse(BaseModel): Response for listing files in OpenAI Files API. :param data: List of file objects + :param has_more: Whether there are more files available beyond this page + :param first_id: ID of the first file in the list for pagination + :param last_id: ID of the last file in the list for pagination :param object: The object type, which is always "list" """ diff --git a/llama_stack/apis/inference/inference.py b/llama_stack/apis/inference/inference.py index aabb41839..7e7bd0a3d 100644 --- a/llama_stack/apis/inference/inference.py +++ b/llama_stack/apis/inference/inference.py @@ -41,11 +41,23 @@ from enum import StrEnum @json_schema_type class GreedySamplingStrategy(BaseModel): + """Greedy sampling strategy that selects the highest probability token at each step. + + :param type: Must be "greedy" to identify this sampling strategy + """ + type: Literal["greedy"] = "greedy" @json_schema_type class TopPSamplingStrategy(BaseModel): + """Top-p (nucleus) sampling strategy that samples from the smallest set of tokens with cumulative probability >= p. + + :param type: Must be "top_p" to identify this sampling strategy + :param temperature: Controls randomness in sampling. Higher values increase randomness + :param top_p: Cumulative probability threshold for nucleus sampling. Defaults to 0.95 + """ + type: Literal["top_p"] = "top_p" temperature: float | None = Field(..., gt=0.0) top_p: float | None = 0.95 @@ -53,6 +65,12 @@ class TopPSamplingStrategy(BaseModel): @json_schema_type class TopKSamplingStrategy(BaseModel): + """Top-k sampling strategy that restricts sampling to the k most likely tokens. + + :param type: Must be "top_k" to identify this sampling strategy + :param top_k: Number of top tokens to consider for sampling. Must be at least 1 + """ + type: Literal["top_k"] = "top_k" top_k: int = Field(..., ge=1) @@ -108,11 +126,21 @@ class QuantizationType(Enum): @json_schema_type class Fp8QuantizationConfig(BaseModel): + """Configuration for 8-bit floating point quantization. + + :param type: Must be "fp8_mixed" to identify this quantization type + """ + type: Literal["fp8_mixed"] = "fp8_mixed" @json_schema_type class Bf16QuantizationConfig(BaseModel): + """Configuration for BFloat16 precision (typically no quantization). + + :param type: Must be "bf16" to identify this quantization type + """ + type: Literal["bf16"] = "bf16" @@ -202,6 +230,14 @@ register_schema(Message, name="Message") @json_schema_type class ToolResponse(BaseModel): + """Response from a tool invocation. + + :param call_id: Unique identifier for the tool call this response is for + :param tool_name: Name of the tool that was invoked + :param content: The response content from the tool + :param metadata: (Optional) Additional metadata about the tool response + """ + call_id: str tool_name: BuiltinTool | str content: InterleavedContent @@ -439,18 +475,36 @@ class EmbeddingsResponse(BaseModel): @json_schema_type class OpenAIChatCompletionContentPartTextParam(BaseModel): + """Text content part for OpenAI-compatible chat completion messages. + + :param type: Must be "text" to identify this as text content + :param text: The text content of the message + """ + type: Literal["text"] = "text" text: str @json_schema_type class OpenAIImageURL(BaseModel): + """Image URL specification for OpenAI-compatible chat completion messages. + + :param url: URL of the image to include in the message + :param detail: (Optional) Level of detail for image processing. Can be "low", "high", or "auto" + """ + url: str detail: str | None = None @json_schema_type class OpenAIChatCompletionContentPartImageParam(BaseModel): + """Image content part for OpenAI-compatible chat completion messages. + + :param type: Must be "image_url" to identify this as image content + :param image_url: Image URL specification and processing details + """ + type: Literal["image_url"] = "image_url" image_url: OpenAIImageURL @@ -510,12 +564,26 @@ class OpenAISystemMessageParam(BaseModel): @json_schema_type class OpenAIChatCompletionToolCallFunction(BaseModel): + """Function call details for OpenAI-compatible tool calls. + + :param name: (Optional) Name of the function to call + :param arguments: (Optional) Arguments to pass to the function as a JSON string + """ + name: str | None = None arguments: str | None = None @json_schema_type class OpenAIChatCompletionToolCall(BaseModel): + """Tool call specification for OpenAI-compatible chat completion responses. + + :param index: (Optional) Index of the tool call in the list + :param id: (Optional) Unique identifier for the tool call + :param type: Must be "function" to identify this as a function call + :param function: (Optional) Function call details + """ + index: int | None = None id: str | None = None type: Literal["function"] = "function" @@ -579,11 +647,24 @@ register_schema(OpenAIMessageParam, name="OpenAIMessageParam") @json_schema_type class OpenAIResponseFormatText(BaseModel): + """Text response format for OpenAI-compatible chat completion requests. + + :param type: Must be "text" to indicate plain text response format + """ + type: Literal["text"] = "text" @json_schema_type class OpenAIJSONSchema(TypedDict, total=False): + """JSON schema specification for OpenAI-compatible structured response format. + + :param name: Name of the schema + :param description: (Optional) Description of the schema + :param strict: (Optional) Whether to enforce strict adherence to the schema + :param schema: (Optional) The JSON schema definition + """ + name: str description: str | None strict: bool | None @@ -597,12 +678,23 @@ class OpenAIJSONSchema(TypedDict, total=False): @json_schema_type class OpenAIResponseFormatJSONSchema(BaseModel): + """JSON schema response format for OpenAI-compatible chat completion requests. + + :param type: Must be "json_schema" to indicate structured JSON response format + :param json_schema: The JSON schema specification for the response + """ + type: Literal["json_schema"] = "json_schema" json_schema: OpenAIJSONSchema @json_schema_type class OpenAIResponseFormatJSONObject(BaseModel): + """JSON object response format for OpenAI-compatible chat completion requests. + + :param type: Must be "json_object" to indicate generic JSON object response format + """ + type: Literal["json_object"] = "json_object" @@ -861,11 +953,21 @@ class EmbeddingTaskType(Enum): @json_schema_type class BatchCompletionResponse(BaseModel): + """Response from a batch completion request. + + :param batch: List of completion responses, one for each input in the batch + """ + batch: list[CompletionResponse] @json_schema_type class BatchChatCompletionResponse(BaseModel): + """Response from a batch chat completion request. + + :param batch: List of chat completion responses, one for each conversation in the batch + """ + batch: list[ChatCompletionResponse] @@ -875,6 +977,15 @@ class OpenAICompletionWithInputMessages(OpenAIChatCompletion): @json_schema_type class ListOpenAIChatCompletionResponse(BaseModel): + """Response from listing OpenAI-compatible chat completions. + + :param data: List of chat completion objects with their input messages + :param has_more: Whether there are more completions available beyond this list + :param first_id: ID of the first completion in this list + :param last_id: ID of the last completion in this list + :param object: Must be "list" to identify this as a list response + """ + data: list[OpenAICompletionWithInputMessages] has_more: bool first_id: str diff --git a/llama_stack/apis/inspect/inspect.py b/llama_stack/apis/inspect/inspect.py index 44a5e95b2..91d9c3da7 100644 --- a/llama_stack/apis/inspect/inspect.py +++ b/llama_stack/apis/inspect/inspect.py @@ -14,6 +14,13 @@ from llama_stack.schema_utils import json_schema_type, webmethod @json_schema_type class RouteInfo(BaseModel): + """Information about an API route including its path, method, and implementing providers. + + :param route: The API endpoint path + :param method: HTTP method for the route + :param provider_types: List of provider types that implement this route + """ + route: str method: str provider_types: list[str] @@ -21,15 +28,30 @@ class RouteInfo(BaseModel): @json_schema_type class HealthInfo(BaseModel): + """Health status information for the service. + + :param status: Current health status of the service + """ + status: HealthStatus @json_schema_type class VersionInfo(BaseModel): + """Version information for the service. + + :param version: Version number of the service + """ + version: str class ListRoutesResponse(BaseModel): + """Response containing a list of all available API routes. + + :param data: List of available route information objects + """ + data: list[RouteInfo] @@ -37,17 +59,17 @@ class ListRoutesResponse(BaseModel): class Inspect(Protocol): @webmethod(route="/inspect/routes", method="GET") async def list_routes(self) -> ListRoutesResponse: - """List all routes. + """List all available API routes with their methods and implementing providers. - :returns: A ListRoutesResponse. + :returns: Response containing information about all available routes. """ ... @webmethod(route="/health", method="GET") async def health(self) -> HealthInfo: - """Get the health of the service. + """Get the current health status of the service. - :returns: A HealthInfo. + :returns: Health information indicating if the service is operational. """ ... @@ -55,6 +77,6 @@ class Inspect(Protocol): async def version(self) -> VersionInfo: """Get the version of the service. - :returns: A VersionInfo. + :returns: Version information containing the service version number. """ ... diff --git a/llama_stack/apis/models/models.py b/llama_stack/apis/models/models.py index 2143346d9..1af6fc9df 100644 --- a/llama_stack/apis/models/models.py +++ b/llama_stack/apis/models/models.py @@ -23,12 +23,27 @@ class CommonModelFields(BaseModel): @json_schema_type class ModelType(StrEnum): + """Enumeration of supported model types in Llama Stack. + :cvar llm: Large language model for text generation and completion + :cvar embedding: Embedding model for converting text to vector representations + """ + llm = "llm" embedding = "embedding" @json_schema_type class Model(CommonModelFields, Resource): + """A model resource representing an AI model registered in Llama Stack. + + :param type: The resource type, always 'model' for model resources + :param model_type: The type of model (LLM or embedding model) + :param metadata: Any additional metadata for this model + :param identifier: Unique identifier for this resource in llama stack + :param provider_resource_id: Unique identifier for this resource in the provider + :param provider_id: ID of the provider that owns this resource + """ + type: Literal[ResourceType.model] = ResourceType.model @property diff --git a/llama_stack/apis/post_training/post_training.py b/llama_stack/apis/post_training/post_training.py index f6860ea4b..9170cba51 100644 --- a/llama_stack/apis/post_training/post_training.py +++ b/llama_stack/apis/post_training/post_training.py @@ -18,6 +18,12 @@ from llama_stack.schema_utils import json_schema_type, register_schema, webmetho @json_schema_type class OptimizerType(Enum): + """Available optimizer algorithms for training. + :cvar adam: Adaptive Moment Estimation optimizer + :cvar adamw: AdamW optimizer with weight decay + :cvar sgd: Stochastic Gradient Descent optimizer + """ + adam = "adam" adamw = "adamw" sgd = "sgd" @@ -25,12 +31,28 @@ class OptimizerType(Enum): @json_schema_type class DatasetFormat(Enum): + """Format of the training dataset. + :cvar instruct: Instruction-following format with prompt and completion + :cvar dialog: Multi-turn conversation format with messages + """ + instruct = "instruct" dialog = "dialog" @json_schema_type class DataConfig(BaseModel): + """Configuration for training data and data loading. + + :param dataset_id: Unique identifier for the training dataset + :param batch_size: Number of samples per training batch + :param shuffle: Whether to shuffle the dataset during training + :param data_format: Format of the dataset (instruct or dialog) + :param validation_dataset_id: (Optional) Unique identifier for the validation dataset + :param packed: (Optional) Whether to pack multiple samples into a single sequence for efficiency + :param train_on_input: (Optional) Whether to compute loss on input tokens as well as output tokens + """ + dataset_id: str batch_size: int shuffle: bool @@ -42,6 +64,14 @@ class DataConfig(BaseModel): @json_schema_type class OptimizerConfig(BaseModel): + """Configuration parameters for the optimization algorithm. + + :param optimizer_type: Type of optimizer to use (adam, adamw, or sgd) + :param lr: Learning rate for the optimizer + :param weight_decay: Weight decay coefficient for regularization + :param num_warmup_steps: Number of steps for learning rate warmup + """ + optimizer_type: OptimizerType lr: float weight_decay: float @@ -50,6 +80,14 @@ class OptimizerConfig(BaseModel): @json_schema_type class EfficiencyConfig(BaseModel): + """Configuration for memory and compute efficiency optimizations. + + :param enable_activation_checkpointing: (Optional) Whether to use activation checkpointing to reduce memory usage + :param enable_activation_offloading: (Optional) Whether to offload activations to CPU to save GPU memory + :param memory_efficient_fsdp_wrap: (Optional) Whether to use memory-efficient FSDP wrapping + :param fsdp_cpu_offload: (Optional) Whether to offload FSDP parameters to CPU + """ + enable_activation_checkpointing: bool | None = False enable_activation_offloading: bool | None = False memory_efficient_fsdp_wrap: bool | None = False @@ -58,6 +96,18 @@ class EfficiencyConfig(BaseModel): @json_schema_type class TrainingConfig(BaseModel): + """Comprehensive configuration for the training process. + + :param n_epochs: Number of training epochs to run + :param max_steps_per_epoch: Maximum number of steps to run per epoch + :param gradient_accumulation_steps: Number of steps to accumulate gradients before updating + :param max_validation_steps: (Optional) Maximum number of validation steps per epoch + :param data_config: (Optional) Configuration for data loading and formatting + :param optimizer_config: (Optional) Configuration for the optimization algorithm + :param efficiency_config: (Optional) Configuration for memory and compute optimizations + :param dtype: (Optional) Data type for model parameters (bf16, fp16, fp32) + """ + n_epochs: int max_steps_per_epoch: int = 1 gradient_accumulation_steps: int = 1 @@ -70,6 +120,18 @@ class TrainingConfig(BaseModel): @json_schema_type class LoraFinetuningConfig(BaseModel): + """Configuration for Low-Rank Adaptation (LoRA) fine-tuning. + + :param type: Algorithm type identifier, always "LoRA" + :param lora_attn_modules: List of attention module names to apply LoRA to + :param apply_lora_to_mlp: Whether to apply LoRA to MLP layers + :param apply_lora_to_output: Whether to apply LoRA to output projection layers + :param rank: Rank of the LoRA adaptation (lower rank = fewer parameters) + :param alpha: LoRA scaling parameter that controls adaptation strength + :param use_dora: (Optional) Whether to use DoRA (Weight-Decomposed Low-Rank Adaptation) + :param quantize_base: (Optional) Whether to quantize the base model weights + """ + type: Literal["LoRA"] = "LoRA" lora_attn_modules: list[str] apply_lora_to_mlp: bool @@ -82,6 +144,13 @@ class LoraFinetuningConfig(BaseModel): @json_schema_type class QATFinetuningConfig(BaseModel): + """Configuration for Quantization-Aware Training (QAT) fine-tuning. + + :param type: Algorithm type identifier, always "QAT" + :param quantizer_name: Name of the quantization algorithm to use + :param group_size: Size of groups for grouped quantization + """ + type: Literal["QAT"] = "QAT" quantizer_name: str group_size: int @@ -93,7 +162,11 @@ register_schema(AlgorithmConfig, name="AlgorithmConfig") @json_schema_type class PostTrainingJobLogStream(BaseModel): - """Stream of logs from a finetuning job.""" + """Stream of logs from a finetuning job. + + :param job_uuid: Unique identifier for the training job + :param log_lines: List of log message strings from the training process + """ job_uuid: str log_lines: list[str] @@ -101,6 +174,10 @@ class PostTrainingJobLogStream(BaseModel): @json_schema_type class RLHFAlgorithm(Enum): + """Available reinforcement learning from human feedback algorithms. + :cvar dpo: Direct Preference Optimization algorithm + """ + dpo = "dpo" @@ -114,13 +191,39 @@ class DPOLossType(Enum): @json_schema_type class DPOAlignmentConfig(BaseModel): + """Configuration for Direct Preference Optimization (DPO) alignment. + + :param reward_scale: Scaling factor for the reward signal + :param reward_clip: Maximum absolute value for reward clipping + :param epsilon: Small value added for numerical stability + :param gamma: Discount factor for future rewards + :param beta: Temperature parameter for the DPO loss + :param loss_type: The type of loss function to use for DPO + """ + + reward_scale: float + reward_clip: float + epsilon: float + gamma: float beta: float loss_type: DPOLossType = DPOLossType.sigmoid @json_schema_type class PostTrainingRLHFRequest(BaseModel): - """Request to finetune a model.""" + """Request to finetune a model using reinforcement learning from human feedback. + + :param job_uuid: Unique identifier for the training job + :param finetuned_model: URL or path to the base model to fine-tune + :param dataset_id: Unique identifier for the training dataset + :param validation_dataset_id: Unique identifier for the validation dataset + :param algorithm: RLHF algorithm to use for training + :param algorithm_config: Configuration parameters for the RLHF algorithm + :param optimizer_config: Configuration parameters for the optimization algorithm + :param training_config: Configuration parameters for the training process + :param hyperparam_search_config: Configuration for hyperparameter search + :param logger_config: Configuration for training logging + """ job_uuid: str @@ -146,7 +249,16 @@ class PostTrainingJob(BaseModel): @json_schema_type class PostTrainingJobStatusResponse(BaseModel): - """Status of a finetuning job.""" + """Status of a finetuning job. + + :param job_uuid: Unique identifier for the training job + :param status: Current status of the training job + :param scheduled_at: (Optional) Timestamp when the job was scheduled + :param started_at: (Optional) Timestamp when the job execution began + :param completed_at: (Optional) Timestamp when the job finished, if completed + :param resources_allocated: (Optional) Information about computational resources allocated to the job + :param checkpoints: List of model checkpoints created during training + """ job_uuid: str status: JobStatus @@ -166,7 +278,11 @@ class ListPostTrainingJobsResponse(BaseModel): @json_schema_type class PostTrainingJobArtifactsResponse(BaseModel): - """Artifacts of a finetuning job.""" + """Artifacts of a finetuning job. + + :param job_uuid: Unique identifier for the training job + :param checkpoints: List of model checkpoints created during training + """ job_uuid: str checkpoints: list[Checkpoint] = Field(default_factory=list) diff --git a/llama_stack/apis/providers/providers.py b/llama_stack/apis/providers/providers.py index 4bc977bf1..8a1e93d8f 100644 --- a/llama_stack/apis/providers/providers.py +++ b/llama_stack/apis/providers/providers.py @@ -14,6 +14,15 @@ from llama_stack.schema_utils import json_schema_type, webmethod @json_schema_type class ProviderInfo(BaseModel): + """Information about a registered provider including its configuration and health status. + + :param api: The API name this provider implements + :param provider_id: Unique identifier for the provider + :param provider_type: The type of provider implementation + :param config: Configuration parameters for the provider + :param health: Current health status of the provider + """ + api: str provider_id: str provider_type: str @@ -22,6 +31,11 @@ class ProviderInfo(BaseModel): class ListProvidersResponse(BaseModel): + """Response containing a list of all available providers. + + :param data: List of provider information objects + """ + data: list[ProviderInfo] diff --git a/llama_stack/apis/safety/safety.py b/llama_stack/apis/safety/safety.py index 3aee52b7e..468cfa63a 100644 --- a/llama_stack/apis/safety/safety.py +++ b/llama_stack/apis/safety/safety.py @@ -17,6 +17,13 @@ from llama_stack.schema_utils import json_schema_type, webmethod @json_schema_type class ViolationLevel(Enum): + """Severity level of a safety violation. + + :cvar INFO: Informational level violation that does not require action + :cvar WARN: Warning level violation that suggests caution but allows continuation + :cvar ERROR: Error level violation that requires blocking or intervention + """ + INFO = "info" WARN = "warn" ERROR = "error" @@ -24,6 +31,13 @@ class ViolationLevel(Enum): @json_schema_type class SafetyViolation(BaseModel): + """Details of a safety violation detected by content moderation. + + :param violation_level: Severity level of the violation + :param user_message: (Optional) Message to convey to the user about the violation + :param metadata: Additional metadata including specific violation codes for debugging and telemetry + """ + violation_level: ViolationLevel # what message should you convey to the user @@ -36,6 +50,11 @@ class SafetyViolation(BaseModel): @json_schema_type class RunShieldResponse(BaseModel): + """Response from running a safety shield. + + :param violation: (Optional) Safety violation detected by the shield, if any + """ + violation: SafetyViolation | None = None diff --git a/llama_stack/apis/scoring/scoring.py b/llama_stack/apis/scoring/scoring.py index 732e80e79..8ca599b44 100644 --- a/llama_stack/apis/scoring/scoring.py +++ b/llama_stack/apis/scoring/scoring.py @@ -31,6 +31,12 @@ class ScoringResult(BaseModel): @json_schema_type class ScoreBatchResponse(BaseModel): + """Response from batch scoring operations on datasets. + + :param dataset_id: (Optional) The identifier of the dataset that was scored + :param results: A map of scoring function name to ScoringResult + """ + dataset_id: str | None = None results: dict[str, ScoringResult] diff --git a/llama_stack/apis/scoring_functions/scoring_functions.py b/llama_stack/apis/scoring_functions/scoring_functions.py index 684041308..05b6325b7 100644 --- a/llama_stack/apis/scoring_functions/scoring_functions.py +++ b/llama_stack/apis/scoring_functions/scoring_functions.py @@ -25,6 +25,12 @@ from llama_stack.schema_utils import json_schema_type, register_schema, webmetho # with standard metrics so they can be rolled up? @json_schema_type class ScoringFnParamsType(StrEnum): + """Types of scoring function parameter configurations. + :cvar llm_as_judge: Use an LLM model to evaluate and score responses + :cvar regex_parser: Use regex patterns to extract and score specific parts of responses + :cvar basic: Basic scoring with simple aggregation functions + """ + llm_as_judge = "llm_as_judge" regex_parser = "regex_parser" basic = "basic" @@ -32,6 +38,14 @@ class ScoringFnParamsType(StrEnum): @json_schema_type class AggregationFunctionType(StrEnum): + """Types of aggregation functions for scoring results. + :cvar average: Calculate the arithmetic mean of scores + :cvar weighted_average: Calculate a weighted average of scores + :cvar median: Calculate the median value of scores + :cvar categorical_count: Count occurrences of categorical values + :cvar accuracy: Calculate accuracy as the proportion of correct answers + """ + average = "average" weighted_average = "weighted_average" median = "median" @@ -41,6 +55,14 @@ class AggregationFunctionType(StrEnum): @json_schema_type class LLMAsJudgeScoringFnParams(BaseModel): + """Parameters for LLM-as-judge scoring function configuration. + :param type: The type of scoring function parameters, always llm_as_judge + :param judge_model: Identifier of the LLM model to use as a judge for scoring + :param prompt_template: (Optional) Custom prompt template for the judge model + :param judge_score_regexes: Regexes to extract the answer from generated response + :param aggregation_functions: Aggregation functions to apply to the scores of each row + """ + type: Literal[ScoringFnParamsType.llm_as_judge] = ScoringFnParamsType.llm_as_judge judge_model: str prompt_template: str | None = None @@ -56,6 +78,12 @@ class LLMAsJudgeScoringFnParams(BaseModel): @json_schema_type class RegexParserScoringFnParams(BaseModel): + """Parameters for regex parser scoring function configuration. + :param type: The type of scoring function parameters, always regex_parser + :param parsing_regexes: Regex to extract the answer from generated response + :param aggregation_functions: Aggregation functions to apply to the scores of each row + """ + type: Literal[ScoringFnParamsType.regex_parser] = ScoringFnParamsType.regex_parser parsing_regexes: list[str] = Field( description="Regex to extract the answer from generated response", @@ -69,6 +97,11 @@ class RegexParserScoringFnParams(BaseModel): @json_schema_type class BasicScoringFnParams(BaseModel): + """Parameters for basic scoring function configuration. + :param type: The type of scoring function parameters, always basic + :param aggregation_functions: Aggregation functions to apply to the scores of each row + """ + type: Literal[ScoringFnParamsType.basic] = ScoringFnParamsType.basic aggregation_functions: list[AggregationFunctionType] = Field( description="Aggregation functions to apply to the scores of each row", @@ -100,6 +133,10 @@ class CommonScoringFnFields(BaseModel): @json_schema_type class ScoringFn(CommonScoringFnFields, Resource): + """A scoring function resource for evaluating model outputs. + :param type: The resource type, always scoring_function + """ + type: Literal[ResourceType.scoring_function] = ResourceType.scoring_function @property diff --git a/llama_stack/apis/shields/shields.py b/llama_stack/apis/shields/shields.py index ce1f73d8e..5d3e55c55 100644 --- a/llama_stack/apis/shields/shields.py +++ b/llama_stack/apis/shields/shields.py @@ -19,7 +19,11 @@ class CommonShieldFields(BaseModel): @json_schema_type class Shield(CommonShieldFields, Resource): - """A safety shield resource that can be used to check content""" + """A safety shield resource that can be used to check content. + + :param params: (Optional) Configuration parameters for the shield + :param type: The resource type, always shield + """ type: Literal[ResourceType.shield] = ResourceType.shield diff --git a/llama_stack/apis/synthetic_data_generation/synthetic_data_generation.py b/llama_stack/apis/synthetic_data_generation/synthetic_data_generation.py index 91e550da9..a7af44b28 100644 --- a/llama_stack/apis/synthetic_data_generation/synthetic_data_generation.py +++ b/llama_stack/apis/synthetic_data_generation/synthetic_data_generation.py @@ -14,7 +14,15 @@ from llama_stack.schema_utils import json_schema_type, webmethod class FilteringFunction(Enum): - """The type of filtering function.""" + """The type of filtering function. + + :cvar none: No filtering applied, accept all generated synthetic data + :cvar random: Random sampling of generated data points + :cvar top_k: Keep only the top-k highest scoring synthetic data samples + :cvar top_p: Nucleus-style filtering, keep samples exceeding cumulative score threshold + :cvar top_k_top_p: Combined top-k and top-p filtering strategy + :cvar sigmoid: Apply sigmoid function for probability-based filtering + """ none = "none" random = "random" @@ -26,7 +34,12 @@ class FilteringFunction(Enum): @json_schema_type class SyntheticDataGenerationRequest(BaseModel): - """Request to generate synthetic data. A small batch of prompts and a filtering function""" + """Request to generate synthetic data. A small batch of prompts and a filtering function + + :param dialogs: List of conversation messages to use as input for synthetic data generation + :param filtering_function: Type of filtering to apply to generated synthetic data samples + :param model: (Optional) The identifier of the model to use. The model must be registered with Llama Stack and available via the /models endpoint + """ dialogs: list[Message] filtering_function: FilteringFunction = FilteringFunction.none @@ -35,7 +48,11 @@ class SyntheticDataGenerationRequest(BaseModel): @json_schema_type class SyntheticDataGenerationResponse(BaseModel): - """Response from the synthetic data generation. Batch of (prompt, response, score) tuples that pass the threshold.""" + """Response from the synthetic data generation. Batch of (prompt, response, score) tuples that pass the threshold. + + :param synthetic_data: List of generated synthetic data samples that passed the filtering criteria + :param statistics: (Optional) Statistical information about the generation process and filtering results + """ synthetic_data: list[dict[str, Any]] statistics: dict[str, Any] | None = None @@ -48,4 +65,12 @@ class SyntheticDataGeneration(Protocol): dialogs: list[Message], filtering_function: FilteringFunction = FilteringFunction.none, model: str | None = None, - ) -> SyntheticDataGenerationResponse: ... + ) -> SyntheticDataGenerationResponse: + """Generate synthetic data based on input dialogs and apply filtering. + + :param dialogs: List of conversation messages to use as input for synthetic data generation + :param filtering_function: Type of filtering to apply to generated synthetic data samples + :param model: (Optional) The identifier of the model to use. The model must be registered with Llama Stack and available via the /models endpoint + :returns: Response containing filtered synthetic data samples and optional statistics + """ + ... diff --git a/llama_stack/apis/telemetry/telemetry.py b/llama_stack/apis/telemetry/telemetry.py index 96b317c29..92422ac1b 100644 --- a/llama_stack/apis/telemetry/telemetry.py +++ b/llama_stack/apis/telemetry/telemetry.py @@ -27,12 +27,27 @@ REQUIRED_SCOPE = "telemetry.read" @json_schema_type class SpanStatus(Enum): + """The status of a span indicating whether it completed successfully or with an error. + :cvar OK: Span completed successfully without errors + :cvar ERROR: Span completed with an error or failure + """ + OK = "ok" ERROR = "error" @json_schema_type class Span(BaseModel): + """A span representing a single operation within a trace. + :param span_id: Unique identifier for the span + :param trace_id: Unique identifier for the trace this span belongs to + :param parent_span_id: (Optional) Unique identifier for the parent span, if this is a child span + :param name: Human-readable name describing the operation this span represents + :param start_time: Timestamp when the operation began + :param end_time: (Optional) Timestamp when the operation finished, if completed + :param attributes: (Optional) Key-value pairs containing additional metadata about the span + """ + span_id: str trace_id: str parent_span_id: str | None = None @@ -49,6 +64,13 @@ class Span(BaseModel): @json_schema_type class Trace(BaseModel): + """A trace representing the complete execution path of a request across multiple operations. + :param trace_id: Unique identifier for the trace + :param root_span_id: Unique identifier for the root span that started this trace + :param start_time: Timestamp when the trace began + :param end_time: (Optional) Timestamp when the trace finished, if completed + """ + trace_id: str root_span_id: str start_time: datetime @@ -57,6 +79,12 @@ class Trace(BaseModel): @json_schema_type class EventType(Enum): + """The type of telemetry event being logged. + :cvar UNSTRUCTURED_LOG: A simple log message with severity level + :cvar STRUCTURED_LOG: A structured log event with typed payload data + :cvar METRIC: A metric measurement with value and unit + """ + UNSTRUCTURED_LOG = "unstructured_log" STRUCTURED_LOG = "structured_log" METRIC = "metric" @@ -64,6 +92,15 @@ class EventType(Enum): @json_schema_type class LogSeverity(Enum): + """The severity level of a log message. + :cvar VERBOSE: Detailed diagnostic information for troubleshooting + :cvar DEBUG: Debug information useful during development + :cvar INFO: General informational messages about normal operation + :cvar WARN: Warning messages about potentially problematic situations + :cvar ERROR: Error messages indicating failures that don't stop execution + :cvar CRITICAL: Critical error messages indicating severe failures + """ + VERBOSE = "verbose" DEBUG = "debug" INFO = "info" @@ -73,6 +110,13 @@ class LogSeverity(Enum): class EventCommon(BaseModel): + """Common fields shared by all telemetry events. + :param trace_id: Unique identifier for the trace this event belongs to + :param span_id: Unique identifier for the span this event belongs to + :param timestamp: Timestamp when the event occurred + :param attributes: (Optional) Key-value pairs containing additional metadata about the event + """ + trace_id: str span_id: str timestamp: datetime @@ -81,6 +125,12 @@ class EventCommon(BaseModel): @json_schema_type class UnstructuredLogEvent(EventCommon): + """An unstructured log event containing a simple text message. + :param type: Event type identifier set to UNSTRUCTURED_LOG + :param message: The log message text + :param severity: The severity level of the log message + """ + type: Literal[EventType.UNSTRUCTURED_LOG] = EventType.UNSTRUCTURED_LOG message: str severity: LogSeverity @@ -88,6 +138,13 @@ class UnstructuredLogEvent(EventCommon): @json_schema_type class MetricEvent(EventCommon): + """A metric event containing a measured value. + :param type: Event type identifier set to METRIC + :param metric: The name of the metric being measured + :param value: The numeric value of the metric measurement + :param unit: The unit of measurement for the metric value + """ + type: Literal[EventType.METRIC] = EventType.METRIC metric: str # this would be an enum value: int | float @@ -96,6 +153,12 @@ class MetricEvent(EventCommon): @json_schema_type class MetricInResponse(BaseModel): + """A metric value included in API responses. + :param metric: The name of the metric + :param value: The numeric value of the metric + :param unit: (Optional) The unit of measurement for the metric value + """ + metric: str value: int | float unit: str | None = None @@ -122,17 +185,32 @@ class MetricInResponse(BaseModel): class MetricResponseMixin(BaseModel): + """Mixin class for API responses that can include metrics. + :param metrics: (Optional) List of metrics associated with the API response + """ + metrics: list[MetricInResponse] | None = None @json_schema_type class StructuredLogType(Enum): + """The type of structured log event payload. + :cvar SPAN_START: Event indicating the start of a new span + :cvar SPAN_END: Event indicating the completion of a span + """ + SPAN_START = "span_start" SPAN_END = "span_end" @json_schema_type class SpanStartPayload(BaseModel): + """Payload for a span start event. + :param type: Payload type identifier set to SPAN_START + :param name: Human-readable name describing the operation this span represents + :param parent_span_id: (Optional) Unique identifier for the parent span, if this is a child span + """ + type: Literal[StructuredLogType.SPAN_START] = StructuredLogType.SPAN_START name: str parent_span_id: str | None = None @@ -140,6 +218,11 @@ class SpanStartPayload(BaseModel): @json_schema_type class SpanEndPayload(BaseModel): + """Payload for a span end event. + :param type: Payload type identifier set to SPAN_END + :param status: The final status of the span indicating success or failure + """ + type: Literal[StructuredLogType.SPAN_END] = StructuredLogType.SPAN_END status: SpanStatus @@ -153,6 +236,11 @@ register_schema(StructuredLogPayload, name="StructuredLogPayload") @json_schema_type class StructuredLogEvent(EventCommon): + """A structured log event containing typed payload data. + :param type: Event type identifier set to STRUCTURED_LOG + :param payload: The structured payload data for the log event + """ + type: Literal[EventType.STRUCTURED_LOG] = EventType.STRUCTURED_LOG payload: StructuredLogPayload @@ -166,6 +254,14 @@ register_schema(Event, name="Event") @json_schema_type class EvalTrace(BaseModel): + """A trace record for evaluation purposes. + :param session_id: Unique identifier for the evaluation session + :param step: The evaluation step or phase identifier + :param input: The input data for the evaluation + :param output: The actual output produced during evaluation + :param expected_output: The expected output for comparison during evaluation + """ + session_id: str step: str input: str @@ -175,11 +271,22 @@ class EvalTrace(BaseModel): @json_schema_type class SpanWithStatus(Span): + """A span that includes status information. + :param status: (Optional) The current status of the span + """ + status: SpanStatus | None = None @json_schema_type class QueryConditionOp(Enum): + """Comparison operators for query conditions. + :cvar EQ: Equal to comparison + :cvar NE: Not equal to comparison + :cvar GT: Greater than comparison + :cvar LT: Less than comparison + """ + EQ = "eq" NE = "ne" GT = "gt" @@ -188,29 +295,59 @@ class QueryConditionOp(Enum): @json_schema_type class QueryCondition(BaseModel): + """A condition for filtering query results. + :param key: The attribute key to filter on + :param op: The comparison operator to apply + :param value: The value to compare against + """ + key: str op: QueryConditionOp value: Any class QueryTracesResponse(BaseModel): + """Response containing a list of traces. + :param data: List of traces matching the query criteria + """ + data: list[Trace] class QuerySpansResponse(BaseModel): + """Response containing a list of spans. + :param data: List of spans matching the query criteria + """ + data: list[Span] class QuerySpanTreeResponse(BaseModel): + """Response containing a tree structure of spans. + :param data: Dictionary mapping span IDs to spans with status information + """ + data: dict[str, SpanWithStatus] class MetricQueryType(Enum): + """The type of metric query to perform. + :cvar RANGE: Query metrics over a time range + :cvar INSTANT: Query metrics at a specific point in time + """ + RANGE = "range" INSTANT = "instant" class MetricLabelOperator(Enum): + """Operators for matching metric labels. + :cvar EQUALS: Label value must equal the specified value + :cvar NOT_EQUALS: Label value must not equal the specified value + :cvar REGEX_MATCH: Label value must match the specified regular expression + :cvar REGEX_NOT_MATCH: Label value must not match the specified regular expression + """ + EQUALS = "=" NOT_EQUALS = "!=" REGEX_MATCH = "=~" @@ -218,6 +355,12 @@ class MetricLabelOperator(Enum): class MetricLabelMatcher(BaseModel): + """A matcher for filtering metrics by label values. + :param name: The name of the label to match + :param value: The value to match against + :param operator: The comparison operator to use for matching + """ + name: str value: str operator: MetricLabelOperator = MetricLabelOperator.EQUALS @@ -225,24 +368,44 @@ class MetricLabelMatcher(BaseModel): @json_schema_type class MetricLabel(BaseModel): + """A label associated with a metric. + :param name: The name of the label + :param value: The value of the label + """ + name: str value: str @json_schema_type class MetricDataPoint(BaseModel): + """A single data point in a metric time series. + :param timestamp: Unix timestamp when the metric value was recorded + :param value: The numeric value of the metric at this timestamp + """ + timestamp: int value: float @json_schema_type class MetricSeries(BaseModel): + """A time series of metric data points. + :param metric: The name of the metric + :param labels: List of labels associated with this metric series + :param values: List of data points in chronological order + """ + metric: str labels: list[MetricLabel] values: list[MetricDataPoint] class QueryMetricsResponse(BaseModel): + """Response containing metric time series data. + :param data: List of metric series matching the query criteria + """ + data: list[MetricSeries] diff --git a/llama_stack/apis/tools/rag_tool.py b/llama_stack/apis/tools/rag_tool.py index 1d5e7b6cb..651016bd1 100644 --- a/llama_stack/apis/tools/rag_tool.py +++ b/llama_stack/apis/tools/rag_tool.py @@ -22,7 +22,7 @@ class RRFRanker(BaseModel): :param type: The type of ranker, always "rrf" :param impact_factor: The impact factor for RRF scoring. Higher values give more weight to higher-ranked results. - Must be greater than 0. Default of 60 is from the original RRF paper (Cormack et al., 2009). + Must be greater than 0 """ type: Literal["rrf"] = "rrf" @@ -76,12 +76,25 @@ class RAGDocument(BaseModel): @json_schema_type class RAGQueryResult(BaseModel): + """Result of a RAG query containing retrieved content and metadata. + + :param content: (Optional) The retrieved content from the query + :param metadata: Additional metadata about the query result + """ + content: InterleavedContent | None = None metadata: dict[str, Any] = Field(default_factory=dict) @json_schema_type class RAGQueryGenerator(Enum): + """Types of query generators for RAG systems. + + :cvar default: Default query generator using simple text processing + :cvar llm: LLM-based query generator for enhanced query understanding + :cvar custom: Custom query generator implementation + """ + default = "default" llm = "llm" custom = "custom" @@ -103,12 +116,25 @@ class RAGSearchMode(StrEnum): @json_schema_type class DefaultRAGQueryGeneratorConfig(BaseModel): + """Configuration for the default RAG query generator. + + :param type: Type of query generator, always 'default' + :param separator: String separator used to join query terms + """ + type: Literal["default"] = "default" separator: str = " " @json_schema_type class LLMRAGQueryGeneratorConfig(BaseModel): + """Configuration for the LLM-based RAG query generator. + + :param type: Type of query generator, always 'llm' + :param model: Name of the language model to use for query generation + :param template: Template string for formatting the query generation prompt + """ + type: Literal["llm"] = "llm" model: str template: str @@ -166,7 +192,12 @@ class RAGToolRuntime(Protocol): vector_db_id: str, chunk_size_in_tokens: int = 512, ) -> None: - """Index documents so they can be used by the RAG system""" + """Index documents so they can be used by the RAG system. + + :param documents: List of documents to index in the RAG system + :param vector_db_id: ID of the vector database to store the document embeddings + :param chunk_size_in_tokens: (Optional) Size in tokens for document chunking during indexing + """ ... @webmethod(route="/tool-runtime/rag-tool/query", method="POST") @@ -176,5 +207,11 @@ class RAGToolRuntime(Protocol): vector_db_ids: list[str], query_config: RAGQueryConfig | None = None, ) -> RAGQueryResult: - """Query the RAG system for context; typically invoked by the agent""" + """Query the RAG system for context; typically invoked by the agent. + + :param content: The query content to search for in the indexed documents + :param vector_db_ids: List of vector database IDs to search within + :param query_config: (Optional) Configuration parameters for the query operation + :returns: RAGQueryResult containing the retrieved content and metadata + """ ... diff --git a/llama_stack/apis/tools/tools.py b/llama_stack/apis/tools/tools.py index 7d1eeeefb..52b86375a 100644 --- a/llama_stack/apis/tools/tools.py +++ b/llama_stack/apis/tools/tools.py @@ -20,6 +20,15 @@ from .rag_tool import RAGToolRuntime @json_schema_type class ToolParameter(BaseModel): + """Parameter definition for a tool. + + :param name: Name of the parameter + :param parameter_type: Type of the parameter (e.g., string, integer) + :param description: Human-readable description of what the parameter does + :param required: Whether this parameter is required for tool invocation + :param default: (Optional) Default value for the parameter if not provided + """ + name: str parameter_type: str description: str @@ -29,6 +38,15 @@ class ToolParameter(BaseModel): @json_schema_type class Tool(Resource): + """A tool that can be invoked by agents. + + :param type: Type of resource, always 'tool' + :param toolgroup_id: ID of the tool group this tool belongs to + :param description: Human-readable description of what the tool does + :param parameters: List of parameters this tool accepts + :param metadata: (Optional) Additional metadata about the tool + """ + type: Literal[ResourceType.tool] = ResourceType.tool toolgroup_id: str description: str @@ -38,6 +56,14 @@ class Tool(Resource): @json_schema_type class ToolDef(BaseModel): + """Tool definition used in runtime contexts. + + :param name: Name of the tool + :param description: (Optional) Human-readable description of what the tool does + :param parameters: (Optional) List of parameters this tool accepts + :param metadata: (Optional) Additional metadata about the tool + """ + name: str description: str | None = None parameters: list[ToolParameter] | None = None @@ -46,6 +72,14 @@ class ToolDef(BaseModel): @json_schema_type class ToolGroupInput(BaseModel): + """Input data for registering a tool group. + + :param toolgroup_id: Unique identifier for the tool group + :param provider_id: ID of the provider that will handle this tool group + :param args: (Optional) Additional arguments to pass to the provider + :param mcp_endpoint: (Optional) Model Context Protocol endpoint for remote tools + """ + toolgroup_id: str provider_id: str args: dict[str, Any] | None = None @@ -54,6 +88,13 @@ class ToolGroupInput(BaseModel): @json_schema_type class ToolGroup(Resource): + """A group of related tools managed together. + + :param type: Type of resource, always 'tool_group' + :param mcp_endpoint: (Optional) Model Context Protocol endpoint for remote tools + :param args: (Optional) Additional arguments for the tool group + """ + type: Literal[ResourceType.tool_group] = ResourceType.tool_group mcp_endpoint: URL | None = None args: dict[str, Any] | None = None @@ -61,6 +102,14 @@ class ToolGroup(Resource): @json_schema_type class ToolInvocationResult(BaseModel): + """Result of a tool invocation. + + :param content: (Optional) The output content from the tool execution + :param error_message: (Optional) Error message if the tool execution failed + :param error_code: (Optional) Numeric error code if the tool execution failed + :param metadata: (Optional) Additional metadata about the tool execution + """ + content: InterleavedContent | None = None error_message: str | None = None error_code: int | None = None @@ -73,14 +122,29 @@ class ToolStore(Protocol): class ListToolGroupsResponse(BaseModel): + """Response containing a list of tool groups. + + :param data: List of tool groups + """ + data: list[ToolGroup] class ListToolsResponse(BaseModel): + """Response containing a list of tools. + + :param data: List of tools + """ + data: list[Tool] class ListToolDefsResponse(BaseModel): + """Response containing a list of tool definitions. + + :param data: List of tool definitions + """ + data: list[ToolDef] @@ -158,6 +222,11 @@ class ToolGroups(Protocol): class SpecialToolGroup(Enum): + """Special tool groups with predefined functionality. + + :cvar rag_tool: Retrieval-Augmented Generation tool group for document search and retrieval + """ + rag_tool = "rag_tool" diff --git a/llama_stack/apis/vector_dbs/vector_dbs.py b/llama_stack/apis/vector_dbs/vector_dbs.py index 325e21bab..47820fa0f 100644 --- a/llama_stack/apis/vector_dbs/vector_dbs.py +++ b/llama_stack/apis/vector_dbs/vector_dbs.py @@ -15,6 +15,13 @@ from llama_stack.schema_utils import json_schema_type, webmethod @json_schema_type class VectorDB(Resource): + """Vector database resource for storing and querying vector embeddings. + + :param type: Type of resource, always 'vector_db' for vector databases + :param embedding_model: Name of the embedding model to use for vector generation + :param embedding_dimension: Dimension of the embedding vectors + """ + type: Literal[ResourceType.vector_db] = ResourceType.vector_db embedding_model: str @@ -31,6 +38,14 @@ class VectorDB(Resource): class VectorDBInput(BaseModel): + """Input parameters for creating or configuring a vector database. + + :param vector_db_id: Unique identifier for the vector database + :param embedding_model: Name of the embedding model to use for vector generation + :param embedding_dimension: Dimension of the embedding vectors + :param provider_vector_db_id: (Optional) Provider-specific identifier for the vector database + """ + vector_db_id: str embedding_model: str embedding_dimension: int @@ -39,6 +54,11 @@ class VectorDBInput(BaseModel): class ListVectorDBsResponse(BaseModel): + """Response from listing vector databases. + + :param data: List of vector databases + """ + data: list[VectorDB] diff --git a/llama_stack/apis/vector_io/vector_io.py b/llama_stack/apis/vector_io/vector_io.py index 853c4656c..b53046093 100644 --- a/llama_stack/apis/vector_io/vector_io.py +++ b/llama_stack/apis/vector_io/vector_io.py @@ -94,12 +94,27 @@ class Chunk(BaseModel): @json_schema_type class QueryChunksResponse(BaseModel): + """Response from querying chunks in a vector database. + + :param chunks: List of content chunks returned from the query + :param scores: Relevance scores corresponding to each returned chunk + """ + chunks: list[Chunk] scores: list[float] @json_schema_type class VectorStoreFileCounts(BaseModel): + """File processing status counts for a vector store. + + :param completed: Number of files that have been successfully processed + :param cancelled: Number of files that had their processing cancelled + :param failed: Number of files that failed to process + :param in_progress: Number of files currently being processed + :param total: Total number of files in the vector store + """ + completed: int cancelled: int failed: int @@ -109,7 +124,20 @@ class VectorStoreFileCounts(BaseModel): @json_schema_type class VectorStoreObject(BaseModel): - """OpenAI Vector Store object.""" + """OpenAI Vector Store object. + + :param id: Unique identifier for the vector store + :param object: Object type identifier, always "vector_store" + :param created_at: Timestamp when the vector store was created + :param name: (Optional) Name of the vector store + :param usage_bytes: Storage space used by the vector store in bytes + :param file_counts: File processing status counts for the vector store + :param status: Current status of the vector store + :param expires_after: (Optional) Expiration policy for the vector store + :param expires_at: (Optional) Timestamp when the vector store will expire + :param last_active_at: (Optional) Timestamp of last activity on the vector store + :param metadata: Set of key-value pairs that can be attached to the vector store + """ id: str object: str = "vector_store" @@ -126,7 +154,14 @@ class VectorStoreObject(BaseModel): @json_schema_type class VectorStoreCreateRequest(BaseModel): - """Request to create a vector store.""" + """Request to create a vector store. + + :param name: (Optional) Name for the vector store + :param file_ids: List of file IDs to include in the vector store + :param expires_after: (Optional) Expiration policy for the vector store + :param chunking_strategy: (Optional) Strategy for splitting files into chunks + :param metadata: Set of key-value pairs that can be attached to the vector store + """ name: str | None = None file_ids: list[str] = Field(default_factory=list) @@ -137,7 +172,12 @@ class VectorStoreCreateRequest(BaseModel): @json_schema_type class VectorStoreModifyRequest(BaseModel): - """Request to modify a vector store.""" + """Request to modify a vector store. + + :param name: (Optional) Updated name for the vector store + :param expires_after: (Optional) Updated expiration policy for the vector store + :param metadata: (Optional) Updated set of key-value pairs for the vector store + """ name: str | None = None expires_after: dict[str, Any] | None = None @@ -146,7 +186,14 @@ class VectorStoreModifyRequest(BaseModel): @json_schema_type class VectorStoreListResponse(BaseModel): - """Response from listing vector stores.""" + """Response from listing vector stores. + + :param object: Object type identifier, always "list" + :param data: List of vector store objects + :param first_id: (Optional) ID of the first vector store in the list for pagination + :param last_id: (Optional) ID of the last vector store in the list for pagination + :param has_more: Whether there are more vector stores available beyond this page + """ object: str = "list" data: list[VectorStoreObject] @@ -157,7 +204,14 @@ class VectorStoreListResponse(BaseModel): @json_schema_type class VectorStoreSearchRequest(BaseModel): - """Request to search a vector store.""" + """Request to search a vector store. + + :param query: Search query as a string or list of strings + :param filters: (Optional) Filters based on file attributes to narrow search results + :param max_num_results: Maximum number of results to return, defaults to 10 + :param ranking_options: (Optional) Options for ranking and filtering search results + :param rewrite_query: Whether to rewrite the query for better vector search performance + """ query: str | list[str] filters: dict[str, Any] | None = None @@ -168,13 +222,26 @@ class VectorStoreSearchRequest(BaseModel): @json_schema_type class VectorStoreContent(BaseModel): + """Content item from a vector store file or search result. + + :param type: Content type, currently only "text" is supported + :param text: The actual text content + """ + type: Literal["text"] text: str @json_schema_type class VectorStoreSearchResponse(BaseModel): - """Response from searching a vector store.""" + """Response from searching a vector store. + + :param file_id: Unique identifier of the file containing the result + :param filename: Name of the file containing the result + :param score: Relevance score for this search result + :param attributes: (Optional) Key-value attributes associated with the file + :param content: List of content items matching the search query + """ file_id: str filename: str @@ -185,7 +252,14 @@ class VectorStoreSearchResponse(BaseModel): @json_schema_type class VectorStoreSearchResponsePage(BaseModel): - """Response from searching a vector store.""" + """Paginated response from searching a vector store. + + :param object: Object type identifier for the search results page + :param search_query: The original search query that was executed + :param data: List of search result objects + :param has_more: Whether there are more results available beyond this page + :param next_page: (Optional) Token for retrieving the next page of results + """ object: str = "vector_store.search_results.page" search_query: str @@ -196,7 +270,12 @@ class VectorStoreSearchResponsePage(BaseModel): @json_schema_type class VectorStoreDeleteResponse(BaseModel): - """Response from deleting a vector store.""" + """Response from deleting a vector store. + + :param id: Unique identifier of the deleted vector store + :param object: Object type identifier for the deletion response + :param deleted: Whether the deletion operation was successful + """ id: str object: str = "vector_store.deleted" @@ -205,17 +284,34 @@ class VectorStoreDeleteResponse(BaseModel): @json_schema_type class VectorStoreChunkingStrategyAuto(BaseModel): + """Automatic chunking strategy for vector store files. + + :param type: Strategy type, always "auto" for automatic chunking + """ + type: Literal["auto"] = "auto" @json_schema_type class VectorStoreChunkingStrategyStaticConfig(BaseModel): + """Configuration for static chunking strategy. + + :param chunk_overlap_tokens: Number of tokens to overlap between adjacent chunks + :param max_chunk_size_tokens: Maximum number of tokens per chunk, must be between 100 and 4096 + """ + chunk_overlap_tokens: int = 400 max_chunk_size_tokens: int = Field(800, ge=100, le=4096) @json_schema_type class VectorStoreChunkingStrategyStatic(BaseModel): + """Static chunking strategy with configurable parameters. + + :param type: Strategy type, always "static" for static chunking + :param static: Configuration parameters for the static chunking strategy + """ + type: Literal["static"] = "static" static: VectorStoreChunkingStrategyStaticConfig @@ -227,6 +323,12 @@ register_schema(VectorStoreChunkingStrategy, name="VectorStoreChunkingStrategy") class SearchRankingOptions(BaseModel): + """Options for ranking and filtering search results. + + :param ranker: (Optional) Name of the ranking algorithm to use + :param score_threshold: (Optional) Minimum relevance score threshold for results + """ + ranker: str | None = None # NOTE: OpenAI File Search Tool requires threshold to be between 0 and 1, however # we don't guarantee that the score is between 0 and 1, so will leave this unconstrained @@ -236,6 +338,12 @@ class SearchRankingOptions(BaseModel): @json_schema_type class VectorStoreFileLastError(BaseModel): + """Error information for failed vector store file processing. + + :param code: Error code indicating the type of failure + :param message: Human-readable error message describing the failure + """ + code: Literal["server_error"] | Literal["rate_limit_exceeded"] message: str @@ -246,7 +354,18 @@ register_schema(VectorStoreFileStatus, name="VectorStoreFileStatus") @json_schema_type class VectorStoreFileObject(BaseModel): - """OpenAI Vector Store File object.""" + """OpenAI Vector Store File object. + + :param id: Unique identifier for the file + :param object: Object type identifier, always "vector_store.file" + :param attributes: Key-value attributes associated with the file + :param chunking_strategy: Strategy used for splitting the file into chunks + :param created_at: Timestamp when the file was added to the vector store + :param last_error: (Optional) Error information if file processing failed + :param status: Current processing status of the file + :param usage_bytes: Storage space used by this file in bytes + :param vector_store_id: ID of the vector store containing this file + """ id: str object: str = "vector_store.file" @@ -261,7 +380,14 @@ class VectorStoreFileObject(BaseModel): @json_schema_type class VectorStoreListFilesResponse(BaseModel): - """Response from listing vector stores.""" + """Response from listing files in a vector store. + + :param object: Object type identifier, always "list" + :param data: List of vector store file objects + :param first_id: (Optional) ID of the first file in the list for pagination + :param last_id: (Optional) ID of the last file in the list for pagination + :param has_more: Whether there are more files available beyond this page + """ object: str = "list" data: list[VectorStoreFileObject] @@ -272,7 +398,13 @@ class VectorStoreListFilesResponse(BaseModel): @json_schema_type class VectorStoreFileContentsResponse(BaseModel): - """Response from retrieving the contents of a vector store file.""" + """Response from retrieving the contents of a vector store file. + + :param file_id: Unique identifier for the file + :param filename: Name of the file + :param attributes: Key-value attributes associated with the file + :param content: List of content items from the file + """ file_id: str filename: str @@ -282,7 +414,12 @@ class VectorStoreFileContentsResponse(BaseModel): @json_schema_type class VectorStoreFileDeleteResponse(BaseModel): - """Response from deleting a vector store file.""" + """Response from deleting a vector store file. + + :param id: Unique identifier of the deleted file + :param object: Object type identifier for the deletion response + :param deleted: Whether the deletion operation was successful + """ id: str object: str = "vector_store.file.deleted" @@ -478,6 +615,11 @@ class VectorIO(Protocol): """List files in a vector store. :param vector_store_id: The ID of the vector store to list files from. + :param limit: (Optional) A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + :param order: (Optional) Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + :param after: (Optional) A cursor for use in pagination. `after` is an object ID that defines your place in the list. + :param before: (Optional) A cursor for use in pagination. `before` is an object ID that defines your place in the list. + :param filter: (Optional) Filter by file status to only return files with the specified status. :returns: A VectorStoreListFilesResponse containing the list of files. """ ...