diff --git a/api_update_plan.md b/api_update_plan.md index 5b73454b3..e14d70430 100644 --- a/api_update_plan.md +++ b/api_update_plan.md @@ -222,8 +222,8 @@ Before finalizing documentation, verify: [x] 1. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/agents/agents.py` - Core agent system (start here, most complete) [x] 2. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/inference/inference.py` - Core LLM functionality [x] 3. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/safety/safety.py` - Safety and moderation -4. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/models/models.py` - Model metadata and management -5. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/tools/tools.py` - Tool system APIs +[x] 4. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/models/models.py` - Model metadata and management +[x] 5. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/tools/tools.py` - Tool system APIs 6. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/tools/rag_tool.py` - RAG tool runtime 7. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/vector_io/vector_io.py` - Vector database operations 8. `/Users/saip/Documents/GitHub/llama-stack/llama_stack/apis/vector_dbs/vector_dbs.py` - Vector database management diff --git a/docs/_static/llama-stack-spec.html b/docs/_static/llama-stack-spec.html index 08a9cf0af..48575c4a3 100644 --- a/docs/_static/llama-stack-spec.html +++ b/docs/_static/llama-stack-spec.html @@ -6466,16 +6466,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", @@ -6500,30 +6503,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": [ @@ -6545,7 +6554,8 @@ { "type": "object" } - ] + ], + "description": "(Optional) Default value for the parameter if not provided" } }, "additionalProperties": false, @@ -6555,7 +6565,8 @@ "description", "required" ], - "title": "ToolParameter" + "title": "ToolParameter", + "description": "Parameter definition for a tool." }, "CreateAgentRequest": { "type": "object", @@ -10472,13 +10483,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", @@ -10492,9 +10506,9 @@ "tool", "tool_group" ], - "title": "ResourceType", "const": "model", - "default": "model" + "default": "model", + "description": "The resource type, always 'model' for model resources" }, "metadata": { "type": "object", @@ -10519,11 +10533,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, @@ -10534,7 +10550,8 @@ "metadata", "model_type" ], - "title": "Model" + "title": "Model", + "description": "A model resource representing an AI model registered in Llama Stack." }, "ModelType": { "type": "string", @@ -10542,7 +10559,8 @@ "llm", "embedding" ], - "title": "ModelType" + "title": "ModelType", + "description": "Enumeration of supported model types in Llama Stack." }, "AgentTurnInputType": { "type": "object", @@ -11064,21 +11082,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", @@ -11103,7 +11124,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) Additional metadata about the tool" } }, "additionalProperties": false, @@ -11115,7 +11137,8 @@ "description", "parameters" ], - "title": "Tool" + "title": "Tool", + "description": "A tool that can be invoked by agents." }, "ToolGroup": { "type": "object", @@ -11141,12 +11164,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", @@ -11171,7 +11195,8 @@ "type": "object" } ] - } + }, + "description": "(Optional) Additional arguments for the tool group" } }, "additionalProperties": false, @@ -11180,7 +11205,8 @@ "provider_id", "type" ], - "title": "ToolGroup" + "title": "ToolGroup", + "description": "A group of related tools managed together." }, "Trace": { "type": "object", @@ -11737,13 +11763,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", @@ -11768,11 +11797,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", @@ -12178,14 +12209,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", @@ -12226,14 +12259,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", @@ -12242,14 +12277,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", diff --git a/docs/_static/llama-stack-spec.yaml b/docs/_static/llama-stack-spec.yaml index 53134a6ec..158eaa61d 100644 --- a/docs/_static/llama-stack-spec.yaml +++ b/docs/_static/llama-stack-spec.yaml @@ -4650,12 +4650,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: @@ -4666,22 +4671,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' @@ -4690,6 +4706,8 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Default value for the parameter if not provided additionalProperties: false required: - name @@ -4697,6 +4715,7 @@ components: - description - required title: ToolParameter + description: Parameter definition for a tool. CreateAgentRequest: type: object properties: @@ -7504,10 +7523,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: @@ -7519,9 +7544,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: @@ -7532,9 +7558,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 @@ -7543,12 +7572,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: @@ -7892,17 +7925,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: @@ -7913,6 +7951,8 @@ components: - type: string - type: array - type: object + description: >- + (Optional) Additional metadata about the tool additionalProperties: false required: - identifier @@ -7922,6 +7962,7 @@ components: - description - parameters title: Tool + description: A tool that can be invoked by agents. ToolGroup: type: object properties: @@ -7942,11 +7983,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: @@ -7957,12 +8000,16 @@ 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: @@ -8356,10 +8403,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: @@ -8370,8 +8423,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: @@ -8670,10 +8726,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: @@ -8703,10 +8762,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: @@ -8714,10 +8776,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: diff --git a/llama_stack/apis/models/models.py b/llama_stack/apis/models/models.py index 36da97e62..485add71f 100644 --- a/llama_stack/apis/models/models.py +++ b/llama_stack/apis/models/models.py @@ -23,12 +23,26 @@ 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/tools/tools.py b/llama_stack/apis/tools/tools.py index 7d1eeeefb..9f4c7b659 100644 --- a/llama_stack/apis/tools/tools.py +++ b/llama_stack/apis/tools/tools.py @@ -20,6 +20,14 @@ 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 +37,14 @@ 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 +54,13 @@ 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 +69,13 @@ 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 +84,12 @@ 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 +97,13 @@ 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 +116,26 @@ 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 +213,10 @@ 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"