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

llama_stack_api/agents/fastapi_routes.py

@@ -0,0 +1,268 @@
+# 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 Agents API.
+
+This module defines the FastAPI router for the Agents API using standard
+FastAPI route decorators.
+"""
+
+import asyncio
+import contextvars
+import json
+import logging  # allow-direct-logging
+from collections.abc import AsyncIterator
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Body, Depends, HTTPException, Path, Query
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+from llama_stack_api.common.responses import Order
+from llama_stack_api.openai_responses import (
+    ListOpenAIResponseInputItem,
+    ListOpenAIResponseObject,
+    OpenAIDeleteResponseObject,
+    OpenAIResponseObject,
+)
+from llama_stack_api.router_utils import (
+    create_path_dependency,
+    create_query_dependency,
+    standard_responses,
+)
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+from .api import Agents
+from .models import (
+    CreateResponseRequest,
+    DeleteResponseRequest,
+    ListResponseInputItemsRequest,
+    ListResponsesRequest,
+    ResponseItemInclude,
+    RetrieveResponseRequest,
+)
+
+logger = logging.LoggerAdapter(logging.getLogger(__name__), {"category": "agents"})
+
+
+def create_sse_event(data: Any) -> str:
+    """Create a Server-Sent Event string from data."""
+    if isinstance(data, BaseModel):
+        data = data.model_dump_json()
+    else:
+        data = json.dumps(data)
+    return f"data: {data}\n\n"
+
+
+async def sse_generator(event_gen):
+    """Convert an async generator to SSE format.
+
+    This function iterates over an async generator and formats each yielded
+    item as a Server-Sent Event.
+    """
+    try:
+        async for item in event_gen:
+            yield create_sse_event(item)
+    except asyncio.CancelledError:
+        if hasattr(event_gen, "aclose"):
+            await event_gen.aclose()
+        raise  # Re-raise to maintain proper cancellation semantics
+    except Exception as e:
+        logger.exception("Error in SSE generator")
+        exc = _http_exception_from_sse_error(e)
+        yield create_sse_event({"error": {"status_code": exc.status_code, "message": exc.detail}})
+
+
+# Automatically generate dependency functions from Pydantic models
+get_retrieve_response_request = create_path_dependency(RetrieveResponseRequest)
+get_delete_response_request = create_path_dependency(DeleteResponseRequest)
+get_list_responses_request = create_query_dependency(ListResponsesRequest)
+
+
+# Manual dependency for ListResponseInputItemsRequest since it mixes Path and Query parameters
+async def get_list_response_input_items_request(
+    response_id: Annotated[str, Path(description="The ID of the response to retrieve input items for.")],
+    after: Annotated[
+        str | None,
+        Query(description="An item ID to list items after, used for pagination."),
+    ] = None,
+    before: Annotated[
+        str | None,
+        Query(description="An item ID to list items before, used for pagination."),
+    ] = None,
+    include: Annotated[
+        list[ResponseItemInclude] | None,
+        Query(description="Additional fields to include in the response."),
+    ] = None,
+    limit: Annotated[
+        int | None,
+        Query(
+            description="A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20."
+        ),
+    ] = 20,
+    order: Annotated[Order | None, Query(description="The order to return the input items in.")] = Order.desc,
+) -> ListResponseInputItemsRequest:
+    return ListResponseInputItemsRequest(
+        response_id=response_id,
+        after=after,
+        before=before,
+        include=include,
+        limit=limit,
+        order=order,
+    )
+
+
+def _http_exception_from_value_error(exc: ValueError) -> HTTPException:
+    """Convert implementation `ValueError` into an OpenAI-compatible HTTP error.
+
+    The compatibility OpenAI client maps HTTP 400 -> `BadRequestError`.
+    The existing API surface (and integration tests) expect "not found" cases
+    to be represented as a 400, not a 404.
+    """
+
+    detail = str(exc) or "Invalid value"
+    return HTTPException(status_code=400, detail=detail)
+
+
+def _http_exception_from_sse_error(exc: Exception) -> HTTPException:
+    if isinstance(exc, HTTPException):
+        return exc
+    if isinstance(exc, ValueError):
+        return _http_exception_from_value_error(exc)
+    status_code = getattr(exc, "status_code", None)
+    if isinstance(status_code, int):
+        return HTTPException(status_code=status_code, detail=str(exc))
+    return HTTPException(status_code=500, detail="Internal server error: An unexpected error occurred.")
+
+
+def _preserve_context_for_sse(event_gen):
+    # StreamingResponse runs in a different task, losing request contextvars.
+    # create_task inside context.run captures the context at task creation.
+    context = contextvars.copy_context()
+
+    async def wrapper():
+        try:
+            while True:
+                try:
+                    task = context.run(asyncio.create_task, event_gen.__anext__())
+                    item = await task
+                except StopAsyncIteration:
+                    break
+                yield item
+        except (asyncio.CancelledError, GeneratorExit):
+            if hasattr(event_gen, "aclose"):
+                await event_gen.aclose()
+            raise
+
+    return wrapper()
+
+
+def create_router(impl: Agents) -> APIRouter:
+    """Create a FastAPI router for the Agents API.
+
+    Args:
+        impl: The Agents implementation instance
+
+    Returns:
+        APIRouter configured for the Agents API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Agents"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/responses/{response_id}",
+        response_model=OpenAIResponseObject,
+        summary="Get a model response.",
+        description="Get a model response.",
+    )
+    async def get_openai_response(
+        request: Annotated[RetrieveResponseRequest, Depends(get_retrieve_response_request)],
+    ) -> OpenAIResponseObject:
+        try:
+            return await impl.get_openai_response(request)
+        except ValueError as exc:
+            raise _http_exception_from_value_error(exc) from exc
+
+    @router.post(
+        "/responses",
+        summary="Create a model response.",
+        description="Create a model response.",
+        status_code=200,
+        response_model=None,
+        responses={
+            200: {
+                "description": "An OpenAIResponseObject or a stream of OpenAIResponseObjectStream.",
+                "content": {
+                    "application/json": {"schema": {"$ref": "#/components/schemas/OpenAIResponseObject"}},
+                    "text/event-stream": {"schema": {"$ref": "#/components/schemas/OpenAIResponseObjectStream"}},
+                },
+            }
+        },
+    )
+    async def create_openai_response(
+        request: Annotated[CreateResponseRequest, Body(...)],
+    ) -> OpenAIResponseObject | StreamingResponse:
+        try:
+            result = await impl.create_openai_response(request)
+        except ValueError as exc:
+            raise _http_exception_from_value_error(exc) from exc
+
+        # For streaming responses, wrap in StreamingResponse for HTTP requests.
+        # The implementation is typed to return an `AsyncIterator` for streaming.
+        if isinstance(result, AsyncIterator):
+            return StreamingResponse(
+                _preserve_context_for_sse(sse_generator(result)),
+                media_type="text/event-stream",
+            )
+
+        return result
+
+    @router.get(
+        "/responses",
+        response_model=ListOpenAIResponseObject,
+        summary="List all responses.",
+        description="List all responses.",
+    )
+    async def list_openai_responses(
+        request: Annotated[ListResponsesRequest, Depends(get_list_responses_request)],
+    ) -> ListOpenAIResponseObject:
+        try:
+            return await impl.list_openai_responses(request)
+        except ValueError as exc:
+            raise _http_exception_from_value_error(exc) from exc
+
+    @router.get(
+        "/responses/{response_id}/input_items",
+        response_model=ListOpenAIResponseInputItem,
+        summary="List input items.",
+        description="List input items.",
+    )
+    async def list_openai_response_input_items(
+        request: Annotated[ListResponseInputItemsRequest, Depends(get_list_response_input_items_request)],
+    ) -> ListOpenAIResponseInputItem:
+        try:
+            return await impl.list_openai_response_input_items(request)
+        except ValueError as exc:
+            raise _http_exception_from_value_error(exc) from exc
+
+    @router.delete(
+        "/responses/{response_id}",
+        response_model=OpenAIDeleteResponseObject,
+        summary="Delete a response.",
+        description="Delete a response.",
+    )
+    async def delete_openai_response(
+        request: Annotated[DeleteResponseRequest, Depends(get_delete_response_request)],
+    ) -> OpenAIDeleteResponseObject:
+        try:
+            return await impl.delete_openai_response(request)
+        except ValueError as exc:
+            raise _http_exception_from_value_error(exc) from exc
+
+    return router

