llama-stack 0.3.5__py3-none-any.whl → 0.4.1__py3-none-any.whl

{llama_stack/providers → llama_stack_api}/datatypes.py

@@ -4,21 +4,177 @@
 # 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 enum import Enum, EnumMeta, StrEnum
 from typing import Any, Protocol
 from urllib.parse import urlparse
 
 from pydantic import BaseModel, Field
 
-from llama_stack.apis.benchmarks import Benchmark
-from llama_stack.apis.datasets import Dataset
-from llama_stack.apis.datatypes import Api
-from llama_stack.apis.models import Model
-from llama_stack.apis.scoring_functions import ScoringFn
-from llama_stack.apis.shields import Shield
-from llama_stack.apis.tools import ToolGroup
-from llama_stack.apis.vector_stores import VectorStore
-from llama_stack.schema_utils import json_schema_type
+from llama_stack_api.benchmarks import Benchmark
+from llama_stack_api.datasets import Dataset
+from llama_stack_api.models import Model
+from llama_stack_api.schema_utils import json_schema_type
+from llama_stack_api.scoring_functions import ScoringFn
+from llama_stack_api.shields import Shield
+from llama_stack_api.tools import ToolGroup
+from llama_stack_api.vector_stores import VectorStore
+
+
+class DynamicApiMeta(EnumMeta):
+    def __new__(cls, name, bases, namespace):
+        # Store the original enum values
+        original_values = {k: v for k, v in namespace.items() if not k.startswith("_")}
+
+        # Create the enum class
+        cls = super().__new__(cls, name, bases, namespace)
+
+        # Store the original values for reference
+        cls._original_values = original_values
+        # Initialize _dynamic_values
+        cls._dynamic_values = {}
+
+        return cls
+
+    def __call__(cls, value):
+        try:
+            return super().__call__(value)
+        except ValueError as e:
+            # If this value was already dynamically added, return it
+            if value in cls._dynamic_values:
+                return cls._dynamic_values[value]
+
+            # If the value doesn't exist, create a new enum member
+            # Create a new member name from the value
+            member_name = value.lower().replace("-", "_")
+
+            # If this member name already exists in the enum, return the existing member
+            if member_name in cls._member_map_:
+                return cls._member_map_[member_name]
+
+            # Instead of creating a new member, raise ValueError to force users to use Api.add() to
+            # register new APIs explicitly
+            raise ValueError(f"API '{value}' does not exist. Use Api.add() to register new APIs.") from e
+
+    def __iter__(cls):
+        # Allow iteration over both static and dynamic members
+        yield from super().__iter__()
+        if hasattr(cls, "_dynamic_values"):
+            yield from cls._dynamic_values.values()
+
+    def add(cls, value):
+        """
+        Add a new API to the enum.
+        Used to register external APIs.
+        """
+        member_name = value.lower().replace("-", "_")
+
+        # If this member name already exists in the enum, return it
+        if member_name in cls._member_map_:
+            return cls._member_map_[member_name]
+
+        # Create a new enum member
+        member = object.__new__(cls)
+        member._name_ = member_name
+        member._value_ = value
+
+        # Add it to the enum class
+        cls._member_map_[member_name] = member
+        cls._member_names_.append(member_name)
+        cls._member_type_ = str
+
+        # Store it in our dynamic values
+        cls._dynamic_values[value] = member
+
+        return member
+
+
+@json_schema_type
+class Api(Enum, metaclass=DynamicApiMeta):
+    """Enumeration of all available APIs in the Llama Stack system.
+    :cvar providers: Provider management and configuration
+    :cvar inference: Text generation, chat completions, and embeddings
+    :cvar safety: Content moderation and safety shields
+    :cvar agents: Agent orchestration and execution
+    :cvar batches: Batch processing for asynchronous API requests
+    :cvar vector_io: Vector database operations and queries
+    :cvar datasetio: Dataset input/output operations
+    :cvar scoring: Model output evaluation and scoring
+    :cvar eval: Model evaluation and benchmarking framework
+    :cvar post_training: Fine-tuning and model training
+    :cvar tool_runtime: Tool execution and management
+    :cvar telemetry: Observability and system monitoring
+    :cvar models: Model metadata and management
+    :cvar shields: Safety shield implementations
+    :cvar datasets: Dataset creation and management
+    :cvar scoring_functions: Scoring function definitions
+    :cvar benchmarks: Benchmark suite management
+    :cvar tool_groups: Tool group organization
+    :cvar files: File storage and management
+    :cvar file_processors: File parsing and processing operations
+    :cvar prompts: Prompt versions and management
+    :cvar connectors: External connector management (e.g., MCP servers)
+    :cvar inspect: Built-in system inspection and introspection
+    """
+
+    providers = "providers"
+    inference = "inference"
+    safety = "safety"
+    agents = "agents"
+    batches = "batches"
+    vector_io = "vector_io"
+    datasetio = "datasetio"
+    scoring = "scoring"
+    eval = "eval"
+    post_training = "post_training"
+    tool_runtime = "tool_runtime"
+
+    models = "models"
+    shields = "shields"
+    vector_stores = "vector_stores"  # only used for routing table
+    datasets = "datasets"
+    scoring_functions = "scoring_functions"
+    benchmarks = "benchmarks"
+    tool_groups = "tool_groups"
+    files = "files"
+    file_processors = "file_processors"
+    prompts = "prompts"
+    conversations = "conversations"
+    connectors = "connectors"
+
+    # built-in API
+    inspect = "inspect"
+    admin = "admin"
+
+
+@json_schema_type
+class Error(BaseModel):
+    """
+    Error response from the API. Roughly follows RFC 7807.
+
+    :param status: HTTP status code
+    :param title: Error title, a short summary of the error which is invariant for an error type
+    :param detail: Error detail, a longer human-readable description of the error
+    :param instance: (Optional) A URL which can be used to retrieve more information about the specific occurrence of the error
+    """
+
+    status: int
+    title: str
+    detail: str
+    instance: str | None = None
+
+
+class ExternalApiSpec(BaseModel):
+    """Specification for an external API implementation."""
+
+    module: str = Field(..., description="Python module containing the API implementation")
+    name: str = Field(..., description="Name of the API")
+    pip_packages: list[str] = Field(default=[], description="List of pip packages to install the API")
+    protocol: str = Field(..., description="Name of the protocol class for the API")
+
+
+# Provider-related types (merged from providers/datatypes.py)
+# NOTE: These imports are forward references to avoid circular dependencies
+# They will be resolved at runtime when the classes are used
 
 
 class ModelsProtocolPrivate(Protocol):

