llama-stack-api 0.4.3__py3-none-any.whl → 0.5.0rc1__py3-none-any.whl

llama_stack_api/shields/__init__.py

@@ -0,0 +1,41 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""Shields API protocol and models.
+
+This module contains the Shields protocol definition.
+Pydantic models are defined in llama_stack_api.shields.models.
+The FastAPI router is defined in llama_stack_api.shields.fastapi_routes.
+"""
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import protocol for re-export
+from .api import Shields
+
+# Import models for re-export
+from .models import (
+    CommonShieldFields,
+    GetShieldRequest,
+    ListShieldsResponse,
+    RegisterShieldRequest,
+    Shield,
+    ShieldInput,
+    UnregisterShieldRequest,
+)
+
+__all__ = [
+    "Shields",
+    "Shield",
+    "ShieldInput",
+    "CommonShieldFields",
+    "ListShieldsResponse",
+    "GetShieldRequest",
+    "RegisterShieldRequest",
+    "UnregisterShieldRequest",
+    "fastapi_routes",
+]

llama_stack_api/shields/api.py

@@ -0,0 +1,39 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""Shields API protocol definition.
+
+This module contains the Shields protocol for managing shield resources.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from .models import (
+    GetShieldRequest,
+    ListShieldsResponse,
+    RegisterShieldRequest,
+    Shield,
+    UnregisterShieldRequest,
+)
+
+
+@runtime_checkable
+class Shields(Protocol):
+    async def list_shields(self) -> ListShieldsResponse:
+        """List all shields."""
+        ...
+
+    async def get_shield(self, request: GetShieldRequest) -> Shield:
+        """Get a shield by its identifier."""
+        ...
+
+    async def register_shield(self, request: RegisterShieldRequest) -> Shield:
+        """Register a shield."""
+        ...
+
+    async def unregister_shield(self, request: UnregisterShieldRequest) -> None:
+        """Unregister a shield."""
+        ...

llama_stack_api/shields/fastapi_routes.py

@@ -0,0 +1,104 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""FastAPI router for the Shields API.
+
+This module defines the FastAPI router for the Shields API using standard
+FastAPI route decorators.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Body, Depends
+
+from llama_stack_api.router_utils import create_path_dependency, standard_responses
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+from .api import Shields
+from .models import (
+    GetShieldRequest,
+    ListShieldsResponse,
+    RegisterShieldRequest,
+    Shield,
+    UnregisterShieldRequest,
+)
+
+# Automatically generate dependency functions from Pydantic models
+get_get_shield_request = create_path_dependency(GetShieldRequest)
+get_unregister_shield_request = create_path_dependency(UnregisterShieldRequest)
+
+
+def create_router(impl: Shields) -> APIRouter:
+    """Create a FastAPI router for the Shields API.
+
+    Args:
+        impl: The Shields implementation instance
+
+    Returns:
+        APIRouter configured for the Shields API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Shields"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/shields",
+        response_model=ListShieldsResponse,
+        summary="List all shields.",
+        description="List all shields.",
+        responses={
+            200: {"description": "A ListShieldsResponse."},
+        },
+    )
+    async def list_shields() -> ListShieldsResponse:
+        return await impl.list_shields()
+
+    @router.get(
+        "/shields/{identifier:path}",
+        response_model=Shield,
+        summary="Get a shield by its identifier.",
+        description="Get a shield by its identifier.",
+        responses={
+            200: {"description": "A Shield."},
+        },
+    )
+    async def get_shield(
+        request: Annotated[GetShieldRequest, Depends(get_get_shield_request)],
+    ) -> Shield:
+        return await impl.get_shield(request)
+
+    @router.post(
+        "/shields",
+        response_model=Shield,
+        summary="Register a shield.",
+        description="Register a shield.",
+        responses={
+            200: {"description": "A Shield."},
+        },
+        deprecated=True,
+    )
+    async def register_shield(
+        request: Annotated[RegisterShieldRequest, Body(...)],
+    ) -> Shield:
+        return await impl.register_shield(request)
+
+    @router.delete(
+        "/shields/{identifier:path}",
+        summary="Unregister a shield.",
+        description="Unregister a shield.",
+        responses={
+            200: {"description": "The shield was successfully unregistered."},
+        },
+        deprecated=True,
+    )
+    async def unregister_shield(
+        request: Annotated[UnregisterShieldRequest, Depends(get_unregister_shield_request)],
+    ) -> None:
+        return await impl.unregister_shield(request)
+
+    return router