llama_stack_api/agents/models.py

@@ -0,0 +1,181 @@
+# 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 Agents API requests and responses.
+
+This module defines the request and response models for the Agents API
+using Pydantic with Field descriptions for OpenAPI schema generation.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from llama_stack_api.common.responses import Order
+from llama_stack_api.openai_responses import (
+    OpenAIResponseInput,
+    OpenAIResponseInputTool,
+    OpenAIResponseInputToolChoice,
+    OpenAIResponsePrompt,
+    OpenAIResponseReasoning,
+    OpenAIResponseText,
+)
+
+
+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"
+
+
+class ResponseGuardrailSpec(BaseModel):
+    """Specification for a guardrail to apply during response generation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: str
+    # TODO: more fields to be added for guardrail configuration
+
+
+ResponseGuardrail = str | ResponseGuardrailSpec
+
+
+class CreateResponseRequest(BaseModel):
+    """Request model for creating a response."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    input: str | list[OpenAIResponseInput] = Field(..., description="Input message(s) to create the response.")
+    model: str = Field(..., description="The underlying LLM used for completions.")
+    prompt: OpenAIResponsePrompt | None = Field(
+        default=None, description="Prompt object with ID, version, and variables."
+    )
+    instructions: str | None = Field(default=None, description="Instructions to guide the model's behavior.")
+    parallel_tool_calls: bool | None = Field(
+        default=True,
+        description="Whether to enable parallel tool calls.",
+    )
+    previous_response_id: str | None = Field(
+        default=None,
+        description="Optional ID of a previous response to continue from.",
+    )
+    conversation: str | None = Field(
+        default=None,
+        description="Optional ID of a conversation to add the response to.",
+    )
+    store: bool | None = Field(
+        default=True,
+        description="Whether to store the response in the database.",
+    )
+    stream: bool | None = Field(
+        default=False,
+        description="Whether to stream the response.",
+    )
+    temperature: float | None = Field(
+        default=None,
+        ge=0.0,
+        le=2.0,
+        description="Sampling temperature.",
+    )
+    text: OpenAIResponseText | None = Field(
+        default=None,
+        description="Configuration for text response generation.",
+    )
+    tool_choice: OpenAIResponseInputToolChoice | None = Field(
+        default=None,
+        description="How the model should select which tool to call (if any).",
+    )
+    tools: list[OpenAIResponseInputTool] | None = Field(
+        default=None,
+        description="List of tools available to the model.",
+    )
+    include: list[ResponseItemInclude] | None = Field(
+        default=None,
+        description="Additional fields to include in the response.",
+    )
+    max_infer_iters: int | None = Field(
+        default=10,
+        ge=1,
+        description="Maximum number of inference iterations.",
+    )
+    guardrails: list[ResponseGuardrail] | None = Field(
+        default=None,
+        description="List of guardrails to apply during response generation.",
+    )
+    max_tool_calls: int | None = Field(
+        default=None,
+        ge=1,
+        description="Max number of total calls to built-in tools that can be processed in a response.",
+    )
+    max_output_tokens: int | None = Field(
+        default=None,
+        ge=16,
+        description="Upper bound for the number of tokens that can be generated for a response.",
+    )
+    reasoning: OpenAIResponseReasoning | None = Field(
+        default=None,
+        description="Configuration for reasoning effort in responses.",
+    )
+    metadata: dict[str, str] | None = Field(
+        default=None,
+        description="Dictionary of metadata key-value pairs to attach to the response.",
+    )
+
+
+class RetrieveResponseRequest(BaseModel):
+    """Request model for retrieving a response."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    response_id: str = Field(..., min_length=1, description="The ID of the OpenAI response to retrieve.")
+
+
+class ListResponsesRequest(BaseModel):
+    """Request model for listing responses."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    after: str | None = Field(default=None, description="The ID of the last response to return.")
+    limit: int | None = Field(default=50, ge=1, le=100, description="The number of responses to return.")
+    model: str | None = Field(default=None, description="The model to filter responses by.")
+    order: Order | None = Field(
+        default=Order.desc,
+        description="The order to sort responses by when sorted by created_at ('asc' or 'desc').",
+    )
+
+
+class ListResponseInputItemsRequest(BaseModel):
+    """Request model for listing input items of a response."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    response_id: str = Field(..., min_length=1, description="The ID of the response to retrieve input items for.")
+    after: str | None = Field(default=None, description="An item ID to list items after, used for pagination.")
+    before: str | None = Field(default=None, description="An item ID to list items before, used for pagination.")
+    include: list[ResponseItemInclude] | None = Field(
+        default=None, description="Additional fields to include in the response."
+    )
+    limit: int | None = Field(
+        default=20,
+        ge=1,
+        le=100,
+        description="A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.",
+    )
+    order: Order | None = Field(default=Order.desc, description="The order to return the input items in.")
+
+
+class DeleteResponseRequest(BaseModel):
+    """Request model for deleting a response."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    response_id: str = Field(..., min_length=1, description="The ID of the OpenAI response to delete.")

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: ...

