llama-stack-api 0.4.3__py3-none-any.whl → 0.5.0rc1__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/__init__.py

@@ -0,0 +1,47 @@
+# 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.
+
+"""Models API protocol and models.
+
+This module contains the Models protocol definition.
+Pydantic models are defined in llama_stack_api.models.models.
+The FastAPI router is defined in llama_stack_api.models.fastapi_routes.
+"""
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import new protocol for FastAPI router
+from .api import Models
+
+# Import models for re-export
+from .models import (
+    CommonModelFields,
+    GetModelRequest,
+    ListModelsResponse,
+    Model,
+    ModelInput,
+    ModelType,
+    OpenAIListModelsResponse,
+    OpenAIModel,
+    RegisterModelRequest,
+    UnregisterModelRequest,
+)
+
+__all__ = [
+    "CommonModelFields",
+    "fastapi_routes",
+    "GetModelRequest",
+    "ListModelsResponse",
+    "Model",
+    "ModelInput",
+    "Models",
+    "ModelType",
+    "OpenAIListModelsResponse",
+    "OpenAIModel",
+    "RegisterModelRequest",
+    "UnregisterModelRequest",
+]

llama_stack_api/models/api.py

@@ -0,0 +1,38 @@
+# 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.
+
+"""Models API protocol definition.
+
+This module contains the Models protocol definition.
+Pydantic models are defined in llama_stack_api.models.models.
+The FastAPI router is defined in llama_stack_api.models.fastapi_routes.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from .models import (
+    GetModelRequest,
+    ListModelsResponse,
+    Model,
+    OpenAIListModelsResponse,
+    RegisterModelRequest,
+    UnregisterModelRequest,
+)
+
+
+@runtime_checkable
+class Models(Protocol):
+    """Protocol for model management operations."""
+
+    async def list_models(self) -> ListModelsResponse: ...
+
+    async def openai_list_models(self) -> OpenAIListModelsResponse: ...
+
+    async def get_model(self, request: GetModelRequest) -> Model: ...
+
+    async def register_model(self, request: RegisterModelRequest) -> Model: ...
+
+    async def unregister_model(self, request: UnregisterModelRequest) -> None: ...

llama_stack_api/models/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 Models API.
+
+This module defines the FastAPI router for the Models 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 Models
+from .models import (
+    GetModelRequest,
+    Model,
+    OpenAIListModelsResponse,
+    RegisterModelRequest,
+    UnregisterModelRequest,
+)
+
+# Path parameter dependencies for single-field models
+get_model_request = create_path_dependency(GetModelRequest)
+unregister_model_request = create_path_dependency(UnregisterModelRequest)
+
+
+def create_router(impl: Models) -> APIRouter:
+    """Create a FastAPI router for the Models API.
+
+    Args:
+        impl: The Models implementation instance
+
+    Returns:
+        APIRouter configured for the Models API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Models"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/models",
+        response_model=OpenAIListModelsResponse,
+        summary="List models using the OpenAI API.",
+        description="List models using the OpenAI API.",
+        responses={
+            200: {"description": "A list of OpenAI model objects."},
+        },
+    )
+    async def openai_list_models() -> OpenAIListModelsResponse:
+        return await impl.openai_list_models()
+
+    @router.get(
+        "/models/{model_id:path}",
+        response_model=Model,
+        summary="Get a model by its identifier.",
+        description="Get a model by its identifier.",
+        responses={
+            200: {"description": "The model object."},
+        },
+    )
+    async def get_model(
+        request: Annotated[GetModelRequest, Depends(get_model_request)],
+    ) -> Model:
+        return await impl.get_model(request)
+
+    @router.post(
+        "/models",
+        response_model=Model,
+        summary="Register a model.",
+        description="Register a model.",
+        responses={
+            200: {"description": "The registered model object."},
+        },
+        deprecated=True,
+    )
+    async def register_model(
+        request: Annotated[RegisterModelRequest, Body(...)],
+    ) -> Model:
+        return await impl.register_model(request)
+
+    @router.delete(
+        "/models/{model_id:path}",
+        summary="Unregister a model.",
+        description="Unregister a model.",
+        responses={
+            200: {"description": "The model was successfully unregistered."},
+        },
+        deprecated=True,
+    )
+    async def unregister_model(
+        request: Annotated[UnregisterModelRequest, Depends(unregister_model_request)],
+    ) -> None:
+        return await impl.unregister_model(request)
+
+    return router

llama_stack_api/models/models.py

@@ -0,0 +1,157 @@
+# 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 Models API requests and responses.
+
+This module defines the request and response models for the Models API
+using Pydantic with Field descriptions for OpenAPI schema generation.
+"""
+
+from enum import StrEnum
+from typing import Any, Literal
+
+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
+
+
+@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"
+
+
+class CommonModelFields(BaseModel):
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Any additional metadata for this model",
+    )
+
+
+@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=())
+
+
+@json_schema_type
+class ListModelsResponse(BaseModel):
+    """Response containing a list of model objects."""
+
+    data: list[Model] = Field(..., description="List of model objects.")
+
+
+@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):
+    """Response containing a list of OpenAI model objects."""
+
+    data: list[OpenAIModel] = Field(..., description="List of OpenAI model objects.")
+
+
+# Request models for each endpoint
+
+
+@json_schema_type
+class GetModelRequest(BaseModel):
+    """Request model for getting a model by ID."""
+
+    model_id: str = Field(..., description="The ID of the model to get.")
+
+
+@json_schema_type
+class RegisterModelRequest(BaseModel):
+    """Request model for registering a model."""
+
+    model_id: str = Field(..., description="The identifier of the model to register.")
+    provider_model_id: str | None = Field(default=None, description="The identifier of the model in the provider.")
+    provider_id: str | None = Field(default=None, description="The identifier of the provider.")
+    metadata: dict[str, Any] | None = Field(default=None, description="Any additional metadata for this model.")
+    model_type: ModelType | None = Field(default=None, description="The type of model to register.")
+
+
+@json_schema_type
+class UnregisterModelRequest(BaseModel):
+    """Request model for unregistering a model."""
+
+    model_id: str = Field(..., description="The ID of the model to unregister.")
+
+
+__all__ = [
+    "CommonModelFields",
+    "GetModelRequest",
+    "ListModelsResponse",
+    "Model",
+    "ModelInput",
+    "ModelType",
+    "OpenAIListModelsResponse",
+    "OpenAIModel",
+    "RegisterModelRequest",
+    "UnregisterModelRequest",
+]