llama_stack_api/shields/models.py

@@ -0,0 +1,74 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""Pydantic models for Shields API requests and responses.
+
+This module defines the request and response models for the Shields API
+using Pydantic with Field descriptions for OpenAPI schema generation.
+"""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.resource import Resource, ResourceType
+from llama_stack_api.schema_utils import json_schema_type
+
+
+class CommonShieldFields(BaseModel):
+    params: dict[str, Any] | None = None
+
+
+@json_schema_type
+class Shield(CommonShieldFields, Resource):
+    """A safety shield resource that can be used to check content."""
+
+    type: Literal[ResourceType.shield] = ResourceType.shield
+
+    @property
+    def shield_id(self) -> str:
+        return self.identifier
+
+    @property
+    def provider_shield_id(self) -> str | None:
+        return self.provider_resource_id
+
+
+class ShieldInput(CommonShieldFields):
+    shield_id: str
+    provider_id: str | None = None
+    provider_shield_id: str | None = None
+
+
+@json_schema_type
+class ListShieldsResponse(BaseModel):
+    """Response containing a list of all shields."""
+
+    data: list[Shield] = Field(..., description="List of shield objects")
+
+
+@json_schema_type
+class GetShieldRequest(BaseModel):
+    """Request model for getting a shield by identifier."""
+
+    identifier: str = Field(..., description="The identifier of the shield to get.")
+
+
+@json_schema_type
+class RegisterShieldRequest(BaseModel):
+    """Request model for registering a shield."""
+
+    shield_id: str = Field(..., description="The identifier of the shield to register.")
+    provider_shield_id: str | None = Field(None, description="The identifier of the shield in the provider.")
+    provider_id: str | None = Field(None, description="The identifier of the provider.")
+    params: dict[str, Any] | None = Field(None, description="The parameters of the shield.")
+
+
+@json_schema_type
+class UnregisterShieldRequest(BaseModel):
+    """Request model for unregistering a shield."""
+
+    identifier: str = Field(..., description="The identifier of the shield to unregister.")

llama_stack_api/tools.py

@@ -0,0 +1,226 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+from enum import Enum
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel
+from typing_extensions import runtime_checkable
+
+from llama_stack_api.common.content_types import URL, InterleavedContent
+from llama_stack_api.resource import Resource, ResourceType
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+
+@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 input_schema: (Optional) JSON Schema for tool inputs (MCP inputSchema)
+    :param output_schema: (Optional) JSON Schema for tool outputs (MCP outputSchema)
+    :param metadata: (Optional) Additional metadata about the tool
+    :param toolgroup_id: (Optional) ID of the tool group this tool belongs to
+    """
+
+    toolgroup_id: str | None = None
+    name: str
+    description: str | None = None
+    input_schema: dict[str, Any] | None = None
+    output_schema: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@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
+    mcp_endpoint: URL | None = None
+
+
+@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
+
+
+@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
+    metadata: dict[str, Any] | None = None
+
+
+class ToolStore(Protocol):
+    async def get_tool(self, tool_name: str) -> ToolDef: ...
+    async def get_tool_group(self, toolgroup_id: str) -> ToolGroup: ...
+
+
+@json_schema_type
+class ListToolGroupsResponse(BaseModel):
+    """Response containing a list of tool groups.
+
+    :param data: List of tool groups
+    """
+
+    data: list[ToolGroup]
+
+
+@json_schema_type
+class ListToolDefsResponse(BaseModel):
+    """Response containing a list of tool definitions.
+
+    :param data: List of tool definitions
+    """
+
+    data: list[ToolDef]
+
+
+@runtime_checkable
+class ToolGroups(Protocol):
+    @webmethod(route="/toolgroups", method="POST", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def register_tool_group(
+        self,
+        toolgroup_id: str,
+        provider_id: str,
+        mcp_endpoint: URL | None = None,
+        args: dict[str, Any] | None = None,
+    ) -> None:
+        """Register a tool group.
+
+        :param toolgroup_id: The ID of the tool group to register.
+        :param provider_id: The ID of the provider to use for the tool group.
+        :param mcp_endpoint: The MCP endpoint to use for the tool group.
+        :param args: A dictionary of arguments to pass to the tool group.
+        """
+        ...
+
+    @webmethod(route="/toolgroups/{toolgroup_id:path}", method="GET", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def get_tool_group(
+        self,
+        toolgroup_id: str,
+    ) -> ToolGroup:
+        """Get a tool group by its ID.
+
+        :param toolgroup_id: The ID of the tool group to get.
+        :returns: A ToolGroup.
+        """
+        ...
+
+    @webmethod(route="/toolgroups", method="GET", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def list_tool_groups(self) -> ListToolGroupsResponse:
+        """List tool groups with optional provider.
+
+        :returns: A ListToolGroupsResponse.
+        """
+        ...
+
+    @webmethod(route="/tools", method="GET", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def list_tools(self, toolgroup_id: str | None = None) -> ListToolDefsResponse:
+        """List tools with optional tool group.
+
+        :param toolgroup_id: The ID of the tool group to list tools for.
+        :returns: A ListToolDefsResponse.
+        """
+        ...
+
+    @webmethod(route="/tools/{tool_name:path}", method="GET", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def get_tool(
+        self,
+        tool_name: str,
+    ) -> ToolDef:
+        """Get a tool by its name.
+
+        :param tool_name: The name of the tool to get.
+        :returns: A ToolDef.
+        """
+        ...
+
+    @webmethod(route="/toolgroups/{toolgroup_id:path}", method="DELETE", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def unregister_toolgroup(
+        self,
+        toolgroup_id: str,
+    ) -> None:
+        """Unregister a tool group.
+
+        :param toolgroup_id: The ID of the tool group to unregister.
+        """
+        ...
+
+
+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"
+
+
+@runtime_checkable
+class ToolRuntime(Protocol):
+    tool_store: ToolStore | None = None
+
+    # TODO: This needs to be renamed once OPEN API generator name conflict issue is fixed.
+    @webmethod(route="/tool-runtime/list-tools", method="GET", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def list_runtime_tools(
+        self,
+        tool_group_id: str | None = None,
+        mcp_endpoint: URL | None = None,
+        authorization: str | None = None,
+    ) -> ListToolDefsResponse:
+        """List all tools in the runtime.
+
+        :param tool_group_id: The ID of the tool group to list tools for.
+        :param mcp_endpoint: The MCP endpoint to use for the tool group.
+        :param authorization: (Optional) OAuth access token for authenticating with the MCP server.
+        :returns: A ListToolDefsResponse.
+        """
+        ...
+
+    @webmethod(route="/tool-runtime/invoke", method="POST", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def invoke_tool(
+        self,
+        tool_name: str,
+        kwargs: dict[str, Any],
+        authorization: str | None = None,
+    ) -> ToolInvocationResult:
+        """Run a tool with the given arguments.
+
+        :param tool_name: The name of the tool to invoke.
+        :param kwargs: A dictionary of arguments to pass to the tool.
+        :param authorization: (Optional) OAuth access token for authenticating with the MCP server.
+        :returns: A ToolInvocationResult.
+        """
+        ...

llama_stack_api/validators.py

@@ -0,0 +1,46 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""Validators for API request parameters.
+
+This module contains validation functions used by providers to validate
+request parameters that cannot be easily validated using Pydantic alone.
+"""
+
+from llama_stack_api.inference import OpenAIEmbeddingsRequestWithExtraBody
+
+
+def validate_embeddings_input_is_text(
+    params: OpenAIEmbeddingsRequestWithExtraBody,
+) -> None:
+    """
+    Validate that embeddings input contains only text strings, not token arrays.
+
+    Token arrays (list[int] and list[list[int]]) are a newer OpenAI feature
+    that is not universally supported across all embedding providers. This
+    validator should be called by providers that only support text input (str or list[str]).
+
+    :param params: The OpenAI embeddings request parameters
+    :raises ValueError: If input contains token arrays
+    """
+    # Valid: string input
+    if isinstance(params.input, str):
+        return
+
+    # Valid: list of strings
+    if isinstance(params.input, list) and isinstance(params.input[0], str):
+        return
+
+    # If we get here, input is a token array (list[int] or list[list[int]])
+    raise ValueError(
+        f"Model '{params.model}' does not support token arrays. "
+        f"Please provide text input as a string or list of strings instead."
+    )
+
+
+__all__ = [
+    "validate_embeddings_input_is_text",
+]

llama_stack_api/vector_io/__init__.py

@@ -0,0 +1,88 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""VectorIO API module.
+
+This module provides the VectorIO API for vector database operations.
+Protocol definitions are in api.py, Pydantic models are in models.py,
+and FastAPI routes are in fastapi_routes.py.
+"""
+
+# Re-export Protocol classes from api.py
+from . import fastapi_routes
+from .api import VectorIO, VectorStoreTable
+
+# Re-export all Pydantic models from models.py
+from .models import (
+    Chunk,
+    ChunkMetadata,
+    EmbeddedChunk,
+    OpenAICreateVectorStoreFileBatchRequestWithExtraBody,
+    OpenAICreateVectorStoreRequestWithExtraBody,
+    QueryChunksResponse,
+    SearchRankingOptions,
+    VectorStoreChunkingStrategy,
+    VectorStoreChunkingStrategyAuto,
+    VectorStoreChunkingStrategyStatic,
+    VectorStoreChunkingStrategyStaticConfig,
+    VectorStoreContent,
+    VectorStoreCreateRequest,
+    VectorStoreDeleteResponse,
+    VectorStoreFileAttributes,
+    VectorStoreFileBatchObject,
+    VectorStoreFileContentResponse,
+    VectorStoreFileCounts,
+    VectorStoreFileDeleteResponse,
+    VectorStoreFileLastError,
+    VectorStoreFileObject,
+    VectorStoreFilesListInBatchResponse,
+    VectorStoreFileStatus,
+    VectorStoreListFilesResponse,
+    VectorStoreListResponse,
+    VectorStoreModifyRequest,
+    VectorStoreObject,
+    VectorStoreSearchRequest,
+    VectorStoreSearchResponse,
+    VectorStoreSearchResponsePage,
+)
+
+__all__ = [
+    # Protocol classes
+    "VectorIO",
+    "VectorStoreTable",
+    # Pydantic models
+    "Chunk",
+    "ChunkMetadata",
+    "EmbeddedChunk",
+    "OpenAICreateVectorStoreFileBatchRequestWithExtraBody",
+    "OpenAICreateVectorStoreRequestWithExtraBody",
+    "QueryChunksResponse",
+    "SearchRankingOptions",
+    "VectorStoreChunkingStrategy",
+    "VectorStoreChunkingStrategyAuto",
+    "VectorStoreChunkingStrategyStatic",
+    "VectorStoreChunkingStrategyStaticConfig",
+    "VectorStoreContent",
+    "VectorStoreCreateRequest",
+    "VectorStoreDeleteResponse",
+    "VectorStoreFileAttributes",
+    "VectorStoreFileBatchObject",
+    "VectorStoreFileContentResponse",
+    "VectorStoreFileCounts",
+    "VectorStoreFileDeleteResponse",
+    "VectorStoreFileLastError",
+    "VectorStoreFileObject",
+    "VectorStoreFileStatus",
+    "VectorStoreFilesListInBatchResponse",
+    "VectorStoreListFilesResponse",
+    "VectorStoreListResponse",
+    "VectorStoreModifyRequest",
+    "VectorStoreObject",
+    "VectorStoreSearchRequest",
+    "VectorStoreSearchResponse",
+    "VectorStoreSearchResponsePage",
+    "fastapi_routes",
+]