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

llama_stack_api/connectors/models.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.
+
+"""Connectors API models.
+
+This module contains the Pydantic models for the Connectors API.
+"""
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.schema_utils import json_schema_type
+from llama_stack_api.tools import ToolDef
+
+
+@json_schema_type
+class ConnectorType(StrEnum):
+    """Type of connector."""
+
+    MCP = "mcp"
+
+
+class CommonConnectorFields(BaseModel):
+    """Common fields for all connectors"""
+
+    connector_type: ConnectorType = Field(default=ConnectorType.MCP)
+    connector_id: str = Field(..., description="Identifier for the connector")
+    url: str = Field(..., description="URL of the connector")
+    server_label: str | None = Field(default=None, description="Label of the server")
+
+
+@json_schema_type
+class Connector(CommonConnectorFields):
+    """A connector registered in Llama Stack"""
+
+    model_config = {"populate_by_name": True}
+    server_name: str | None = Field(default=None, description="Name of the server")
+    server_description: str | None = Field(default=None, description="Description of the server")
+    server_version: str | None = Field(default=None, description="Version of the server")
+
+
+@json_schema_type
+class ConnectorInput(CommonConnectorFields):
+    """Input for creating a connector"""
+
+
+# Path parameter models (single field for create_path_dependency)
+
+
+@json_schema_type
+class GetConnectorRequest(BaseModel):
+    """Request model for getting a connector by ID."""
+
+    connector_id: str = Field(..., description="Identifier for the connector")
+
+
+@json_schema_type
+class ListConnectorToolsRequest(BaseModel):
+    """Request model for listing tools from a connector."""
+
+    connector_id: str = Field(..., description="Identifier for the connector")
+
+
+@json_schema_type
+class GetConnectorToolRequest(BaseModel):
+    """Request model for getting a tool from a connector."""
+
+    connector_id: str = Field(..., description="Identifier for the connector")
+    tool_name: str = Field(..., description="Name of the tool")
+
+
+# Response models
+
+
+@json_schema_type
+class ListConnectorsResponse(BaseModel):
+    """Response containing a list of configured connectors"""
+
+    data: list[Connector]
+
+
+@json_schema_type
+class ListToolsResponse(BaseModel):
+    """Response containing a list of tools"""
+
+    data: list[ToolDef]
+
+
+__all__ = [
+    "ConnectorType",
+    "CommonConnectorFields",
+    "Connector",
+    "ConnectorInput",
+    "GetConnectorRequest",
+    "ListConnectorsResponse",
+    "ListConnectorToolsRequest",
+    "ListToolsResponse",
+    "GetConnectorToolRequest",
+]

llama_stack_api/conversations/__init__.py

@@ -0,0 +1,61 @@
+# 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.
+
+"""Conversations API protocol and models.
+
+This module contains the Conversations protocol definition.
+Pydantic models are defined in llama_stack_api.conversations.models.
+The FastAPI router is defined in llama_stack_api.conversations.fastapi_routes.
+"""
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import protocol for re-export
+from .api import Conversations
+
+# Import models for re-export
+from .models import (
+    AddItemsRequest,
+    Conversation,
+    ConversationDeletedResource,
+    ConversationItem,
+    ConversationItemCreateRequest,
+    ConversationItemDeletedResource,
+    ConversationItemInclude,
+    ConversationItemList,
+    ConversationMessage,
+    CreateConversationRequest,
+    DeleteConversationRequest,
+    DeleteItemRequest,
+    GetConversationRequest,
+    ListItemsRequest,
+    Metadata,
+    RetrieveItemRequest,
+    UpdateConversationRequest,
+)
+
+__all__ = [
+    "Conversations",
+    "Conversation",
+    "ConversationMessage",
+    "ConversationItem",
+    "ConversationDeletedResource",
+    "ConversationItemCreateRequest",
+    "ConversationItemInclude",
+    "ConversationItemList",
+    "ConversationItemDeletedResource",
+    "Metadata",
+    "CreateConversationRequest",
+    "GetConversationRequest",
+    "UpdateConversationRequest",
+    "DeleteConversationRequest",
+    "AddItemsRequest",
+    "RetrieveItemRequest",
+    "ListItemsRequest",
+    "DeleteItemRequest",
+    "fastapi_routes",
+]