llama_stack_api/batches/fastapi_routes.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.
+
+"""FastAPI router for the Batches API.
+
+This module defines the FastAPI router for the Batches 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, Body, Depends
+
+from llama_stack_api.batches.models import (
+    CancelBatchRequest,
+    CreateBatchRequest,
+    ListBatchesRequest,
+    RetrieveBatchRequest,
+)
+from llama_stack_api.router_utils import create_path_dependency, create_query_dependency, standard_responses
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+from .api import Batches
+from .models import BatchObject, ListBatchesResponse
+
+# Automatically generate dependency functions from Pydantic models
+# This ensures the models are the single source of truth for descriptions
+get_retrieve_batch_request = create_path_dependency(RetrieveBatchRequest)
+get_cancel_batch_request = create_path_dependency(CancelBatchRequest)
+
+
+# Automatically generate dependency function from Pydantic model
+# This ensures the model is the single source of truth for descriptions and defaults
+get_list_batches_request = create_query_dependency(ListBatchesRequest)
+
+
+def create_router(impl: Batches) -> APIRouter:
+    """Create a FastAPI router for the Batches API.
+
+    Args:
+        impl: The Batches implementation instance
+
+    Returns:
+        APIRouter configured for the Batches API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Batches"],
+        responses=standard_responses,
+    )
+
+    @router.post(
+        "/batches",
+        response_model=BatchObject,
+        summary="Create a new batch for processing multiple API requests.",
+        description="Create a new batch for processing multiple API requests.",
+        responses={
+            200: {"description": "The created batch object."},
+            409: {"description": "Conflict: The idempotency key was previously used with different parameters."},
+        },
+    )
+    async def create_batch(
+        request: Annotated[CreateBatchRequest, Body(...)],
+    ) -> BatchObject:
+        return await impl.create_batch(request)
+
+    @router.get(
+        "/batches/{batch_id}",
+        response_model=BatchObject,
+        summary="Retrieve information about a specific batch.",
+        description="Retrieve information about a specific batch.",
+        responses={
+            200: {"description": "The batch object."},
+        },
+    )
+    async def retrieve_batch(
+        request: Annotated[RetrieveBatchRequest, Depends(get_retrieve_batch_request)],
+    ) -> BatchObject:
+        return await impl.retrieve_batch(request)
+
+    @router.post(
+        "/batches/{batch_id}/cancel",
+        response_model=BatchObject,
+        summary="Cancel a batch that is in progress.",
+        description="Cancel a batch that is in progress.",
+        responses={
+            200: {"description": "The updated batch object."},
+        },
+    )
+    async def cancel_batch(
+        request: Annotated[CancelBatchRequest, Depends(get_cancel_batch_request)],
+    ) -> BatchObject:
+        return await impl.cancel_batch(request)
+
+    @router.get(
+        "/batches",
+        response_model=ListBatchesResponse,
+        summary="List all batches for the current user.",
+        description="List all batches for the current user.",
+        responses={
+            200: {"description": "A list of batch objects."},
+        },
+    )
+    async def list_batches(
+        request: Annotated[ListBatchesRequest, Depends(get_list_batches_request)],
+    ) -> ListBatchesResponse:
+        return await impl.list_batches(request)
+
+    return router