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

llama_stack_api/admin/__init__.py

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

llama_stack_api/admin/api.py

@@ -0,0 +1,72 @@
+# 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 (
+    HealthInfo,
+    InspectProviderRequest,
+    ListProvidersResponse,
+    ListRoutesRequest,
+    ListRoutesResponse,
+    ProviderInfo,
+    VersionInfo,
+)
+
+
+@runtime_checkable
+class Admin(Protocol):
+    """Admin
+
+    Admin API for stack operations only available to administrative users.
+    """
+
+    async def list_providers(self) -> ListProvidersResponse:
+        """List providers.
+
+        List all available providers.
+
+        :returns: A ListProvidersResponse containing information about all providers.
+        """
+        ...
+
+    async def inspect_provider(self, request: InspectProviderRequest) -> ProviderInfo:
+        """Get provider.
+
+        Get detailed information about a specific provider.
+
+        :param request: Request containing the provider ID to inspect
+        :returns: A ProviderInfo object containing the provider's details.
+        """
+        ...
+
+    async def list_routes(self, request: ListRoutesRequest) -> ListRoutesResponse:
+        """List routes.
+
+        List all available API routes with their methods and implementing providers.
+
+        :param request: Request containing optional filter parameters
+        :returns: Response containing information about all available routes.
+        """
+        ...
+
+    async def health(self) -> HealthInfo:
+        """Get health status.
+
+        Get the current health status of the service.
+
+        :returns: Health information indicating if the service is operational.
+        """
+        ...
+
+    async def version(self) -> VersionInfo:
+        """Get version.
+
+        Get the version of the service.
+
+        :returns: Version information containing the service version number.
+        """
+        ...

llama_stack_api/admin/fastapi_routes.py

