llama-stack-api 0.4.2__py3-none-any.whl → 0.4.4__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.py

@@ -0,0 +1,173 @@
+# 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 enum import StrEnum
+from typing import Annotated, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from llama_stack_api.common.responses import Order
+from llama_stack_api.schema_utils import ExtraBodyField, json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+from .openai_responses import (
+    ListOpenAIResponseInputItem,
+    ListOpenAIResponseObject,
+    OpenAIDeleteResponseObject,
+    OpenAIResponseInput,
+    OpenAIResponseInputTool,
+    OpenAIResponseInputToolChoice,
+    OpenAIResponseObject,
+    OpenAIResponseObjectStream,
+    OpenAIResponsePrompt,
+    OpenAIResponseText,
+)
+
+
+@json_schema_type
+class ResponseGuardrailSpec(BaseModel):
+    """Specification for a guardrail to apply during response generation.
+
+    :param type: The type/identifier of the guardrail.
+    """
+
+    type: str
+    # TODO: more fields to be added for guardrail configuration
+
+
+ResponseGuardrail = str | ResponseGuardrailSpec
+
+
+class ResponseItemInclude(StrEnum):
+    """
+    Specify additional output data to include in the model response.
+    """
+
+    web_search_call_action_sources = "web_search_call.action.sources"
+    code_interpreter_call_outputs = "code_interpreter_call.outputs"
+    computer_call_output_output_image_url = "computer_call_output.output.image_url"
+    file_search_call_results = "file_search_call.results"
+    message_input_image_image_url = "message.input_image.image_url"
+    message_output_text_logprobs = "message.output_text.logprobs"
+    reasoning_encrypted_content = "reasoning.encrypted_content"
+
+
+@runtime_checkable
+class Agents(Protocol):
+    """Agents
+
+    APIs for creating and interacting with agentic systems."""
+
+    # We situate the OpenAI Responses API in the Agents API just like we did things
+    # for Inference. The Responses API, in its intent, serves the same purpose as
+    # the Agents API above -- it is essentially a lightweight "agentic loop" with
+    # integrated tool calling.
+    #
+    # Both of these APIs are inherently stateful.
+
+    @webmethod(route="/responses/{response_id}", method="GET", level=LLAMA_STACK_API_V1)
+    async def get_openai_response(
+        self,
+        response_id: str,
+    ) -> OpenAIResponseObject:
+        """Get a model response.
+
+        :param response_id: The ID of the OpenAI response to retrieve.
+        :returns: An OpenAIResponseObject.
+        """
+        ...
+
+    @webmethod(route="/responses", method="POST", level=LLAMA_STACK_API_V1)
+    async def create_openai_response(
+        self,
+        input: str | list[OpenAIResponseInput],
+        model: str,
+        prompt: OpenAIResponsePrompt | None = None,
+        instructions: str | None = None,
+        parallel_tool_calls: bool | None = True,
+        previous_response_id: str | None = None,
+        conversation: str | None = None,
+        store: bool | None = True,
+        stream: bool | None = False,
+        temperature: float | None = None,
+        text: OpenAIResponseText | None = None,
+        tool_choice: OpenAIResponseInputToolChoice | None = None,
+        tools: list[OpenAIResponseInputTool] | None = None,
+        include: list[ResponseItemInclude] | None = None,
+        max_infer_iters: int | None = 10,  # this is an extension to the OpenAI API
+        guardrails: Annotated[
+            list[ResponseGuardrail] | None,
+            ExtraBodyField(
+                "List of guardrails to apply during response generation. Guardrails provide safety and content moderation."
+            ),
+        ] = None,
+        max_tool_calls: int | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> OpenAIResponseObject | AsyncIterator[OpenAIResponseObjectStream]:
+        """Create a model response.
+
+        :param input: Input message(s) to create the response.
+        :param model: The underlying LLM used for completions.
+        :param prompt: (Optional) Prompt object with ID, version, and variables.
+        :param previous_response_id: (Optional) if specified, the new response will be a continuation of the previous response. This can be used to easily fork-off new responses from existing responses.
+        :param conversation: (Optional) The ID of a conversation to add the response to. Must begin with 'conv_'. Input and output messages will be automatically added to the conversation.
+        :param include: (Optional) Additional fields to include in the response.
+        :param guardrails: (Optional) List of guardrails to apply during response generation. Can be guardrail IDs (strings) or guardrail specifications.
+        :param max_tool_calls: (Optional) Max number of total calls to built-in tools that can be processed in a response.
+        :param metadata: (Optional) Dictionary of metadata key-value pairs to attach to the response.
+        :returns: An OpenAIResponseObject.
+        """
+        ...
+
+    @webmethod(route="/responses", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_openai_responses(
+        self,
+        after: str | None = None,
+        limit: int | None = 50,
+        model: str | None = None,
+        order: Order | None = Order.desc,
+    ) -> ListOpenAIResponseObject:
+        """List all responses.
+
+        :param after: The ID of the last response to return.
+        :param limit: The number of responses to return.
+        :param model: The model to filter responses by.
+        :param order: The order to sort responses by when sorted by created_at ('asc' or 'desc').
+        :returns: A ListOpenAIResponseObject.
+        """
+        ...
+
+    @webmethod(route="/responses/{response_id}/input_items", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_openai_response_input_items(
+        self,
+        response_id: str,
+        after: str | None = None,
+        before: str | None = None,
+        include: list[str] | None = None,
+        limit: int | None = 20,
+        order: Order | None = Order.desc,
+    ) -> ListOpenAIResponseInputItem:
+        """List input items.
+
+        :param response_id: The ID of the response to retrieve input items for.
+        :param after: An item ID to list items after, used for pagination.
+        :param before: An item ID to list items before, used for pagination.
+        :param include: Additional fields to include in the response.
+        :param limit: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
+        :param order: The order to return the input items in. Default is desc.
+        :returns: An ListOpenAIResponseInputItem.
+        """
+        ...
+
+    @webmethod(route="/responses/{response_id}", method="DELETE", level=LLAMA_STACK_API_V1)
+    async def delete_openai_response(self, response_id: str) -> OpenAIDeleteResponseObject:
+        """Delete a response.
+
+        :param response_id: The ID of the OpenAI response to delete.
+        :returns: An OpenAIDeleteResponseObject
+        """
+        ...

llama_stack_api/batches/__init__.py

@@ -0,0 +1,40 @@
+# 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.
+
+"""Batches API protocol and models.
+
+This module contains the Batches protocol definition.
+Pydantic models are defined in llama_stack_api.batches.models.
+The FastAPI router is defined in llama_stack_api.batches.fastapi_routes.
+"""
+
+from openai.types import Batch as BatchObject
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import protocol for re-export
+from .api import Batches
+
+# Import models for re-export
+from .models import (
+    CancelBatchRequest,
+    CreateBatchRequest,
+    ListBatchesRequest,
+    ListBatchesResponse,
+    RetrieveBatchRequest,
+)
+
+__all__ = [
+    "Batches",
+    "BatchObject",
+    "CancelBatchRequest",
+    "CreateBatchRequest",
+    "ListBatchesRequest",
+    "ListBatchesResponse",
+    "RetrieveBatchRequest",
+    "fastapi_routes",
+]

llama_stack_api/batches/api.py

@@ -0,0 +1,53 @@
+# 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 openai.types import Batch as BatchObject
+
+from .models import (
+    CancelBatchRequest,
+    CreateBatchRequest,
+    ListBatchesRequest,
+    ListBatchesResponse,
+    RetrieveBatchRequest,
+)
+
+
+@runtime_checkable
+class Batches(Protocol):
+    """
+    The Batches API enables efficient processing of multiple requests in a single operation,
+    particularly useful for processing large datasets, batch evaluation workflows, and
+    cost-effective inference at scale.
+
+    The API is designed to allow use of openai client libraries for seamless integration.
+
+    This API provides the following extensions:
+     - idempotent batch creation
+
+    Note: This API is currently under active development and may undergo changes.
+    """
+
+    async def create_batch(
+        self,
+        request: CreateBatchRequest,
+    ) -> BatchObject: ...
+
+    async def retrieve_batch(
+        self,
+        request: RetrieveBatchRequest,
+    ) -> BatchObject: ...
+
+    async def cancel_batch(
+        self,
+        request: CancelBatchRequest,
+    ) -> BatchObject: ...
+
+    async def list_batches(
+        self,
+        request: ListBatchesRequest,
+    ) -> ListBatchesResponse: ...