llama-stack-api 0.4.3__py3-none-any.whl → 0.4.4__py3-none-any.whl

llama_stack_api/conversations.py

@@ -0,0 +1,270 @@
+# 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 enum import StrEnum
+from typing import Annotated, Literal, Protocol, runtime_checkable
+
+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, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+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")
+
+# Using OpenAI types directly caused issues but some notes for reference:
+# Note that ConversationItem is a Annotated Union of the types below:
+# from openai.types.responses import *
+# from openai.types.responses.response_item import *
+# from openai.types.conversations import ConversationItem
+# f = [
+#     ResponseFunctionToolCallItem,
+#     ResponseFunctionToolCallOutputItem,
+#     ResponseFileSearchToolCall,
+#     ResponseFunctionWebSearch,
+#     ImageGenerationCall,
+#     ResponseComputerToolCall,
+#     ResponseComputerToolCallOutputItem,
+#     ResponseReasoningItem,
+#     ResponseCodeInterpreterToolCall,
+#     LocalShellCall,
+#     LocalShellCallOutput,
+#     McpListTools,
+#     McpApprovalRequest,
+#     McpApprovalResponse,
+#     McpCall,
+#     ResponseCustomToolCall,
+#     ResponseCustomToolCallOutput
+# ]
+
+
+@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")
+
+
+@runtime_checkable
+class Conversations(Protocol):
+    """Conversations
+
+    Protocol for conversation management operations."""
+
+    @webmethod(route="/conversations", method="POST", level=LLAMA_STACK_API_V1)
+    async def create_conversation(
+        self, items: list[ConversationItem] | None = None, metadata: Metadata | None = None
+    ) -> Conversation:
+        """Create a conversation.
+
+        Create a conversation.
+
+        :param items: Initial items to include in the conversation context.
+        :param metadata: Set of key-value pairs that can be attached to an object.
+        :returns: The created conversation object.
+        """
+        ...
+
+    @webmethod(route="/conversations/{conversation_id}", method="GET", level=LLAMA_STACK_API_V1)
+    async def get_conversation(self, conversation_id: str) -> Conversation:
+        """Retrieve a conversation.
+
+        Get a conversation with the given ID.
+
+        :param conversation_id: The conversation identifier.
+        :returns: The conversation object.
+        """
+        ...
+
+    @webmethod(route="/conversations/{conversation_id}", method="POST", level=LLAMA_STACK_API_V1)
+    async def update_conversation(self, conversation_id: str, metadata: Metadata) -> Conversation:
+        """Update a conversation.
+
+        Update a conversation's metadata with the given ID.
+
+        :param conversation_id: The conversation identifier.
+        :param metadata: Set of key-value pairs that can be attached to an object.
+        :returns: The updated conversation object.
+        """
+        ...
+
+    @webmethod(route="/conversations/{conversation_id}", method="DELETE", level=LLAMA_STACK_API_V1)
+    async def openai_delete_conversation(self, conversation_id: str) -> ConversationDeletedResource:
+        """Delete a conversation.
+
+        Delete a conversation with the given ID.
+
+        :param conversation_id: The conversation identifier.
+        :returns: The deleted conversation resource.
+        """
+        ...
+
+    @webmethod(route="/conversations/{conversation_id}/items", method="POST", level=LLAMA_STACK_API_V1)
+    async def add_items(self, conversation_id: str, items: list[ConversationItem]) -> ConversationItemList:
+        """Create items.
+
+        Create items in the conversation.
+
+        :param conversation_id: The conversation identifier.
+        :param items: Items to include in the conversation context.
+        :returns: List of created items.
+        """
+        ...
+
+    @webmethod(route="/conversations/{conversation_id}/items/{item_id}", method="GET", level=LLAMA_STACK_API_V1)
+    async def retrieve(self, conversation_id: str, item_id: str) -> ConversationItem:
+        """Retrieve an item.
+
+        Retrieve a conversation item.
+
+        :param conversation_id: The conversation identifier.
+        :param item_id: The item identifier.
+        :returns: The conversation item.
+        """
+        ...
+
+    @webmethod(route="/conversations/{conversation_id}/items", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_items(
+        self,
+        conversation_id: str,
+        after: str | None = None,
+        include: list[ConversationItemInclude] | None = None,
+        limit: int | None = None,
+        order: Literal["asc", "desc"] | None = None,
+    ) -> ConversationItemList:
+        """List items.
+
+        List items in the conversation.
+
+        :param conversation_id: The conversation identifier.
+        :param after: An item ID to list items after, used in pagination.
+        :param include: Specify additional output data to include in the response.
+        :param limit: A limit on the number of objects to be returned (1-100, default 20).
+        :param order: The order to return items in (asc or desc, default desc).
+        :returns: List of conversation items.
+        """
+        ...
+
+    @webmethod(route="/conversations/{conversation_id}/items/{item_id}", method="DELETE", level=LLAMA_STACK_API_V1)
+    async def openai_delete_conversation_item(
+        self, conversation_id: str, item_id: str
+    ) -> ConversationItemDeletedResource:
+        """Delete an item.
+
+        Delete a conversation item.
+
+        :param conversation_id: The conversation identifier.
+        :param item_id: The item identifier.
+        :returns: The deleted item resource.
+        """
+        ...

llama_stack_api/datasetio.py

@@ -0,0 +1,55 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+from typing import Any, Protocol, runtime_checkable
+
+from llama_stack_api.common.responses import PaginatedResponse
+from llama_stack_api.datasets import Dataset
+from llama_stack_api.schema_utils import webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1BETA
+
+
+class DatasetStore(Protocol):
+    def get_dataset(self, dataset_id: str) -> Dataset: ...
+
+
+@runtime_checkable
+class DatasetIO(Protocol):
+    # keeping for aligning with inference/safety, but this is not used
+    dataset_store: DatasetStore
+
+    @webmethod(route="/datasetio/iterrows/{dataset_id:path}", method="GET", level=LLAMA_STACK_API_V1BETA)
+    async def iterrows(
+        self,
+        dataset_id: str,
+        start_index: int | None = None,
+        limit: int | None = None,
+    ) -> PaginatedResponse:
+        """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.
+
+        :param dataset_id: The ID of the dataset to get the rows from.
+        :param start_index: Index into dataset for the first row to get. Get all rows if None.
+        :param limit: The number of rows to get.
+        :returns: A PaginatedResponse.
+        """
+        ...
+
+    @webmethod(route="/datasetio/append-rows/{dataset_id:path}", method="POST", level=LLAMA_STACK_API_V1BETA)
+    async def append_rows(self, dataset_id: str, rows: list[dict[str, Any]]) -> None:
+        """Append rows to a dataset.
+
+        :param dataset_id: The ID of the dataset to append the rows to.
+        :param rows: The rows to append to the dataset.
+        """
+        ...

llama_stack_api/datasets/__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.
+
+"""Datasets API protocol and models.
+
+This module contains the Datasets protocol definition.
+Pydantic models are defined in llama_stack_api.datasets.models.
+The FastAPI router is defined in llama_stack_api.datasets.fastapi_routes.
+"""
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import new protocol for FastAPI router
+from .api import Datasets
+
+# Import models for re-export
+from .models import (
+    CommonDatasetFields,
+    Dataset,
+    DatasetPurpose,
+    DatasetType,
+    DataSource,
+    GetDatasetRequest,
+    ListDatasetsResponse,
+    RegisterDatasetRequest,
+    RowsDataSource,
+    UnregisterDatasetRequest,
+    URIDataSource,
+)
+
+
+# Define DatasetInput for backward compatibility
+class DatasetInput(CommonDatasetFields):
+    """Input parameters for dataset operations.
+
+    :param dataset_id: Unique identifier for the dataset
+    """
+
+    dataset_id: str
+
+
+__all__ = [
+    "Datasets",
+    "Dataset",
+    "CommonDatasetFields",
+    "DatasetPurpose",
+    "DataSource",
+    "DatasetInput",
+    "DatasetType",
+    "RowsDataSource",
+    "URIDataSource",
+    "ListDatasetsResponse",
+    "RegisterDatasetRequest",
+    "GetDatasetRequest",
+    "UnregisterDatasetRequest",
+    "fastapi_routes",
+]

llama_stack_api/datasets/api.py

@@ -0,0 +1,35 @@
+# 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.
+
+"""Datasets API protocol definition.
+
+This module contains the Datasets protocol definition.
+Pydantic models are defined in llama_stack_api.datasets.models.
+The FastAPI router is defined in llama_stack_api.datasets.fastapi_routes.
+"""
+
+from typing import Protocol, runtime_checkable
+
+from .models import (
+    Dataset,
+    GetDatasetRequest,
+    ListDatasetsResponse,
+    RegisterDatasetRequest,
+    UnregisterDatasetRequest,
+)
+
+
+@runtime_checkable
+class Datasets(Protocol):
+    """Protocol for dataset management operations."""
+
+    async def register_dataset(self, request: RegisterDatasetRequest) -> Dataset: ...
+
+    async def get_dataset(self, request: GetDatasetRequest) -> Dataset: ...
+
+    async def list_datasets(self) -> ListDatasetsResponse: ...
+
+    async def unregister_dataset(self, request: UnregisterDatasetRequest) -> None: ...

llama_stack_api/datasets/fastapi_routes.py

@@ -0,0 +1,104 @@
+# 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 Datasets API.
+
+This module defines the FastAPI router for the Datasets API using standard
+FastAPI route decorators.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Body, Depends
+
+from llama_stack_api.router_utils import create_path_dependency, standard_responses
+from llama_stack_api.version import LLAMA_STACK_API_V1BETA
+
+from .api import Datasets
+from .models import (
+    Dataset,
+    GetDatasetRequest,
+    ListDatasetsResponse,
+    RegisterDatasetRequest,
+    UnregisterDatasetRequest,
+)
+
+# Path parameter dependencies for single-field models
+get_dataset_request = create_path_dependency(GetDatasetRequest)
+unregister_dataset_request = create_path_dependency(UnregisterDatasetRequest)
+
+
+def create_router(impl: Datasets) -> APIRouter:
+    """Create a FastAPI router for the Datasets API.
+
+    Args:
+        impl: The Datasets implementation instance
+
+    Returns:
+        APIRouter configured for the Datasets API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1BETA}",
+        tags=["Datasets"],
+        responses=standard_responses,
+    )
+
+    @router.post(
+        "/datasets",
+        response_model=Dataset,
+        summary="Register a new dataset.",
+        description="Register a new dataset.",
+        responses={
+            200: {"description": "The registered dataset object."},
+        },
+        deprecated=True,
+    )
+    async def register_dataset(
+        request: Annotated[RegisterDatasetRequest, Body(...)],
+    ) -> Dataset:
+        return await impl.register_dataset(request)
+
+    @router.get(
+        "/datasets/{dataset_id:path}",
+        response_model=Dataset,
+        summary="Get a dataset by its ID.",
+        description="Get a dataset by its ID.",
+        responses={
+            200: {"description": "The dataset object."},
+        },
+    )
+    async def get_dataset(
+        request: Annotated[GetDatasetRequest, Depends(get_dataset_request)],
+    ) -> Dataset:
+        return await impl.get_dataset(request)
+
+    @router.get(
+        "/datasets",
+        response_model=ListDatasetsResponse,
+        summary="List all datasets.",
+        description="List all datasets.",
+        responses={
+            200: {"description": "A list of dataset objects."},
+        },
+    )
+    async def list_datasets() -> ListDatasetsResponse:
+        return await impl.list_datasets()
+
+    @router.delete(
+        "/datasets/{dataset_id:path}",
+        summary="Unregister a dataset by its ID.",
+        description="Unregister a dataset by its ID.",
+        responses={
+            200: {"description": "The dataset was successfully unregistered."},
+        },
+        deprecated=True,
+    )
+    async def unregister_dataset(
+        request: Annotated[UnregisterDatasetRequest, Depends(unregister_dataset_request)],
+    ) -> None:
+        return await impl.unregister_dataset(request)
+
+    return router

llama_stack_api/datasets/models.py

@@ -0,0 +1,152 @@
+# 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 Datasets API requests and responses.
+
+This module defines the request and response models for the Datasets API
+using Pydantic with Field descriptions for OpenAPI schema generation.
+"""
+
+from enum import Enum, StrEnum
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.resource import Resource, ResourceType
+from llama_stack_api.schema_utils import json_schema_type, register_schema
+
+
+class DatasetPurpose(StrEnum):
+    """Purpose of the dataset. Each purpose has a required input data schema."""
+
+    post_training_messages = "post-training/messages"
+    """The dataset contains messages used for post-training."""
+    eval_question_answer = "eval/question-answer"
+    """The dataset contains a question column and an answer column."""
+    eval_messages_answer = "eval/messages-answer"
+    """The dataset contains a messages column with list of messages and an answer column."""
+
+
+class DatasetType(Enum):
+    """Type of the dataset source."""
+
+    uri = "uri"
+    """The dataset can be obtained from a URI."""
+    rows = "rows"
+    """The dataset is stored in rows."""
+
+
+@json_schema_type
+class URIDataSource(BaseModel):
+    """A dataset that can be obtained from a URI."""
+
+    type: Literal["uri"] = Field(default="uri", description="The type of data source.")
+    uri: str = Field(
+        ...,
+        description='The dataset can be obtained from a URI. E.g. "https://mywebsite.com/mydata.jsonl", "lsfs://mydata.jsonl", "data:csv;base64,{base64_content}"',
+    )
+
+
+@json_schema_type
+class RowsDataSource(BaseModel):
+    """A dataset stored in rows."""
+
+    type: Literal["rows"] = Field(default="rows", description="The type of data source.")
+    rows: list[dict[str, Any]] = Field(
+        ...,
+        description='The dataset is stored in rows. E.g. [{"messages": [{"role": "user", "content": "Hello, world!"}, {"role": "assistant", "content": "Hello, world!"}]}]',
+    )
+
+
+DataSource = Annotated[
+    URIDataSource | RowsDataSource,
+    Field(discriminator="type"),
+]
+register_schema(DataSource, name="DataSource")
+
+
+class CommonDatasetFields(BaseModel):
+    """Common fields for a dataset."""
+
+    purpose: DatasetPurpose = Field(..., description="Purpose of the dataset indicating its intended use")
+    source: DataSource = Field(..., description="Data source configuration for the dataset")
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Any additional metadata for this dataset",
+    )
+
+
+@json_schema_type
+class Dataset(CommonDatasetFields, Resource):
+    """Dataset resource for storing and accessing training or evaluation data."""
+
+    type: Literal[ResourceType.dataset] = Field(
+        default=ResourceType.dataset,
+        description="Type of resource, always 'dataset' for datasets",
+    )
+
+    @property
+    def dataset_id(self) -> str:
+        return self.identifier
+
+    @property
+    def provider_dataset_id(self) -> str | None:
+        return self.provider_resource_id
+
+
+@json_schema_type
+class ListDatasetsResponse(BaseModel):
+    """Response from listing datasets."""
+
+    data: list[Dataset] = Field(..., description="List of datasets")
+
+
+# Request models for each endpoint
+
+
+@json_schema_type
+class RegisterDatasetRequest(BaseModel):
+    """Request model for registering a dataset."""
+
+    purpose: DatasetPurpose = Field(..., description="The purpose of the dataset.")
+    source: DataSource = Field(..., description="The data source of the dataset.")
+    metadata: dict[str, Any] | None = Field(
+        default=None,
+        description="The metadata for the dataset.",
+    )
+    dataset_id: str | None = Field(
+        default=None,
+        description="The ID of the dataset. If not provided, an ID will be generated.",
+    )
+
+
+@json_schema_type
+class GetDatasetRequest(BaseModel):
+    """Request model for getting a dataset by ID."""
+
+    dataset_id: str = Field(..., description="The ID of the dataset to get.")
+
+
+@json_schema_type
+class UnregisterDatasetRequest(BaseModel):
+    """Request model for unregistering a dataset."""
+
+    dataset_id: str = Field(..., description="The ID of the dataset to unregister.")
+
+
+__all__ = [
+    "CommonDatasetFields",
+    "Dataset",
+    "DatasetPurpose",
+    "DatasetType",
+    "DataSource",
+    "RowsDataSource",
+    "URIDataSource",
+    "ListDatasetsResponse",
+    "RegisterDatasetRequest",
+    "GetDatasetRequest",
+    "UnregisterDatasetRequest",
+]