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

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",
+]

llama_stack_api/datasetio/api.py

@@ -0,0 +1,42 @@
+# 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 definition.
+
+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.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from llama_stack_api.datasets import Dataset
+
+from .models import (
+    AppendRowsRequest,
+    IterRowsRequest,
+    PaginatedResponse,
+)
+
+
+class DatasetStore(Protocol):
+    def get_dataset(self, dataset_id: str) -> Dataset: ...
+
+
+@runtime_checkable
+class DatasetIO(Protocol):
+    """Protocol for dataset I/O operations.
+
+    The DatasetIO API provides operations for reading and writing data to datasets.
+    This includes iterating over rows and appending new rows to existing datasets.
+    """
+
+    # keeping for aligning with inference/safety, but this is not used
+    dataset_store: DatasetStore
+
+    async def iterrows(self, request: IterRowsRequest) -> PaginatedResponse: ...
+
+    async def append_rows(self, request: AppendRowsRequest) -> None: ...

llama_stack_api/datasetio/fastapi_routes.py

@@ -0,0 +1,94 @@
+# 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 DatasetIO API.
+
+This module defines the FastAPI router for the DatasetIO API using standard
+FastAPI route decorators.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Body, Path, Query
+
+from llama_stack_api.common.responses import PaginatedResponse
+from llama_stack_api.router_utils import standard_responses
+from llama_stack_api.version import LLAMA_STACK_API_V1BETA
+
+from .api import DatasetIO
+from .models import (
+    AppendRowsRequest,
+    IterRowsRequest,
+)
+
+
+def create_router(impl: DatasetIO) -> APIRouter:
+    """Create a FastAPI router for the DatasetIO API.
+
+    Args:
+        impl: The DatasetIO implementation instance
+
+    Returns:
+        APIRouter configured for the DatasetIO API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1BETA}",
+        tags=["DatasetIO"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/datasetio/iterrows/{dataset_id:path}",
+        response_model=PaginatedResponse,
+        summary="Get a paginated list of rows from a dataset.",
+        description="""Get a paginated list of rows from a dataset.
+
+Uses offset-based pagination where:
+- start_index: The starting index (0-based). If None, starts from beginning.
+- limit: Number of items to return. If None or -1, returns all items.
+
+The response includes:
+- data: List of items for the current page.
+- has_more: Whether there are more items available after this set.""",
+        responses={
+            200: {"description": "A PaginatedResponse containing the rows."},
+        },
+    )
+    async def iterrows(
+        dataset_id: Annotated[str, Path(description="The ID of the dataset to get the rows from.")],
+        start_index: Annotated[
+            int | None, Query(description="Index into dataset for the first row to get. Get all rows if None.")
+        ] = None,
+        limit: Annotated[int | None, Query(description="The number of rows to get.")] = None,
+    ) -> PaginatedResponse:
+        request = IterRowsRequest(
+            dataset_id=dataset_id,
+            start_index=start_index,
+            limit=limit,
+        )
+        return await impl.iterrows(request)
+
+    @router.post(
+        "/datasetio/append-rows/{dataset_id:path}",
+        status_code=204,
+        summary="Append rows to a dataset.",
+        description="Append rows to a dataset.",
+        responses={
+            204: {"description": "Rows were successfully appended."},
+        },
+    )
+    async def append_rows(
+        dataset_id: Annotated[str, Path(description="The ID of the dataset to append the rows to.")],
+        request: Annotated[AppendRowsRequest, Body(...)],
+    ) -> None:
+        # Override the dataset_id from the path
+        request_with_id = AppendRowsRequest(
+            dataset_id=dataset_id,
+            rows=request.rows,
+        )
+        return await impl.append_rows(request_with_id)
+
+    return router

llama_stack_api/datasetio/models.py

@@ -0,0 +1,48 @@
+# 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 DatasetIO API requests and responses.
+
+This module defines the request and response models for the DatasetIO API
+using Pydantic with Field descriptions for OpenAPI schema generation.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.common.responses import PaginatedResponse
+from llama_stack_api.schema_utils import json_schema_type
+
+
+@json_schema_type
+class IterRowsRequest(BaseModel):
+    """Request model for iterating over rows in a dataset."""
+
+    dataset_id: str = Field(..., description="The ID of the dataset to get the rows from.")
+    start_index: int | None = Field(
+        default=None,
+        description="Index into dataset for the first row to get. Get all rows if None.",
+    )
+    limit: int | None = Field(
+        default=None,
+        description="The number of rows to get.",
+    )
+
+
+@json_schema_type
+class AppendRowsRequest(BaseModel):
+    """Request model for appending rows to a dataset."""
+
+    dataset_id: str = Field(..., description="The ID of the dataset to append the rows to.")
+    rows: list[dict[str, Any]] = Field(..., description="The rows to append to the dataset.")
+
+
+__all__ = [
+    "AppendRowsRequest",
+    "IterRowsRequest",
+    "PaginatedResponse",
+]