llama-stack-api 0.4.4__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/common/errors.py

@@ -93,3 +93,18 @@ class InvalidConversationIdError(ValueError):
     def __init__(self, conversation_id: str) -> None:
         message = f"Invalid conversation ID '{conversation_id}'. Expected an ID that begins with 'conv_'."
         super().__init__(message)
+
+
+class ConnectorNotFoundError(ResourceNotFoundError):
+    """raised when Llama Stack cannot find a referenced connector"""
+
+    def __init__(self, connector_id: str) -> None:
+        super().__init__(connector_id, "Connector", "client.connectors.list()")
+
+
+class ConnectorToolNotFoundError(ValueError):
+    """raised when Llama Stack cannot find a referenced tool in a connector"""
+
+    def __init__(self, connector_id: str, tool_name: str) -> None:
+        message = f"Tool '{tool_name}' not found in connector '{connector_id}'. Use 'client.connectors.list_tools(\"{connector_id}\")' to list available tools."
+        super().__init__(message)

llama_stack_api/connectors/__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.
+
+"""Connectors API package.
+
+This package contains the Connectors API definition, models, and FastAPI router.
+"""
+
+from . import fastapi_routes
+from .api import Connectors
+from .models import (
+    CommonConnectorFields,
+    Connector,
+    ConnectorInput,
+    ConnectorType,
+    GetConnectorRequest,
+    GetConnectorToolRequest,
+    ListConnectorsResponse,
+    ListConnectorToolsRequest,
+    ListToolsResponse,
+)
+
+__all__ = [
+    "Connectors",
+    "CommonConnectorFields",
+    "Connector",
+    "ConnectorInput",
+    "ConnectorType",
+    "GetConnectorRequest",
+    "GetConnectorToolRequest",
+    "ListConnectorsResponse",
+    "ListConnectorToolsRequest",
+    "ListToolsResponse",
+    "fastapi_routes",
+]

llama_stack_api/connectors/api.py

@@ -0,0 +1,50 @@
+# 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.
+
+"""Connectors API protocol definition.
+
+This module contains the Connectors protocol definition.
+Pydantic models are defined in llama_stack_api.connectors.models.
+The FastAPI router is defined in llama_stack_api.connectors.fastapi_routes.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from llama_stack_api.tools import ToolDef
+
+from .models import (
+    Connector,
+    GetConnectorRequest,
+    GetConnectorToolRequest,
+    ListConnectorsResponse,
+    ListConnectorToolsRequest,
+    ListToolsResponse,
+)
+
+
+@runtime_checkable
+class Connectors(Protocol):
+    """Protocol for connector management operations."""
+
+    async def get_connector(
+        self,
+        request: GetConnectorRequest,
+        authorization: str | None = None,
+    ) -> Connector: ...
+
+    async def list_connectors(self) -> ListConnectorsResponse: ...
+
+    async def list_connector_tools(
+        self,
+        request: ListConnectorToolsRequest,
+        authorization: str | None = None,
+    ) -> ListToolsResponse: ...
+
+    async def get_connector_tool(
+        self,
+        request: GetConnectorToolRequest,
+        authorization: str | None = None,
+    ) -> ToolDef: ...

llama_stack_api/connectors/fastapi_routes.py

@@ -0,0 +1,103 @@
+# 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 Connectors API.
+
+This module defines the FastAPI router for the Connectors API using standard
+FastAPI route decorators.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Path, Query
+
+from llama_stack_api.router_utils import create_path_dependency, standard_responses
+from llama_stack_api.tools import ToolDef
+from llama_stack_api.version import LLAMA_STACK_API_V1ALPHA
+
+from .api import Connectors
+from .models import (
+    Connector,
+    GetConnectorRequest,
+    GetConnectorToolRequest,
+    ListConnectorsResponse,
+    ListConnectorToolsRequest,
+    ListToolsResponse,
+)
+
+# Path parameter dependencies for single-field request models
+get_connector_request = create_path_dependency(GetConnectorRequest)
+list_connector_tools_request = create_path_dependency(ListConnectorToolsRequest)
+
+
+def create_router(impl: Connectors) -> APIRouter:
+    """Create a FastAPI router for the Connectors API.
+
+    Args:
+        impl: The Connectors implementation instance
+
+    Returns:
+        APIRouter configured for the Connectors API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1ALPHA}",
+        tags=["Connectors"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/connectors",
+        response_model=ListConnectorsResponse,
+        summary="List all connectors.",
+        description="List all configured connectors.",
+    )
+    async def list_connectors() -> ListConnectorsResponse:
+        return await impl.list_connectors()
+
+    # NOTE: Route order matters! More specific routes must come before less specific ones.
+    # /connectors/{connector_id}/tools/{tool_name} must come before /connectors/{connector_id}/tools
+    # /connectors/{connector_id}/tools must come before /connectors/{connector_id}
+
+    @router.get(
+        "/connectors/{connector_id}/tools/{tool_name}",
+        response_model=ToolDef,
+        summary="Get a tool by name from a connector.",
+        description="Get a tool definition by its name from a connector.",
+    )
+    async def get_connector_tool(
+        connector_id: Annotated[str, Path(description="Identifier for the connector")],
+        tool_name: Annotated[str, Path(description="Name of the tool")],
+        authorization: Annotated[str | None, Query(description="Authorization token")] = None,
+    ) -> ToolDef:
+        # GetConnectorToolRequest has 2 path params, so we construct it manually
+        request = GetConnectorToolRequest(connector_id=connector_id, tool_name=tool_name)
+        return await impl.get_connector_tool(request, authorization=authorization)
+
+    @router.get(
+        "/connectors/{connector_id}/tools",
+        response_model=ListToolsResponse,
+        summary="List tools from a connector.",
+        description="List all tools available from a connector.",
+    )
+    async def list_connector_tools(
+        request: Annotated[ListConnectorToolsRequest, Depends(list_connector_tools_request)],
+        authorization: Annotated[str | None, Query(description="Authorization token")] = None,
+    ) -> ListToolsResponse:
+        return await impl.list_connector_tools(request, authorization=authorization)
+
+    @router.get(
+        "/connectors/{connector_id}",
+        response_model=Connector,
+        summary="Get a connector by its ID.",
+        description="Get a connector by its ID.",
+    )
+    async def get_connector(
+        request: Annotated[GetConnectorRequest, Depends(get_connector_request)],
+        authorization: Annotated[str | None, Query(description="Authorization token")] = None,
+    ) -> Connector:
+        return await impl.get_connector(request, authorization=authorization)
+
+    return router