@@ -0,0 +1,117 @@
+# 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 Admin API.
+
+This module defines the FastAPI router for the Admin API using standard
+FastAPI route decorators. The router is defined in the API package to keep
+all API-related code together.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+
+from llama_stack_api.router_utils import create_path_dependency, create_query_dependency, standard_responses
+from llama_stack_api.version import LLAMA_STACK_API_V1ALPHA
+
+from .api import Admin
+from .models import (
+    HealthInfo,
+    InspectProviderRequest,
+    ListProvidersResponse,
+    ListRoutesRequest,
+    ListRoutesResponse,
+    ProviderInfo,
+    VersionInfo,
+)
+
+# Automatically generate dependency functions from Pydantic models
+get_inspect_provider_request = create_path_dependency(InspectProviderRequest)
+get_list_routes_request = create_query_dependency(ListRoutesRequest)
+
+
+def create_router(impl: Admin) -> APIRouter:
+    """Create a FastAPI router for the Admin API.
+
+    Args:
+        impl: The Admin implementation instance
+
+    Returns:
+        APIRouter configured for the Admin API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1ALPHA}",
+        tags=["Admin"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/admin/providers",
+        response_model=ListProvidersResponse,
+        summary="List all available providers",
+        description="List all available providers with their configuration and health status.",
+        responses={
+            200: {"description": "A list of provider information objects."},
+        },
+    )
+    async def list_providers() -> ListProvidersResponse:
+        return await impl.list_providers()
+
+    @router.get(
+        "/admin/providers/{provider_id}",
+        response_model=ProviderInfo,
+        summary="Get provider details",
+        description="Get detailed information about a specific provider.",
+        responses={
+            200: {"description": "The provider information object."},
+            404: {"description": "Provider not found."},
+        },
+    )
+    async def inspect_provider(
+        request: Annotated[InspectProviderRequest, Depends(get_inspect_provider_request)],
+    ) -> ProviderInfo:
+        return await impl.inspect_provider(request)
+
+    @router.get(
+        "/admin/inspect/routes",
+        response_model=ListRoutesResponse,
+        summary="List all available API routes",
+        description="List all available API routes with their methods and implementing providers.",
+        responses={
+            200: {"description": "A list of route information objects."},
+        },
+    )
+    async def list_routes(
+        request: Annotated[ListRoutesRequest, Depends(get_list_routes_request)],
+    ) -> ListRoutesResponse:
+        return await impl.list_routes(request)
+
+    @router.get(
+        "/admin/health",
+        response_model=HealthInfo,
+        summary="Get service health status",
+        description="Get the current health status of the service.",
+        responses={
+            200: {"description": "Health information object."},
+        },
+    )
+    async def health() -> HealthInfo:
+        return await impl.health()
+
+    @router.get(
+        "/admin/version",
+        response_model=VersionInfo,
+        summary="Get service version",
+        description="Get the version of the service.",
+        responses={
+            200: {"description": "Version information object."},
+        },
+    )
+    async def version() -> VersionInfo:
+        return await impl.version()
+
+    return router

llama_stack_api/admin/models.py

@@ -0,0 +1,113 @@
+# 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 Any, Literal
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.datatypes import HealthResponse, HealthStatus
+from llama_stack_api.schema_utils import json_schema_type
+
+# Valid values for the route filter parameter.
+# Actual API levels: v1, v1alpha, v1beta (filters by level, excludes deprecated)
+# Special filter value: "deprecated" (shows deprecated routes regardless of level)
+ApiFilter = Literal["v1", "v1alpha", "v1beta", "deprecated"]
+
+
+@json_schema_type
+class RouteInfo(BaseModel):
+    """Information about an API route including its path, method, and implementing providers.
+
+    :param route: The API endpoint path
+    :param method: HTTP method for the route
+    :param provider_types: List of provider types that implement this route
+    """
+
+    route: str = Field(description="The API route path")
+    method: str = Field(description="The HTTP method for the route")
+    provider_types: list[str] = Field(description="List of provider types implementing this route")
+
+
+@json_schema_type
+class HealthInfo(BaseModel):
+    """Health status information for the service.
+
+    :param status: Current health status of the service
+    """
+
+    status: HealthStatus = Field(description="The health status of the service")
+
+
+@json_schema_type
+class VersionInfo(BaseModel):
+    """Version information for the service.
+
+    :param version: Version number of the service
+    """
+
+    version: str = Field(description="The version string of the service")
+
+
+@json_schema_type
+class ListRoutesResponse(BaseModel):
+    """Response containing a list of all available API routes.
+
+    :param data: List of available route information objects
+    """
+
+    data: list[RouteInfo] = Field(description="List of available API routes")
+
+
+@json_schema_type
+class ProviderInfo(BaseModel):
+    """Information about a registered provider including its configuration and health status.
+
+    :param api: The API name this provider implements
+    :param provider_id: Unique identifier for the provider
+    :param provider_type: The type of provider implementation
+    :param config: Configuration parameters for the provider
+    :param health: Current health status of the provider
+    """
+
+    api: str = Field(..., description="The API name this provider implements")
+    provider_id: str = Field(..., description="Unique identifier for the provider")
+    provider_type: str = Field(..., description="The type of provider implementation")
+    config: dict[str, Any] = Field(..., description="Configuration parameters for the provider")
+    health: HealthResponse = Field(..., description="Current health status of the provider")
+
+
+@json_schema_type
+class ListProvidersResponse(BaseModel):
+    """Response containing a list of all available providers.
+
+    :param data: List of provider information objects
+    """
+
+    data: list[ProviderInfo] = Field(..., description="List of provider information objects")
+
+
+# Request models for FastAPI
+@json_schema_type
+class ListRoutesRequest(BaseModel):
+    """Request to list API routes.
+
+    :param api_filter: Optional filter to control which routes are returned
+    """
+
+    api_filter: ApiFilter | None = Field(
+        default=None,
+        description="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.",
+    )
+
+
+@json_schema_type
+class InspectProviderRequest(BaseModel):
+    """Request to inspect a specific provider.
+
+    :param provider_id: The ID of the provider to inspect
+    """
+
+    provider_id: str = Field(..., description="The ID of the provider to inspect.")

llama_stack_api/agents/__init__.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.
+
+"""Agents API protocol and models.
+
+This module contains the Agents protocol definition for the OpenAI Responses API.
+Pydantic models are defined in llama_stack_api.agents.models.
+The FastAPI router is defined in llama_stack_api.agents.fastapi_routes.
+"""
+
+from . import fastapi_routes
+from .api import Agents
+from .models import (
+    CreateResponseRequest,
+    DeleteResponseRequest,
+    ListResponseInputItemsRequest,
+    ListResponsesRequest,
+    ResponseGuardrail,
+    ResponseGuardrailSpec,
+    ResponseItemInclude,
+    RetrieveResponseRequest,
+)
+
+__all__ = [
+    "Agents",
+    "CreateResponseRequest",
+    "DeleteResponseRequest",
+    "ListResponseInputItemsRequest",
+    "ListResponsesRequest",
+    "ResponseGuardrail",
+    "ResponseGuardrailSpec",
+    "ResponseItemInclude",
+    "RetrieveResponseRequest",
+    "fastapi_routes",
+]

llama_stack_api/agents/api.py

@@ -0,0 +1,52 @@
+# 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 AsyncIterator
+from typing import Protocol, runtime_checkable
+
+from llama_stack_api.openai_responses import (
+    ListOpenAIResponseInputItem,
+    ListOpenAIResponseObject,
+    OpenAIDeleteResponseObject,
+    OpenAIResponseObject,
+    OpenAIResponseObjectStream,
+)
+
+from .models import (
+    CreateResponseRequest,
+    DeleteResponseRequest,
+    ListResponseInputItemsRequest,
+    ListResponsesRequest,
+    RetrieveResponseRequest,
+)
+
+
+@runtime_checkable
+class Agents(Protocol):
+    async def get_openai_response(
+        self,
+        request: RetrieveResponseRequest,
+    ) -> OpenAIResponseObject: ...
+
+    async def create_openai_response(
+        self,
+        request: CreateResponseRequest,
+    ) -> OpenAIResponseObject | AsyncIterator[OpenAIResponseObjectStream]: ...
+
+    async def list_openai_responses(
+        self,
+        request: ListResponsesRequest,
+    ) -> ListOpenAIResponseObject: ...
+
+    async def list_openai_response_input_items(
+        self,
+        request: ListResponseInputItemsRequest,
+    ) -> ListOpenAIResponseInputItem: ...
+
+    async def delete_openai_response(
+        self,
+        request: DeleteResponseRequest,
+    ) -> OpenAIDeleteResponseObject: ...