llama_stack_api/conversations/api.py

@@ -0,0 +1,44 @@
+# 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 (
+    AddItemsRequest,
+    Conversation,
+    ConversationDeletedResource,
+    ConversationItem,
+    ConversationItemDeletedResource,
+    ConversationItemList,
+    CreateConversationRequest,
+    DeleteConversationRequest,
+    DeleteItemRequest,
+    GetConversationRequest,
+    ListItemsRequest,
+    RetrieveItemRequest,
+    UpdateConversationRequest,
+)
+
+
+@runtime_checkable
+class Conversations(Protocol):
+    """Protocol for conversation management operations."""
+
+    async def create_conversation(self, request: CreateConversationRequest) -> Conversation: ...
+
+    async def get_conversation(self, request: GetConversationRequest) -> Conversation: ...
+
+    async def update_conversation(self, conversation_id: str, request: UpdateConversationRequest) -> Conversation: ...
+
+    async def openai_delete_conversation(self, request: DeleteConversationRequest) -> ConversationDeletedResource: ...
+
+    async def add_items(self, conversation_id: str, request: AddItemsRequest) -> ConversationItemList: ...
+
+    async def retrieve(self, request: RetrieveItemRequest) -> ConversationItem: ...
+
+    async def list_items(self, request: ListItemsRequest) -> ConversationItemList: ...
+
+    async def openai_delete_conversation_item(self, request: DeleteItemRequest) -> ConversationItemDeletedResource: ...

llama_stack_api/conversations/fastapi_routes.py

