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

llama_stack_api/file_processors/fastapi_routes.py

@@ -0,0 +1,78 @@
+# 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 File Processors API.
+
+This module defines the FastAPI router for the File Processors API using standard
+FastAPI route decorators. The router is defined in the API package to keep
+all API-related code together.
+"""
+
+from typing import Annotated, Any
+
+from fastapi import APIRouter, File, Form, UploadFile
+
+from llama_stack_api.router_utils import standard_responses
+from llama_stack_api.vector_io import VectorStoreChunkingStrategy
+from llama_stack_api.version import LLAMA_STACK_API_V1ALPHA
+
+from .api import FileProcessors
+from .models import ProcessFileResponse
+
+
+def create_router(impl: FileProcessors) -> APIRouter:
+    """Create a FastAPI router for the File Processors API.
+
+    Args:
+        impl: The FileProcessors implementation instance
+
+    Returns:
+        APIRouter configured for the File Processors API
+    """
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1ALPHA}",
+        tags=["File Processors"],
+        responses=standard_responses,
+    )
+
+    @router.post(
+        "/file-processors/process",
+        response_model=ProcessFileResponse,
+        summary="Process a file into chunks ready for vector database storage.",
+        description="Process a file into chunks ready for vector database storage. Supports direct upload via multipart form or processing files already uploaded to file storage via file_id. Exactly one of file or file_id must be provided.",
+        responses={
+            200: {"description": "The processed file chunks."},
+        },
+    )
+    async def process_file(
+        file: Annotated[
+            UploadFile | None,
+            File(description="The File object to be uploaded and processed. Mutually exclusive with file_id."),
+        ] = None,
+        file_id: Annotated[
+            str | None, Form(description="ID of file already uploaded to file storage. Mutually exclusive with file.")
+        ] = None,
+        options: Annotated[
+            dict[str, Any] | None,
+            Form(
+                description="Optional processing options. Provider-specific parameters (e.g., OCR settings, output format)."
+            ),
+        ] = None,
+        chunking_strategy: Annotated[
+            VectorStoreChunkingStrategy | None,
+            Form(description="Optional chunking strategy for splitting content into chunks."),
+        ] = None,
+    ) -> ProcessFileResponse:
+        # Pass the parameters directly to the implementation
+        # The protocol method signature expects individual parameters for multipart handling
+        return await impl.process_file(
+            file=file,
+            file_id=file_id,
+            options=options,
+            chunking_strategy=chunking_strategy,
+        )
+
+    return router

llama_stack_api/file_processors/models.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.
+
+"""Pydantic models for File Processors API responses.
+
+This module defines the response models for the File Processors API
+using Pydantic with Field descriptions for OpenAPI schema generation.
+
+Request models are not needed for this API since it uses multipart form data
+with individual parameters rather than a JSON request body.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.schema_utils import json_schema_type
+from llama_stack_api.vector_io import Chunk
+
+
+@json_schema_type
+class ProcessFileResponse(BaseModel):
+    """Response model for file processing operation.
+
+    Returns a list of chunks ready for storage in vector databases.
+    Each chunk contains the content and metadata.
+    """
+
+    chunks: list[Chunk] = Field(..., description="Processed chunks from the file. Always returns at least one chunk.")
+
+    metadata: dict[str, Any] = Field(
+        ...,
+        description="Processing-run metadata such as processor name/version, processing_time_ms, page_count, extraction_method (e.g. docling/pypdf/ocr), confidence scores, plus provider-specific fields.",
+    )
+
+
+__all__ = [
+    "ProcessFileResponse",
+]

llama_stack_api/files/__init__.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.
+
+from . import fastapi_routes
+from .api import Files
+from .models import (
+    DeleteFileRequest,
+    ExpiresAfter,
+    ListFilesRequest,
+    ListOpenAIFileResponse,
+    OpenAIFileDeleteResponse,
+    OpenAIFileObject,
+    OpenAIFilePurpose,
+    RetrieveFileContentRequest,
+    RetrieveFileRequest,
+    UploadFileRequest,
+)
+
+__all__ = [
+    "DeleteFileRequest",
+    "ExpiresAfter",
+    "fastapi_routes",
+    "Files",
+    "ListFilesRequest",
+    "ListOpenAIFileResponse",
+    "OpenAIFileDeleteResponse",
+    "OpenAIFileObject",
+    "OpenAIFilePurpose",
+    "RetrieveFileContentRequest",
+    "RetrieveFileRequest",
+    "UploadFileRequest",
+]