{llama_stack/apis/eval → llama_stack_api}/eval.py

@@ -4,17 +4,16 @@
 # 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, Any, Literal, Protocol
+from typing import Any, Literal, Protocol
 
 from pydantic import BaseModel, Field
 
-from llama_stack.apis.agents import AgentConfig
-from llama_stack.apis.common.job_types import Job
-from llama_stack.apis.inference import SamplingParams, SystemMessage
-from llama_stack.apis.scoring import ScoringResult
-from llama_stack.apis.scoring_functions import ScoringFnParams
-from llama_stack.apis.version import LLAMA_STACK_API_V1, LLAMA_STACK_API_V1ALPHA
-from llama_stack.schema_utils import json_schema_type, register_schema, webmethod
+from llama_stack_api.common.job_types import Job
+from llama_stack_api.inference import SamplingParams, SystemMessage
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.scoring import ScoringResult
+from llama_stack_api.scoring_functions import ScoringFnParams
+from llama_stack_api.version import LLAMA_STACK_API_V1ALPHA
 
 
 @json_schema_type
@@ -32,19 +31,7 @@ class ModelCandidate(BaseModel):
     system_message: SystemMessage | None = None
 
 
-@json_schema_type
-class AgentCandidate(BaseModel):
-    """An agent candidate for evaluation.
-
-    :param config: The configuration for the agent candidate.
-    """
-
-    type: Literal["agent"] = "agent"
-    config: AgentConfig
-
-
-EvalCandidate = Annotated[ModelCandidate | AgentCandidate, Field(discriminator="type")]
-register_schema(EvalCandidate, name="EvalCandidate")
+EvalCandidate = ModelCandidate
 
 
 @json_schema_type
@@ -86,7 +73,6 @@ class Eval(Protocol):
 
     Llama Stack Evaluation API for running evaluations on model and agent candidates."""
 
-    @webmethod(route="/eval/benchmarks/{benchmark_id}/jobs", method="POST", level=LLAMA_STACK_API_V1, deprecated=True)
     @webmethod(route="/eval/benchmarks/{benchmark_id}/jobs", method="POST", level=LLAMA_STACK_API_V1ALPHA)
     async def run_eval(
         self,
@@ -101,9 +87,6 @@ class Eval(Protocol):
         """
         ...
 
