Update API docs

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"
@@ -89,12 +102,25 @@ class RAGQueryGenerator(Enum):
 
 @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
@@ -152,7 +178,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")
@@ -162,5 +193,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
+        """
         ...

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"