llama_stack_api/files/api.py

@@ -0,0 +1,51 @@
+# 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 fastapi import Response, UploadFile
+
+from .models import (
+    DeleteFileRequest,
+    ListFilesRequest,
+    ListOpenAIFileResponse,
+    OpenAIFileDeleteResponse,
+    OpenAIFileObject,
+    RetrieveFileContentRequest,
+    RetrieveFileRequest,
+    UploadFileRequest,
+)
+
+
+@runtime_checkable
+class Files(Protocol):
+    """Files API for managing file uploads and retrieval."""
+
+    async def openai_upload_file(
+        self,
+        request: UploadFileRequest,
+        file: UploadFile,
+    ) -> OpenAIFileObject: ...
+
+    async def openai_list_files(
+        self,
+        request: ListFilesRequest,
+    ) -> ListOpenAIFileResponse: ...
+
+    async def openai_retrieve_file(
+        self,
+        request: RetrieveFileRequest,
+    ) -> OpenAIFileObject: ...
+
+    async def openai_delete_file(
+        self,
+        request: DeleteFileRequest,
+    ) -> OpenAIFileDeleteResponse: ...
+
+    async def openai_retrieve_file_content(
+        self,
+        request: RetrieveFileContentRequest,
+    ) -> Response: ...

llama_stack_api/files/fastapi_routes.py

@@ -0,0 +1,124 @@
+# 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 Annotated
+
+from fastapi import APIRouter, Depends, UploadFile
+from fastapi.param_functions import File, Form
+from fastapi.responses import Response
+
+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 Files
+from .models import (
+    DeleteFileRequest,
+    ExpiresAfter,
+    ListFilesRequest,
+    ListOpenAIFileResponse,
+    OpenAIFileDeleteResponse,
+    OpenAIFileObject,
+    OpenAIFilePurpose,
+    RetrieveFileContentRequest,
+    RetrieveFileRequest,
+    UploadFileRequest,
+)
+
+# Automatically generate dependency functions from Pydantic models
+# This ensures the models are the single source of truth for descriptions
+get_list_files_request = create_query_dependency(ListFilesRequest)
+get_get_files_request = create_path_dependency(RetrieveFileRequest)
+get_delete_files_request = create_path_dependency(DeleteFileRequest)
+get_retrieve_file_content_request = create_path_dependency(RetrieveFileContentRequest)
+
+
+def create_router(impl: Files) -> APIRouter:
+    router = APIRouter(
+        prefix=f"/{LLAMA_STACK_API_V1}",
+        tags=["Files"],
+        responses=standard_responses,
+    )
+
+    @router.get(
+        "/files",
+        response_model=ListOpenAIFileResponse,
+        summary="List files",
+        description="List files",
+        responses={
+            200: {"description": "The list of files."},
+        },
+    )
+    async def list_files(
+        request: Annotated[ListFilesRequest, Depends(get_list_files_request)],
+    ) -> ListOpenAIFileResponse:
+        return await impl.openai_list_files(request)
+
+    @router.get(
+        "/files/{file_id}",
+        response_model=OpenAIFileObject,
+        summary="Get file",
+        description="Get file",
+        responses={
+            200: {"description": "The file."},
+        },
+    )
+    async def get_file(
+        request: Annotated[RetrieveFileRequest, Depends(get_get_files_request)],
+    ) -> OpenAIFileObject:
+        return await impl.openai_retrieve_file(request)
+
+    @router.delete(
+        "/files/{file_id}",
+        response_model=OpenAIFileDeleteResponse,
+        summary="Delete file",
+        description="Delete file",
+        responses={
+            200: {"description": "The file was deleted."},
+        },
+    )
+    async def delete_file(
+        request: Annotated[DeleteFileRequest, Depends(get_delete_files_request)],
+    ) -> OpenAIFileDeleteResponse:
+        return await impl.openai_delete_file(request)
+
+    @router.get(
+        "/files/{file_id}/content",
+        status_code=200,
+        summary="Retrieve file content",
+        description="Retrieve file content",
+        responses={
+            200: {
+                "description": "The raw file content as a binary response.",
+                "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Response"}}},
+            },
+        },
+    )
+    async def retrieve_file_content(
+        request: Annotated[RetrieveFileContentRequest, Depends(get_retrieve_file_content_request)],
+    ) -> Response:
+        return await impl.openai_retrieve_file_content(request)
+
+    @router.post(
+        "/files",
+        response_model=OpenAIFileObject,
+        summary="Upload file",
+        description="Upload a file.",
+        responses={
+            200: {"description": "The uploaded file."},
+        },
+    )
+    async def upload_file(
+        file: Annotated[UploadFile, File(description="The file to upload.")],
+        purpose: Annotated[OpenAIFilePurpose, Form(description="The intended purpose of the uploaded file.")],
+        expires_after: Annotated[ExpiresAfter | None, Form(description="Optional expiration settings.")] = None,
+    ) -> OpenAIFileObject:
+        request = UploadFileRequest(
+            purpose=purpose,
+            expires_after=expires_after,
+        )
+        return await impl.openai_upload_file(request, file)
+
+    return router