-    @webmethod(
-        route="/eval/benchmarks/{benchmark_id}/evaluations", method="POST", level=LLAMA_STACK_API_V1, deprecated=True
-    )
     @webmethod(route="/eval/benchmarks/{benchmark_id}/evaluations", method="POST", level=LLAMA_STACK_API_V1ALPHA)
     async def evaluate_rows(
         self,
@@ -122,9 +105,6 @@ class Eval(Protocol):
         """
         ...
 
-    @webmethod(
-        route="/eval/benchmarks/{benchmark_id}/jobs/{job_id}", method="GET", level=LLAMA_STACK_API_V1, deprecated=True
-    )
     @webmethod(route="/eval/benchmarks/{benchmark_id}/jobs/{job_id}", method="GET", level=LLAMA_STACK_API_V1ALPHA)
     async def job_status(self, benchmark_id: str, job_id: str) -> Job:
         """Get the status of a job.
@@ -135,12 +115,6 @@ class Eval(Protocol):
         """
         ...
 
-    @webmethod(
-        route="/eval/benchmarks/{benchmark_id}/jobs/{job_id}",
-        method="DELETE",
-        level=LLAMA_STACK_API_V1,
-        deprecated=True,
-    )
     @webmethod(route="/eval/benchmarks/{benchmark_id}/jobs/{job_id}", method="DELETE", level=LLAMA_STACK_API_V1ALPHA)
     async def job_cancel(self, benchmark_id: str, job_id: str) -> None:
         """Cancel a job.
@@ -150,12 +124,6 @@ class Eval(Protocol):
         """
         ...
 
-    @webmethod(
-        route="/eval/benchmarks/{benchmark_id}/jobs/{job_id}/result",
-        method="GET",
-        level=LLAMA_STACK_API_V1,
-        deprecated=True,
-    )
     @webmethod(
         route="/eval/benchmarks/{benchmark_id}/jobs/{job_id}/result", method="GET", level=LLAMA_STACK_API_V1ALPHA
     )

llama_stack_api/file_processors/__init__.py

@@ -0,0 +1,27 @@
+# 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.
+
+"""File Processors API protocol and models.
+
+This module contains the File Processors protocol definition.
+Pydantic models are defined in llama_stack_api.file_processors.models.
+The FastAPI router is defined in llama_stack_api.file_processors.fastapi_routes.
+"""
+
+# Import fastapi_routes for router factory access
+from . import fastapi_routes
+
+# Import protocol for re-export
+from .api import FileProcessors
+
+# Import models for re-export
+from .models import ProcessFileResponse
+
+__all__ = [
+    "FileProcessors",
+    "ProcessFileResponse",
+    "fastapi_routes",
+]

llama_stack_api/file_processors/api.py

@@ -0,0 +1,64 @@
+# 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 fastapi import UploadFile
+
+from llama_stack_api.vector_io import VectorStoreChunkingStrategy
+
+from .models import ProcessFileResponse
+
+
+@runtime_checkable
+class FileProcessors(Protocol):
+    """
+    File Processor API for converting files into structured, processable content.
+
+    This API provides a flexible interface for processing various file formats
+    (PDFs, documents, images, etc.) into normalized text content that can be used for
+    vector store ingestion, RAG applications, or standalone content extraction.
+
+    The API focuses on parsing and normalization:
+    - Multiple file formats through extensible provider architecture
+    - Multipart form uploads or file ID references
+    - Configurable processing options per provider
+    - Optional chunking using provider's native capabilities
+    - Rich metadata about processing results
+
+    For embedding generation, use the chunks from this API with the separate
+    embedding API to maintain clean separation of concerns.
+
+    Future providers can extend this interface to support additional formats,
+    processing capabilities, and optimization strategies.
+    """
+
+    async def process_file(
+        self,
+        file: UploadFile | None = None,
+        file_id: str | None = None,
+        options: dict[str, Any] | None = None,
+        chunking_strategy: VectorStoreChunkingStrategy | None = None,
+    ) -> ProcessFileResponse:
+        """
+        Process a file into chunks ready for vector database storage.
+
+        This method supports two modes of operation via multipart form request:
+        1. Direct upload: Upload and process a file directly (file parameter)
+        2. File storage: Process files already uploaded to file storage (file_id parameter)
+
+        Exactly one of file or file_id must be provided.
+
+        If no chunking_strategy is provided, the entire file content is returned as a single chunk.
+        If chunking_strategy is provided, the file is split according to the strategy.
+
+        :param file: The uploaded file object containing content and metadata (filename, content_type, etc.). Mutually exclusive with file_id.
+        :param file_id: ID of file already uploaded to file storage. Mutually exclusive with file.
+        :param options: Provider-specific processing options (e.g., OCR settings, output format).
+        :param chunking_strategy: Optional strategy for splitting content into chunks.
+        :returns: ProcessFileResponse with chunks ready for vector database storage.
+        """
+        ...

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: ...