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

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.")