llama_stack_api/files/models.py

@@ -0,0 +1,107 @@
+# 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 ClassVar, Literal
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.common.responses import Order
+from llama_stack_api.schema_utils import json_schema_type
+
+
+class OpenAIFilePurpose(StrEnum):
+    """
+    Valid purpose values for OpenAI Files API.
+    """
+
+    ASSISTANTS = "assistants"
+    BATCH = "batch"
+
+
+@json_schema_type
+class OpenAIFileObject(BaseModel):
+    """OpenAI File object as defined in the OpenAI Files API."""
+
+    object: Literal["file"] = Field(default="file", description="The object type, which is always 'file'.")
+    id: str = Field(..., description="The file identifier, which can be referenced in the API endpoints.")
+    bytes: int = Field(..., description="The size of the file, in bytes.")
+    created_at: int = Field(..., description="The Unix timestamp (in seconds) for when the file was created.")
+    expires_at: int = Field(..., description="The Unix timestamp (in seconds) for when the file expires.")
+    filename: str = Field(..., description="The name of the file.")
+    purpose: OpenAIFilePurpose = Field(..., description="The intended purpose of the file.")
+
+
+@json_schema_type
+class ExpiresAfter(BaseModel):
+    """Control expiration of uploaded files."""
+
+    MIN: ClassVar[int] = 3600  # 1 hour
+    MAX: ClassVar[int] = 2592000  # 30 days
+
+    anchor: Literal["created_at"] = Field(..., description="The anchor point for expiration, must be 'created_at'.")
+    seconds: int = Field(
+        ..., ge=MIN, le=MAX, description="Seconds until expiration, between 3600 (1 hour) and 2592000 (30 days)."
+    )
+
+
+@json_schema_type
+class ListOpenAIFileResponse(BaseModel):
+    """Response for listing files in OpenAI Files API."""
+
+    data: list[OpenAIFileObject] = Field(..., description="The list of files.")
+    has_more: bool = Field(..., description="Whether there are more files available beyond this page.")
+    first_id: str = Field(..., description="The ID of the first file in the list for pagination.")
+    last_id: str = Field(..., description="The ID of the last file in the list for pagination.")
+    object: Literal["list"] = Field(default="list", description="The object type, which is always 'list'.")
+
+
+@json_schema_type
+class OpenAIFileDeleteResponse(BaseModel):
+    """Response for deleting a file in OpenAI Files API."""
+
+    id: str = Field(..., description="The file identifier that was deleted.")
+    object: Literal["file"] = Field(default="file", description="The object type, which is always 'file'.")
+    deleted: bool = Field(..., description="Whether the file was successfully deleted.")
+
+
+@json_schema_type
+class ListFilesRequest(BaseModel):
+    """Request model for listing files."""
+
+    after: str | None = Field(default=None, description="A cursor for pagination. Returns files after this ID.")
+    limit: int | None = Field(default=10000, description="Maximum number of files to return (1-10,000).")
+    order: Order | None = Field(default=Order.desc, description="Sort order by created_at timestamp ('asc' or 'desc').")
+    purpose: OpenAIFilePurpose | None = Field(default=None, description="Filter files by purpose.")
+
+
+@json_schema_type
+class RetrieveFileRequest(BaseModel):
+    """Request model for retrieving a file."""
+
+    file_id: str = Field(..., description="The ID of the file to retrieve.")
+
+
+@json_schema_type
+class DeleteFileRequest(BaseModel):
+    """Request model for deleting a file."""
+
+    file_id: str = Field(..., description="The ID of the file to delete.")
+
+
+@json_schema_type
+class RetrieveFileContentRequest(BaseModel):
+    """Request model for retrieving file content."""
+
+    file_id: str = Field(..., description="The ID of the file to retrieve content from.")
+
+
+@json_schema_type
+class UploadFileRequest(BaseModel):
+    """Request model for uploading a file."""
+
+    purpose: OpenAIFilePurpose = Field(..., description="The intended purpose of the uploaded file.")
+    expires_after: ExpiresAfter | None = Field(default=None, description="Optional expiration settings for the file.")

