llama-stack-api 0.4.3__py3-none-any.whl → 0.4.4__py3-none-any.whl

llama_stack_api/inspect_api/__init__.py

@@ -0,0 +1,37 @@
+# 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.
+
+"""Inspect API protocol and models.
+
+This module contains the Inspect protocol definition.
+Pydantic models are defined in llama_stack_api.inspect.models.
+The FastAPI router is defined in llama_stack_api.inspect.fastapi_routes.
+"""
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import protocol for re-export
+from .api import Inspect
+
+# Import models for re-export
+from .models import (
+    ApiFilter,
+    HealthInfo,
+    ListRoutesResponse,
+    RouteInfo,
+    VersionInfo,
+)
+
+__all__ = [
+    "Inspect",
+    "ApiFilter",
+    "HealthInfo",
+    "ListRoutesResponse",
+    "RouteInfo",
+    "VersionInfo",
+    "fastapi_routes",
+]

llama_stack_api/inspect_api/api.py

@@ -0,0 +1,25 @@
+# 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 typing import Protocol, runtime_checkable
+
+from .models import (
+    ApiFilter,
+    HealthInfo,
+    ListRoutesResponse,
+    VersionInfo,
+)
+
+
+@runtime_checkable
+class Inspect(Protocol):
+    """APIs for inspecting the Llama Stack service, including health status, available API routes with methods and implementing providers."""
+
+    async def list_routes(self, api_filter: ApiFilter | None = None) -> ListRoutesResponse: ...
+
+    async def health(self) -> HealthInfo: ...
+
+    async def version(self) -> VersionInfo: ...

llama_stack_api/inspect_api/fastapi_routes.py

@@ -0,0 +1,76 @@
+# 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 Inspect API.
+
+This module defines the FastAPI router for the Inspect API using standard
+FastAPI route decorators.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Query
+
+from llama_stack_api.router_utils import PUBLIC_ROUTE_KEY, standard_responses
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+from .api import Inspect
+from .models import (
+    ApiFilter,
+    HealthInfo,
+    ListRoutesResponse,
+    VersionInfo,
+)
+
+
+def create_router(impl: Inspect) -> APIRouter:
+    """Create a FastAPI router for the Inspect API."""
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Inspect"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/inspect/routes",
+        response_model=ListRoutesResponse,
+        summary="List routes.",
+        description="List all available API routes with their methods and implementing providers.",
+        responses={200: {"description": "Response containing information about all available routes."}},
+    )
+    async def list_routes(
+        api_filter: Annotated[
+            ApiFilter | None,
+            Query(
+                description="Optional filter to control which routes are returned. Can be an API level ('v1', 'v1alpha', 'v1beta') to show non-deprecated routes at that level, or 'deprecated' to show deprecated routes across all levels. If not specified, returns all non-deprecated routes."
+            ),
+        ] = None,
+    ) -> ListRoutesResponse:
+        return await impl.list_routes(api_filter)
+
+    @router.get(
+        "/health",
+        response_model=HealthInfo,
+        summary="Get health status.",
+        description="Get the current health status of the service.",
+        responses={200: {"description": "Health information indicating if the service is operational."}},
+        openapi_extra={PUBLIC_ROUTE_KEY: True},
+    )
+    async def health() -> HealthInfo:
+        return await impl.health()
+
+    @router.get(
+        "/version",
+        response_model=VersionInfo,
+        summary="Get version.",
+        description="Get the version of the service.",
+        responses={200: {"description": "Version information containing the service version number."}},
+        openapi_extra={PUBLIC_ROUTE_KEY: True},
+    )
+    async def version() -> VersionInfo:
+        return await impl.version()
+
+    return router

llama_stack_api/inspect_api/models.py