@@ -0,0 +1,177 @@
+# 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 Conversations API.
+
+This module defines the FastAPI router for the Conversations API using standard
+FastAPI route decorators.
+"""
+
+from typing import Annotated, Literal
+
+from fastapi import APIRouter, Body, Depends, Path
+from pydantic import BaseModel
+
+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 Conversations
+from .models import (
+    AddItemsRequest,
+    Conversation,
+    ConversationDeletedResource,
+    ConversationItem,
+    ConversationItemDeletedResource,
+    ConversationItemInclude,
+    ConversationItemList,
+    CreateConversationRequest,
+    DeleteConversationRequest,
+    DeleteItemRequest,
+    GetConversationRequest,
+    ListItemsRequest,
+    RetrieveItemRequest,
+    UpdateConversationRequest,
+)
+
+
+class _ListItemsQueryParams(BaseModel):
+    """Query parameters for list_items endpoint (excludes conversation_id path param).
+
+    This is a subset of ListItemsRequest that only includes query parameters,
+    excluding the conversation_id which is a path parameter.
+    """
+
+    after: str | None = None
+    include: list[ConversationItemInclude] | None = None
+    limit: int | None = None
+    order: Literal["asc", "desc"] | None = None
+
+
+# Dependency functions for request models
+get_conversation_request = create_path_dependency(GetConversationRequest)
+delete_conversation_request = create_path_dependency(DeleteConversationRequest)
+get_list_items_query_params = create_query_dependency(_ListItemsQueryParams)
+
+
+def create_router(impl: Conversations) -> APIRouter:
+    """Create a FastAPI router for the Conversations API."""
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Conversations"],
+        responses=standard_responses,
+    )
+
+    @router.post(
+        "/conversations",
+        response_model=Conversation,
+        summary="Create a conversation.",
+        description="Create a conversation.",
+        responses={200: {"description": "The created conversation object."}},
+    )
+    async def create_conversation(
+        request: Annotated[CreateConversationRequest, Body(...)],
+    ) -> Conversation:
+        return await impl.create_conversation(request)
+
+    @router.get(
+        "/conversations/{conversation_id}",
+        response_model=Conversation,
+        summary="Retrieve a conversation.",
+        description="Get a conversation with the given ID.",
+        responses={200: {"description": "The conversation object."}},
+    )
+    async def get_conversation(
+        request: Annotated[GetConversationRequest, Depends(get_conversation_request)],
+    ) -> Conversation:
+        return await impl.get_conversation(request)
+
+    @router.post(
+        "/conversations/{conversation_id}",
+        response_model=Conversation,
+        summary="Update a conversation.",
+        description="Update a conversation's metadata with the given ID.",
+        responses={200: {"description": "The updated conversation object."}},
+    )
+    async def update_conversation(
+        conversation_id: Annotated[str, Path(description="The conversation identifier.")],
+        request: Annotated[UpdateConversationRequest, Body(...)],
+    ) -> Conversation:
+        return await impl.update_conversation(conversation_id, request)
+
+    @router.delete(
+        "/conversations/{conversation_id}",
+        response_model=ConversationDeletedResource,
+        summary="Delete a conversation.",
+        description="Delete a conversation with the given ID.",
+        responses={200: {"description": "The deleted conversation resource."}},
+    )
+    async def delete_conversation(
+        request: Annotated[DeleteConversationRequest, Depends(delete_conversation_request)],
+    ) -> ConversationDeletedResource:
+        return await impl.openai_delete_conversation(request)
+
+    @router.post(
+        "/conversations/{conversation_id}/items",
+        response_model=ConversationItemList,
+        summary="Create items.",
+        description="Create items in the conversation.",
+        responses={200: {"description": "List of created items."}},
+    )
+    async def add_items(
+        conversation_id: Annotated[str, Path(description="The conversation identifier.")],
+        request: Annotated[AddItemsRequest, Body(...)],
+    ) -> ConversationItemList:
+        return await impl.add_items(conversation_id, request)
+
+    @router.get(
+        "/conversations/{conversation_id}/items/{item_id}",
+        response_model=ConversationItem,
+        summary="Retrieve an item.",
+        description="Retrieve a conversation item.",
+        responses={200: {"description": "The conversation item."}},
+    )
+    async def retrieve_item(
+        conversation_id: Annotated[str, Path(description="The conversation identifier.")],
+        item_id: Annotated[str, Path(description="The item identifier.")],
+    ) -> ConversationItem:
+        request = RetrieveItemRequest(conversation_id=conversation_id, item_id=item_id)
+        return await impl.retrieve(request)
+
+    @router.get(
+        "/conversations/{conversation_id}/items",
+        response_model=ConversationItemList,
+        summary="List items.",
+        description="List items in the conversation.",
+        responses={200: {"description": "List of conversation items."}},
+    )
+    async def list_items(
+        conversation_id: Annotated[str, Path(description="The conversation identifier.")],
+        query_params: Annotated[_ListItemsQueryParams, Depends(get_list_items_query_params)],
+    ) -> ConversationItemList:
+        request = ListItemsRequest(
+            conversation_id=conversation_id,
+            after=query_params.after,
+            include=query_params.include,
+            limit=query_params.limit,
+            order=query_params.order,
+        )
+        return await impl.list_items(request)
+
+    @router.delete(
+        "/conversations/{conversation_id}/items/{item_id}",
+        response_model=ConversationItemDeletedResource,
+        summary="Delete an item.",
+        description="Delete a conversation item.",
+        responses={200: {"description": "The deleted item resource."}},
+    )
+    async def delete_item(
+        conversation_id: Annotated[str, Path(description="The conversation identifier.")],
+        item_id: Annotated[str, Path(description="The item identifier.")],
+    ) -> ConversationItemDeletedResource:
+        request = DeleteItemRequest(conversation_id=conversation_id, item_id=item_id)
+        return await impl.openai_delete_conversation_item(request)
+
+    return router

llama_stack_api/conversations/models.py

@@ -0,0 +1,245 @@
+# 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 Conversations API requests and responses.
+
+This module defines the request and response models for the Conversations API
+using Pydantic with Field descriptions for OpenAPI schema generation.
+"""
+
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.openai_responses import (
+    OpenAIResponseInputFunctionToolCallOutput,
+    OpenAIResponseMCPApprovalRequest,
+    OpenAIResponseMCPApprovalResponse,
+    OpenAIResponseMessage,
+    OpenAIResponseOutputMessageFileSearchToolCall,
+    OpenAIResponseOutputMessageFunctionToolCall,
+    OpenAIResponseOutputMessageMCPCall,
+    OpenAIResponseOutputMessageMCPListTools,
+    OpenAIResponseOutputMessageWebSearchToolCall,
+)
+from llama_stack_api.schema_utils import json_schema_type, register_schema
+
+Metadata = dict[str, str]
+
+
+@json_schema_type
+class Conversation(BaseModel):
+    """OpenAI-compatible conversation object."""
+
+    id: str = Field(..., description="The unique ID of the conversation.")
+    object: Literal["conversation"] = Field(
+        default="conversation", description="The object type, which is always conversation."
+    )
+    created_at: int = Field(
+        ..., description="The time at which the conversation was created, measured in seconds since the Unix epoch."
+    )
+    metadata: Metadata | None = Field(
+        default=None,
+        description="Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.",
+    )
+    items: list[dict] | None = Field(
+        default=None,
+        description="Initial items to include in the conversation context. You may add up to 20 items at a time.",
+    )
+
+
+@json_schema_type
+class ConversationMessage(BaseModel):
+    """OpenAI-compatible message item for conversations."""
+
+    id: str = Field(..., description="unique identifier for this message")
+    content: list[dict] = Field(..., description="message content")
+    role: str = Field(..., description="message role")
+    status: str = Field(..., description="message status")
+    type: Literal["message"] = "message"
+    object: Literal["message"] = "message"
+
+
+ConversationItem = Annotated[
+    OpenAIResponseMessage
+    | OpenAIResponseOutputMessageWebSearchToolCall
+    | OpenAIResponseOutputMessageFileSearchToolCall
+    | OpenAIResponseOutputMessageFunctionToolCall
+    | OpenAIResponseInputFunctionToolCallOutput
+    | OpenAIResponseMCPApprovalRequest
+    | OpenAIResponseMCPApprovalResponse
+    | OpenAIResponseOutputMessageMCPCall
+    | OpenAIResponseOutputMessageMCPListTools
+    | OpenAIResponseOutputMessageMCPCall
+    | OpenAIResponseOutputMessageMCPListTools,
+    Field(discriminator="type"),
+]
+register_schema(ConversationItem, name="ConversationItem")
+
+
+@json_schema_type
+class ConversationDeletedResource(BaseModel):
+    """Response for deleted conversation."""
+
+    id: str = Field(..., description="The deleted conversation identifier")
+    object: str = Field(default="conversation.deleted", description="Object type")
+    deleted: bool = Field(default=True, description="Whether the object was deleted")
+
+
+@json_schema_type
+class ConversationItemCreateRequest(BaseModel):
+    """Request body for creating conversation items."""
+
+    items: list[ConversationItem] = Field(
+        ...,
+        description="Items to include in the conversation context. You may add up to 20 items at a time.",
+        max_length=20,
+    )
+
+
+class ConversationItemInclude(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"
+
+
+@json_schema_type
+class ConversationItemList(BaseModel):
+    """List of conversation items with pagination."""
+
+    object: str = Field(default="list", description="Object type")
+    data: list[ConversationItem] = Field(..., description="List of conversation items")
+    first_id: str | None = Field(default=None, description="The ID of the first item in the list")
+    last_id: str | None = Field(default=None, description="The ID of the last item in the list")
+    has_more: bool = Field(default=False, description="Whether there are more items available")
+
+
+@json_schema_type
+class ConversationItemDeletedResource(BaseModel):
+    """Response for deleted conversation item."""
+
+    id: str = Field(..., description="The deleted item identifier")
+    object: str = Field(default="conversation.item.deleted", description="Object type")
+    deleted: bool = Field(default=True, description="Whether the object was deleted")
+
+
+# Request models for each endpoint
+
+
+@json_schema_type
+class CreateConversationRequest(BaseModel):
+    """Request model for creating a conversation."""
+
+    items: list[ConversationItem] | None = Field(
+        default=None,
+        description="Initial items to include in the conversation context.",
+    )
+    metadata: Metadata | None = Field(
+        default=None,
+        description="Set of key-value pairs that can be attached to an object.",
+    )
+
+
+@json_schema_type
+class GetConversationRequest(BaseModel):
+    """Request model for getting a conversation by ID."""
+
+    conversation_id: str = Field(..., description="The conversation identifier.")
+
+
+@json_schema_type
+class UpdateConversationRequest(BaseModel):
+    """Request model for updating a conversation's metadata."""
+
+    metadata: Metadata = Field(
+        ...,
+        description="Set of key-value pairs that can be attached to an object.",
+    )
+
+
+@json_schema_type
+class DeleteConversationRequest(BaseModel):
+    """Request model for deleting a conversation."""
+
+    conversation_id: str = Field(..., description="The conversation identifier.")
+
+
+@json_schema_type
+class AddItemsRequest(BaseModel):
+    """Request model for adding items to a conversation."""
+
+    items: list[ConversationItem] = Field(
+        ...,
+        description="Items to include in the conversation context. You may add up to 20 items at a time.",
+        max_length=20,
+    )
+
+
+@json_schema_type
+class RetrieveItemRequest(BaseModel):
+    """Request model for retrieving a conversation item."""
+
+    conversation_id: str = Field(..., description="The conversation identifier.")
+    item_id: str = Field(..., description="The item identifier.")
+
+
+@json_schema_type
+class ListItemsRequest(BaseModel):
+    """Request model for listing items in a conversation."""
+
+    conversation_id: str = Field(..., description="The conversation identifier.")
+    after: str | None = Field(
+        default=None,
+        description="An item ID to list items after, used in pagination.",
+    )
+    include: list[ConversationItemInclude] | None = Field(
+        default=None,
+        description="Specify additional output data to include in the response.",
+    )
+    limit: int | None = Field(
+        default=None,
+        description="A limit on the number of objects to be returned (1-100, default 20).",
+    )
+    order: Literal["asc", "desc"] | None = Field(
+        default=None,
+        description="The order to return items in (asc or desc, default desc).",
+    )
+
+
+@json_schema_type
+class DeleteItemRequest(BaseModel):
+    """Request model for deleting a conversation item."""
+
+    conversation_id: str = Field(..., description="The conversation identifier.")
+    item_id: str = Field(..., description="The item identifier.")
+
+
+__all__ = [
+    "Metadata",
+    "Conversation",
+    "ConversationMessage",
+    "ConversationItem",
+    "ConversationDeletedResource",
+    "ConversationItemCreateRequest",
+    "ConversationItemInclude",
+    "ConversationItemList",
+    "ConversationItemDeletedResource",
+    "CreateConversationRequest",
+    "GetConversationRequest",
+    "UpdateConversationRequest",
+    "DeleteConversationRequest",
+    "AddItemsRequest",
+    "RetrieveItemRequest",
+    "ListItemsRequest",
+    "DeleteItemRequest",
+]

llama_stack_api/datasetio/__init__.py

@@ -0,0 +1,34 @@
+# 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.
+
+"""DatasetIO API protocol and models.
+
+This module contains the DatasetIO protocol definition.
+Pydantic models are defined in llama_stack_api.datasetio.models.
+The FastAPI router is defined in llama_stack_api.datasetio.fastapi_routes.
+"""
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import protocol for FastAPI router
+from .api import DatasetIO, DatasetStore
+
+# Import models for re-export
+from .models import (
+    AppendRowsRequest,
+    IterRowsRequest,
+    PaginatedResponse,
+)
+
+__all__ = [
+    "DatasetIO",
+    "DatasetStore",
+    "AppendRowsRequest",
+    "IterRowsRequest",
+    "PaginatedResponse",
+    "fastapi_routes",
+]