llama_stack_api/inference/__init__.py

@@ -0,0 +1,207 @@
+# 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.
+
+"""Inference API protocol and models.
+
+This module contains the Inference protocol definition.
+Pydantic models are defined in llama_stack_api.inference.models.
+The FastAPI router is defined in llama_stack_api.inference.fastapi_routes.
+"""
+
+# Import common types for backward compatibility
+# (these were previously available from the old inference.py)
+from llama_stack_api.common.content_types import InterleavedContent
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import protocol for re-export
+from .api import Inference, InferenceProvider, ModelStore
+
+# Import models for re-export
+from .models import (
+    AllowedToolsConfig,
+    Bf16QuantizationConfig,
+    ChatCompletionResponseEventType,
+    CompletionRequest,
+    CustomToolConfig,
+    EmbeddingsResponse,
+    EmbeddingTaskType,
+    Fp8QuantizationConfig,
+    FunctionToolConfig,
+    GetChatCompletionRequest,
+    GrammarResponseFormat,
+    GreedySamplingStrategy,
+    Int4QuantizationConfig,
+    JsonSchemaResponseFormat,
+    ListChatCompletionsRequest,
+    ListOpenAIChatCompletionResponse,
+    LogProbConfig,
+    OpenAIAssistantMessageParam,
+    OpenAIChatCompletion,
+    OpenAIChatCompletionChunk,
+    OpenAIChatCompletionContentPartImageParam,
+    OpenAIChatCompletionContentPartParam,
+    OpenAIChatCompletionContentPartTextParam,
+    OpenAIChatCompletionMessageContent,
+    OpenAIChatCompletionRequestWithExtraBody,
+    OpenAIChatCompletionTextOnlyMessageContent,
+    OpenAIChatCompletionToolCall,
+    OpenAIChatCompletionToolCallFunction,
+    OpenAIChatCompletionToolChoice,
+    OpenAIChatCompletionToolChoiceAllowedTools,
+    OpenAIChatCompletionToolChoiceCustomTool,
+    OpenAIChatCompletionToolChoiceFunctionTool,
+    OpenAIChatCompletionUsage,
+    OpenAIChatCompletionUsageCompletionTokensDetails,
+    OpenAIChatCompletionUsagePromptTokensDetails,
+    OpenAIChoice,
+    OpenAIChoiceDelta,
+    OpenAIChoiceLogprobs,
+    OpenAIChunkChoice,
+    OpenAICompletion,
+    OpenAICompletionChoice,
+    OpenAICompletionLogprobs,
+    OpenAICompletionRequestWithExtraBody,
+    OpenAICompletionWithInputMessages,
+    OpenAIDeveloperMessageParam,
+    OpenAIEmbeddingData,
+    OpenAIEmbeddingsRequestWithExtraBody,
+    OpenAIEmbeddingsResponse,
+    OpenAIEmbeddingUsage,
+    OpenAIFile,
+    OpenAIFileFile,
+    OpenAIFinishReason,
+    OpenAIImageURL,
+    OpenAIJSONSchema,
+    OpenAIMessageParam,
+    OpenAIResponseFormatJSONObject,
+    OpenAIResponseFormatJSONSchema,
+    OpenAIResponseFormatParam,
+    OpenAIResponseFormatText,
+    OpenAISystemMessageParam,
+    OpenAITokenLogProb,
+    OpenAIToolMessageParam,
+    OpenAITopLogProb,
+    OpenAIUserMessageParam,
+    QuantizationConfig,
+    QuantizationType,
+    RerankData,
+    RerankRequest,
+    RerankResponse,
+    ResponseFormat,
+    ResponseFormatType,
+    SamplingParams,
+    SamplingStrategy,
+    SystemMessage,
+    SystemMessageBehavior,
+    TextTruncation,
+    TokenLogProbs,
+    ToolChoice,
+    ToolResponseMessage,
+    TopKSamplingStrategy,
+    TopPSamplingStrategy,
+    UserMessage,
+)
+
+__all__ = [
+    # Protocol
+    "Inference",
+    "InferenceProvider",
+    "ModelStore",
+    # Common types (for backward compatibility)
+    "InterleavedContent",
+    # Sampling
+    "GreedySamplingStrategy",
+    "TopPSamplingStrategy",
+    "TopKSamplingStrategy",
+    "SamplingStrategy",
+    "SamplingParams",
+    "LogProbConfig",
+    # Quantization
+    "QuantizationType",
+    "Fp8QuantizationConfig",
+    "Bf16QuantizationConfig",
+    "Int4QuantizationConfig",
+    "QuantizationConfig",
+    # Messages
+    "UserMessage",
+    "SystemMessage",
+    "ToolResponseMessage",
+    "ToolChoice",
+    "TokenLogProbs",
+    # Response
+    "ChatCompletionResponseEventType",
+    "ResponseFormatType",
+    "JsonSchemaResponseFormat",
+    "GrammarResponseFormat",
+    "ResponseFormat",
+    "CompletionRequest",
+    "SystemMessageBehavior",
+    "EmbeddingsResponse",
+    "RerankData",
+    "RerankResponse",
+    # OpenAI Compatibility
+    "OpenAIChatCompletionContentPartTextParam",
+    "OpenAIImageURL",
+    "OpenAIChatCompletionContentPartImageParam",
+    "OpenAIFileFile",
+    "OpenAIFile",
+    "OpenAIChatCompletionContentPartParam",
+    "OpenAIChatCompletionMessageContent",
+    "OpenAIChatCompletionTextOnlyMessageContent",
+    "OpenAIUserMessageParam",
+    "OpenAISystemMessageParam",
+    "OpenAIChatCompletionToolCallFunction",
+    "OpenAIChatCompletionToolCall",
+    "OpenAIAssistantMessageParam",
+    "OpenAIToolMessageParam",
+    "OpenAIDeveloperMessageParam",
+    "OpenAIMessageParam",
+    "OpenAIResponseFormatText",
+    "OpenAIJSONSchema",
+    "OpenAIResponseFormatJSONSchema",
+    "OpenAIResponseFormatJSONObject",
+    "OpenAIResponseFormatParam",
+    "FunctionToolConfig",
+    "OpenAIChatCompletionToolChoiceFunctionTool",
+    "CustomToolConfig",
+    "OpenAIChatCompletionToolChoiceCustomTool",
+    "AllowedToolsConfig",
+    "OpenAIChatCompletionToolChoiceAllowedTools",
+    "OpenAIChatCompletionToolChoice",
+    "OpenAITopLogProb",
+    "OpenAITokenLogProb",
+    "OpenAIChoiceLogprobs",
+    "OpenAIChoiceDelta",
+    "OpenAIChunkChoice",
+    "OpenAIChoice",
+    "OpenAIChatCompletionUsageCompletionTokensDetails",
+    "OpenAIChatCompletionUsagePromptTokensDetails",
+    "OpenAIChatCompletionUsage",
+    "OpenAIChatCompletion",
+    "OpenAIChatCompletionChunk",
+    "OpenAICompletionLogprobs",
+    "OpenAICompletionChoice",
+    "OpenAICompletion",
+    "OpenAIFinishReason",
+    "OpenAIEmbeddingData",
+    "OpenAIEmbeddingUsage",
+    "OpenAIEmbeddingsResponse",
+    "TextTruncation",
+    "EmbeddingTaskType",
+    "OpenAICompletionWithInputMessages",
+    "ListOpenAIChatCompletionResponse",
+    "OpenAICompletionRequestWithExtraBody",
+    "OpenAIChatCompletionRequestWithExtraBody",
+    "OpenAIEmbeddingsRequestWithExtraBody",
+    # Request Models
+    "ListChatCompletionsRequest",
+    "GetChatCompletionRequest",
+    "RerankRequest",
+    # Router factory module
+    "fastapi_routes",
+]