@@ -0,0 +1,28 @@
+# 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 Inspect API requests and responses.
+
+This module re-exports models from llama_stack_api.admin.models to ensure
+a single source of truth and avoid type conflicts.
+"""
+
+# Import and re-export shared models from admin
+from llama_stack_api.admin.models import (
+    ApiFilter,
+    HealthInfo,
+    ListRoutesResponse,
+    RouteInfo,
+    VersionInfo,
+)
+
+__all__ = [
+    "ApiFilter",
+    "RouteInfo",
+    "HealthInfo",
+    "VersionInfo",
+    "ListRoutesResponse",
+]

llama_stack_api/internal/__init__.py

@@ -0,0 +1,9 @@
+# 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.
+
+# Internal subpackage for shared interfaces that are not part of the public API.
+
+__all__: list[str] = []

llama_stack_api/internal/kvstore.py

@@ -0,0 +1,28 @@
+# 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 datetime import datetime
+from typing import Protocol
+
+
+class KVStore(Protocol):
+    """Protocol for simple key/value storage backends."""
+
+    # TODO: make the value type bytes instead of str
+    async def set(self, key: str, value: str, expiration: datetime | None = None) -> None: ...
+
+    async def get(self, key: str) -> str | None: ...
+
+    async def delete(self, key: str) -> None: ...
+
+    async def values_in_range(self, start_key: str, end_key: str) -> list[str]: ...
+
+    async def keys_in_range(self, start_key: str, end_key: str) -> list[str]: ...
+
+    async def shutdown(self) -> None: ...
+
+
+__all__ = ["KVStore"]

llama_stack_api/internal/sqlstore.py

@@ -0,0 +1,81 @@
+# 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 collections.abc import Mapping, Sequence
+from enum import Enum
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel
+
+from llama_stack_api import PaginatedResponse
+
+
+class ColumnType(Enum):
+    INTEGER = "INTEGER"
+    STRING = "STRING"
+    TEXT = "TEXT"
+    FLOAT = "FLOAT"
+    BOOLEAN = "BOOLEAN"
+    JSON = "JSON"
+    DATETIME = "DATETIME"
+
+
+class ColumnDefinition(BaseModel):
+    type: ColumnType
+    primary_key: bool = False
+    nullable: bool = True
+    default: Any = None
+
+
+class SqlStore(Protocol):
+    """Protocol for common SQL-store functionality."""
+
+    async def create_table(self, table: str, schema: Mapping[str, ColumnType | ColumnDefinition]) -> None: ...
+
+    async def insert(self, table: str, data: Mapping[str, Any] | Sequence[Mapping[str, Any]]) -> None: ...
+
+    async def upsert(
+        self,
+        table: str,
+        data: Mapping[str, Any],
+        conflict_columns: list[str],
+        update_columns: list[str] | None = None,
+    ) -> None: ...
+
+    async def fetch_all(
+        self,
+        table: str,
+        where: Mapping[str, Any] | None = None,
+        where_sql: str | None = None,
+        limit: int | None = None,
+        order_by: list[tuple[str, Literal["asc", "desc"]]] | None = None,
+        cursor: tuple[str, str] | None = None,
+    ) -> PaginatedResponse: ...
+
+    async def fetch_one(
+        self,
+        table: str,
+        where: Mapping[str, Any] | None = None,
+        where_sql: str | None = None,
+        order_by: list[tuple[str, Literal["asc", "desc"]]] | None = None,
+    ) -> dict[str, Any] | None: ...
+
+    async def update(self, table: str, data: Mapping[str, Any], where: Mapping[str, Any]) -> None: ...
+
+    async def delete(self, table: str, where: Mapping[str, Any]) -> None: ...
+
+    async def add_column_if_not_exists(
+        self,
+        table: str,
+        column_name: str,
+        column_type: ColumnType,
+        nullable: bool = True,
+    ) -> None: ...
+
+    async def shutdown(self) -> None: ...
+
+
+__all__ = ["ColumnDefinition", "ColumnType", "SqlStore"]

llama_stack_api/models.py

@@ -0,0 +1,171 @@
+# 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 StrEnum
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+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
+
+
+class CommonModelFields(BaseModel):
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Any additional metadata for this model",
+    )
+
+
+@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
+    :cvar rerank: Reranking model for reordering documents based on their relevance to a query
+    """
+
+    llm = "llm"
+    embedding = "embedding"
+    rerank = "rerank"
+
+
+@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
+    def model_id(self) -> str:
+        return self.identifier
+
+    @property
+    def provider_model_id(self) -> str:
+        assert self.provider_resource_id is not None, "Provider resource ID must be set"
+        return self.provider_resource_id
+
+    model_config = ConfigDict(protected_namespaces=())
+
+    model_type: ModelType = Field(default=ModelType.llm)
+
+    @field_validator("provider_resource_id")
+    @classmethod
+    def validate_provider_resource_id(cls, v):
+        if v is None:
+            raise ValueError("provider_resource_id cannot be None")
+        return v
+
+
+class ModelInput(CommonModelFields):
+    model_id: str
+    provider_id: str | None = None
+    provider_model_id: str | None = None
+    model_type: ModelType | None = ModelType.llm
+    model_config = ConfigDict(protected_namespaces=())
+
+
+class ListModelsResponse(BaseModel):
+    data: list[Model]
+
+
+@json_schema_type
+class OpenAIModel(BaseModel):
+    """A model from OpenAI.
+
+    :id: The ID of the model
+    :object: The object type, which will be "model"
+    :created: The Unix timestamp in seconds when the model was created
+    :owned_by: The owner of the model
+    :custom_metadata: Llama Stack-specific metadata including model_type, provider info, and additional metadata
+    """
+
+    id: str
+    object: Literal["model"] = "model"
+    created: int
+    owned_by: str
+    custom_metadata: dict[str, Any] | None = None
+
+
+@json_schema_type
+class OpenAIListModelsResponse(BaseModel):
+    data: list[OpenAIModel]
+
+
+@runtime_checkable
+class Models(Protocol):
+    async def list_models(self) -> ListModelsResponse:
+        """List all models.
+
+        :returns: A ListModelsResponse.
+        """
+        ...
+
+    @webmethod(route="/models", method="GET", level=LLAMA_STACK_API_V1)
+    async def openai_list_models(self) -> OpenAIListModelsResponse:
+        """List models using the OpenAI API.
+
+        :returns: A OpenAIListModelsResponse.
+        """
+        ...
+
+    @webmethod(route="/models/{model_id:path}", method="GET", level=LLAMA_STACK_API_V1)
+    async def get_model(
+        self,
+        model_id: str,
+    ) -> Model:
+        """Get model.
+
+        Get a model by its identifier.
+
+        :param model_id: The identifier of the model to get.
+        :returns: A Model.
+        """
+        ...
+
+    @webmethod(route="/models", method="POST", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def register_model(
+        self,
+        model_id: str,
+        provider_model_id: str | None = None,
+        provider_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        model_type: ModelType | None = None,
+    ) -> Model:
+        """Register model.
+
+        Register a model.
+
+        :param model_id: The identifier of the model to register.
+        :param provider_model_id: The identifier of the model in the provider.
+        :param provider_id: The identifier of the provider.
+        :param metadata: Any additional metadata for this model.
+        :param model_type: The type of model to register.
+        :returns: A Model.
+        """
+        ...
+
+    @webmethod(route="/models/{model_id:path}", method="DELETE", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def unregister_model(
+        self,
+        model_id: str,
+    ) -> None:
+        """Unregister model.
+
+        Unregister a model.
+
+        :param model_id: The identifier of the model to unregister.
+        """
+        ...