fix: rename llama_stack_api dir (#4155)

# What does this PR do?

the directory structure was src/llama-stack-api/llama_stack_api

instead it should just be src/llama_stack_api to match the other
packages.

update the structure and pyproject/linting config

---------

Signed-off-by: Charlie Doern <cdoern@redhat.com>
Co-authored-by: Ashwin Bharambe <ashwin.bharambe@gmail.com>

src/llama_stack_api/README.md

@@ -0,0 +1,103 @@
+# llama-stack-api
+
+API and Provider specifications for Llama Stack - a lightweight package with protocol definitions and provider specs.
+
+## Overview
+
+`llama-stack-api` is a minimal dependency package that contains:
+
+- **API Protocol Definitions**: Type-safe protocol definitions for all Llama Stack APIs (inference, agents, safety, etc.)
+- **Provider Specifications**: Provider spec definitions for building custom providers
+- **Data Types**: Shared data types and models used across the Llama Stack ecosystem
+- **Type Utilities**: Strong typing utilities and schema validation
+
+## What This Package Does NOT Include
+
+- Server implementation (see `llama-stack` package)
+- Provider implementations (see `llama-stack` package)
+- CLI tools (see `llama-stack` package)
+- Runtime orchestration (see `llama-stack` package)
+
+## Use Cases
+
+This package is designed for:
+
+1. **Third-party Provider Developers**: Build custom providers without depending on the full Llama Stack server
+2. **Client Library Authors**: Use type definitions without server dependencies
+3. **Documentation Generation**: Generate API docs from protocol definitions
+4. **Type Checking**: Validate implementations against the official specs
+
+## Installation
+
+```bash
+pip install llama-stack-api
+```
+
+Or with uv:
+
+```bash
+uv pip install llama-stack-api
+```
+
+## Dependencies
+
+Minimal dependencies:
+- `pydantic>=2.11.9` - For data validation and serialization
+- `jsonschema` - For JSON schema utilities
+
+## Versioning
+
+This package follows semantic versioning independently from the main `llama-stack` package:
+
+- **Patch versions** (0.1.x): Documentation, internal improvements
+- **Minor versions** (0.x.0): New APIs, backward-compatible changes
+- **Major versions** (x.0.0): Breaking changes to existing APIs
+
+Current version: **0.4.0.dev0**
+
+## Usage Example
+
+```python
+from llama_stack_api.inference import Inference, ChatCompletionRequest
+from llama_stack_api.providers.datatypes import ProviderSpec, InlineProviderSpec
+from llama_stack_api.datatypes import Api
+
+
+# Use protocol definitions for type checking
+class MyInferenceProvider(Inference):
+    async def chat_completion(self, request: ChatCompletionRequest):
+        # Your implementation
+        pass
+
+
+# Define provider specifications
+my_provider_spec = InlineProviderSpec(
+    api=Api.inference,
+    provider_type="inline::my-provider",
+    pip_packages=["my-dependencies"],
+    module="my_package.providers.inference",
+    config_class="my_package.providers.inference.MyConfig",
+)
+```
+
+## Relationship to llama-stack
+
+The main `llama-stack` package depends on `llama-stack-api` and provides:
+- Full server implementation
+- Built-in provider implementations
+- CLI tools for running and managing stacks
+- Runtime provider resolution and orchestration
+
+## Contributing
+
+See the main [Llama Stack repository](https://github.com/llamastack/llama-stack) for contribution guidelines.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Links
+
+- [Main Llama Stack Repository](https://github.com/llamastack/llama-stack)
+- [Documentation](https://llamastack.ai/)
+- [Client Library](https://pypi.org/project/llama-stack-client/)

src/llama_stack_api/__init__.py

@@ -0,0 +1,871 @@
+# 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.
+
+"""
+Llama Stack API Specifications
+
+This package contains the API definitions, data types, and protocol specifications
+for Llama Stack. It is designed to be a lightweight dependency for external providers
+and clients that need to interact with Llama Stack APIs without requiring the full
+server implementation.
+
+All imports from this package MUST use the form:
+    from llama_stack_api import <symbol>
+
+Sub-module imports (e.g., from llama_stack_api.agents import Agents) are NOT supported
+and considered a code smell. All exported symbols are explicitly listed in __all__.
+"""
+
+__version__ = "0.4.0.dev0"
+
+# Import submodules for those who need them
+from . import common, strong_typing  # noqa: F401
+
+# Import all public API symbols
+from .agents import Agents, ResponseGuardrail, ResponseGuardrailSpec
+from .batches import Batches, BatchObject, ListBatchesResponse
+from .benchmarks import (
+    Benchmark,
+    BenchmarkInput,
+    Benchmarks,
+    CommonBenchmarkFields,
+    ListBenchmarksResponse,
+)
+
+# Import commonly used types from common submodule
+from .common.content_types import (
+    URL,
+    ImageContentItem,
+    InterleavedContent,
+    InterleavedContentItem,
+    TextContentItem,
+    _URLOrData,
+)
+from .common.errors import (
+    ConflictError,
+    DatasetNotFoundError,
+    InvalidConversationIdError,
+    ModelNotFoundError,
+    ModelTypeError,
+    ResourceNotFoundError,
+    TokenValidationError,
+    ToolGroupNotFoundError,
+    UnsupportedModelError,
+    VectorStoreNotFoundError,
+)
+from .common.job_types import Job, JobStatus
+from .common.responses import Order, PaginatedResponse
+from .common.training_types import Checkpoint, PostTrainingMetric
+from .common.type_system import (
+    ChatCompletionInputType,
+    CompletionInputType,
+    NumberType,
+    ParamType,
+    StringType,
+)
+from .conversations import (
+    Conversation,
+    ConversationDeletedResource,
+    ConversationItem,
+    ConversationItemCreateRequest,
+    ConversationItemDeletedResource,
+    ConversationItemInclude,
+    ConversationItemList,
+    ConversationMessage,
+    Conversations,
+    Metadata,
+)
+from .datasetio import DatasetIO, DatasetStore
+from .datasets import (
+    CommonDatasetFields,
+    Dataset,
+    DatasetInput,
+    DatasetPurpose,
+    Datasets,
+    DatasetType,
+    DataSource,
+    ListDatasetsResponse,
+    RowsDataSource,
+    URIDataSource,
+)
+from .datatypes import (
+    Api,
+    BenchmarksProtocolPrivate,
+    DatasetsProtocolPrivate,
+    DynamicApiMeta,
+    Error,
+    ExternalApiSpec,
+    HealthResponse,
+    HealthStatus,
+    InlineProviderSpec,
+    ModelsProtocolPrivate,
+    ProviderSpec,
+    RemoteProviderConfig,
+    RemoteProviderSpec,
+    RoutingTable,
+    ScoringFunctionsProtocolPrivate,
+    ShieldsProtocolPrivate,
+    ToolGroupsProtocolPrivate,
+    VectorStoresProtocolPrivate,
+)
+from .eval import BenchmarkConfig, Eval, EvalCandidate, EvaluateResponse, ModelCandidate
+from .files import (
+    ExpiresAfter,
+    Files,
+    ListOpenAIFileResponse,
+    OpenAIFileDeleteResponse,
+    OpenAIFileObject,
+    OpenAIFilePurpose,
+)
+from .inference import (
+    Bf16QuantizationConfig,
+    ChatCompletionResponseEventType,
+    CompletionRequest,
+    EmbeddingsResponse,
+    EmbeddingTaskType,
+    Fp8QuantizationConfig,
+    GrammarResponseFormat,
+    GreedySamplingStrategy,
+    Inference,
+    InferenceProvider,
+    Int4QuantizationConfig,
+    JsonSchemaResponseFormat,
+    ListOpenAIChatCompletionResponse,
+    LogProbConfig,
+    ModelStore,
+    OpenAIAssistantMessageParam,
+    OpenAIChatCompletion,
+    OpenAIChatCompletionChunk,
+    OpenAIChatCompletionContentPartImageParam,
+    OpenAIChatCompletionContentPartParam,
+    OpenAIChatCompletionContentPartTextParam,
+    OpenAIChatCompletionMessageContent,
+    OpenAIChatCompletionRequestWithExtraBody,
+    OpenAIChatCompletionTextOnlyMessageContent,
+    OpenAIChatCompletionToolCall,
+    OpenAIChatCompletionToolCallFunction,
+    OpenAIChatCompletionUsage,
+    OpenAIChatCompletionUsageCompletionTokensDetails,
+    OpenAIChatCompletionUsagePromptTokensDetails,
+    OpenAIChoice,
+    OpenAIChoiceDelta,
+    OpenAIChoiceLogprobs,
+    OpenAIChunkChoice,
+    OpenAICompletion,
+    OpenAICompletionChoice,
+    OpenAICompletionLogprobs,
+    OpenAICompletionRequestWithExtraBody,
+    OpenAICompletionWithInputMessages,
+    OpenAIDeveloperMessageParam,
+    OpenAIEmbeddingData,
+    OpenAIEmbeddingsRequestWithExtraBody,
+    OpenAIEmbeddingsResponse,
+    OpenAIEmbeddingUsage,
+    OpenAIFile,
+    OpenAIFileFile,
+    OpenAIImageURL,
+    OpenAIJSONSchema,
+    OpenAIMessageParam,
+    OpenAIResponseFormatJSONObject,
+    OpenAIResponseFormatJSONSchema,
+    OpenAIResponseFormatParam,
+    OpenAIResponseFormatText,
+    OpenAISystemMessageParam,
+    OpenAITokenLogProb,
+    OpenAIToolMessageParam,
+    OpenAITopLogProb,
+    OpenAIUserMessageParam,
+    QuantizationConfig,
+    QuantizationType,
+    RerankData,
+    RerankResponse,
+    ResponseFormat,
+    ResponseFormatType,
+    SamplingParams,
+    SamplingStrategy,
+    SystemMessage,
+    SystemMessageBehavior,
+    TextTruncation,
+    TokenLogProbs,
+    ToolChoice,
+    ToolResponseMessage,
+    TopKSamplingStrategy,
+    TopPSamplingStrategy,
+    UserMessage,
+)
+from .inspect import (
+    ApiFilter,
+    HealthInfo,
+    Inspect,
+    ListRoutesResponse,
+    RouteInfo,
+    VersionInfo,
+)
+from .models import (
+    CommonModelFields,
+    ListModelsResponse,
+    Model,
+    ModelInput,
+    Models,
+    ModelType,
+    OpenAIListModelsResponse,
+    OpenAIModel,
+)
+from .openai_responses import (
+    AllowedToolsFilter,
+    ApprovalFilter,
+    ListOpenAIResponseInputItem,
+    ListOpenAIResponseObject,
+    MCPListToolsTool,
+    OpenAIDeleteResponseObject,
+    OpenAIResponseAnnotationCitation,
+    OpenAIResponseAnnotationContainerFileCitation,
+    OpenAIResponseAnnotationFileCitation,
+    OpenAIResponseAnnotationFilePath,
+    OpenAIResponseAnnotations,
+    OpenAIResponseContentPart,
+    OpenAIResponseContentPartOutputText,
+    OpenAIResponseContentPartReasoningSummary,
+    OpenAIResponseContentPartReasoningText,
+    OpenAIResponseContentPartRefusal,
+    OpenAIResponseError,
+    OpenAIResponseInput,
+    OpenAIResponseInputFunctionToolCallOutput,
+    OpenAIResponseInputMessageContent,
+    OpenAIResponseInputMessageContentFile,
+    OpenAIResponseInputMessageContentImage,
+    OpenAIResponseInputMessageContentText,
+    OpenAIResponseInputTool,
+    OpenAIResponseInputToolFileSearch,
+    OpenAIResponseInputToolFunction,
+    OpenAIResponseInputToolMCP,
+    OpenAIResponseInputToolWebSearch,
+    OpenAIResponseMCPApprovalRequest,
+    OpenAIResponseMCPApprovalResponse,
+    OpenAIResponseMessage,
+    OpenAIResponseObject,
+    OpenAIResponseObjectStream,
+    OpenAIResponseObjectStreamResponseCompleted,
+    OpenAIResponseObjectStreamResponseContentPartAdded,
+    OpenAIResponseObjectStreamResponseContentPartDone,
+    OpenAIResponseObjectStreamResponseCreated,
+    OpenAIResponseObjectStreamResponseFailed,
+    OpenAIResponseObjectStreamResponseFileSearchCallCompleted,
+    OpenAIResponseObjectStreamResponseFileSearchCallInProgress,
+    OpenAIResponseObjectStreamResponseFileSearchCallSearching,
+    OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta,
+    OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone,
+    OpenAIResponseObjectStreamResponseIncomplete,
+    OpenAIResponseObjectStreamResponseInProgress,
+    OpenAIResponseObjectStreamResponseMcpCallArgumentsDelta,
+    OpenAIResponseObjectStreamResponseMcpCallArgumentsDone,
+    OpenAIResponseObjectStreamResponseMcpCallCompleted,
+    OpenAIResponseObjectStreamResponseMcpCallFailed,
+    OpenAIResponseObjectStreamResponseMcpCallInProgress,
+    OpenAIResponseObjectStreamResponseMcpListToolsCompleted,
+    OpenAIResponseObjectStreamResponseMcpListToolsFailed,
+    OpenAIResponseObjectStreamResponseMcpListToolsInProgress,
+    OpenAIResponseObjectStreamResponseOutputItemAdded,
+    OpenAIResponseObjectStreamResponseOutputItemDone,
+    OpenAIResponseObjectStreamResponseOutputTextAnnotationAdded,
+    OpenAIResponseObjectStreamResponseOutputTextDelta,
+    OpenAIResponseObjectStreamResponseOutputTextDone,
+    OpenAIResponseObjectStreamResponseReasoningSummaryPartAdded,
+    OpenAIResponseObjectStreamResponseReasoningSummaryPartDone,
+    OpenAIResponseObjectStreamResponseReasoningSummaryTextDelta,
+    OpenAIResponseObjectStreamResponseReasoningSummaryTextDone,
+    OpenAIResponseObjectStreamResponseReasoningTextDelta,
+    OpenAIResponseObjectStreamResponseReasoningTextDone,
+    OpenAIResponseObjectStreamResponseRefusalDelta,
+    OpenAIResponseObjectStreamResponseRefusalDone,
+    OpenAIResponseObjectStreamResponseWebSearchCallCompleted,
+    OpenAIResponseObjectStreamResponseWebSearchCallInProgress,
+    OpenAIResponseObjectStreamResponseWebSearchCallSearching,
+    OpenAIResponseObjectWithInput,
+    OpenAIResponseOutput,
+    OpenAIResponseOutputMessageContent,
+    OpenAIResponseOutputMessageContentOutputText,
+    OpenAIResponseOutputMessageFileSearchToolCall,
+    OpenAIResponseOutputMessageFileSearchToolCallResults,
+    OpenAIResponseOutputMessageFunctionToolCall,
+    OpenAIResponseOutputMessageMCPCall,
+    OpenAIResponseOutputMessageMCPListTools,
+    OpenAIResponseOutputMessageWebSearchToolCall,
+    OpenAIResponsePrompt,
+    OpenAIResponseText,
+    OpenAIResponseTextFormat,
+    OpenAIResponseTool,
+    OpenAIResponseToolMCP,
+    OpenAIResponseUsage,
+    OpenAIResponseUsageInputTokensDetails,
+    OpenAIResponseUsageOutputTokensDetails,
+    WebSearchToolTypes,
+)
+from .post_training import (
+    AlgorithmConfig,
+    DataConfig,
+    DatasetFormat,
+    DPOAlignmentConfig,
+    DPOLossType,
+    EfficiencyConfig,
+    ListPostTrainingJobsResponse,
+    LoraFinetuningConfig,
+    OptimizerConfig,
+    OptimizerType,
+    PostTraining,
+    PostTrainingJob,
+    PostTrainingJobArtifactsResponse,
+    PostTrainingJobLogStream,
+    PostTrainingJobStatusResponse,
+    PostTrainingRLHFRequest,
+    QATFinetuningConfig,
+    RLHFAlgorithm,
+    TrainingConfig,
+)
+from .prompts import ListPromptsResponse, Prompt, Prompts
+from .providers import ListProvidersResponse, ProviderInfo, Providers
+from .rag_tool import (
+    DefaultRAGQueryGeneratorConfig,
+    LLMRAGQueryGeneratorConfig,
+    RAGDocument,
+    RAGQueryConfig,
+    RAGQueryGenerator,
+    RAGQueryGeneratorConfig,
+    RAGQueryResult,
+    RAGSearchMode,
+    Ranker,
+    RRFRanker,
+    WeightedRanker,
+)
+from .resource import Resource, ResourceType
+from .safety import (
+    ModerationObject,
+    ModerationObjectResults,
+    RunShieldResponse,
+    Safety,
+    SafetyViolation,
+    ShieldStore,
+    ViolationLevel,
+)
+from .schema_utils import (
+    CallableT,
+    ExtraBodyField,
+    WebMethod,
+    json_schema_type,
+    register_schema,
+    webmethod,
+)
+from .scoring import (
+    ScoreBatchResponse,
+    ScoreResponse,
+    Scoring,
+    ScoringFunctionStore,
+    ScoringResult,
+    ScoringResultRow,
+)
+from .scoring_functions import (
+    AggregationFunctionType,
+    BasicScoringFnParams,
+    CommonScoringFnFields,
+    ListScoringFunctionsResponse,
+    LLMAsJudgeScoringFnParams,
+    RegexParserScoringFnParams,
+    ScoringFn,
+    ScoringFnInput,
+    ScoringFnParams,
+    ScoringFnParamsType,
+    ScoringFunctions,
+)
+from .shields import (
+    CommonShieldFields,
+    ListShieldsResponse,
+    Shield,
+    ShieldInput,
+    Shields,
+)
+
+# Import from strong_typing
+from .strong_typing.core import JsonType
+from .strong_typing.docstring import Docstring, parse_type
+from .strong_typing.inspection import (
+    get_signature,
+    is_generic_list,
+    is_type_optional,
+    is_type_union,
+    is_unwrapped_body_param,
+    unwrap_generic_list,
+    unwrap_optional_type,
+    unwrap_union_types,
+)
+from .strong_typing.name import python_type_to_name
+from .strong_typing.schema import (
+    JsonSchemaGenerator,
+    Schema,
+    SchemaOptions,
+    StrictJsonType,
+    get_schema_identifier,
+)
+from .strong_typing.serialization import json_dump_string, object_to_json
+from .tools import (
+    ListToolDefsResponse,
+    ListToolGroupsResponse,
+    SpecialToolGroup,
+    ToolDef,
+    ToolGroup,
+    ToolGroupInput,
+    ToolGroups,
+    ToolInvocationResult,
+    ToolRuntime,
+    ToolStore,
+)
+from .vector_io import (
+    Chunk,
+    ChunkMetadata,
+    OpenAICreateVectorStoreFileBatchRequestWithExtraBody,
+    OpenAICreateVectorStoreRequestWithExtraBody,
+    QueryChunksResponse,
+    SearchRankingOptions,
+    VectorIO,
+    VectorStoreChunkingStrategy,
+    VectorStoreChunkingStrategyAuto,
+    VectorStoreChunkingStrategyStatic,
+    VectorStoreChunkingStrategyStaticConfig,
+    VectorStoreContent,
+    VectorStoreCreateRequest,
+    VectorStoreDeleteResponse,
+    VectorStoreFileBatchObject,
+    VectorStoreFileContentResponse,
+    VectorStoreFileCounts,
+    VectorStoreFileDeleteResponse,
+    VectorStoreFileLastError,
+    VectorStoreFileObject,
+    VectorStoreFilesListInBatchResponse,
+    VectorStoreFileStatus,
+    VectorStoreListFilesResponse,
+    VectorStoreListResponse,
+    VectorStoreModifyRequest,
+    VectorStoreObject,
+    VectorStoreSearchRequest,
+    VectorStoreSearchResponse,
+    VectorStoreSearchResponsePage,
+    VectorStoreTable,
+)
+from .vector_stores import VectorStore, VectorStoreInput
+from .version import (
+    LLAMA_STACK_API_V1,
+    LLAMA_STACK_API_V1ALPHA,
+    LLAMA_STACK_API_V1BETA,
+)
+
+__all__ = [
+    # Submodules
+    "common",
+    "strong_typing",
+    # Version constants
+    "LLAMA_STACK_API_V1",
+    "LLAMA_STACK_API_V1ALPHA",
+    "LLAMA_STACK_API_V1BETA",
+    # API Symbols
+    "Agents",
+    "AggregationFunctionType",
+    "AlgorithmConfig",
+    "AllowedToolsFilter",
+    "Api",
+    "ApiFilter",
+    "ApprovalFilter",
+    "BasicScoringFnParams",
+    "Batches",
+    "BatchObject",
+    "Benchmark",
+    "BenchmarkConfig",
+    "BenchmarkInput",
+    "Benchmarks",
+    "BenchmarksProtocolPrivate",
+    "Bf16QuantizationConfig",
+    "CallableT",
+    "ChatCompletionInputType",
+    "ChatCompletionResponseEventType",
+    "Checkpoint",
+    "Chunk",
+    "ChunkMetadata",
+    "CommonBenchmarkFields",
+    "ConflictError",
+    "CommonDatasetFields",
+    "CommonModelFields",
+    "CommonScoringFnFields",
+    "CommonShieldFields",
+    "CompletionInputType",
+    "CompletionRequest",
+    "Conversation",
+    "ConversationDeletedResource",
+    "ConversationItem",
+    "ConversationItemCreateRequest",
+    "ConversationItemDeletedResource",
+    "ConversationItemInclude",
+    "ConversationItemList",
+    "ConversationMessage",
+    "Conversations",
+    "DPOAlignmentConfig",
+    "DPOLossType",
+    "DataConfig",
+    "DataSource",
+    "Dataset",
+    "DatasetFormat",
+    "DatasetIO",
+    "DatasetInput",
+    "DatasetPurpose",
+    "DatasetNotFoundError",
+    "DatasetStore",
+    "DatasetType",
+    "Datasets",
+    "DatasetsProtocolPrivate",
+    "DefaultRAGQueryGeneratorConfig",
+    "Docstring",
+    "DynamicApiMeta",
+    "EfficiencyConfig",
+    "EmbeddingTaskType",
+    "EmbeddingsResponse",
+    "Error",
+    "Eval",
+    "EvalCandidate",
+    "EvaluateResponse",
+    "ExpiresAfter",
+    "ExternalApiSpec",
+    "ExtraBodyField",
+    "Files",
+    "Fp8QuantizationConfig",
+    "get_schema_identifier",
+    "get_signature",
+    "GrammarResponseFormat",
+    "GreedySamplingStrategy",
+    "HealthInfo",
+    "HealthResponse",
+    "HealthStatus",
+    "ImageContentItem",
+    "Inference",
+    "InferenceProvider",
+    "InlineProviderSpec",
+    "Inspect",
+    "Int4QuantizationConfig",
+    "InterleavedContent",
+    "InterleavedContentItem",
+    "InvalidConversationIdError",
+    "is_generic_list",
+    "is_type_optional",
+    "is_type_union",
+    "is_unwrapped_body_param",
+    "Job",
+    "JobStatus",
+    "json_dump_string",
+    "json_schema_type",
+    "JsonSchemaGenerator",
+    "JsonSchemaResponseFormat",
+    "JsonType",
+    "LLMAsJudgeScoringFnParams",
+    "LLMRAGQueryGeneratorConfig",
+    "ListBatchesResponse",
+    "ListBenchmarksResponse",
+    "ListDatasetsResponse",
+    "ListModelsResponse",
+    "ListOpenAIChatCompletionResponse",
+    "ListOpenAIFileResponse",
+    "ListOpenAIResponseInputItem",
+    "ListOpenAIResponseObject",
+    "ListPostTrainingJobsResponse",
+    "ListPromptsResponse",
+    "ListProvidersResponse",
+    "ListRoutesResponse",
+    "ListScoringFunctionsResponse",
+    "ListShieldsResponse",
+    "ListToolDefsResponse",
+    "ListToolGroupsResponse",
+    "LogProbConfig",
+    "LoraFinetuningConfig",
+    "MCPListToolsTool",
+    "Metadata",
+    "Model",
+    "ModelCandidate",
+    "ModelInput",
+    "ModelNotFoundError",
+    "ModelStore",
+    "ModelType",
+    "ModelTypeError",
+    "Models",
+    "ModelsProtocolPrivate",
+    "ModerationObject",
+    "ModerationObjectResults",
+    "NumberType",
+    "object_to_json",
+    "OpenAIAssistantMessageParam",
+    "OpenAIChatCompletion",
+    "OpenAIChatCompletionChunk",
+    "OpenAIChatCompletionContentPartImageParam",
+    "OpenAIChatCompletionContentPartParam",
+    "OpenAIChatCompletionContentPartTextParam",
+    "OpenAIChatCompletionMessageContent",
+    "OpenAIChatCompletionRequestWithExtraBody",
+    "OpenAIChatCompletionTextOnlyMessageContent",
+    "OpenAIChatCompletionToolCall",
+    "OpenAIChatCompletionToolCallFunction",
+    "OpenAIChatCompletionUsage",
+    "OpenAIChatCompletionUsageCompletionTokensDetails",
+    "OpenAIChatCompletionUsagePromptTokensDetails",
+    "OpenAIChoice",
+    "OpenAIChoiceDelta",
+    "OpenAIChoiceLogprobs",
+    "OpenAIChunkChoice",
+    "OpenAICompletion",
+    "OpenAICompletionChoice",
+    "OpenAICompletionLogprobs",
+    "OpenAICompletionRequestWithExtraBody",
+    "OpenAICompletionWithInputMessages",
+    "OpenAICreateVectorStoreFileBatchRequestWithExtraBody",
+    "OpenAICreateVectorStoreRequestWithExtraBody",
+    "OpenAIDeleteResponseObject",
+    "OpenAIDeveloperMessageParam",
+    "OpenAIEmbeddingData",
+    "OpenAIEmbeddingUsage",
+    "OpenAIEmbeddingsRequestWithExtraBody",
+    "OpenAIEmbeddingsResponse",
+    "OpenAIFile",
+    "OpenAIFileDeleteResponse",
+    "OpenAIFileFile",
+    "OpenAIFileObject",
+    "OpenAIFilePurpose",
+    "OpenAIImageURL",
+    "OpenAIJSONSchema",
+    "OpenAIListModelsResponse",
+    "OpenAIMessageParam",
+    "OpenAIModel",
+    "Order",
+    "OpenAIResponseAnnotationCitation",
+    "OpenAIResponseAnnotationContainerFileCitation",
+    "OpenAIResponseAnnotationFileCitation",
+    "OpenAIResponseAnnotationFilePath",
+    "OpenAIResponseAnnotations",
+    "OpenAIResponseContentPart",
+    "OpenAIResponseContentPartOutputText",
+    "OpenAIResponseContentPartReasoningSummary",
+    "OpenAIResponseContentPartReasoningText",
+    "OpenAIResponseContentPartRefusal",
+    "OpenAIResponseError",
+    "OpenAIResponseFormatJSONObject",
+    "OpenAIResponseFormatJSONSchema",
+    "OpenAIResponseFormatParam",
+    "OpenAIResponseFormatText",
+    "OpenAIResponseInput",
+    "OpenAIResponseInputFunctionToolCallOutput",
+    "OpenAIResponseInputMessageContent",
+    "OpenAIResponseInputMessageContentFile",
+    "OpenAIResponseInputMessageContentImage",
+    "OpenAIResponseInputMessageContentText",
+    "OpenAIResponseInputTool",
+    "OpenAIResponseInputToolFileSearch",
+    "OpenAIResponseInputToolFunction",
+    "OpenAIResponseInputToolMCP",
+    "OpenAIResponseInputToolWebSearch",
+    "OpenAIResponseMCPApprovalRequest",
+    "OpenAIResponseMCPApprovalResponse",
+    "OpenAIResponseMessage",
+    "OpenAIResponseObject",
+    "OpenAIResponseObjectStream",
+    "OpenAIResponseObjectStreamResponseCompleted",
+    "OpenAIResponseObjectStreamResponseContentPartAdded",
+    "OpenAIResponseObjectStreamResponseContentPartDone",
+    "OpenAIResponseObjectStreamResponseCreated",
+    "OpenAIResponseObjectStreamResponseFailed",
+    "OpenAIResponseObjectStreamResponseFileSearchCallCompleted",
+    "OpenAIResponseObjectStreamResponseFileSearchCallInProgress",
+    "OpenAIResponseObjectStreamResponseFileSearchCallSearching",
+    "OpenAIResponseObjectStreamResponseFunctionCallArgumentsDelta",
+    "OpenAIResponseObjectStreamResponseFunctionCallArgumentsDone",
+    "OpenAIResponseObjectStreamResponseInProgress",
+    "OpenAIResponseObjectStreamResponseIncomplete",
+    "OpenAIResponseObjectStreamResponseMcpCallArgumentsDelta",
+    "OpenAIResponseObjectStreamResponseMcpCallArgumentsDone",
+    "OpenAIResponseObjectStreamResponseMcpCallCompleted",
+    "OpenAIResponseObjectStreamResponseMcpCallFailed",
+    "OpenAIResponseObjectStreamResponseMcpCallInProgress",
+    "OpenAIResponseObjectStreamResponseMcpListToolsCompleted",
+    "OpenAIResponseObjectStreamResponseMcpListToolsFailed",
+    "OpenAIResponseObjectStreamResponseMcpListToolsInProgress",
+    "OpenAIResponseObjectStreamResponseOutputItemAdded",
+    "OpenAIResponseObjectStreamResponseOutputItemDone",
+    "OpenAIResponseObjectStreamResponseOutputTextAnnotationAdded",
+    "OpenAIResponseObjectStreamResponseOutputTextDelta",
+    "OpenAIResponseObjectStreamResponseOutputTextDone",
+    "OpenAIResponseObjectStreamResponseReasoningSummaryPartAdded",
+    "OpenAIResponseObjectStreamResponseReasoningSummaryPartDone",
+    "OpenAIResponseObjectStreamResponseReasoningSummaryTextDelta",
+    "OpenAIResponseObjectStreamResponseReasoningSummaryTextDone",
+    "OpenAIResponseObjectStreamResponseReasoningTextDelta",
+    "OpenAIResponseObjectStreamResponseReasoningTextDone",
+    "OpenAIResponseObjectStreamResponseRefusalDelta",
+    "OpenAIResponseObjectStreamResponseRefusalDone",
+    "OpenAIResponseObjectStreamResponseWebSearchCallCompleted",
+    "OpenAIResponseObjectStreamResponseWebSearchCallInProgress",
+    "OpenAIResponseObjectStreamResponseWebSearchCallSearching",
+    "OpenAIResponseObjectWithInput",
+    "OpenAIResponseOutput",
+    "OpenAIResponseOutputMessageContent",
+    "OpenAIResponseOutputMessageContentOutputText",
+    "OpenAIResponseOutputMessageFileSearchToolCall",
+    "OpenAIResponseOutputMessageFileSearchToolCallResults",
+    "OpenAIResponseOutputMessageFunctionToolCall",
+    "OpenAIResponseOutputMessageMCPCall",
+    "OpenAIResponseOutputMessageMCPListTools",
+    "OpenAIResponseOutputMessageWebSearchToolCall",
+    "OpenAIResponsePrompt",
+    "OpenAIResponseText",
+    "OpenAIResponseTextFormat",
+    "OpenAIResponseTool",
+    "OpenAIResponseToolMCP",
+    "OpenAIResponseUsage",
+    "OpenAIResponseUsageInputTokensDetails",
+    "OpenAIResponseUsageOutputTokensDetails",
+    "OpenAISystemMessageParam",
+    "OpenAITokenLogProb",
+    "OpenAIToolMessageParam",
+    "OpenAITopLogProb",
+    "OpenAIUserMessageParam",
+    "OptimizerConfig",
+    "OptimizerType",
+    "PaginatedResponse",
+    "ParamType",
+    "parse_type",
+    "PostTraining",
+    "PostTrainingMetric",
+    "PostTrainingJob",
+    "PostTrainingJobArtifactsResponse",
+    "PostTrainingJobLogStream",
+    "PostTrainingJobStatusResponse",
+    "PostTrainingRLHFRequest",
+    "Prompt",
+    "Prompts",
+    "ProviderInfo",
+    "ProviderSpec",
+    "Providers",
+    "python_type_to_name",
+    "QATFinetuningConfig",
+    "QuantizationConfig",
+    "QuantizationType",
+    "QueryChunksResponse",
+    "RAGDocument",
+    "RAGQueryConfig",
+    "RAGQueryGenerator",
+    "RAGQueryGeneratorConfig",
+    "RAGQueryResult",
+    "RAGSearchMode",
+    "register_schema",
+    "RLHFAlgorithm",
+    "RRFRanker",
+    "Ranker",
+    "RegexParserScoringFnParams",
+    "RemoteProviderConfig",
+    "RemoteProviderSpec",
+    "RerankData",
+    "RerankResponse",
+    "Resource",
+    "ResourceNotFoundError",
+    "ResourceType",
+    "ResponseFormat",
+    "ResponseFormatType",
+    "ResponseGuardrail",
+    "ResponseGuardrailSpec",
+    "RouteInfo",
+    "RoutingTable",
+    "RowsDataSource",
+    "RunShieldResponse",
+    "Safety",
+    "SafetyViolation",
+    "SamplingParams",
+    "SamplingStrategy",
+    "ScoreBatchResponse",
+    "ScoreResponse",
+    "Scoring",
+    "ScoringFn",
+    "ScoringFnInput",
+    "ScoringFnParams",
+    "ScoringFnParamsType",
+    "ScoringFunctionStore",
+    "ScoringFunctions",
+    "ScoringFunctionsProtocolPrivate",
+    "ScoringResult",
+    "ScoringResultRow",
+    "Schema",
+    "SchemaOptions",
+    "SearchRankingOptions",
+    "Shield",
+    "ShieldInput",
+    "ShieldStore",
+    "Shields",
+    "ShieldsProtocolPrivate",
+    "SpecialToolGroup",
+    "StrictJsonType",
+    "StringType",
+    "SystemMessage",
+    "SystemMessageBehavior",
+    "TextContentItem",
+    "TextTruncation",
+    "TokenLogProbs",
+    "TokenValidationError",
+    "ToolChoice",
+    "ToolGroupNotFoundError",
+    "ToolDef",
+    "ToolGroup",
+    "ToolGroupInput",
+    "ToolGroups",
+    "ToolGroupsProtocolPrivate",
+    "ToolInvocationResult",
+    "ToolResponseMessage",
+    "ToolRuntime",
+    "ToolStore",
+    "TopKSamplingStrategy",
+    "TopPSamplingStrategy",
+    "TrainingConfig",
+    "UnsupportedModelError",
+    "unwrap_generic_list",
+    "unwrap_optional_type",
+    "unwrap_union_types",
+    "URIDataSource",
+    "URL",
+    "_URLOrData",
+    "UserMessage",
+    "VectorIO",
+    "VectorStore",
+    "VectorStoreChunkingStrategy",
+    "VectorStoreChunkingStrategyAuto",
+    "VectorStoreChunkingStrategyStatic",
+    "VectorStoreChunkingStrategyStaticConfig",
+    "VectorStoreContent",
+    "VectorStoreCreateRequest",
+    "VectorStoreDeleteResponse",
+    "VectorStoreFileBatchObject",
+    "VectorStoreFileContentResponse",
+    "VectorStoreFileCounts",
+    "VectorStoreFileDeleteResponse",
+    "VectorStoreFileLastError",
+    "VectorStoreFileObject",
+    "VectorStoreFileStatus",
+    "VectorStoreFilesListInBatchResponse",
+    "VectorStoreInput",
+    "VectorStoreListFilesResponse",
+    "VectorStoreListResponse",
+    "VectorStoreModifyRequest",
+    "VectorStoreObject",
+    "VectorStoreSearchRequest",
+    "VectorStoreSearchResponse",
+    "VectorStoreSearchResponsePage",
+    "VectorStoreTable",
+    "VectorStoreNotFoundError",
+    "VectorStoresProtocolPrivate",
+    "VersionInfo",
+    "ViolationLevel",
+    "webmethod",
+    "WebMethod",
+    "WebSearchToolTypes",
+    "WeightedRanker",
+]

src/llama_stack_api/agents.py

@@ -0,0 +1,153 @@
+# 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 collections.abc import AsyncIterator
+from typing import Annotated, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from llama_stack_api.common.responses import Order
+from llama_stack_api.schema_utils import ExtraBodyField, json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+from .openai_responses import (
+    ListOpenAIResponseInputItem,
+    ListOpenAIResponseObject,
+    OpenAIDeleteResponseObject,
+    OpenAIResponseInput,
+    OpenAIResponseInputTool,
+    OpenAIResponseObject,
+    OpenAIResponseObjectStream,
+    OpenAIResponsePrompt,
+    OpenAIResponseText,
+)
+
+
+@json_schema_type
+class ResponseGuardrailSpec(BaseModel):
+    """Specification for a guardrail to apply during response generation.
+
+    :param type: The type/identifier of the guardrail.
+    """
+
+    type: str
+    # TODO: more fields to be added for guardrail configuration
+
+
+ResponseGuardrail = str | ResponseGuardrailSpec
+
+
+@runtime_checkable
+class Agents(Protocol):
+    """Agents
+
+    APIs for creating and interacting with agentic systems."""
+
+    # We situate the OpenAI Responses API in the Agents API just like we did things
+    # for Inference. The Responses API, in its intent, serves the same purpose as
+    # the Agents API above -- it is essentially a lightweight "agentic loop" with
+    # integrated tool calling.
+    #
+    # Both of these APIs are inherently stateful.
+
+    @webmethod(route="/responses/{response_id}", method="GET", level=LLAMA_STACK_API_V1)
+    async def get_openai_response(
+        self,
+        response_id: str,
+    ) -> OpenAIResponseObject:
+        """Get a model response.
+
+        :param response_id: The ID of the OpenAI response to retrieve.
+        :returns: An OpenAIResponseObject.
+        """
+        ...
+
+    @webmethod(route="/responses", method="POST", level=LLAMA_STACK_API_V1)
+    async def create_openai_response(
+        self,
+        input: str | list[OpenAIResponseInput],
+        model: str,
+        prompt: OpenAIResponsePrompt | None = None,
+        instructions: str | None = None,
+        previous_response_id: str | None = None,
+        conversation: str | None = None,
+        store: bool | None = True,
+        stream: bool | None = False,
+        temperature: float | None = None,
+        text: OpenAIResponseText | None = None,
+        tools: list[OpenAIResponseInputTool] | None = None,
+        include: list[str] | None = None,
+        max_infer_iters: int | None = 10,  # this is an extension to the OpenAI API
+        guardrails: Annotated[
+            list[ResponseGuardrail] | None,
+            ExtraBodyField(
+                "List of guardrails to apply during response generation. Guardrails provide safety and content moderation."
+            ),
+        ] = None,
+        max_tool_calls: int | None = None,
+    ) -> OpenAIResponseObject | AsyncIterator[OpenAIResponseObjectStream]:
+        """Create a model response.
+
+        :param input: Input message(s) to create the response.
+        :param model: The underlying LLM used for completions.
+        :param prompt: (Optional) Prompt object with ID, version, and variables.
+        :param previous_response_id: (Optional) if specified, the new response will be a continuation of the previous response. This can be used to easily fork-off new responses from existing responses.
+        :param conversation: (Optional) The ID of a conversation to add the response to. Must begin with 'conv_'. Input and output messages will be automatically added to the conversation.
+        :param include: (Optional) Additional fields to include in the response.
+        :param guardrails: (Optional) List of guardrails to apply during response generation. Can be guardrail IDs (strings) or guardrail specifications.
+        :param max_tool_calls: (Optional) Max number of total calls to built-in tools that can be processed in a response.
+        :returns: An OpenAIResponseObject.
+        """
+        ...
+
+    @webmethod(route="/responses", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_openai_responses(
+        self,
+        after: str | None = None,
+        limit: int | None = 50,
+        model: str | None = None,
+        order: Order | None = Order.desc,
+    ) -> ListOpenAIResponseObject:
+        """List all responses.
+
+        :param after: The ID of the last response to return.
+        :param limit: The number of responses to return.
+        :param model: The model to filter responses by.
+        :param order: The order to sort responses by when sorted by created_at ('asc' or 'desc').
+        :returns: A ListOpenAIResponseObject.
+        """
+        ...
+
+    @webmethod(route="/responses/{response_id}/input_items", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_openai_response_input_items(
+        self,
+        response_id: str,
+        after: str | None = None,
+        before: str | None = None,
+        include: list[str] | None = None,
+        limit: int | None = 20,
+        order: Order | None = Order.desc,
+    ) -> ListOpenAIResponseInputItem:
+        """List input items.
+
+        :param response_id: The ID of the response to retrieve input items for.
+        :param after: An item ID to list items after, used for pagination.
+        :param before: An item ID to list items before, used for pagination.
+        :param include: Additional fields to include in the response.
+        :param limit: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
+        :param order: The order to return the input items in. Default is desc.
+        :returns: An ListOpenAIResponseInputItem.
+        """
+        ...
+
+    @webmethod(route="/responses/{response_id}", method="DELETE", level=LLAMA_STACK_API_V1)
+    async def delete_openai_response(self, response_id: str) -> OpenAIDeleteResponseObject:
+        """Delete a response.
+
+        :param response_id: The ID of the OpenAI response to delete.
+        :returns: An OpenAIDeleteResponseObject
+        """
+        ...

src/llama_stack_api/batches.py

@@ -0,0 +1,96 @@
+# 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 Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+try:
+    from openai.types import Batch as BatchObject
+except ImportError as e:
+    raise ImportError("OpenAI package is required for batches API. Please install it with: pip install openai") from e
+
+
+@json_schema_type
+class ListBatchesResponse(BaseModel):
+    """Response containing a list of batch objects."""
+
+    object: Literal["list"] = "list"
+    data: list[BatchObject] = Field(..., description="List of batch objects")
+    first_id: str | None = Field(default=None, description="ID of the first batch in the list")
+    last_id: str | None = Field(default=None, description="ID of the last batch in the list")
+    has_more: bool = Field(default=False, description="Whether there are more batches available")
+
+
+@runtime_checkable
+class Batches(Protocol):
+    """
+    The Batches API enables efficient processing of multiple requests in a single operation,
+    particularly useful for processing large datasets, batch evaluation workflows, and
+    cost-effective inference at scale.
+
+    The API is designed to allow use of openai client libraries for seamless integration.
+
+    This API provides the following extensions:
+     - idempotent batch creation
+
+    Note: This API is currently under active development and may undergo changes.
+    """
+
+    @webmethod(route="/batches", method="POST", level=LLAMA_STACK_API_V1)
+    async def create_batch(
+        self,
+        input_file_id: str,
+        endpoint: str,
+        completion_window: Literal["24h"],
+        metadata: dict[str, str] | None = None,
+        idempotency_key: str | None = None,
+    ) -> BatchObject:
+        """Create a new batch for processing multiple API requests.
+
+        :param input_file_id: The ID of an uploaded file containing requests for the batch.
+        :param endpoint: The endpoint to be used for all requests in the batch.
+        :param completion_window: The time window within which the batch should be processed.
+        :param metadata: Optional metadata for the batch.
+        :param idempotency_key: Optional idempotency key. When provided, enables idempotent behavior.
+        :returns: The created batch object.
+        """
+        ...
+
+    @webmethod(route="/batches/{batch_id}", method="GET", level=LLAMA_STACK_API_V1)
+    async def retrieve_batch(self, batch_id: str) -> BatchObject:
+        """Retrieve information about a specific batch.
+
+        :param batch_id: The ID of the batch to retrieve.
+        :returns: The batch object.
+        """
+        ...
+
+    @webmethod(route="/batches/{batch_id}/cancel", method="POST", level=LLAMA_STACK_API_V1)
+    async def cancel_batch(self, batch_id: str) -> BatchObject:
+        """Cancel a batch that is in progress.
+
+        :param batch_id: The ID of the batch to cancel.
+        :returns: The updated batch object.
+        """
+        ...
+
+    @webmethod(route="/batches", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_batches(
+        self,
+        after: str | None = None,
+        limit: int = 20,
+    ) -> ListBatchesResponse:
+        """List all batches for the current user.
+
+        :param after: A cursor for pagination; returns batches after this batch ID.
+        :param limit: Number of batches to return (default 20, max 100).
+        :returns: A list of batch objects.
+        """
+        ...

src/llama_stack_api/benchmarks.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.
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.resource import Resource, ResourceType
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1ALPHA
+
+
+class CommonBenchmarkFields(BaseModel):
+    dataset_id: str
+    scoring_functions: list[str]
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Metadata for this evaluation task",
+    )
+
+
+@json_schema_type
+class Benchmark(CommonBenchmarkFields, Resource):
+    """A benchmark resource for evaluating model performance.
+
+    :param dataset_id: Identifier of the dataset to use for the benchmark evaluation
+    :param scoring_functions: List of scoring function identifiers to apply during evaluation
+    :param metadata: Metadata for this evaluation task
+    :param type: The resource type, always benchmark
+    """
+
+    type: Literal[ResourceType.benchmark] = ResourceType.benchmark
+
+    @property
+    def benchmark_id(self) -> str:
+        return self.identifier
+
+    @property
+    def provider_benchmark_id(self) -> str | None:
+        return self.provider_resource_id
+
+
+class BenchmarkInput(CommonBenchmarkFields, BaseModel):
+    benchmark_id: str
+    provider_id: str | None = None
+    provider_benchmark_id: str | None = None
+
+
+class ListBenchmarksResponse(BaseModel):
+    data: list[Benchmark]
+
+
+@runtime_checkable
+class Benchmarks(Protocol):
+    @webmethod(route="/eval/benchmarks", method="GET", level=LLAMA_STACK_API_V1ALPHA)
+    async def list_benchmarks(self) -> ListBenchmarksResponse:
+        """List all benchmarks.
+
+        :returns: A ListBenchmarksResponse.
+        """
+        ...
+
+    @webmethod(route="/eval/benchmarks/{benchmark_id}", method="GET", level=LLAMA_STACK_API_V1ALPHA)
+    async def get_benchmark(
+        self,
+        benchmark_id: str,
+    ) -> Benchmark:
+        """Get a benchmark by its ID.
+
+        :param benchmark_id: The ID of the benchmark to get.
+        :returns: A Benchmark.
+        """
+        ...
+
+    @webmethod(route="/eval/benchmarks", method="POST", level=LLAMA_STACK_API_V1ALPHA, deprecated=True)
+    async def register_benchmark(
+        self,
+        benchmark_id: str,
+        dataset_id: str,
+        scoring_functions: list[str],
+        provider_benchmark_id: str | None = None,
+        provider_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Register a benchmark.
+
+        :param benchmark_id: The ID of the benchmark to register.
+        :param dataset_id: The ID of the dataset to use for the benchmark.
+        :param scoring_functions: The scoring functions to use for the benchmark.
+        :param provider_benchmark_id: The ID of the provider benchmark to use for the benchmark.
+        :param provider_id: The ID of the provider to use for the benchmark.
+        :param metadata: The metadata to use for the benchmark.
+        """
+        ...
+
+    @webmethod(route="/eval/benchmarks/{benchmark_id}", method="DELETE", level=LLAMA_STACK_API_V1ALPHA, deprecated=True)
+    async def unregister_benchmark(self, benchmark_id: str) -> None:
+        """Unregister a benchmark.
+
+        :param benchmark_id: The ID of the benchmark to unregister.
+        """
+        ...

src/llama_stack_api/common/__init__.py

@@ -0,0 +1,5 @@
+# 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.

src/llama_stack_api/common/content_types.py

@@ -0,0 +1,101 @@
+# 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, Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from llama_stack_api.schema_utils import json_schema_type, register_schema
+
+
+@json_schema_type
+class URL(BaseModel):
+    """A URL reference to external content.
+
+    :param uri: The URL string pointing to the resource
+    """
+
+    uri: str
+
+
+class _URLOrData(BaseModel):
+    """
+    A URL or a base64 encoded string
+
+    :param url: A URL of the image or data URL in the format of data:image/{type};base64,{data}. Note that URL could have length limits.
+    :param data: base64 encoded image data as string
+    """
+
+    url: URL | None = None
+    # data is a base64 encoded string, hint with contentEncoding=base64
+    data: str | None = Field(default=None, json_schema_extra={"contentEncoding": "base64"})
+
+    @model_validator(mode="before")
+    @classmethod
+    def validator(cls, values):
+        if isinstance(values, dict):
+            return values
+        return {"url": values}
+
+
+@json_schema_type
+class ImageContentItem(BaseModel):
+    """A image content item
+
+    :param type: Discriminator type of the content item. Always "image"
+    :param image: Image as a base64 encoded string or an URL
+    """
+
+    type: Literal["image"] = "image"
+    image: _URLOrData
+
+
+@json_schema_type
+class TextContentItem(BaseModel):
+    """A text content item
+
+    :param type: Discriminator type of the content item. Always "text"
+    :param text: Text content
+    """
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+# other modalities can be added here
+InterleavedContentItem = Annotated[
+    ImageContentItem | TextContentItem,
+    Field(discriminator="type"),
+]
+register_schema(InterleavedContentItem, name="InterleavedContentItem")
+
+# accept a single "str" as a special case since it is common
+InterleavedContent = str | InterleavedContentItem | list[InterleavedContentItem]
+register_schema(InterleavedContent, name="InterleavedContent")
+
+
+@json_schema_type
+class TextDelta(BaseModel):
+    """A text content delta for streaming responses.
+
+    :param type: Discriminator type of the delta. Always "text"
+    :param text: The incremental text content
+    """
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+@json_schema_type
+class ImageDelta(BaseModel):
+    """An image content delta for streaming responses.
+
+    :param type: Discriminator type of the delta. Always "image"
+    :param image: The incremental image data as bytes
+    """
+
+    type: Literal["image"] = "image"
+    image: bytes

src/llama_stack_api/common/errors.py

@@ -0,0 +1,95 @@
+# 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.
+
+# Custom Llama Stack Exception classes should follow the following schema
+#   1. All classes should inherit from an existing Built-In Exception class: https://docs.python.org/3/library/exceptions.html
+#   2. All classes should have a custom error message with the goal of informing the Llama Stack user specifically
+#   3. All classes should propogate the inherited __init__ function otherwise via 'super().__init__(message)'
+
+
+class ResourceNotFoundError(ValueError):
+    """generic exception for a missing Llama Stack resource"""
+
+    def __init__(self, resource_name: str, resource_type: str, client_list: str) -> None:
+        message = (
+            f"{resource_type} '{resource_name}' not found. Use '{client_list}' to list available {resource_type}s."
+        )
+        super().__init__(message)
+
+
+class UnsupportedModelError(ValueError):
+    """raised when model is not present in the list of supported models"""
+
+    def __init__(self, model_name: str, supported_models_list: list[str]):
+        message = f"'{model_name}' model is not supported. Supported models are: {', '.join(supported_models_list)}"
+        super().__init__(message)
+
+
+class ModelNotFoundError(ResourceNotFoundError):
+    """raised when Llama Stack cannot find a referenced model"""
+
+    def __init__(self, model_name: str) -> None:
+        super().__init__(model_name, "Model", "client.models.list()")
+
+
+class VectorStoreNotFoundError(ResourceNotFoundError):
+    """raised when Llama Stack cannot find a referenced vector store"""
+
+    def __init__(self, vector_store_name: str) -> None:
+        super().__init__(vector_store_name, "Vector Store", "client.vector_dbs.list()")
+
+
+class DatasetNotFoundError(ResourceNotFoundError):
+    """raised when Llama Stack cannot find a referenced dataset"""
+
+    def __init__(self, dataset_name: str) -> None:
+        super().__init__(dataset_name, "Dataset", "client.datasets.list()")
+
+
+class ToolGroupNotFoundError(ResourceNotFoundError):
+    """raised when Llama Stack cannot find a referenced tool group"""
+
+    def __init__(self, toolgroup_name: str) -> None:
+        super().__init__(toolgroup_name, "Tool Group", "client.toolgroups.list()")
+
+
+class ModelTypeError(TypeError):
+    """raised when a model is present but not the correct type"""
+
+    def __init__(self, model_name: str, model_type: str, expected_model_type: str) -> None:
+        message = (
+            f"Model '{model_name}' is of type '{model_type}' rather than the expected type '{expected_model_type}'"
+        )
+        super().__init__(message)
+
+
+class ConflictError(ValueError):
+    """raised when an operation cannot be performed due to a conflict with the current state"""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class TokenValidationError(ValueError):
+    """raised when token validation fails during authentication"""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class ConversationNotFoundError(ResourceNotFoundError):
+    """raised when Llama Stack cannot find a referenced conversation"""
+
+    def __init__(self, conversation_id: str) -> None:
+        super().__init__(conversation_id, "Conversation", "client.conversations.list()")
+
+
+class InvalidConversationIdError(ValueError):
+    """raised when a conversation ID has an invalid format"""
+
+    def __init__(self, conversation_id: str) -> None:
+        message = f"Invalid conversation ID '{conversation_id}'. Expected an ID that begins with 'conv_'."
+        super().__init__(message)

src/llama_stack_api/common/job_types.py

@@ -0,0 +1,38 @@
+# 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 Enum
+
+from pydantic import BaseModel
+
+from llama_stack_api.schema_utils import json_schema_type
+
+
+class JobStatus(Enum):
+    """Status of a job execution.
+    :cvar completed: Job has finished successfully
+    :cvar in_progress: Job is currently running
+    :cvar failed: Job has failed during execution
+    :cvar scheduled: Job is scheduled but not yet started
+    :cvar cancelled: Job was cancelled before completion
+    """
+
+    completed = "completed"
+    in_progress = "in_progress"
+    failed = "failed"
+    scheduled = "scheduled"
+    cancelled = "cancelled"
+
+
+@json_schema_type
+class Job(BaseModel):
+    """A job execution instance with status tracking.
+
+    :param job_id: Unique identifier for the job
+    :param status: Current execution status of the job
+    """
+
+    job_id: str
+    status: JobStatus

src/llama_stack_api/common/responses.py

@@ -0,0 +1,77 @@
+# 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 Enum
+from typing import Any
+
+from pydantic import BaseModel
+
+from llama_stack_api.schema_utils import json_schema_type
+
+
+class Order(Enum):
+    """Sort order for paginated responses.
+    :cvar asc: Ascending order
+    :cvar desc: Descending order
+    """
+
+    asc = "asc"
+    desc = "desc"
+
+
+@json_schema_type
+class PaginatedResponse(BaseModel):
+    """A generic paginated response that follows a simple format.
+
+    :param data: The list of items for the current page
+    :param has_more: Whether there are more items available after this set
+    :param url: The URL for accessing this list
+    """
+
+    data: list[dict[str, Any]]
+    has_more: bool
+    url: str | None = None
+
+
+# This is a short term solution to allow inference API to return metrics
+# The ideal way to do this is to have a way for all response types to include metrics
+# and all metric events logged to the telemetry API to be included with the response
+# To do this, we will need to augment all response types with a metrics field.
+# We have hit a blocker from stainless SDK that prevents us from doing this.
+# The blocker is that if we were to augment the response types that have a data field
+# in them like so
+# class ListModelsResponse(BaseModel):
+# metrics: Optional[List[MetricEvent]] = None
+# data: List[Models]
+# ...
+# The client SDK will need to access the data by using a .data field, which is not
+# ergonomic. Stainless SDK does support unwrapping the response type, but it
+# requires that the response type to only have a single field.
+
+# We will need a way in the client SDK to signal that the metrics are needed
+# and if they are needed, the client SDK has to return the full response type
+# without unwrapping it.
+
+
+@json_schema_type
+class MetricInResponse(BaseModel):
+    """A metric value included in API responses.
+    :param metric: The name of the metric
+    :param value: The numeric value of the metric
+    :param unit: (Optional) The unit of measurement for the metric value
+    """
+
+    metric: str
+    value: int | float
+    unit: str | None = None
+
+
+class MetricResponseMixin(BaseModel):
+    """Mixin class for API responses that can include metrics.
+    :param metrics: (Optional) List of metrics associated with the API response
+    """
+
+    metrics: list[MetricInResponse] | None = None

src/llama_stack_api/common/tracing.py

@@ -0,0 +1,22 @@
+# 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.
+
+
+def telemetry_traceable(cls):
+    """
+    Mark a protocol for automatic tracing when telemetry is enabled.
+
+    This is a metadata-only decorator with no dependencies on core.
+    Actual tracing is applied by core routers at runtime if telemetry is enabled.
+
+    Usage:
+        @runtime_checkable
+        @telemetry_traceable
+        class MyProtocol(Protocol):
+            ...
+    """
+    cls.__marked_for_tracing__ = True
+    return cls

src/llama_stack_api/common/training_types.py

@@ -0,0 +1,47 @@
+# 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 datetime import datetime
+
+from pydantic import BaseModel
+
+from llama_stack_api.schema_utils import json_schema_type
+
+
+@json_schema_type
+class PostTrainingMetric(BaseModel):
+    """Training metrics captured during post-training jobs.
+
+    :param epoch: Training epoch number
+    :param train_loss: Loss value on the training dataset
+    :param validation_loss: Loss value on the validation dataset
+    :param perplexity: Perplexity metric indicating model confidence
+    """
+
+    epoch: int
+    train_loss: float
+    validation_loss: float
+    perplexity: float
+
+
+@json_schema_type
+class Checkpoint(BaseModel):
+    """Checkpoint created during training runs.
+
+    :param identifier: Unique identifier for the checkpoint
+    :param created_at: Timestamp when the checkpoint was created
+    :param epoch: Training epoch when the checkpoint was saved
+    :param post_training_job_id: Identifier of the training job that created this checkpoint
+    :param path: File system path where the checkpoint is stored
+    :param training_metrics: (Optional) Training metrics associated with this checkpoint
+    """
+
+    identifier: str
+    created_at: datetime
+    epoch: int
+    post_training_job_id: str
+    path: str
+    training_metrics: PostTrainingMetric | None = None

src/llama_stack_api/common/type_system.py

@@ -0,0 +1,146 @@
+# 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, Literal
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.schema_utils import json_schema_type, register_schema
+
+
+@json_schema_type
+class StringType(BaseModel):
+    """Parameter type for string values.
+
+    :param type: Discriminator type. Always "string"
+    """
+
+    type: Literal["string"] = "string"
+
+
+@json_schema_type
+class NumberType(BaseModel):
+    """Parameter type for numeric values.
+
+    :param type: Discriminator type. Always "number"
+    """
+
+    type: Literal["number"] = "number"
+
+
+@json_schema_type
+class BooleanType(BaseModel):
+    """Parameter type for boolean values.
+
+    :param type: Discriminator type. Always "boolean"
+    """
+
+    type: Literal["boolean"] = "boolean"
+
+
+@json_schema_type
+class ArrayType(BaseModel):
+    """Parameter type for array values.
+
+    :param type: Discriminator type. Always "array"
+    """
+
+    type: Literal["array"] = "array"
+
+
+@json_schema_type
+class ObjectType(BaseModel):
+    """Parameter type for object values.
+
+    :param type: Discriminator type. Always "object"
+    """
+
+    type: Literal["object"] = "object"
+
+
+@json_schema_type
+class JsonType(BaseModel):
+    """Parameter type for JSON values.
+
+    :param type: Discriminator type. Always "json"
+    """
+
+    type: Literal["json"] = "json"
+
+
+@json_schema_type
+class UnionType(BaseModel):
+    """Parameter type for union values.
+
+    :param type: Discriminator type. Always "union"
+    """
+
+    type: Literal["union"] = "union"
+
+
+@json_schema_type
+class ChatCompletionInputType(BaseModel):
+    """Parameter type for chat completion input.
+
+    :param type: Discriminator type. Always "chat_completion_input"
+    """
+
+    # expects List[Message] for messages
+    type: Literal["chat_completion_input"] = "chat_completion_input"
+
+
+@json_schema_type
+class CompletionInputType(BaseModel):
+    """Parameter type for completion input.
+
+    :param type: Discriminator type. Always "completion_input"
+    """
+
+    # expects InterleavedTextMedia for content
+    type: Literal["completion_input"] = "completion_input"
+
+
+@json_schema_type
+class DialogType(BaseModel):
+    """Parameter type for dialog data with semantic output labels.
+
+    :param type: Discriminator type. Always "dialog"
+    """
+
+    # expects List[Message] for messages
+    # this type semantically contains the output label whereas ChatCompletionInputType does not
+    type: Literal["dialog"] = "dialog"
+
+
+ParamType = Annotated[
+    StringType
+    | NumberType
+    | BooleanType
+    | ArrayType
+    | ObjectType
+    | JsonType
+    | UnionType
+    | ChatCompletionInputType
+    | CompletionInputType,
+    Field(discriminator="type"),
+]
+register_schema(ParamType, name="ParamType")
+
+"""
+# TODO: recursive definition of ParamType in these containers
+# will cause infinite recursion in OpenAPI generation script
+# since we are going with ChatCompletionInputType and CompletionInputType
+# we don't need to worry about ArrayType/ObjectType/UnionType for now
+ArrayType.model_rebuild()
+ObjectType.model_rebuild()
+UnionType.model_rebuild()
+
+
+class CustomType(BaseModel):
+pylint: disable=syntax-error
+    type: Literal["custom"] = "custom"
+    validator_class: str
+"""

src/llama_stack_api/conversations.py

@@ -0,0 +1,272 @@
+# 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.common.tracing import telemetry_traceable
+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
+@telemetry_traceable
+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.
+        """
+        ...

src/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.
+        """
+        ...

src/llama_stack_api/datasets.py

@@ -0,0 +1,247 @@
+# 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 Enum, StrEnum
+from typing import Annotated, Any, Literal, Protocol
+
+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, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1BETA
+
+
+class DatasetPurpose(StrEnum):
+    """
+    Purpose of the dataset. Each purpose has a required input data schema.
+
+    :cvar post-training/messages: The dataset contains messages used for post-training.
+        {
+            "messages": [
+                {"role": "user", "content": "Hello, world!"},
+                {"role": "assistant", "content": "Hello, world!"},
+            ]
+        }
+    :cvar eval/question-answer: The dataset contains a question column and an answer column.
+        {
+            "question": "What is the capital of France?",
+            "answer": "Paris"
+        }
+    :cvar eval/messages-answer: The dataset contains a messages column with list of messages and an answer column.
+        {
+            "messages": [
+                {"role": "user", "content": "Hello, my name is John Doe."},
+                {"role": "assistant", "content": "Hello, John Doe. How can I help you today?"},
+                {"role": "user", "content": "What's my name?"},
+            ],
+            "answer": "John Doe"
+        }
+    """
+
+    post_training_messages = "post-training/messages"
+    eval_question_answer = "eval/question-answer"
+    eval_messages_answer = "eval/messages-answer"
+
+    # TODO: add more schemas here
+
+
+class DatasetType(Enum):
+    """
+    Type of the dataset source.
+    :cvar uri: The dataset can be obtained from a URI.
+    :cvar rows: The dataset is stored in rows.
+    """
+
+    uri = "uri"
+    rows = "rows"
+
+
+@json_schema_type
+class URIDataSource(BaseModel):
+    """A dataset that can be obtained from a URI.
+    :param uri: The dataset can be obtained from a URI. E.g.
+        - "https://mywebsite.com/mydata.jsonl"
+        - "lsfs://mydata.jsonl"
+        - "data:csv;base64,{base64_content}"
+    """
+
+    type: Literal["uri"] = "uri"
+    uri: str
+
+
+@json_schema_type
+class RowsDataSource(BaseModel):
+    """A dataset stored in rows.
+    :param rows: The dataset is stored in rows. E.g.
+        - [
+            {"messages": [{"role": "user", "content": "Hello, world!"}, {"role": "assistant", "content": "Hello, world!"}]}
+        ]
+    """
+
+    type: Literal["rows"] = "rows"
+    rows: list[dict[str, Any]]
+
+
+DataSource = Annotated[
+    URIDataSource | RowsDataSource,
+    Field(discriminator="type"),
+]
+register_schema(DataSource, name="DataSource")
+
+
+class CommonDatasetFields(BaseModel):
+    """
+    Common fields for a dataset.
+
+    :param purpose: Purpose of the dataset indicating its intended use
+    :param source: Data source configuration for the dataset
+    :param metadata: Additional metadata for the dataset
+    """
+
+    purpose: DatasetPurpose
+    source: DataSource
+    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.
+
+    :param type: Type of resource, always 'dataset' for datasets
+    """
+
+    type: Literal[ResourceType.dataset] = ResourceType.dataset
+
+    @property
+    def dataset_id(self) -> str:
+        return self.identifier
+
+    @property
+    def provider_dataset_id(self) -> str | None:
+        return self.provider_resource_id
+
+
+class DatasetInput(CommonDatasetFields, BaseModel):
+    """Input parameters for dataset operations.
+
+    :param dataset_id: Unique identifier for the dataset
+    """
+
+    dataset_id: str
+
+
+class ListDatasetsResponse(BaseModel):
+    """Response from listing datasets.
+
+    :param data: List of datasets
+    """
+
+    data: list[Dataset]
+
+
+class Datasets(Protocol):
+    @webmethod(route="/datasets", method="POST", level=LLAMA_STACK_API_V1BETA, deprecated=True)
+    async def register_dataset(
+        self,
+        purpose: DatasetPurpose,
+        source: DataSource,
+        metadata: dict[str, Any] | None = None,
+        dataset_id: str | None = None,
+    ) -> Dataset:
+        """
+        Register a new dataset.
+
+        :param purpose: The purpose of the dataset.
+        One of:
+            - "post-training/messages": The dataset contains a messages column with list of messages for post-training.
+                {
+                    "messages": [
+                        {"role": "user", "content": "Hello, world!"},
+                        {"role": "assistant", "content": "Hello, world!"},
+                    ]
+                }
+            - "eval/question-answer": The dataset contains a question column and an answer column for evaluation.
+                {
+                    "question": "What is the capital of France?",
+                    "answer": "Paris"
+                }
+            - "eval/messages-answer": The dataset contains a messages column with list of messages and an answer column for evaluation.
+                {
+                    "messages": [
+                        {"role": "user", "content": "Hello, my name is John Doe."},
+                        {"role": "assistant", "content": "Hello, John Doe. How can I help you today?"},
+                        {"role": "user", "content": "What's my name?"},
+                    ],
+                    "answer": "John Doe"
+                }
+        :param source: The data source of the dataset. Ensure that the data source schema is compatible with the purpose of the dataset. Examples:
+           - {
+               "type": "uri",
+               "uri": "https://mywebsite.com/mydata.jsonl"
+           }
+           - {
+               "type": "uri",
+               "uri": "lsfs://mydata.jsonl"
+           }
+           - {
+               "type": "uri",
+               "uri": "data:csv;base64,{base64_content}"
+           }
+           - {
+               "type": "uri",
+               "uri": "huggingface://llamastack/simpleqa?split=train"
+           }
+           - {
+               "type": "rows",
+               "rows": [
+                   {
+                       "messages": [
+                           {"role": "user", "content": "Hello, world!"},
+                           {"role": "assistant", "content": "Hello, world!"},
+                       ]
+                   }
+               ]
+           }
+        :param metadata: The metadata for the dataset.
+           - E.g. {"description": "My dataset"}.
+        :param dataset_id: The ID of the dataset. If not provided, an ID will be generated.
+        :returns: A Dataset.
+        """
+        ...
+
+    @webmethod(route="/datasets/{dataset_id:path}", method="GET", level=LLAMA_STACK_API_V1BETA)
+    async def get_dataset(
+        self,
+        dataset_id: str,
+    ) -> Dataset:
+        """Get a dataset by its ID.
+
+        :param dataset_id: The ID of the dataset to get.
+        :returns: A Dataset.
+        """
+        ...
+
+    @webmethod(route="/datasets", method="GET", level=LLAMA_STACK_API_V1BETA)
+    async def list_datasets(self) -> ListDatasetsResponse:
+        """List all datasets.
+
+        :returns: A ListDatasetsResponse.
+        """
+        ...
+
+    @webmethod(route="/datasets/{dataset_id:path}", method="DELETE", level=LLAMA_STACK_API_V1BETA, deprecated=True)
+    async def unregister_dataset(
+        self,
+        dataset_id: str,
+    ) -> None:
+        """Unregister a dataset by its ID.
+
+        :param dataset_id: The ID of the dataset to unregister.
+        """
+        ...

src/llama_stack_api/datatypes.py

@@ -0,0 +1,368 @@
+# 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 Enum, EnumMeta, StrEnum
+from typing import Any, Protocol
+from urllib.parse import urlparse
+
+from pydantic import BaseModel, Field
+
+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 prompts: Prompt versions and management
+    :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"
+    prompts = "prompts"
+    conversations = "conversations"
+
+    # built-in API
+    inspect = "inspect"
+
+
+@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):
+    """
+    Protocol for model management.
+
+    This allows users to register their preferred model identifiers.
+
+    Model registration requires -
+     - a provider, used to route the registration request
+     - a model identifier, user's intended name for the model during inference
+     - a provider model identifier, a model identifier supported by the provider
+
+    Providers will only accept registration for provider model ids they support.
+
+    Example,
+      register: provider x my-model-id x provider-model-id
+       -> Error if provider does not support provider-model-id
+       -> Error if my-model-id is already registered
+       -> Success if provider supports provider-model-id
+      inference: my-model-id x ...
+       -> Provider uses provider-model-id for inference
+    """
+
+    # this should be called `on_model_register` or something like that.
+    # the provider should _not_ be able to change the object in this
+    # callback
+    async def register_model(self, model: Model) -> Model: ...
+
+    async def unregister_model(self, model_id: str) -> None: ...
+
+    # the Stack router will query each provider for their list of models
+    # if a `refresh_interval_seconds` is provided, this method will be called
+    # periodically to refresh the list of models
+    #
+    # NOTE: each model returned will be registered with the model registry. this means
+    # a callback to the `register_model()` method will be made. this is duplicative and
+    # may be removed in the future.
+    async def list_models(self) -> list[Model] | None: ...
+
+    async def should_refresh_models(self) -> bool: ...
+
+
+class ShieldsProtocolPrivate(Protocol):
+    async def register_shield(self, shield: Shield) -> None: ...
+
+    async def unregister_shield(self, identifier: str) -> None: ...
+
+
+class VectorStoresProtocolPrivate(Protocol):
+    async def register_vector_store(self, vector_store: VectorStore) -> None: ...
+
+    async def unregister_vector_store(self, vector_store_id: str) -> None: ...
+
+
+class DatasetsProtocolPrivate(Protocol):
+    async def register_dataset(self, dataset: Dataset) -> None: ...
+
+    async def unregister_dataset(self, dataset_id: str) -> None: ...
+
+
+class ScoringFunctionsProtocolPrivate(Protocol):
+    async def list_scoring_functions(self) -> list[ScoringFn]: ...
+
+    async def register_scoring_function(self, scoring_fn: ScoringFn) -> None: ...
+
+
+class BenchmarksProtocolPrivate(Protocol):
+    async def register_benchmark(self, benchmark: Benchmark) -> None: ...
+
+
+class ToolGroupsProtocolPrivate(Protocol):
+    async def register_toolgroup(self, toolgroup: ToolGroup) -> None: ...
+
+    async def unregister_toolgroup(self, toolgroup_id: str) -> None: ...
+
+
+@json_schema_type
+class ProviderSpec(BaseModel):
+    api: Api
+    provider_type: str
+    config_class: str = Field(
+        ...,
+        description="Fully-qualified classname of the config for this provider",
+    )
+    api_dependencies: list[Api] = Field(
+        default_factory=list,
+        description="Higher-level API surfaces may depend on other providers to provide their functionality",
+    )
+    optional_api_dependencies: list[Api] = Field(
+        default_factory=list,
+    )
+    deprecation_warning: str | None = Field(
+        default=None,
+        description="If this provider is deprecated, specify the warning message here",
+    )
+    deprecation_error: str | None = Field(
+        default=None,
+        description="If this provider is deprecated and does NOT work, specify the error message here",
+    )
+
+    module: str | None = Field(
+        default=None,
+        description="""
+ Fully-qualified name of the module to import. The module is expected to have:
+
+  - `get_adapter_impl(config, deps)`: returns the adapter implementation
+
+  Example: `module: ramalama_stack`
+ """,
+    )
+
+    pip_packages: list[str] = Field(
+        default_factory=list,
+        description="The pip dependencies needed for this implementation",
+    )
+
+    provider_data_validator: str | None = Field(
+        default=None,
+    )
+
+    is_external: bool = Field(default=False, description="Notes whether this provider is an external provider.")
+
+    # used internally by the resolver; this is a hack for now
+    deps__: list[str] = Field(default_factory=list)
+
+    @property
+    def is_sample(self) -> bool:
+        return self.provider_type in ("sample", "remote::sample")
+
+
+class RoutingTable(Protocol):
+    async def get_provider_impl(self, routing_key: str) -> Any: ...
+
+
+@json_schema_type
+class InlineProviderSpec(ProviderSpec):
+    container_image: str | None = Field(
+        default=None,
+        description="""
+The container image to use for this implementation. If one is provided, pip_packages will be ignored.
+If a provider depends on other providers, the dependencies MUST NOT specify a container image.
+""",
+    )
+    description: str | None = Field(
+        default=None,
+        description="""
+A description of the provider. This is used to display in the documentation.
+""",
+    )
+
+
+class RemoteProviderConfig(BaseModel):
+    host: str = "localhost"
+    port: int | None = None
+    protocol: str = "http"
+
+    @property
+    def url(self) -> str:
+        if self.port is None:
+            return f"{self.protocol}://{self.host}"
+        return f"{self.protocol}://{self.host}:{self.port}"
+
+    @classmethod
+    def from_url(cls, url: str) -> "RemoteProviderConfig":
+        parsed = urlparse(url)
+        attrs = {k: v for k, v in parsed._asdict().items() if v is not None}
+        return cls(**attrs)
+
+
+@json_schema_type
+class RemoteProviderSpec(ProviderSpec):
+    adapter_type: str = Field(
+        ...,
+        description="Unique identifier for this adapter",
+    )
+
+    description: str | None = Field(
+        default=None,
+        description="""
+A description of the provider. This is used to display in the documentation.
+""",
+    )
+
+    @property
+    def container_image(self) -> str | None:
+        return None
+
+
+class HealthStatus(StrEnum):
+    OK = "OK"
+    ERROR = "Error"
+    NOT_IMPLEMENTED = "Not Implemented"
+
+
+HealthResponse = dict[str, Any]

src/llama_stack_api/eval.py

@@ -0,0 +1,137 @@
+# 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, Literal, Protocol
+
+from pydantic import BaseModel, Field
+
+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
+class ModelCandidate(BaseModel):
+    """A model candidate for evaluation.
+
+    :param model: The model ID to evaluate.
+    :param sampling_params: The sampling parameters for the model.
+    :param system_message: (Optional) The system message providing instructions or context to the model.
+    """
+
+    type: Literal["model"] = "model"
+    model: str
+    sampling_params: SamplingParams
+    system_message: SystemMessage | None = None
+
+
+EvalCandidate = ModelCandidate
+
+
+@json_schema_type
+class BenchmarkConfig(BaseModel):
+    """A benchmark configuration for evaluation.
+
+    :param eval_candidate: The candidate to evaluate.
+    :param scoring_params: Map between scoring function id and parameters for each scoring function you want to run
+    :param num_examples: (Optional) The number of examples to evaluate. If not provided, all examples in the dataset will be evaluated
+    """
+
+    eval_candidate: EvalCandidate
+    scoring_params: dict[str, ScoringFnParams] = Field(
+        description="Map between scoring function id and parameters for each scoring function you want to run",
+        default_factory=dict,
+    )
+    num_examples: int | None = Field(
+        description="Number of examples to evaluate (useful for testing), if not provided, all examples in the dataset will be evaluated",
+        default=None,
+    )
+    # we could optinally add any specific dataset config here
+
+
+@json_schema_type
+class EvaluateResponse(BaseModel):
+    """The response from an evaluation.
+
+    :param generations: The generations from the evaluation.
+    :param scores: The scores from the evaluation.
+    """
+
+    generations: list[dict[str, Any]]
+    # each key in the dict is a scoring function name
+    scores: dict[str, ScoringResult]
+
+
+class Eval(Protocol):
+    """Evaluations
+
+    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_V1ALPHA)
+    async def run_eval(
+        self,
+        benchmark_id: str,
+        benchmark_config: BenchmarkConfig,
+    ) -> Job:
+        """Run an evaluation on a benchmark.
+
+        :param benchmark_id: The ID of the benchmark to run the evaluation on.
+        :param benchmark_config: The configuration for the benchmark.
+        :returns: The job that was created to run the evaluation.
+        """
+        ...
+
+    @webmethod(route="/eval/benchmarks/{benchmark_id}/evaluations", method="POST", level=LLAMA_STACK_API_V1ALPHA)
+    async def evaluate_rows(
+        self,
+        benchmark_id: str,
+        input_rows: list[dict[str, Any]],
+        scoring_functions: list[str],
+        benchmark_config: BenchmarkConfig,
+    ) -> EvaluateResponse:
+        """Evaluate a list of rows on a benchmark.
+
+        :param benchmark_id: The ID of the benchmark to run the evaluation on.
+        :param input_rows: The rows to evaluate.
+        :param scoring_functions: The scoring functions to use for the evaluation.
+        :param benchmark_config: The configuration for the benchmark.
+        :returns: EvaluateResponse object containing generations and scores.
+        """
+        ...
+
+    @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.
+
+        :param benchmark_id: The ID of the benchmark to run the evaluation on.
+        :param job_id: The ID of the job to get the status of.
+        :returns: The status of the evaluation job.
+        """
+        ...
+
+    @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.
+
+        :param benchmark_id: The ID of the benchmark to run the evaluation on.
+        :param job_id: The ID of the job to cancel.
+        """
+        ...
+
+    @webmethod(
+        route="/eval/benchmarks/{benchmark_id}/jobs/{job_id}/result", method="GET", level=LLAMA_STACK_API_V1ALPHA
+    )
+    async def job_result(self, benchmark_id: str, job_id: str) -> EvaluateResponse:
+        """Get the result of a job.
+
+        :param benchmark_id: The ID of the benchmark to run the evaluation on.
+        :param job_id: The ID of the job to get the result of.
+        :returns: The result of the job.
+        """
+        ...

src/llama_stack_api/files.py

@@ -0,0 +1,194 @@
+# 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, ClassVar, Literal, Protocol, runtime_checkable
+
+from fastapi import File, Form, Response, UploadFile
+from pydantic import BaseModel, Field
+
+from llama_stack_api.common.responses import Order
+from llama_stack_api.common.tracing import telemetry_traceable
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+
+# OpenAI Files API Models
+class OpenAIFilePurpose(StrEnum):
+    """
+    Valid purpose values for OpenAI Files API.
+    """
+
+    ASSISTANTS = "assistants"
+    BATCH = "batch"
+    # TODO: Add other purposes as needed
+
+
+@json_schema_type
+class OpenAIFileObject(BaseModel):
+    """
+    OpenAI File object as defined in the OpenAI Files API.
+
+    :param object: The object type, which is always "file"
+    :param id: The file identifier, which can be referenced in the API endpoints
+    :param bytes: The size of the file, in bytes
+    :param created_at: The Unix timestamp (in seconds) for when the file was created
+    :param expires_at: The Unix timestamp (in seconds) for when the file expires
+    :param filename: The name of the file
+    :param purpose: The intended purpose of the file
+    """
+
+    object: Literal["file"] = "file"
+    id: str
+    bytes: int
+    created_at: int
+    expires_at: int
+    filename: str
+    purpose: OpenAIFilePurpose
+
+
+@json_schema_type
+class ExpiresAfter(BaseModel):
+    """
+    Control expiration of uploaded files.
+
+    Params:
+     - anchor, must be "created_at"
+     - seconds, must be int between 3600 and 2592000 (1 hour to 30 days)
+    """
+
+    MIN: ClassVar[int] = 3600  # 1 hour
+    MAX: ClassVar[int] = 2592000  # 30 days
+
+    anchor: Literal["created_at"]
+    seconds: int = Field(..., ge=3600, le=2592000)
+
+
+@json_schema_type
+class ListOpenAIFileResponse(BaseModel):
+    """
+    Response for listing files in OpenAI Files API.
+
+    :param data: List of file objects
+    :param has_more: Whether there are more files available beyond this page
+    :param first_id: ID of the first file in the list for pagination
+    :param last_id: ID of the last file in the list for pagination
+    :param object: The object type, which is always "list"
+    """
+
+    data: list[OpenAIFileObject]
+    has_more: bool
+    first_id: str
+    last_id: str
+    object: Literal["list"] = "list"
+
+
+@json_schema_type
+class OpenAIFileDeleteResponse(BaseModel):
+    """
+    Response for deleting a file in OpenAI Files API.
+
+    :param id: The file identifier that was deleted
+    :param object: The object type, which is always "file"
+    :param deleted: Whether the file was successfully deleted
+    """
+
+    id: str
+    object: Literal["file"] = "file"
+    deleted: bool
+
+
+@runtime_checkable
+@telemetry_traceable
+class Files(Protocol):
+    """Files
+
+    This API is used to upload documents that can be used with other Llama Stack APIs.
+    """
+
+    # OpenAI Files API Endpoints
+    @webmethod(route="/files", method="POST", level=LLAMA_STACK_API_V1)
+    async def openai_upload_file(
+        self,
+        file: Annotated[UploadFile, File()],
+        purpose: Annotated[OpenAIFilePurpose, Form()],
+        expires_after: Annotated[ExpiresAfter | None, Form()] = None,
+    ) -> OpenAIFileObject:
+        """Upload file.
+
+        Upload a file that can be used across various endpoints.
+
+        The file upload should be a multipart form request with:
+        - file: The File object (not file name) to be uploaded.
+        - purpose: The intended purpose of the uploaded file.
+        - expires_after: Optional form values describing expiration for the file.
+
+        :param file: The uploaded file object containing content and metadata (filename, content_type, etc.).
+        :param purpose: The intended purpose of the uploaded file (e.g., "assistants", "fine-tune").
+        :param expires_after: Optional form values describing expiration for the file.
+        :returns: An OpenAIFileObject representing the uploaded file.
+        """
+        ...
+
+    @webmethod(route="/files", method="GET", level=LLAMA_STACK_API_V1)
+    async def openai_list_files(
+        self,
+        after: str | None = None,
+        limit: int | None = 10000,
+        order: Order | None = Order.desc,
+        purpose: OpenAIFilePurpose | None = None,
+    ) -> ListOpenAIFileResponse:
+        """List files.
+
+        Returns a list of files that belong to the user's organization.
+
+        :param after: A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
+        :param limit: A limit on the number of objects to be returned. Limit can range between 1 and 10,000, and the default is 10,000.
+        :param order: Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
+        :param purpose: Only return files with the given purpose.
+        :returns: An ListOpenAIFileResponse containing the list of files.
+        """
+        ...
+
+    @webmethod(route="/files/{file_id}", method="GET", level=LLAMA_STACK_API_V1)
+    async def openai_retrieve_file(
+        self,
+        file_id: str,
+    ) -> OpenAIFileObject:
+        """Retrieve file.
+
+        Returns information about a specific file.
+
+        :param file_id: The ID of the file to use for this request.
+        :returns: An OpenAIFileObject containing file information.
+        """
+        ...
+
+    @webmethod(route="/files/{file_id}", method="DELETE", level=LLAMA_STACK_API_V1)
+    async def openai_delete_file(
+        self,
+        file_id: str,
+    ) -> OpenAIFileDeleteResponse:
+        """Delete file.
+
+        :param file_id: The ID of the file to use for this request.
+        :returns: An OpenAIFileDeleteResponse indicating successful deletion.
+        """
+        ...
+
+    @webmethod(route="/files/{file_id}/content", method="GET", level=LLAMA_STACK_API_V1)
+    async def openai_retrieve_file_content(
+        self,
+        file_id: str,
+    ) -> Response:
+        """Retrieve file content.
+
+        Returns the contents of the specified file.
+
+        :param file_id: The ID of the file to use for this request.
+        :returns: The raw file content as a binary response.
+        """
+        ...

src/llama_stack_api/inspect.py

@@ -0,0 +1,102 @@
+# 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 Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from llama_stack_api.datatypes import HealthStatus
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.version import (
+    LLAMA_STACK_API_V1,
+)
+
+# Valid values for the route filter parameter.
+# Actual API levels: v1, v1alpha, v1beta (filters by level, excludes deprecated)
+# Special filter value: "deprecated" (shows deprecated routes regardless of level)
+ApiFilter = Literal["v1", "v1alpha", "v1beta", "deprecated"]
+
+
+@json_schema_type
+class RouteInfo(BaseModel):
+    """Information about an API route including its path, method, and implementing providers.
+
+    :param route: The API endpoint path
+    :param method: HTTP method for the route
+    :param provider_types: List of provider types that implement this route
+    """
+
+    route: str
+    method: str
+    provider_types: list[str]
+
+
+@json_schema_type
+class HealthInfo(BaseModel):
+    """Health status information for the service.
+
+    :param status: Current health status of the service
+    """
+
+    status: HealthStatus
+
+
+@json_schema_type
+class VersionInfo(BaseModel):
+    """Version information for the service.
+
+    :param version: Version number of the service
+    """
+
+    version: str
+
+
+class ListRoutesResponse(BaseModel):
+    """Response containing a list of all available API routes.
+
+    :param data: List of available route information objects
+    """
+
+    data: list[RouteInfo]
+
+
+@runtime_checkable
+class Inspect(Protocol):
+    """Inspect
+
+    APIs for inspecting the Llama Stack service, including health status, available API routes with methods and implementing providers.
+    """
+
+    @webmethod(route="/inspect/routes", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_routes(self, api_filter: ApiFilter | None = None) -> ListRoutesResponse:
+        """List routes.
+
+        List all available API routes with their methods and implementing providers.
+
+        :param api_filter: Optional filter to control which routes are returned. Can be an API level ('v1', 'v1alpha', 'v1beta') to show non-deprecated routes at that level, or 'deprecated' to show deprecated routes across all levels. If not specified, returns all non-deprecated routes.
+        :returns: Response containing information about all available routes.
+        """
+        ...
+
+    @webmethod(route="/health", method="GET", level=LLAMA_STACK_API_V1, require_authentication=False)
+    async def health(self) -> HealthInfo:
+        """Get health status.
+
+        Get the current health status of the service.
+
+        :returns: Health information indicating if the service is operational.
+        """
+        ...
+
+    @webmethod(route="/version", method="GET", level=LLAMA_STACK_API_V1, require_authentication=False)
+    async def version(self) -> VersionInfo:
+        """Get version.
+
+        Get the version of the service.
+
+        :returns: Version information containing the service version number.
+        """
+        ...

src/llama_stack_api/models.py

@@ -0,0 +1,172 @@
+# 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 Any, Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from llama_stack_api.common.tracing import telemetry_traceable
+from llama_stack_api.resource import Resource, ResourceType
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+
+class CommonModelFields(BaseModel):
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Any additional metadata for this model",
+    )
+
+
+@json_schema_type
+class ModelType(StrEnum):
+    """Enumeration of supported model types in Llama Stack.
+    :cvar llm: Large language model for text generation and completion
+    :cvar embedding: Embedding model for converting text to vector representations
+    :cvar rerank: Reranking model for reordering documents based on their relevance to a query
+    """
+
+    llm = "llm"
+    embedding = "embedding"
+    rerank = "rerank"
+
+
+@json_schema_type
+class Model(CommonModelFields, Resource):
+    """A model resource representing an AI model registered in Llama Stack.
+
+    :param type: The resource type, always 'model' for model resources
+    :param model_type: The type of model (LLM or embedding model)
+    :param metadata: Any additional metadata for this model
+    :param identifier: Unique identifier for this resource in llama stack
+    :param provider_resource_id: Unique identifier for this resource in the provider
+    :param provider_id: ID of the provider that owns this resource
+    """
+
+    type: Literal[ResourceType.model] = ResourceType.model
+
+    @property
+    def model_id(self) -> str:
+        return self.identifier
+
+    @property
+    def provider_model_id(self) -> str:
+        assert self.provider_resource_id is not None, "Provider resource ID must be set"
+        return self.provider_resource_id
+
+    model_config = ConfigDict(protected_namespaces=())
+
+    model_type: ModelType = Field(default=ModelType.llm)
+
+    @field_validator("provider_resource_id")
+    @classmethod
+    def validate_provider_resource_id(cls, v):
+        if v is None:
+            raise ValueError("provider_resource_id cannot be None")
+        return v
+
+
+class ModelInput(CommonModelFields):
+    model_id: str
+    provider_id: str | None = None
+    provider_model_id: str | None = None
+    model_type: ModelType | None = ModelType.llm
+    model_config = ConfigDict(protected_namespaces=())
+
+
+class ListModelsResponse(BaseModel):
+    data: list[Model]
+
+
+@json_schema_type
+class OpenAIModel(BaseModel):
+    """A model from OpenAI.
+
+    :id: The ID of the model
+    :object: The object type, which will be "model"
+    :created: The Unix timestamp in seconds when the model was created
+    :owned_by: The owner of the model
+    :custom_metadata: Llama Stack-specific metadata including model_type, provider info, and additional metadata
+    """
+
+    id: str
+    object: Literal["model"] = "model"
+    created: int
+    owned_by: str
+    custom_metadata: dict[str, Any] | None = None
+
+
+class OpenAIListModelsResponse(BaseModel):
+    data: list[OpenAIModel]
+
+
+@runtime_checkable
+@telemetry_traceable
+class Models(Protocol):
+    async def list_models(self) -> ListModelsResponse:
+        """List all models.
+
+        :returns: A ListModelsResponse.
+        """
+        ...
+
+    @webmethod(route="/models", method="GET", level=LLAMA_STACK_API_V1)
+    async def openai_list_models(self) -> OpenAIListModelsResponse:
+        """List models using the OpenAI API.
+
+        :returns: A OpenAIListModelsResponse.
+        """
+        ...
+
+    @webmethod(route="/models/{model_id:path}", method="GET", level=LLAMA_STACK_API_V1)
+    async def get_model(
+        self,
+        model_id: str,
+    ) -> Model:
+        """Get model.
+
+        Get a model by its identifier.
+
+        :param model_id: The identifier of the model to get.
+        :returns: A Model.
+        """
+        ...
+
+    @webmethod(route="/models", method="POST", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def register_model(
+        self,
+        model_id: str,
+        provider_model_id: str | None = None,
+        provider_id: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        model_type: ModelType | None = None,
+    ) -> Model:
+        """Register model.
+
+        Register a model.
+
+        :param model_id: The identifier of the model to register.
+        :param provider_model_id: The identifier of the model in the provider.
+        :param provider_id: The identifier of the provider.
+        :param metadata: Any additional metadata for this model.
+        :param model_type: The type of model to register.
+        :returns: A Model.
+        """
+        ...
+
+    @webmethod(route="/models/{model_id:path}", method="DELETE", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def unregister_model(
+        self,
+        model_id: str,
+    ) -> None:
+        """Unregister model.
+
+        Unregister a model.
+
+        :param model_id: The identifier of the model to unregister.
+        """
+        ...

src/llama_stack_api/post_training.py

@@ -0,0 +1,368 @@
+# 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 datetime import datetime
+from enum import Enum
+from typing import Annotated, Any, Literal, Protocol
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.common.content_types import URL
+from llama_stack_api.common.job_types import JobStatus
+from llama_stack_api.common.training_types import Checkpoint
+from llama_stack_api.schema_utils import json_schema_type, register_schema, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1ALPHA
+
+
+@json_schema_type
+class OptimizerType(Enum):
+    """Available optimizer algorithms for training.
+    :cvar adam: Adaptive Moment Estimation optimizer
+    :cvar adamw: AdamW optimizer with weight decay
+    :cvar sgd: Stochastic Gradient Descent optimizer
+    """
+
+    adam = "adam"
+    adamw = "adamw"
+    sgd = "sgd"
+
+
+@json_schema_type
+class DatasetFormat(Enum):
+    """Format of the training dataset.
+    :cvar instruct: Instruction-following format with prompt and completion
+    :cvar dialog: Multi-turn conversation format with messages
+    """
+
+    instruct = "instruct"
+    dialog = "dialog"
+
+
+@json_schema_type
+class DataConfig(BaseModel):
+    """Configuration for training data and data loading.
+
+    :param dataset_id: Unique identifier for the training dataset
+    :param batch_size: Number of samples per training batch
+    :param shuffle: Whether to shuffle the dataset during training
+    :param data_format: Format of the dataset (instruct or dialog)
+    :param validation_dataset_id: (Optional) Unique identifier for the validation dataset
+    :param packed: (Optional) Whether to pack multiple samples into a single sequence for efficiency
+    :param train_on_input: (Optional) Whether to compute loss on input tokens as well as output tokens
+    """
+
+    dataset_id: str
+    batch_size: int
+    shuffle: bool
+    data_format: DatasetFormat
+    validation_dataset_id: str | None = None
+    packed: bool | None = False
+    train_on_input: bool | None = False
+
+
+@json_schema_type
+class OptimizerConfig(BaseModel):
+    """Configuration parameters for the optimization algorithm.
+
+    :param optimizer_type: Type of optimizer to use (adam, adamw, or sgd)
+    :param lr: Learning rate for the optimizer
+    :param weight_decay: Weight decay coefficient for regularization
+    :param num_warmup_steps: Number of steps for learning rate warmup
+    """
+
+    optimizer_type: OptimizerType
+    lr: float
+    weight_decay: float
+    num_warmup_steps: int
+
+
+@json_schema_type
+class EfficiencyConfig(BaseModel):
+    """Configuration for memory and compute efficiency optimizations.
+
+    :param enable_activation_checkpointing: (Optional) Whether to use activation checkpointing to reduce memory usage
+    :param enable_activation_offloading: (Optional) Whether to offload activations to CPU to save GPU memory
+    :param memory_efficient_fsdp_wrap: (Optional) Whether to use memory-efficient FSDP wrapping
+    :param fsdp_cpu_offload: (Optional) Whether to offload FSDP parameters to CPU
+    """
+
+    enable_activation_checkpointing: bool | None = False
+    enable_activation_offloading: bool | None = False
+    memory_efficient_fsdp_wrap: bool | None = False
+    fsdp_cpu_offload: bool | None = False
+
+
+@json_schema_type
+class TrainingConfig(BaseModel):
+    """Comprehensive configuration for the training process.
+
+    :param n_epochs: Number of training epochs to run
+    :param max_steps_per_epoch: Maximum number of steps to run per epoch
+    :param gradient_accumulation_steps: Number of steps to accumulate gradients before updating
+    :param max_validation_steps: (Optional) Maximum number of validation steps per epoch
+    :param data_config: (Optional) Configuration for data loading and formatting
+    :param optimizer_config: (Optional) Configuration for the optimization algorithm
+    :param efficiency_config: (Optional) Configuration for memory and compute optimizations
+    :param dtype: (Optional) Data type for model parameters (bf16, fp16, fp32)
+    """
+
+    n_epochs: int
+    max_steps_per_epoch: int = 1
+    gradient_accumulation_steps: int = 1
+    max_validation_steps: int | None = 1
+    data_config: DataConfig | None = None
+    optimizer_config: OptimizerConfig | None = None
+    efficiency_config: EfficiencyConfig | None = None
+    dtype: str | None = "bf16"
+
+
+@json_schema_type
+class LoraFinetuningConfig(BaseModel):
+    """Configuration for Low-Rank Adaptation (LoRA) fine-tuning.
+
+    :param type: Algorithm type identifier, always "LoRA"
+    :param lora_attn_modules: List of attention module names to apply LoRA to
+    :param apply_lora_to_mlp: Whether to apply LoRA to MLP layers
+    :param apply_lora_to_output: Whether to apply LoRA to output projection layers
+    :param rank: Rank of the LoRA adaptation (lower rank = fewer parameters)
+    :param alpha: LoRA scaling parameter that controls adaptation strength
+    :param use_dora: (Optional) Whether to use DoRA (Weight-Decomposed Low-Rank Adaptation)
+    :param quantize_base: (Optional) Whether to quantize the base model weights
+    """
+
+    type: Literal["LoRA"] = "LoRA"
+    lora_attn_modules: list[str]
+    apply_lora_to_mlp: bool
+    apply_lora_to_output: bool
+    rank: int
+    alpha: int
+    use_dora: bool | None = False
+    quantize_base: bool | None = False
+
+
+@json_schema_type
+class QATFinetuningConfig(BaseModel):
+    """Configuration for Quantization-Aware Training (QAT) fine-tuning.
+
+    :param type: Algorithm type identifier, always "QAT"
+    :param quantizer_name: Name of the quantization algorithm to use
+    :param group_size: Size of groups for grouped quantization
+    """
+
+    type: Literal["QAT"] = "QAT"
+    quantizer_name: str
+    group_size: int
+
+
+AlgorithmConfig = Annotated[LoraFinetuningConfig | QATFinetuningConfig, Field(discriminator="type")]
+register_schema(AlgorithmConfig, name="AlgorithmConfig")
+
+
+@json_schema_type
+class PostTrainingJobLogStream(BaseModel):
+    """Stream of logs from a finetuning job.
+
+    :param job_uuid: Unique identifier for the training job
+    :param log_lines: List of log message strings from the training process
+    """
+
+    job_uuid: str
+    log_lines: list[str]
+
+
+@json_schema_type
+class RLHFAlgorithm(Enum):
+    """Available reinforcement learning from human feedback algorithms.
+    :cvar dpo: Direct Preference Optimization algorithm
+    """
+
+    dpo = "dpo"
+
+
+@json_schema_type
+class DPOLossType(Enum):
+    sigmoid = "sigmoid"
+    hinge = "hinge"
+    ipo = "ipo"
+    kto_pair = "kto_pair"
+
+
+@json_schema_type
+class DPOAlignmentConfig(BaseModel):
+    """Configuration for Direct Preference Optimization (DPO) alignment.
+
+    :param beta: Temperature parameter for the DPO loss
+    :param loss_type: The type of loss function to use for DPO
+    """
+
+    beta: float
+    loss_type: DPOLossType = DPOLossType.sigmoid
+
+
+@json_schema_type
+class PostTrainingRLHFRequest(BaseModel):
+    """Request to finetune a model using reinforcement learning from human feedback.
+
+    :param job_uuid: Unique identifier for the training job
+    :param finetuned_model: URL or path to the base model to fine-tune
+    :param dataset_id: Unique identifier for the training dataset
+    :param validation_dataset_id: Unique identifier for the validation dataset
+    :param algorithm: RLHF algorithm to use for training
+    :param algorithm_config: Configuration parameters for the RLHF algorithm
+    :param optimizer_config: Configuration parameters for the optimization algorithm
+    :param training_config: Configuration parameters for the training process
+    :param hyperparam_search_config: Configuration for hyperparameter search
+    :param logger_config: Configuration for training logging
+    """
+
+    job_uuid: str
+
+    finetuned_model: URL
+
+    dataset_id: str
+    validation_dataset_id: str
+
+    algorithm: RLHFAlgorithm
+    algorithm_config: DPOAlignmentConfig
+
+    optimizer_config: OptimizerConfig
+    training_config: TrainingConfig
+
+    # TODO: define these
+    hyperparam_search_config: dict[str, Any]
+    logger_config: dict[str, Any]
+
+
+class PostTrainingJob(BaseModel):
+    job_uuid: str
+
+
+@json_schema_type
+class PostTrainingJobStatusResponse(BaseModel):
+    """Status of a finetuning job.
+
+    :param job_uuid: Unique identifier for the training job
+    :param status: Current status of the training job
+    :param scheduled_at: (Optional) Timestamp when the job was scheduled
+    :param started_at: (Optional) Timestamp when the job execution began
+    :param completed_at: (Optional) Timestamp when the job finished, if completed
+    :param resources_allocated: (Optional) Information about computational resources allocated to the job
+    :param checkpoints: List of model checkpoints created during training
+    """
+
+    job_uuid: str
+    status: JobStatus
+
+    scheduled_at: datetime | None = None
+    started_at: datetime | None = None
+    completed_at: datetime | None = None
+
+    resources_allocated: dict[str, Any] | None = None
+
+    checkpoints: list[Checkpoint] = Field(default_factory=list)
+
+
+class ListPostTrainingJobsResponse(BaseModel):
+    data: list[PostTrainingJob]
+
+
+@json_schema_type
+class PostTrainingJobArtifactsResponse(BaseModel):
+    """Artifacts of a finetuning job.
+
+    :param job_uuid: Unique identifier for the training job
+    :param checkpoints: List of model checkpoints created during training
+    """
+
+    job_uuid: str
+    checkpoints: list[Checkpoint] = Field(default_factory=list)
+
+    # TODO(ashwin): metrics, evals
+
+
+class PostTraining(Protocol):
+    @webmethod(route="/post-training/supervised-fine-tune", method="POST", level=LLAMA_STACK_API_V1ALPHA)
+    async def supervised_fine_tune(
+        self,
+        job_uuid: str,
+        training_config: TrainingConfig,
+        hyperparam_search_config: dict[str, Any],
+        logger_config: dict[str, Any],
+        model: str | None = Field(
+            default=None,
+            description="Model descriptor for training if not in provider config`",
+        ),
+        checkpoint_dir: str | None = None,
+        algorithm_config: AlgorithmConfig | None = None,
+    ) -> PostTrainingJob:
+        """Run supervised fine-tuning of a model.
+
+        :param job_uuid: The UUID of the job to create.
+        :param training_config: The training configuration.
+        :param hyperparam_search_config: The hyperparam search configuration.
+        :param logger_config: The logger configuration.
+        :param model: The model to fine-tune.
+        :param checkpoint_dir: The directory to save checkpoint(s) to.
+        :param algorithm_config: The algorithm configuration.
+        :returns: A PostTrainingJob.
+        """
+        ...
+
+    @webmethod(route="/post-training/preference-optimize", method="POST", level=LLAMA_STACK_API_V1ALPHA)
+    async def preference_optimize(
+        self,
+        job_uuid: str,
+        finetuned_model: str,
+        algorithm_config: DPOAlignmentConfig,
+        training_config: TrainingConfig,
+        hyperparam_search_config: dict[str, Any],
+        logger_config: dict[str, Any],
+    ) -> PostTrainingJob:
+        """Run preference optimization of a model.
+
+        :param job_uuid: The UUID of the job to create.
+        :param finetuned_model: The model to fine-tune.
+        :param algorithm_config: The algorithm configuration.
+        :param training_config: The training configuration.
+        :param hyperparam_search_config: The hyperparam search configuration.
+        :param logger_config: The logger configuration.
+        :returns: A PostTrainingJob.
+        """
+        ...
+
+    @webmethod(route="/post-training/jobs", method="GET", level=LLAMA_STACK_API_V1ALPHA)
+    async def get_training_jobs(self) -> ListPostTrainingJobsResponse:
+        """Get all training jobs.
+
+        :returns: A ListPostTrainingJobsResponse.
+        """
+        ...
+
+    @webmethod(route="/post-training/job/status", method="GET", level=LLAMA_STACK_API_V1ALPHA)
+    async def get_training_job_status(self, job_uuid: str) -> PostTrainingJobStatusResponse:
+        """Get the status of a training job.
+
+        :param job_uuid: The UUID of the job to get the status of.
+        :returns: A PostTrainingJobStatusResponse.
+        """
+        ...
+
+    @webmethod(route="/post-training/job/cancel", method="POST", level=LLAMA_STACK_API_V1ALPHA)
+    async def cancel_training_job(self, job_uuid: str) -> None:
+        """Cancel a training job.
+
+        :param job_uuid: The UUID of the job to cancel.
+        """
+        ...
+
+    @webmethod(route="/post-training/job/artifacts", method="GET", level=LLAMA_STACK_API_V1ALPHA)
+    async def get_training_job_artifacts(self, job_uuid: str) -> PostTrainingJobArtifactsResponse:
+        """Get the artifacts of a training job.
+
+        :param job_uuid: The UUID of the job to get the artifacts of.
+        :returns: A PostTrainingJobArtifactsResponse.
+        """
+        ...

src/llama_stack_api/prompts.py

@@ -0,0 +1,204 @@
+# 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.
+
+import re
+import secrets
+from typing import Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from llama_stack_api.common.tracing import telemetry_traceable
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+
+@json_schema_type
+class Prompt(BaseModel):
+    """A prompt resource representing a stored OpenAI Compatible prompt template in Llama Stack.
+
+    :param prompt: The system prompt text with variable placeholders. Variables are only supported when using the Responses API.
+    :param version: Version (integer starting at 1, incremented on save)
+    :param prompt_id: Unique identifier formatted as 'pmpt_<48-digit-hash>'
+    :param variables: List of prompt variable names that can be used in the prompt template
+    :param is_default: Boolean indicating whether this version is the default version for this prompt
+    """
+
+    prompt: str | None = Field(default=None, description="The system prompt with variable placeholders")
+    version: int = Field(description="Version (integer starting at 1, incremented on save)", ge=1)
+    prompt_id: str = Field(description="Unique identifier in format 'pmpt_<48-digit-hash>'")
+    variables: list[str] = Field(
+        default_factory=list, description="List of variable names that can be used in the prompt template"
+    )
+    is_default: bool = Field(
+        default=False, description="Boolean indicating whether this version is the default version"
+    )
+
+    @field_validator("prompt_id")
+    @classmethod
+    def validate_prompt_id(cls, prompt_id: str) -> str:
+        if not isinstance(prompt_id, str):
+            raise TypeError("prompt_id must be a string in format 'pmpt_<48-digit-hash>'")
+
+        if not prompt_id.startswith("pmpt_"):
+            raise ValueError("prompt_id must start with 'pmpt_' prefix")
+
+        hex_part = prompt_id[5:]
+        if len(hex_part) != 48:
+            raise ValueError("prompt_id must be in format 'pmpt_<48-digit-hash>' (48 lowercase hex chars)")
+
+        for char in hex_part:
+            if char not in "0123456789abcdef":
+                raise ValueError("prompt_id hex part must contain only lowercase hex characters [0-9a-f]")
+
+        return prompt_id
+
+    @field_validator("version")
+    @classmethod
+    def validate_version(cls, prompt_version: int) -> int:
+        if prompt_version < 1:
+            raise ValueError("version must be >= 1")
+        return prompt_version
+
+    @model_validator(mode="after")
+    def validate_prompt_variables(self):
+        """Validate that all variables used in the prompt are declared in the variables list."""
+        if not self.prompt:
+            return self
+
+        prompt_variables = set(re.findall(r"{{\s*(\w+)\s*}}", self.prompt))
+        declared_variables = set(self.variables)
+
+        undeclared = prompt_variables - declared_variables
+        if undeclared:
+            raise ValueError(f"Prompt contains undeclared variables: {sorted(undeclared)}")
+
+        return self
+
+    @classmethod
+    def generate_prompt_id(cls) -> str:
+        # Generate 48 hex characters (24 bytes)
+        random_bytes = secrets.token_bytes(24)
+        hex_string = random_bytes.hex()
+        return f"pmpt_{hex_string}"
+
+
+class ListPromptsResponse(BaseModel):
+    """Response model to list prompts."""
+
+    data: list[Prompt]
+
+
+@runtime_checkable
+@telemetry_traceable
+class Prompts(Protocol):
+    """Prompts
+
+    Protocol for prompt management operations."""
+
+    @webmethod(route="/prompts", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_prompts(self) -> ListPromptsResponse:
+        """List all prompts.
+
+        :returns: A ListPromptsResponse containing all prompts.
+        """
+        ...
+
+    @webmethod(route="/prompts/{prompt_id}/versions", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_prompt_versions(
+        self,
+        prompt_id: str,
+    ) -> ListPromptsResponse:
+        """List prompt versions.
+
+        List all versions of a specific prompt.
+
+        :param prompt_id: The identifier of the prompt to list versions for.
+        :returns: A ListPromptsResponse containing all versions of the prompt.
+        """
+        ...
+
+    @webmethod(route="/prompts/{prompt_id}", method="GET", level=LLAMA_STACK_API_V1)
+    async def get_prompt(
+        self,
+        prompt_id: str,
+        version: int | None = None,
+    ) -> Prompt:
+        """Get prompt.
+
+        Get a prompt by its identifier and optional version.
+
+        :param prompt_id: The identifier of the prompt to get.
+        :param version: The version of the prompt to get (defaults to latest).
+        :returns: A Prompt resource.
+        """
+        ...
+
+    @webmethod(route="/prompts", method="POST", level=LLAMA_STACK_API_V1)
+    async def create_prompt(
+        self,
+        prompt: str,
+        variables: list[str] | None = None,
+    ) -> Prompt:
+        """Create prompt.
+
+        Create a new prompt.
+
+        :param prompt: The prompt text content with variable placeholders.
+        :param variables: List of variable names that can be used in the prompt template.
+        :returns: The created Prompt resource.
+        """
+        ...
+
+    @webmethod(route="/prompts/{prompt_id}", method="PUT", level=LLAMA_STACK_API_V1)
+    async def update_prompt(
+        self,
+        prompt_id: str,
+        prompt: str,
+        version: int,
+        variables: list[str] | None = None,
+        set_as_default: bool = True,
+    ) -> Prompt:
+        """Update prompt.
+
+        Update an existing prompt (increments version).
+
+        :param prompt_id: The identifier of the prompt to update.
+        :param prompt: The updated prompt text content.
+        :param version: The current version of the prompt being updated.
+        :param variables: Updated list of variable names that can be used in the prompt template.
+        :param set_as_default: Set the new version as the default (default=True).
+        :returns: The updated Prompt resource with incremented version.
+        """
+        ...
+
+    @webmethod(route="/prompts/{prompt_id}", method="DELETE", level=LLAMA_STACK_API_V1)
+    async def delete_prompt(
+        self,
+        prompt_id: str,
+    ) -> None:
+        """Delete prompt.
+
+        Delete a prompt.
+
+        :param prompt_id: The identifier of the prompt to delete.
+        """
+        ...
+
+    @webmethod(route="/prompts/{prompt_id}/set-default-version", method="PUT", level=LLAMA_STACK_API_V1)
+    async def set_default_version(
+        self,
+        prompt_id: str,
+        version: int,
+    ) -> Prompt:
+        """Set prompt version.
+
+        Set which version of a prompt should be the default in get_prompt (latest).
+
+        :param prompt_id: The identifier of the prompt.
+        :param version: The version to set as default.
+        :returns: The prompt with the specified version now set as default.
+        """
+        ...

src/llama_stack_api/providers.py

@@ -0,0 +1,69 @@
+# 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 pydantic import BaseModel
+
+from llama_stack_api.datatypes import HealthResponse
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+
+@json_schema_type
+class ProviderInfo(BaseModel):
+    """Information about a registered provider including its configuration and health status.
+
+    :param api: The API name this provider implements
+    :param provider_id: Unique identifier for the provider
+    :param provider_type: The type of provider implementation
+    :param config: Configuration parameters for the provider
+    :param health: Current health status of the provider
+    """
+
+    api: str
+    provider_id: str
+    provider_type: str
+    config: dict[str, Any]
+    health: HealthResponse
+
+
+class ListProvidersResponse(BaseModel):
+    """Response containing a list of all available providers.
+
+    :param data: List of provider information objects
+    """
+
+    data: list[ProviderInfo]
+
+
+@runtime_checkable
+class Providers(Protocol):
+    """Providers
+
+    Providers API for inspecting, listing, and modifying providers and their configurations.
+    """
+
+    @webmethod(route="/providers", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_providers(self) -> ListProvidersResponse:
+        """List providers.
+
+        List all available providers.
+
+        :returns: A ListProvidersResponse containing information about all providers.
+        """
+        ...
+
+    @webmethod(route="/providers/{provider_id}", method="GET", level=LLAMA_STACK_API_V1)
+    async def inspect_provider(self, provider_id: str) -> ProviderInfo:
+        """Get provider.
+
+        Get detailed information about a specific provider.
+
+        :param provider_id: The ID of the provider to inspect.
+        :returns: A ProviderInfo object containing the provider's details.
+        """
+        ...

src/llama_stack_api/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.uv]
+required-version = ">=0.7.0"
+
+[project]
+name = "llama-stack-api"
+version = "0.4.0.dev0"
+authors = [{ name = "Meta Llama", email = "llama-oss@meta.com" }]
+description = "API and Provider specifications for Llama Stack - lightweight package with protocol definitions and provider specs"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { "text" = "MIT" }
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "pydantic>=2.11.9",
+    "jsonschema",
+    "opentelemetry-sdk>=1.30.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.30.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/llamastack/llama-stack"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["llama_stack_api", "llama_stack_api.*"]
+
+[tool.setuptools.package-data]
+llama_stack_api = ["py.typed"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "UP",      # pyupgrade
+    "B",       # flake8-bugbear
+    "B9",      # flake8-bugbear subset
+    "C",       # comprehensions
+    "E",       # pycodestyle
+    "F",       # Pyflakes
+    "N",       # Naming
+    "W",       # Warnings
+    "DTZ",     # datetime rules
+    "I",       # isort (imports order)
+    "RUF001",  # Checks for ambiguous Unicode characters in strings
+    "RUF002",  # Checks for ambiguous Unicode characters in docstrings
+    "RUF003",  # Checks for ambiguous Unicode characters in comments
+    "PLC2401", # Checks for the use of non-ASCII characters in variable names
+]
+ignore = [
+    # The following ignores are desired by the project maintainers.
+    "E402",   # Module level import not at top of file
+    "E501",   # Line too long
+    "F405",   # Maybe undefined or defined from star import
+    "C408",   # Ignored because we like the dict keyword argument syntax
+    "N812",   # Ignored because import torch.nn.functional as F is PyTorch convention
+
+    # These are the additional ones we started ignoring after moving to ruff. We should look into each one of them later.
+    "C901",   # Complexity of the function is too high
+]
+unfixable = [
+    "PLE2515",
+] # Do not fix this automatically since ruff will replace the zero-width space with \u200b - let's do it manually
+
+[tool.ruff.lint.per-file-ignores]
+"llama_stack_api/apis/**/__init__.py" = ["F403"]
+
+[tool.ruff.lint.pep8-naming]
+classmethod-decorators = ["classmethod", "pydantic.field_validator"]

src/llama_stack_api/rag_tool.py

@@ -0,0 +1,168 @@
+# 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 Enum, StrEnum
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from llama_stack_api.common.content_types import URL, InterleavedContent
+
+
+class RRFRanker(BaseModel):
+    """
+    Reciprocal Rank Fusion (RRF) ranker configuration.
+
+    :param type: The type of ranker, always "rrf"
+    :param impact_factor: The impact factor for RRF scoring. Higher values give more weight to higher-ranked results.
+                         Must be greater than 0
+    """
+
+    type: Literal["rrf"] = "rrf"
+    impact_factor: float = Field(default=60.0, gt=0.0)  # default of 60 for optimal performance
+
+
+class WeightedRanker(BaseModel):
+    """
+    Weighted ranker configuration that combines vector and keyword scores.
+
+    :param type: The type of ranker, always "weighted"
+    :param alpha: Weight factor between 0 and 1.
+                 0 means only use keyword scores,
+                 1 means only use vector scores,
+                 values in between blend both scores.
+    """
+
+    type: Literal["weighted"] = "weighted"
+    alpha: float = Field(
+        default=0.5,
+        ge=0.0,
+        le=1.0,
+        description="Weight factor between 0 and 1. 0 means only keyword scores, 1 means only vector scores.",
+    )
+
+
+Ranker = Annotated[
+    RRFRanker | WeightedRanker,
+    Field(discriminator="type"),
+]
+
+
+class RAGDocument(BaseModel):
+    """
+    A document to be used for document ingestion in the RAG Tool.
+
+    :param document_id: The unique identifier for the document.
+    :param content: The content of the document.
+    :param mime_type: The MIME type of the document.
+    :param metadata: Additional metadata for the document.
+    """
+
+    document_id: str
+    content: InterleavedContent | URL
+    mime_type: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RAGQueryResult(BaseModel):
+    """Result of a RAG query containing retrieved content and metadata.
+
+    :param content: (Optional) The retrieved content from the query
+    :param metadata: Additional metadata about the query result
+    """
+
+    content: InterleavedContent | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RAGQueryGenerator(Enum):
+    """Types of query generators for RAG systems.
+
+    :cvar default: Default query generator using simple text processing
+    :cvar llm: LLM-based query generator for enhanced query understanding
+    :cvar custom: Custom query generator implementation
+    """
+
+    default = "default"
+    llm = "llm"
+    custom = "custom"
+
+
+class RAGSearchMode(StrEnum):
+    """
+    Search modes for RAG query retrieval:
+    - VECTOR: Uses vector similarity search for semantic matching
+    - KEYWORD: Uses keyword-based search for exact matching
+    - HYBRID: Combines both vector and keyword search for better results
+    """
+
+    VECTOR = "vector"
+    KEYWORD = "keyword"
+    HYBRID = "hybrid"
+
+
+class DefaultRAGQueryGeneratorConfig(BaseModel):
+    """Configuration for the default RAG query generator.
+
+    :param type: Type of query generator, always 'default'
+    :param separator: String separator used to join query terms
+    """
+
+    type: Literal["default"] = "default"
+    separator: str = " "
+
+
+class LLMRAGQueryGeneratorConfig(BaseModel):
+    """Configuration for the LLM-based RAG query generator.
+
+    :param type: Type of query generator, always 'llm'
+    :param model: Name of the language model to use for query generation
+    :param template: Template string for formatting the query generation prompt
+    """
+
+    type: Literal["llm"] = "llm"
+    model: str
+    template: str
+
+
+RAGQueryGeneratorConfig = Annotated[
+    DefaultRAGQueryGeneratorConfig | LLMRAGQueryGeneratorConfig,
+    Field(discriminator="type"),
+]
+
+
+class RAGQueryConfig(BaseModel):
+    """
+    Configuration for the RAG query generation.
+
+    :param query_generator_config: Configuration for the query generator.
+    :param max_tokens_in_context: Maximum number of tokens in the context.
+    :param max_chunks: Maximum number of chunks to retrieve.
+    :param chunk_template: Template for formatting each retrieved chunk in the context.
+        Available placeholders: {index} (1-based chunk ordinal), {chunk.content} (chunk content string), {metadata} (chunk metadata dict).
+        Default: "Result {index}\\nContent: {chunk.content}\\nMetadata: {metadata}\\n"
+    :param mode: Search mode for retrieval—either "vector", "keyword", or "hybrid". Default "vector".
+    :param ranker: Configuration for the ranker to use in hybrid search. Defaults to RRF ranker.
+    """
+
+    # This config defines how a query is generated using the messages
+    # for memory bank retrieval.
+    query_generator_config: RAGQueryGeneratorConfig = Field(default=DefaultRAGQueryGeneratorConfig())
+    max_tokens_in_context: int = 4096
+    max_chunks: int = 5
+    chunk_template: str = "Result {index}\nContent: {chunk.content}\nMetadata: {metadata}\n"
+    mode: RAGSearchMode | None = RAGSearchMode.VECTOR
+    ranker: Ranker | None = Field(default=None)  # Only used for hybrid mode
+
+    @field_validator("chunk_template")
+    def validate_chunk_template(cls, v: str) -> str:
+        if "{chunk.content}" not in v:
+            raise ValueError("chunk_template must contain {chunk.content}")
+        if "{index}" not in v:
+            raise ValueError("chunk_template must contain {index}")
+        if len(v) == 0:
+            raise ValueError("chunk_template must not be empty")
+        return v

src/llama_stack_api/resource.py

@@ -0,0 +1,37 @@
+# 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 pydantic import BaseModel, Field
+
+
+class ResourceType(StrEnum):
+    model = "model"
+    shield = "shield"
+    vector_store = "vector_store"
+    dataset = "dataset"
+    scoring_function = "scoring_function"
+    benchmark = "benchmark"
+    tool = "tool"
+    tool_group = "tool_group"
+    prompt = "prompt"
+
+
+class Resource(BaseModel):
+    """Base class for all Llama Stack resources"""
+
+    identifier: str = Field(description="Unique identifier for this resource in llama stack")
+
+    provider_resource_id: str | None = Field(
+        default=None,
+        description="Unique identifier for this resource in the provider",
+    )
+
+    provider_id: str = Field(description="ID of the provider that owns this resource")
+
+    type: ResourceType = Field(description="Type of resource (e.g. 'model', 'shield', 'vector_store', etc.)")

src/llama_stack_api/safety.py

@@ -0,0 +1,134 @@
+# 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 Enum
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.common.tracing import telemetry_traceable
+from llama_stack_api.inference import OpenAIMessageParam
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.shields import Shield
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+
+@json_schema_type
+class ModerationObjectResults(BaseModel):
+    """A moderation object.
+    :param flagged: Whether any of the below categories are flagged.
+    :param categories: A list of the categories, and whether they are flagged or not.
+    :param category_applied_input_types: A list of the categories along with the input type(s) that the score applies to.
+    :param category_scores: A list of the categories along with their scores as predicted by model.
+    """
+
+    flagged: bool
+    categories: dict[str, bool] | None = None
+    category_applied_input_types: dict[str, list[str]] | None = None
+    category_scores: dict[str, float] | None = None
+    user_message: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+@json_schema_type
+class ModerationObject(BaseModel):
+    """A moderation object.
+    :param id: The unique identifier for the moderation request.
+    :param model: The model used to generate the moderation results.
+    :param results: A list of moderation objects
+    """
+
+    id: str
+    model: str
+    results: list[ModerationObjectResults]
+
+
+@json_schema_type
+class ViolationLevel(Enum):
+    """Severity level of a safety violation.
+
+    :cvar INFO: Informational level violation that does not require action
+    :cvar WARN: Warning level violation that suggests caution but allows continuation
+    :cvar ERROR: Error level violation that requires blocking or intervention
+    """
+
+    INFO = "info"
+    WARN = "warn"
+    ERROR = "error"
+
+
+@json_schema_type
+class SafetyViolation(BaseModel):
+    """Details of a safety violation detected by content moderation.
+
+    :param violation_level: Severity level of the violation
+    :param user_message: (Optional) Message to convey to the user about the violation
+    :param metadata: Additional metadata including specific violation codes for debugging and telemetry
+    """
+
+    violation_level: ViolationLevel
+
+    # what message should you convey to the user
+    user_message: str | None = None
+
+    # additional metadata (including specific violation codes) more for
+    # debugging, telemetry
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+@json_schema_type
+class RunShieldResponse(BaseModel):
+    """Response from running a safety shield.
+
+    :param violation: (Optional) Safety violation detected by the shield, if any
+    """
+
+    violation: SafetyViolation | None = None
+
+
+class ShieldStore(Protocol):
+    async def get_shield(self, identifier: str) -> Shield: ...
+
+
+@runtime_checkable
+@telemetry_traceable
+class Safety(Protocol):
+    """Safety
+
+    OpenAI-compatible Moderations API.
+    """
+
+    shield_store: ShieldStore
+
+    @webmethod(route="/safety/run-shield", method="POST", level=LLAMA_STACK_API_V1)
+    async def run_shield(
+        self,
+        shield_id: str,
+        messages: list[OpenAIMessageParam],
+        params: dict[str, Any],
+    ) -> RunShieldResponse:
+        """Run shield.
+
+        Run a shield.
+
+        :param shield_id: The identifier of the shield to run.
+        :param messages: The messages to run the shield on.
+        :param params: The parameters of the shield.
+        :returns: A RunShieldResponse.
+        """
+        ...
+
+    @webmethod(route="/moderations", method="POST", level=LLAMA_STACK_API_V1)
+    async def run_moderation(self, input: str | list[str], model: str | None = None) -> ModerationObject:
+        """Create moderation.
+
+        Classifies if text and/or image inputs are potentially harmful.
+        :param input: Input (or inputs) to classify.
+        Can be a single string, an array of strings, or an array of multi-modal input objects similar to other models.
+        :param model: (Optional) The content moderation model you would like to use.
+        :returns: A moderation object.
+        """
+        ...

src/llama_stack_api/schema_utils.py

@@ -0,0 +1,118 @@
+# 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 collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+from .strong_typing.schema import json_schema_type, register_schema  # noqa: F401
+
+
+class ExtraBodyField[T]:
+    """
+    Marker annotation for parameters that arrive via extra_body in the client SDK.
+
+    These parameters:
+    - Will NOT appear in the generated client SDK method signature
+    - WILL be documented in OpenAPI spec under x-llama-stack-extra-body-params
+    - MUST be passed via the extra_body parameter in client SDK calls
+    - WILL be available in server-side method signature with proper typing
+
+    Example:
+        ```python
+        async def create_openai_response(
+            self,
+            input: str,
+            model: str,
+            shields: Annotated[
+                list[str] | None, ExtraBodyField("List of shields to apply")
+            ] = None,
+        ) -> ResponseObject:
+            # shields is available here with proper typing
+            if shields:
+                print(f"Using shields: {shields}")
+        ```
+
+        Client usage:
+        ```python
+        client.responses.create(
+            input="hello", model="llama-3", extra_body={"shields": ["shield-1"]}
+        )
+        ```
+    """
+
+    def __init__(self, description: str | None = None):
+        self.description = description
+
+
+@dataclass
+class WebMethod:
+    level: str | None = None
+    route: str | None = None
+    public: bool = False
+    request_examples: list[Any] | None = None
+    response_examples: list[Any] | None = None
+    method: str | None = None
+    raw_bytes_request_body: bool | None = False
+    # A descriptive name of the corresponding span created by tracing
+    descriptive_name: str | None = None
+    required_scope: str | None = None
+    deprecated: bool | None = False
+    require_authentication: bool | None = True
+
+
+CallableT = TypeVar("CallableT", bound=Callable[..., Any])
+
+
+def webmethod(
+    route: str | None = None,
+    method: str | None = None,
+    level: str | None = None,
+    public: bool | None = False,
+    request_examples: list[Any] | None = None,
+    response_examples: list[Any] | None = None,
+    raw_bytes_request_body: bool | None = False,
+    descriptive_name: str | None = None,
+    required_scope: str | None = None,
+    deprecated: bool | None = False,
+    require_authentication: bool | None = True,
+) -> Callable[[CallableT], CallableT]:
+    """
+    Decorator that supplies additional metadata to an endpoint operation function.
+
+    :param route: The URL path pattern associated with this operation which path parameters are substituted into.
+    :param public: True if the operation can be invoked without prior authentication.
+    :param request_examples: Sample requests that the operation might take. Pass a list of objects, not JSON.
+    :param response_examples: Sample responses that the operation might produce. Pass a list of objects, not JSON.
+    :param required_scope: Required scope for this endpoint (e.g., 'monitoring.viewer').
+    :param require_authentication: Whether this endpoint requires authentication (default True).
+    """
+
+    def wrap(func: CallableT) -> CallableT:
+        webmethod_obj = WebMethod(
+            route=route,
+            method=method,
+            level=level,
+            public=public or False,
+            request_examples=request_examples,
+            response_examples=response_examples,
+            raw_bytes_request_body=raw_bytes_request_body,
+            descriptive_name=descriptive_name,
+            required_scope=required_scope,
+            deprecated=deprecated,
+            require_authentication=require_authentication if require_authentication is not None else True,
+        )
+
+        # Store all webmethods in a list to support multiple decorators
+        if not hasattr(func, "__webmethods__"):
+            func.__webmethods__ = []  # type: ignore
+        func.__webmethods__.append(webmethod_obj)  # type: ignore
+
+        # Keep the last one as __webmethod__ for backwards compatibility
+        func.__webmethod__ = webmethod_obj  # type: ignore
+        return func
+
+    return wrap

src/llama_stack_api/scoring.py

@@ -0,0 +1,93 @@
+# 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 pydantic import BaseModel
+
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.scoring_functions import ScoringFn, ScoringFnParams
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+# mapping of metric to value
+ScoringResultRow = dict[str, Any]
+
+
+@json_schema_type
+class ScoringResult(BaseModel):
+    """
+    A scoring result for a single row.
+
+    :param score_rows: The scoring result for each row. Each row is a map of column name to value.
+    :param aggregated_results: Map of metric name to aggregated value
+    """
+
+    score_rows: list[ScoringResultRow]
+    # aggregated metrics to value
+    aggregated_results: dict[str, Any]
+
+
+@json_schema_type
+class ScoreBatchResponse(BaseModel):
+    """Response from batch scoring operations on datasets.
+
+    :param dataset_id: (Optional) The identifier of the dataset that was scored
+    :param results: A map of scoring function name to ScoringResult
+    """
+
+    dataset_id: str | None = None
+    results: dict[str, ScoringResult]
+
+
+@json_schema_type
+class ScoreResponse(BaseModel):
+    """
+    The response from scoring.
+
+    :param results: A map of scoring function name to ScoringResult.
+    """
+
+    # each key in the dict is a scoring function name
+    results: dict[str, ScoringResult]
+
+
+class ScoringFunctionStore(Protocol):
+    def get_scoring_function(self, scoring_fn_id: str) -> ScoringFn: ...
+
+
+@runtime_checkable
+class Scoring(Protocol):
+    scoring_function_store: ScoringFunctionStore
+
+    @webmethod(route="/scoring/score-batch", method="POST", level=LLAMA_STACK_API_V1)
+    async def score_batch(
+        self,
+        dataset_id: str,
+        scoring_functions: dict[str, ScoringFnParams | None],
+        save_results_dataset: bool = False,
+    ) -> ScoreBatchResponse:
+        """Score a batch of rows.
+
+        :param dataset_id: The ID of the dataset to score.
+        :param scoring_functions: The scoring functions to use for the scoring.
+        :param save_results_dataset: Whether to save the results to a dataset.
+        :returns: A ScoreBatchResponse.
+        """
+        ...
+
+    @webmethod(route="/scoring/score", method="POST", level=LLAMA_STACK_API_V1)
+    async def score(
+        self,
+        input_rows: list[dict[str, Any]],
+        scoring_functions: dict[str, ScoringFnParams | None],
+    ) -> ScoreResponse:
+        """Score a list of rows.
+
+        :param input_rows: The rows to score.
+        :param scoring_functions: The scoring functions to use for the scoring.
+        :returns: A ScoreResponse object containing rows and aggregated results.
+        """
+        ...

src/llama_stack_api/scoring_functions.py

@@ -0,0 +1,210 @@
+# 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.
+
+# TODO: use enum.StrEnum when we drop support for python 3.10
+from enum import StrEnum
+from typing import (
+    Annotated,
+    Any,
+    Literal,
+    Protocol,
+    runtime_checkable,
+)
+
+from pydantic import BaseModel, Field
+
+from llama_stack_api.common.type_system import ParamType
+from llama_stack_api.resource import Resource, ResourceType
+from llama_stack_api.schema_utils import json_schema_type, register_schema, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+
+# Perhaps more structure can be imposed on these functions. Maybe they could be associated
+# with standard metrics so they can be rolled up?
+@json_schema_type
+class ScoringFnParamsType(StrEnum):
+    """Types of scoring function parameter configurations.
+    :cvar llm_as_judge: Use an LLM model to evaluate and score responses
+    :cvar regex_parser: Use regex patterns to extract and score specific parts of responses
+    :cvar basic: Basic scoring with simple aggregation functions
+    """
+
+    llm_as_judge = "llm_as_judge"
+    regex_parser = "regex_parser"
+    basic = "basic"
+
+
+@json_schema_type
+class AggregationFunctionType(StrEnum):
+    """Types of aggregation functions for scoring results.
+    :cvar average: Calculate the arithmetic mean of scores
+    :cvar weighted_average: Calculate a weighted average of scores
+    :cvar median: Calculate the median value of scores
+    :cvar categorical_count: Count occurrences of categorical values
+    :cvar accuracy: Calculate accuracy as the proportion of correct answers
+    """
+
+    average = "average"
+    weighted_average = "weighted_average"
+    median = "median"
+    categorical_count = "categorical_count"
+    accuracy = "accuracy"
+
+
+@json_schema_type
+class LLMAsJudgeScoringFnParams(BaseModel):
+    """Parameters for LLM-as-judge scoring function configuration.
+    :param type: The type of scoring function parameters, always llm_as_judge
+    :param judge_model: Identifier of the LLM model to use as a judge for scoring
+    :param prompt_template: (Optional) Custom prompt template for the judge model
+    :param judge_score_regexes: Regexes to extract the answer from generated response
+    :param aggregation_functions: Aggregation functions to apply to the scores of each row
+    """
+
+    type: Literal[ScoringFnParamsType.llm_as_judge] = ScoringFnParamsType.llm_as_judge
+    judge_model: str
+    prompt_template: str | None = None
+    judge_score_regexes: list[str] = Field(
+        description="Regexes to extract the answer from generated response",
+        default_factory=lambda: [],
+    )
+    aggregation_functions: list[AggregationFunctionType] = Field(
+        description="Aggregation functions to apply to the scores of each row",
+        default_factory=lambda: [],
+    )
+
+
+@json_schema_type
+class RegexParserScoringFnParams(BaseModel):
+    """Parameters for regex parser scoring function configuration.
+    :param type: The type of scoring function parameters, always regex_parser
+    :param parsing_regexes: Regex to extract the answer from generated response
+    :param aggregation_functions: Aggregation functions to apply to the scores of each row
+    """
+
+    type: Literal[ScoringFnParamsType.regex_parser] = ScoringFnParamsType.regex_parser
+    parsing_regexes: list[str] = Field(
+        description="Regex to extract the answer from generated response",
+        default_factory=lambda: [],
+    )
+    aggregation_functions: list[AggregationFunctionType] = Field(
+        description="Aggregation functions to apply to the scores of each row",
+        default_factory=lambda: [],
+    )
+
+
+@json_schema_type
+class BasicScoringFnParams(BaseModel):
+    """Parameters for basic scoring function configuration.
+    :param type: The type of scoring function parameters, always basic
+    :param aggregation_functions: Aggregation functions to apply to the scores of each row
+    """
+
+    type: Literal[ScoringFnParamsType.basic] = ScoringFnParamsType.basic
+    aggregation_functions: list[AggregationFunctionType] = Field(
+        description="Aggregation functions to apply to the scores of each row",
+        default_factory=list,
+    )
+
+
+ScoringFnParams = Annotated[
+    LLMAsJudgeScoringFnParams | RegexParserScoringFnParams | BasicScoringFnParams,
+    Field(discriminator="type"),
+]
+register_schema(ScoringFnParams, name="ScoringFnParams")
+
+
+class CommonScoringFnFields(BaseModel):
+    description: str | None = None
+    metadata: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Any additional metadata for this definition",
+    )
+    return_type: ParamType = Field(
+        description="The return type of the deterministic function",
+    )
+    params: ScoringFnParams | None = Field(
+        description="The parameters for the scoring function for benchmark eval, these can be overridden for app eval",
+        default=None,
+    )
+
+
+@json_schema_type
+class ScoringFn(CommonScoringFnFields, Resource):
+    """A scoring function resource for evaluating model outputs.
+    :param type: The resource type, always scoring_function
+    """
+
+    type: Literal[ResourceType.scoring_function] = ResourceType.scoring_function
+
+    @property
+    def scoring_fn_id(self) -> str:
+        return self.identifier
+
+    @property
+    def provider_scoring_fn_id(self) -> str | None:
+        return self.provider_resource_id
+
+
+class ScoringFnInput(CommonScoringFnFields, BaseModel):
+    scoring_fn_id: str
+    provider_id: str | None = None
+    provider_scoring_fn_id: str | None = None
+
+
+class ListScoringFunctionsResponse(BaseModel):
+    data: list[ScoringFn]
+
+
+@runtime_checkable
+class ScoringFunctions(Protocol):
+    @webmethod(route="/scoring-functions", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_scoring_functions(self) -> ListScoringFunctionsResponse:
+        """List all scoring functions.
+
+        :returns: A ListScoringFunctionsResponse.
+        """
+        ...
+
+    @webmethod(route="/scoring-functions/{scoring_fn_id:path}", method="GET", level=LLAMA_STACK_API_V1)
+    async def get_scoring_function(self, scoring_fn_id: str, /) -> ScoringFn:
+        """Get a scoring function by its ID.
+
+        :param scoring_fn_id: The ID of the scoring function to get.
+        :returns: A ScoringFn.
+        """
+        ...
+
+    @webmethod(route="/scoring-functions", method="POST", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def register_scoring_function(
+        self,
+        scoring_fn_id: str,
+        description: str,
+        return_type: ParamType,
+        provider_scoring_fn_id: str | None = None,
+        provider_id: str | None = None,
+        params: ScoringFnParams | None = None,
+    ) -> None:
+        """Register a scoring function.
+
+        :param scoring_fn_id: The ID of the scoring function to register.
+        :param description: The description of the scoring function.
+        :param return_type: The return type of the scoring function.
+        :param provider_scoring_fn_id: The ID of the provider scoring function to use for the scoring function.
+        :param provider_id: The ID of the provider to use for the scoring function.
+        :param params: The parameters for the scoring function for benchmark eval, these can be overridden for app eval.
+        """
+        ...
+
+    @webmethod(
+        route="/scoring-functions/{scoring_fn_id:path}", method="DELETE", level=LLAMA_STACK_API_V1, deprecated=True
+    )
+    async def unregister_scoring_function(self, scoring_fn_id: str) -> None:
+        """Unregister a scoring function.
+
+        :param scoring_fn_id: The ID of the scoring function to unregister.
+        """
+        ...

src/llama_stack_api/shields.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.
+
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+from llama_stack_api.common.tracing import telemetry_traceable
+from llama_stack_api.resource import Resource, ResourceType
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+
+class CommonShieldFields(BaseModel):
+    params: dict[str, Any] | None = None
+
+
+@json_schema_type
+class Shield(CommonShieldFields, Resource):
+    """A safety shield resource that can be used to check content.
+
+    :param params: (Optional) Configuration parameters for the shield
+    :param type: The resource type, always shield
+    """
+
+    type: Literal[ResourceType.shield] = ResourceType.shield
+
+    @property
+    def shield_id(self) -> str:
+        return self.identifier
+
+    @property
+    def provider_shield_id(self) -> str | None:
+        return self.provider_resource_id
+
+
+class ShieldInput(CommonShieldFields):
+    shield_id: str
+    provider_id: str | None = None
+    provider_shield_id: str | None = None
+
+
+class ListShieldsResponse(BaseModel):
+    data: list[Shield]
+
+
+@runtime_checkable
+@telemetry_traceable
+class Shields(Protocol):
+    @webmethod(route="/shields", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_shields(self) -> ListShieldsResponse:
+        """List all shields.
+
+        :returns: A ListShieldsResponse.
+        """
+        ...
+
+    @webmethod(route="/shields/{identifier:path}", method="GET", level=LLAMA_STACK_API_V1)
+    async def get_shield(self, identifier: str) -> Shield:
+        """Get a shield by its identifier.
+
+        :param identifier: The identifier of the shield to get.
+        :returns: A Shield.
+        """
+        ...
+
+    @webmethod(route="/shields", method="POST", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def register_shield(
+        self,
+        shield_id: str,
+        provider_shield_id: str | None = None,
+        provider_id: str | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Shield:
+        """Register a shield.
+
+        :param shield_id: The identifier of the shield to register.
+        :param provider_shield_id: The identifier of the shield in the provider.
+        :param provider_id: The identifier of the provider.
+        :param params: The parameters of the shield.
+        :returns: A Shield.
+        """
+        ...
+
+    @webmethod(route="/shields/{identifier:path}", method="DELETE", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def unregister_shield(self, identifier: str) -> None:
+        """Unregister a shield.
+
+        :param identifier: The identifier of the shield to unregister.
+        """
+        ...

src/llama_stack_api/strong_typing/__init__.py

@@ -0,0 +1,19 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+Provides auxiliary services for working with Python type annotations, converting typed data to and from JSON,
+and generating a JSON schema for a complex type.
+"""
+
+__version__ = "0.3.4"
+__author__ = "Levente Hunyadi"
+__copyright__ = "Copyright 2021-2024, Levente Hunyadi"
+__license__ = "MIT"
+__maintainer__ = "Levente Hunyadi"
+__status__ = "Production"

src/llama_stack_api/strong_typing/auxiliary.py

@@ -0,0 +1,229 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+import dataclasses
+import sys
+from collections.abc import Callable
+from dataclasses import is_dataclass
+from typing import TypeVar, overload
+
+if sys.version_info >= (3, 9):
+    from typing import Annotated as Annotated
+else:
+    from typing import Annotated as Annotated
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias as TypeAlias
+else:
+    from typing import TypeAlias as TypeAlias
+
+if sys.version_info >= (3, 11):
+    from typing import dataclass_transform as dataclass_transform
+else:
+    from typing import dataclass_transform as dataclass_transform
+
+T = TypeVar("T")
+
+
+def _compact_dataclass_repr(obj: object) -> str:
+    """
+    Compact data-class representation where positional arguments are used instead of keyword arguments.
+
+    :param obj: A data-class object.
+    :returns: A string that matches the pattern `Class(arg1, arg2, ...)`.
+    """
+
+    if is_dataclass(obj):
+        arglist = ", ".join(repr(getattr(obj, field.name)) for field in dataclasses.fields(obj))
+        return f"{obj.__class__.__name__}({arglist})"
+    else:
+        return obj.__class__.__name__
+
+
+class CompactDataClass:
+    "A data class whose repr() uses positional rather than keyword arguments."
+
+    def __repr__(self) -> str:
+        return _compact_dataclass_repr(self)
+
+
+@overload
+def typeannotation(cls: type[T], /) -> type[T]: ...
+
+
+@overload
+def typeannotation(cls: None, *, eq: bool = True, order: bool = False) -> Callable[[type[T]], type[T]]: ...
+
+
+@dataclass_transform(eq_default=True, order_default=False)
+def typeannotation(
+    cls: type[T] | None = None, *, eq: bool = True, order: bool = False
+) -> type[T] | Callable[[type[T]], type[T]]:
+    """
+    Returns the same class as was passed in, with dunder methods added based on the fields defined in the class.
+
+    :param cls: The data-class type to transform into a type annotation.
+    :param eq: Whether to generate functions to support equality comparison.
+    :param order: Whether to generate functions to support ordering.
+    :returns: A data-class type, or a wrapper for data-class types.
+    """
+
+    def wrap(cls: type[T]) -> type[T]:
+        # mypy fails to equate bound-y functions (first argument interpreted as
+        # the bound object) with class methods, hence the `ignore` directive.
+        cls.__repr__ = _compact_dataclass_repr  # type: ignore[method-assign]
+        if not dataclasses.is_dataclass(cls):
+            cls = dataclasses.dataclass(  # type: ignore[call-overload]
+                cls,
+                init=True,
+                repr=False,
+                eq=eq,
+                order=order,
+                unsafe_hash=False,
+                frozen=True,
+            )
+        return cls
+
+    # see if decorator is used as @typeannotation or @typeannotation()
+    if cls is None:
+        # called with parentheses
+        return wrap
+    else:
+        # called without parentheses
+        return wrap(cls)
+
+
+@typeannotation
+class Alias:
+    "Alternative name of a property, typically used in JSON serialization."
+
+    name: str
+
+
+@typeannotation
+class Signed:
+    "Signedness of an integer type."
+
+    is_signed: bool
+
+
+@typeannotation
+class Storage:
+    "Number of bytes the binary representation of an integer type takes, e.g. 4 bytes for an int32."
+
+    bytes: int
+
+
+@typeannotation
+class IntegerRange:
+    "Minimum and maximum value of an integer. The range is inclusive."
+
+    minimum: int
+    maximum: int
+
+
+@typeannotation
+class Precision:
+    "Precision of a floating-point value."
+
+    significant_digits: int
+    decimal_digits: int = 0
+
+    @property
+    def integer_digits(self) -> int:
+        return self.significant_digits - self.decimal_digits
+
+
+@typeannotation
+class TimePrecision:
+    """
+    Precision of a timestamp or time interval.
+
+    :param decimal_digits: Number of fractional digits retained in the sub-seconds field for a timestamp.
+    """
+
+    decimal_digits: int = 0
+
+
+@typeannotation
+class Length:
+    "Exact length of a string."
+
+    value: int
+
+
+@typeannotation
+class MinLength:
+    "Minimum length of a string."
+
+    value: int
+
+
+@typeannotation
+class MaxLength:
+    "Maximum length of a string."
+
+    value: int
+
+
+@typeannotation
+class SpecialConversion:
+    "Indicates that the annotated type is subject to custom conversion rules."
+
+
+int8: TypeAlias = Annotated[int, Signed(True), Storage(1), IntegerRange(-128, 127)]
+int16: TypeAlias = Annotated[int, Signed(True), Storage(2), IntegerRange(-32768, 32767)]
+int32: TypeAlias = Annotated[
+    int,
+    Signed(True),
+    Storage(4),
+    IntegerRange(-2147483648, 2147483647),
+]
+int64: TypeAlias = Annotated[
+    int,
+    Signed(True),
+    Storage(8),
+    IntegerRange(-9223372036854775808, 9223372036854775807),
+]
+
+uint8: TypeAlias = Annotated[int, Signed(False), Storage(1), IntegerRange(0, 255)]
+uint16: TypeAlias = Annotated[int, Signed(False), Storage(2), IntegerRange(0, 65535)]
+uint32: TypeAlias = Annotated[
+    int,
+    Signed(False),
+    Storage(4),
+    IntegerRange(0, 4294967295),
+]
+uint64: TypeAlias = Annotated[
+    int,
+    Signed(False),
+    Storage(8),
+    IntegerRange(0, 18446744073709551615),
+]
+
+float32: TypeAlias = Annotated[float, Storage(4)]
+float64: TypeAlias = Annotated[float, Storage(8)]
+
+# maps globals of type Annotated[T, ...] defined in this module to their string names
+_auxiliary_types: dict[object, str] = {}
+module = sys.modules[__name__]
+for var in dir(module):
+    typ = getattr(module, var)
+    if getattr(typ, "__metadata__", None) is not None:
+        # type is Annotated[T, ...]
+        _auxiliary_types[typ] = var
+
+
+def get_auxiliary_format(data_type: object) -> str | None:
+    "Returns the JSON format string corresponding to an auxiliary type."
+
+    return _auxiliary_types.get(data_type)

src/llama_stack_api/strong_typing/classdef.py

@@ -0,0 +1,440 @@
+# 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.
+
+import copy
+import dataclasses
+import datetime
+import decimal
+import enum
+import ipaddress
+import math
+import re
+import sys
+import types
+import typing
+import uuid
+from dataclasses import dataclass
+from typing import Any, Literal, TypeVar, Union
+
+from .auxiliary import (
+    Alias,
+    Annotated,
+    MaxLength,
+    Precision,
+    float32,
+    float64,
+    int16,
+    int32,
+    int64,
+)
+from .core import JsonType, Schema
+from .docstring import Docstring, DocstringParam
+from .inspection import TypeLike
+from .serialization import json_to_object, object_to_json
+
+T = TypeVar("T")
+
+
+@dataclass
+class JsonSchemaNode:
+    title: str | None
+    description: str | None
+
+
+@dataclass
+class JsonSchemaType(JsonSchemaNode):
+    type: str
+    format: str | None
+
+
+@dataclass
+class JsonSchemaBoolean(JsonSchemaType):
+    type: Literal["boolean"]
+    const: bool | None
+    default: bool | None
+    examples: list[bool] | None
+
+
+@dataclass
+class JsonSchemaInteger(JsonSchemaType):
+    type: Literal["integer"]
+    const: int | None
+    default: int | None
+    examples: list[int] | None
+    enum: list[int] | None
+    minimum: int | None
+    maximum: int | None
+
+
+@dataclass
+class JsonSchemaNumber(JsonSchemaType):
+    type: Literal["number"]
+    const: float | None
+    default: float | None
+    examples: list[float] | None
+    minimum: float | None
+    maximum: float | None
+    exclusiveMinimum: float | None
+    exclusiveMaximum: float | None
+    multipleOf: float | None
+
+
+@dataclass
+class JsonSchemaString(JsonSchemaType):
+    type: Literal["string"]
+    const: str | None
+    default: str | None
+    examples: list[str] | None
+    enum: list[str] | None
+    minLength: int | None
+    maxLength: int | None
+
+
+@dataclass
+class JsonSchemaArray(JsonSchemaType):
+    type: Literal["array"]
+    items: "JsonSchemaAny"
+
+
+@dataclass
+class JsonSchemaObject(JsonSchemaType):
+    type: Literal["object"]
+    properties: dict[str, "JsonSchemaAny"] | None
+    additionalProperties: bool | None
+    required: list[str] | None
+
+
+@dataclass
+class JsonSchemaRef(JsonSchemaNode):
+    ref: Annotated[str, Alias("$ref")]
+
+
+@dataclass
+class JsonSchemaAllOf(JsonSchemaNode):
+    allOf: list["JsonSchemaAny"]
+
+
+@dataclass
+class JsonSchemaAnyOf(JsonSchemaNode):
+    anyOf: list["JsonSchemaAny"]
+
+
+@dataclass
+class Discriminator:
+    propertyName: str
+    mapping: dict[str, str]
+
+
+@dataclass
+class JsonSchemaOneOf(JsonSchemaNode):
+    oneOf: list["JsonSchemaAny"]
+    discriminator: Discriminator | None
+
+
+JsonSchemaAny = Union[
+    JsonSchemaRef,
+    JsonSchemaBoolean,
+    JsonSchemaInteger,
+    JsonSchemaNumber,
+    JsonSchemaString,
+    JsonSchemaArray,
+    JsonSchemaObject,
+    JsonSchemaOneOf,
+]
+
+
+@dataclass
+class JsonSchemaTopLevelObject(JsonSchemaObject):
+    schema: Annotated[str, Alias("$schema")]
+    definitions: dict[str, JsonSchemaAny] | None
+
+
+def integer_range_to_type(min_value: float, max_value: float) -> type:
+    if min_value >= -(2**15) and max_value < 2**15:
+        return int16
+    elif min_value >= -(2**31) and max_value < 2**31:
+        return int32
+    else:
+        return int64
+
+
+def enum_safe_name(name: str) -> str:
+    name = re.sub(r"\W", "_", name)
+    is_dunder = name.startswith("__")
+    is_sunder = name.startswith("_") and name.endswith("_")
+    if is_dunder or is_sunder:  # provide an alternative for dunder and sunder names
+        name = f"v{name}"
+    return name
+
+
+def enum_values_to_type(
+    module: types.ModuleType,
+    name: str,
+    values: dict[str, Any],
+    title: str | None = None,
+    description: str | None = None,
+) -> type[enum.Enum]:
+    enum_class: type[enum.Enum] = enum.Enum(name, values)  # type: ignore
+
+    # assign the newly created type to the same module where the defining class is
+    enum_class.__module__ = module.__name__
+    enum_class.__doc__ = str(Docstring(short_description=title, long_description=description))
+    setattr(module, name, enum_class)
+
+    return enum.unique(enum_class)
+
+
+def schema_to_type(schema: Schema, *, module: types.ModuleType, class_name: str) -> TypeLike:
+    """
+    Creates a Python type from a JSON schema.
+
+    :param schema: The JSON schema that the types would correspond to.
+    :param module: The module in which to create the new types.
+    :param class_name: The name assigned to the top-level class.
+    """
+
+    top_node = typing.cast(JsonSchemaTopLevelObject, json_to_object(JsonSchemaTopLevelObject, schema))
+    if top_node.definitions is not None:
+        for type_name, type_node in top_node.definitions.items():
+            type_def = node_to_typedef(module, type_name, type_node)
+            if type_def.default is not dataclasses.MISSING:
+                raise TypeError("disallowed: `default` for top-level type definitions")
+
+            type_def.type.__module__ = module.__name__
+            setattr(module, type_name, type_def.type)
+
+    return node_to_typedef(module, class_name, top_node).type
+
+
+@dataclass
+class TypeDef:
+    type: TypeLike
+    default: Any = dataclasses.MISSING
+
+
+def json_to_value(target_type: TypeLike, data: JsonType) -> Any:
+    if data is not None:
+        return json_to_object(target_type, data)
+    else:
+        return dataclasses.MISSING
+
+
+def node_to_typedef(module: types.ModuleType, context: str, node: JsonSchemaNode) -> TypeDef:
+    if isinstance(node, JsonSchemaRef):
+        match_obj = re.match(r"^#/definitions/(\w+)$", node.ref)
+        if not match_obj:
+            raise ValueError(f"invalid reference: {node.ref}")
+
+        type_name = match_obj.group(1)
+        return TypeDef(getattr(module, type_name), dataclasses.MISSING)
+
+    elif isinstance(node, JsonSchemaBoolean):
+        if node.const is not None:
+            return TypeDef(Literal[node.const], dataclasses.MISSING)
+
+        default = json_to_value(bool, node.default)
+        return TypeDef(bool, default)
+
+    elif isinstance(node, JsonSchemaInteger):
+        if node.const is not None:
+            return TypeDef(Literal[node.const], dataclasses.MISSING)
+
+        integer_type: TypeLike
+        if node.format == "int16":
+            integer_type = int16
+        elif node.format == "int32":
+            integer_type = int32
+        elif node.format == "int64":
+            integer_type = int64
+        else:
+            if node.enum is not None:
+                integer_type = integer_range_to_type(min(node.enum), max(node.enum))
+            elif node.minimum is not None and node.maximum is not None:
+                integer_type = integer_range_to_type(node.minimum, node.maximum)
+            else:
+                integer_type = int
+
+        default = json_to_value(integer_type, node.default)
+        return TypeDef(integer_type, default)
+
+    elif isinstance(node, JsonSchemaNumber):
+        if node.const is not None:
+            return TypeDef(Literal[node.const], dataclasses.MISSING)
+
+        number_type: TypeLike
+        if node.format == "float32":
+            number_type = float32
+        elif node.format == "float64":
+            number_type = float64
+        else:
+            if (
+                node.exclusiveMinimum is not None
+                and node.exclusiveMaximum is not None
+                and node.exclusiveMinimum == -node.exclusiveMaximum
+            ):
+                integer_digits = round(math.log10(node.exclusiveMaximum))
+            else:
+                integer_digits = None
+
+            if node.multipleOf is not None:
+                decimal_digits = -round(math.log10(node.multipleOf))
+            else:
+                decimal_digits = None
+
+            if integer_digits is not None and decimal_digits is not None:
+                number_type = Annotated[
+                    decimal.Decimal,
+                    Precision(integer_digits + decimal_digits, decimal_digits),
+                ]
+            else:
+                number_type = float
+
+        default = json_to_value(number_type, node.default)
+        return TypeDef(number_type, default)
+
+    elif isinstance(node, JsonSchemaString):
+        if node.const is not None:
+            return TypeDef(Literal[node.const], dataclasses.MISSING)
+
+        string_type: TypeLike
+        if node.format == "date-time":
+            string_type = datetime.datetime
+        elif node.format == "uuid":
+            string_type = uuid.UUID
+        elif node.format == "ipv4":
+            string_type = ipaddress.IPv4Address
+        elif node.format == "ipv6":
+            string_type = ipaddress.IPv6Address
+
+        elif node.enum is not None:
+            string_type = enum_values_to_type(
+                module,
+                context,
+                {enum_safe_name(e): e for e in node.enum},
+                title=node.title,
+                description=node.description,
+            )
+
+        elif node.maxLength is not None:
+            string_type = Annotated[str, MaxLength(node.maxLength)]
+        else:
+            string_type = str
+
+        default = json_to_value(string_type, node.default)
+        return TypeDef(string_type, default)
+
+    elif isinstance(node, JsonSchemaArray):
+        type_def = node_to_typedef(module, context, node.items)
+        if type_def.default is not dataclasses.MISSING:
+            raise TypeError("disallowed: `default` for array element type")
+        list_type = list[(type_def.type,)]  # type: ignore
+        return TypeDef(list_type, dataclasses.MISSING)
+
+    elif isinstance(node, JsonSchemaObject):
+        if node.properties is None:
+            return TypeDef(JsonType, dataclasses.MISSING)
+
+        if node.additionalProperties is None or node.additionalProperties is not False:
+            raise TypeError("expected: `additionalProperties` equals `false`")
+
+        required = node.required if node.required is not None else []
+
+        class_name = context
+
+        fields: list[tuple[str, Any, dataclasses.Field]] = []
+        params: dict[str, DocstringParam] = {}
+        for prop_name, prop_node in node.properties.items():
+            type_def = node_to_typedef(module, f"{class_name}__{prop_name}", prop_node)
+            if prop_name in required:
+                prop_type = type_def.type
+            else:
+                prop_type = Union[(None, type_def.type)]
+            fields.append((prop_name, prop_type, dataclasses.field(default=type_def.default)))
+            prop_desc = prop_node.title or prop_node.description
+            if prop_desc is not None:
+                params[prop_name] = DocstringParam(prop_name, prop_desc)
+
+        fields.sort(key=lambda t: t[2].default is not dataclasses.MISSING)
+        if sys.version_info >= (3, 12):
+            class_type = dataclasses.make_dataclass(class_name, fields, module=module.__name__)
+        else:
+            class_type = dataclasses.make_dataclass(class_name, fields, namespace={"__module__": module.__name__})
+        class_type.__doc__ = str(
+            Docstring(
+                short_description=node.title,
+                long_description=node.description,
+                params=params,
+            )
+        )
+        setattr(module, class_name, class_type)
+        return TypeDef(class_type, dataclasses.MISSING)
+
+    elif isinstance(node, JsonSchemaOneOf):
+        union_defs = tuple(node_to_typedef(module, context, n) for n in node.oneOf)
+        if any(d.default is not dataclasses.MISSING for d in union_defs):
+            raise TypeError("disallowed: `default` for union member type")
+        union_types = tuple(d.type for d in union_defs)
+        return TypeDef(Union[union_types], dataclasses.MISSING)
+
+    raise NotImplementedError()
+
+
+@dataclass
+class SchemaFlatteningOptions:
+    qualified_names: bool = False
+    recursive: bool = False
+
+
+def flatten_schema(schema: Schema, *, options: SchemaFlatteningOptions | None = None) -> Schema:
+    top_node = typing.cast(JsonSchemaTopLevelObject, json_to_object(JsonSchemaTopLevelObject, schema))
+    flattener = SchemaFlattener(options)
+    obj = flattener.flatten(top_node)
+    return typing.cast(Schema, object_to_json(obj))
+
+
+class SchemaFlattener:
+    options: SchemaFlatteningOptions
+
+    def __init__(self, options: SchemaFlatteningOptions | None = None) -> None:
+        self.options = options or SchemaFlatteningOptions()
+
+    def flatten(self, source_node: JsonSchemaObject) -> JsonSchemaObject:
+        if source_node.type != "object":
+            return source_node
+
+        source_props = source_node.properties or {}
+        target_props: dict[str, JsonSchemaAny] = {}
+
+        source_reqs = source_node.required or []
+        target_reqs: list[str] = []
+
+        for name, prop in source_props.items():
+            if not isinstance(prop, JsonSchemaObject):
+                target_props[name] = prop
+                if name in source_reqs:
+                    target_reqs.append(name)
+                continue
+
+            if self.options.recursive:
+                obj = self.flatten(prop)
+            else:
+                obj = prop
+            if obj.properties is not None:
+                if self.options.qualified_names:
+                    target_props.update((f"{name}.{n}", p) for n, p in obj.properties.items())
+                else:
+                    target_props.update(obj.properties.items())
+            if obj.required is not None:
+                if self.options.qualified_names:
+                    target_reqs.extend(f"{name}.{n}" for n in obj.required)
+                else:
+                    target_reqs.extend(obj.required)
+
+        target_node = copy.copy(source_node)
+        target_node.properties = target_props or None
+        target_node.additionalProperties = False
+        target_node.required = target_reqs or None
+        return target_node

src/llama_stack_api/strong_typing/core.py

@@ -0,0 +1,46 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+from typing import Union
+
+
+class JsonObject:
+    "Placeholder type for an unrestricted JSON object."
+
+
+class JsonArray:
+    "Placeholder type for an unrestricted JSON array."
+
+
+# a JSON type with possible `null` values
+JsonType = Union[
+    None,
+    bool,
+    int,
+    float,
+    str,
+    dict[str, "JsonType"],
+    list["JsonType"],
+]
+
+# a JSON type that cannot contain `null` values
+StrictJsonType = Union[
+    bool,
+    int,
+    float,
+    str,
+    dict[str, "StrictJsonType"],
+    list["StrictJsonType"],
+]
+
+# a meta-type that captures the object type in a JSON schema
+Schema = dict[str, JsonType]

src/llama_stack_api/strong_typing/deserializer.py

@@ -0,0 +1,872 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+import abc
+import base64
+import dataclasses
+import datetime
+import enum
+import inspect
+import ipaddress
+import sys
+import typing
+import uuid
+from collections.abc import Callable
+from types import ModuleType
+from typing import (
+    Any,
+    Generic,
+    Literal,
+    NamedTuple,
+    Optional,
+    TypeVar,
+    Union,
+)
+
+from .core import JsonType
+from .exception import JsonKeyError, JsonTypeError, JsonValueError
+from .inspection import (
+    TypeLike,
+    create_object,
+    enum_value_types,
+    evaluate_type,
+    get_class_properties,
+    get_class_property,
+    get_resolved_hints,
+    is_dataclass_instance,
+    is_dataclass_type,
+    is_named_tuple_type,
+    is_type_annotated,
+    is_type_literal,
+    is_type_optional,
+    unwrap_annotated_type,
+    unwrap_literal_values,
+    unwrap_optional_type,
+)
+from .mapping import python_field_to_json_property
+from .name import python_type_to_str
+
+E = TypeVar("E", bound=enum.Enum)
+T = TypeVar("T")
+R = TypeVar("R")
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class Deserializer(abc.ABC, Generic[T]):
+    "Parses a JSON value into a Python type."
+
+    def build(self, context: ModuleType | None) -> None:
+        """
+        Creates auxiliary parsers that this parser is depending on.
+
+        :param context: A module context for evaluating types specified as a string.
+        """
+
+    @abc.abstractmethod
+    def parse(self, data: JsonType) -> T:
+        """
+        Parses a JSON value into a Python type.
+
+        :param data: The JSON value to de-serialize.
+        :returns: The Python object that the JSON value de-serializes to.
+        """
+
+
+class NoneDeserializer(Deserializer[None]):
+    "Parses JSON `null` values into Python `None`."
+
+    def parse(self, data: JsonType) -> None:
+        if data is not None:
+            raise JsonTypeError(f"`None` type expects JSON `null` but instead received: {data}")
+        return None
+
+
+class BoolDeserializer(Deserializer[bool]):
+    "Parses JSON `boolean` values into Python `bool` type."
+
+    def parse(self, data: JsonType) -> bool:
+        if not isinstance(data, bool):
+            raise JsonTypeError(f"`bool` type expects JSON `boolean` data but instead received: {data}")
+        return bool(data)
+
+
+class IntDeserializer(Deserializer[int]):
+    "Parses JSON `number` values into Python `int` type."
+
+    def parse(self, data: JsonType) -> int:
+        if not isinstance(data, int):
+            raise JsonTypeError(f"`int` type expects integer data as JSON `number` but instead received: {data}")
+        return int(data)
+
+
+class FloatDeserializer(Deserializer[float]):
+    "Parses JSON `number` values into Python `float` type."
+
+    def parse(self, data: JsonType) -> float:
+        if not isinstance(data, float) and not isinstance(data, int):
+            raise JsonTypeError(f"`int` type expects data as JSON `number` but instead received: {data}")
+        return float(data)
+
+
+class StringDeserializer(Deserializer[str]):
+    "Parses JSON `string` values into Python `str` type."
+
+    def parse(self, data: JsonType) -> str:
+        if not isinstance(data, str):
+            raise JsonTypeError(f"`str` type expects JSON `string` data but instead received: {data}")
+        return str(data)
+
+
+class BytesDeserializer(Deserializer[bytes]):
+    "Parses JSON `string` values of Base64-encoded strings into Python `bytes` type."
+
+    def parse(self, data: JsonType) -> bytes:
+        if not isinstance(data, str):
+            raise JsonTypeError(f"`bytes` type expects JSON `string` data but instead received: {data}")
+        return base64.b64decode(data, validate=True)
+
+
+class DateTimeDeserializer(Deserializer[datetime.datetime]):
+    "Parses JSON `string` values representing timestamps in ISO 8601 format to Python `datetime` with time zone."
+
+    def parse(self, data: JsonType) -> datetime.datetime:
+        if not isinstance(data, str):
+            raise JsonTypeError(f"`datetime` type expects JSON `string` data but instead received: {data}")
+
+        if data.endswith("Z"):
+            data = f"{data[:-1]}+00:00"  # Python's isoformat() does not support military time zones like "Zulu" for UTC
+        timestamp = datetime.datetime.fromisoformat(data)
+        if timestamp.tzinfo is None:
+            raise JsonValueError(f"timestamp lacks explicit time zone designator: {data}")
+        return timestamp
+
+
+class DateDeserializer(Deserializer[datetime.date]):
+    "Parses JSON `string` values representing dates in ISO 8601 format to Python `date` type."
+
+    def parse(self, data: JsonType) -> datetime.date:
+        if not isinstance(data, str):
+            raise JsonTypeError(f"`date` type expects JSON `string` data but instead received: {data}")
+
+        return datetime.date.fromisoformat(data)
+
+
+class TimeDeserializer(Deserializer[datetime.time]):
+    "Parses JSON `string` values representing time instances in ISO 8601 format to Python `time` type with time zone."
+
+    def parse(self, data: JsonType) -> datetime.time:
+        if not isinstance(data, str):
+            raise JsonTypeError(f"`time` type expects JSON `string` data but instead received: {data}")
+
+        return datetime.time.fromisoformat(data)
+
+
+class UUIDDeserializer(Deserializer[uuid.UUID]):
+    "Parses JSON `string` values of UUID strings into Python `uuid.UUID` type."
+
+    def parse(self, data: JsonType) -> uuid.UUID:
+        if not isinstance(data, str):
+            raise JsonTypeError(f"`UUID` type expects JSON `string` data but instead received: {data}")
+        return uuid.UUID(data)
+
+
+class IPv4Deserializer(Deserializer[ipaddress.IPv4Address]):
+    "Parses JSON `string` values of IPv4 address strings into Python `ipaddress.IPv4Address` type."
+
+    def parse(self, data: JsonType) -> ipaddress.IPv4Address:
+        if not isinstance(data, str):
+            raise JsonTypeError(f"`IPv4Address` type expects JSON `string` data but instead received: {data}")
+        return ipaddress.IPv4Address(data)
+
+
+class IPv6Deserializer(Deserializer[ipaddress.IPv6Address]):
+    "Parses JSON `string` values of IPv6 address strings into Python `ipaddress.IPv6Address` type."
+
+    def parse(self, data: JsonType) -> ipaddress.IPv6Address:
+        if not isinstance(data, str):
+            raise JsonTypeError(f"`IPv6Address` type expects JSON `string` data but instead received: {data}")
+        return ipaddress.IPv6Address(data)
+
+
+class ListDeserializer(Deserializer[list[T]]):
+    "Recursively de-serializes a JSON array into a Python `list`."
+
+    item_type: type[T]
+    item_parser: Deserializer
+
+    def __init__(self, item_type: type[T]) -> None:
+        self.item_type = item_type
+
+    def build(self, context: ModuleType | None) -> None:
+        self.item_parser = _get_deserializer(self.item_type, context)
+
+    def parse(self, data: JsonType) -> list[T]:
+        if not isinstance(data, list):
+            type_name = python_type_to_str(self.item_type)
+            raise JsonTypeError(f"type `List[{type_name}]` expects JSON `array` data but instead received: {data}")
+
+        return [self.item_parser.parse(item) for item in data]
+
+
+class DictDeserializer(Deserializer[dict[K, V]]):
+    "Recursively de-serializes a JSON object into a Python `dict`."
+
+    key_type: type[K]
+    value_type: type[V]
+    value_parser: Deserializer[V]
+
+    def __init__(self, key_type: type[K], value_type: type[V]) -> None:
+        self.key_type = key_type
+        self.value_type = value_type
+        self._check_key_type()
+
+    def build(self, context: ModuleType | None) -> None:
+        self.value_parser = _get_deserializer(self.value_type, context)
+
+    def _check_key_type(self) -> None:
+        if self.key_type is str:
+            return
+
+        if issubclass(self.key_type, enum.Enum):
+            value_types = enum_value_types(self.key_type)
+            if len(value_types) != 1:
+                raise JsonTypeError(
+                    f"type `{self.container_type}` has invalid key type, "
+                    f"enumerations must have a consistent member value type but several types found: {value_types}"
+                )
+            value_type = value_types.pop()
+            if value_type is not str:
+                f"`type `{self.container_type}` has invalid enumeration key type, expected `enum.Enum` with string values"
+            return
+
+        raise JsonTypeError(
+            f"`type `{self.container_type}` has invalid key type, expected `str` or `enum.Enum` with string values"
+        )
+
+    @property
+    def container_type(self) -> str:
+        key_type_name = python_type_to_str(self.key_type)
+        value_type_name = python_type_to_str(self.value_type)
+        return f"Dict[{key_type_name}, {value_type_name}]"
+
+    def parse(self, data: JsonType) -> dict[K, V]:
+        if not isinstance(data, dict):
+            raise JsonTypeError(
+                f"`type `{self.container_type}` expects JSON `object` data but instead received: {data}"
+            )
+
+        return dict(
+            (self.key_type(key), self.value_parser.parse(value))  # type: ignore[call-arg]
+            for key, value in data.items()
+        )
+
+
+class SetDeserializer(Deserializer[set[T]]):
+    "Recursively de-serializes a JSON list into a Python `set`."
+
+    member_type: type[T]
+    member_parser: Deserializer
+
+    def __init__(self, member_type: type[T]) -> None:
+        self.member_type = member_type
+
+    def build(self, context: ModuleType | None) -> None:
+        self.member_parser = _get_deserializer(self.member_type, context)
+
+    def parse(self, data: JsonType) -> set[T]:
+        if not isinstance(data, list):
+            type_name = python_type_to_str(self.member_type)
+            raise JsonTypeError(f"type `Set[{type_name}]` expects JSON `array` data but instead received: {data}")
+
+        return set(self.member_parser.parse(item) for item in data)
+
+
+class TupleDeserializer(Deserializer[tuple[Any, ...]]):
+    "Recursively de-serializes a JSON list into a Python `tuple`."
+
+    item_types: tuple[type[Any], ...]
+    item_parsers: tuple[Deserializer[Any], ...]
+
+    def __init__(self, item_types: tuple[type[Any], ...]) -> None:
+        self.item_types = item_types
+
+    def build(self, context: ModuleType | None) -> None:
+        self.item_parsers = tuple(_get_deserializer(item_type, context) for item_type in self.item_types)
+
+    @property
+    def container_type(self) -> str:
+        type_names = ", ".join(python_type_to_str(item_type) for item_type in self.item_types)
+        return f"Tuple[{type_names}]"
+
+    def parse(self, data: JsonType) -> tuple[Any, ...]:
+        if not isinstance(data, list) or len(data) != len(self.item_parsers):
+            if not isinstance(data, list):
+                raise JsonTypeError(
+                    f"type `{self.container_type}` expects JSON `array` data but instead received: {data}"
+                )
+            else:
+                count = len(self.item_parsers)
+                raise JsonValueError(
+                    f"type `{self.container_type}` expects a JSON `array` of length {count} but received length {len(data)}"
+                )
+
+        return tuple(item_parser.parse(item) for item_parser, item in zip(self.item_parsers, data, strict=False))
+
+
+class UnionDeserializer(Deserializer):
+    "De-serializes a JSON value (of any type) into a Python union type."
+
+    member_types: tuple[type, ...]
+    member_parsers: tuple[Deserializer, ...]
+
+    def __init__(self, member_types: tuple[type, ...]) -> None:
+        self.member_types = member_types
+
+    def build(self, context: ModuleType | None) -> None:
+        self.member_parsers = tuple(_get_deserializer(member_type, context) for member_type in self.member_types)
+
+    def parse(self, data: JsonType) -> Any:
+        for member_parser in self.member_parsers:
+            # iterate over potential types of discriminated union
+            try:
+                return member_parser.parse(data)
+            except (JsonKeyError, JsonTypeError):
+                # indicates a required field is missing from JSON dict -OR- the data cannot be cast to the expected type,
+                # i.e. we don't have the type that we are looking for
+                continue
+
+        type_names = ", ".join(python_type_to_str(member_type) for member_type in self.member_types)
+        raise JsonKeyError(f"type `Union[{type_names}]` could not be instantiated from: {data}")
+
+
+def get_literal_properties(typ: type) -> set[str]:
+    "Returns the names of all properties in a class that are of a literal type."
+
+    return set(
+        property_name for property_name, property_type in get_class_properties(typ) if is_type_literal(property_type)
+    )
+
+
+def get_discriminating_properties(types: tuple[type, ...]) -> set[str]:
+    "Returns a set of properties with literal type that are common across all specified classes."
+
+    if not types or not all(isinstance(typ, type) for typ in types):
+        return set()
+
+    props = get_literal_properties(types[0])
+    for typ in types[1:]:
+        props = props & get_literal_properties(typ)
+
+    return props
+
+
+class TaggedUnionDeserializer(Deserializer):
+    "De-serializes a JSON value with one or more disambiguating properties into a Python union type."
+
+    member_types: tuple[type, ...]
+    disambiguating_properties: set[str]
+    member_parsers: dict[tuple[str, Any], Deserializer]
+
+    def __init__(self, member_types: tuple[type, ...]) -> None:
+        self.member_types = member_types
+        self.disambiguating_properties = get_discriminating_properties(member_types)
+
+    def build(self, context: ModuleType | None) -> None:
+        self.member_parsers = {}
+        for member_type in self.member_types:
+            for property_name in self.disambiguating_properties:
+                literal_type = get_class_property(member_type, property_name)
+                if not literal_type:
+                    continue
+
+                for literal_value in unwrap_literal_values(literal_type):
+                    tpl = (property_name, literal_value)
+                    if tpl in self.member_parsers:
+                        raise JsonTypeError(
+                            f"disambiguating property `{property_name}` in type `{self.union_type}` has a duplicate value: {literal_value}"
+                        )
+
+                    self.member_parsers[tpl] = _get_deserializer(member_type, context)
+
+    @property
+    def union_type(self) -> str:
+        type_names = ", ".join(python_type_to_str(member_type) for member_type in self.member_types)
+        return f"Union[{type_names}]"
+
+    def parse(self, data: JsonType) -> Any:
+        if not isinstance(data, dict):
+            raise JsonTypeError(
+                f"tagged union type `{self.union_type}` expects JSON `object` data but instead received: {data}"
+            )
+
+        for property_name in self.disambiguating_properties:
+            disambiguating_value = data.get(property_name)
+            if disambiguating_value is None:
+                continue
+
+            member_parser = self.member_parsers.get((property_name, disambiguating_value))
+            if member_parser is None:
+                raise JsonTypeError(
+                    f"disambiguating property value is invalid for tagged union type `{self.union_type}`: {data}"
+                )
+
+            return member_parser.parse(data)
+
+        raise JsonTypeError(
+            f"disambiguating property value is missing for tagged union type `{self.union_type}`: {data}"
+        )
+
+
+class LiteralDeserializer(Deserializer):
+    "De-serializes a JSON value into a Python literal type."
+
+    values: tuple[Any, ...]
+    parser: Deserializer
+
+    def __init__(self, values: tuple[Any, ...]) -> None:
+        self.values = values
+
+    def build(self, context: ModuleType | None) -> None:
+        literal_type_tuple = tuple(type(value) for value in self.values)
+        literal_type_set = set(literal_type_tuple)
+        if len(literal_type_set) != 1:
+            value_names = ", ".join(repr(value) for value in self.values)
+            raise TypeError(
+                f"type `Literal[{value_names}]` expects consistent literal value types but got: {literal_type_tuple}"
+            )
+
+        literal_type = literal_type_set.pop()
+        self.parser = _get_deserializer(literal_type, context)
+
+    def parse(self, data: JsonType) -> Any:
+        value = self.parser.parse(data)
+        if value not in self.values:
+            value_names = ", ".join(repr(value) for value in self.values)
+            raise JsonTypeError(f"type `Literal[{value_names}]` could not be instantiated from: {data}")
+        return value
+
+
+class EnumDeserializer(Deserializer[E]):
+    "Returns an enumeration instance based on the enumeration value read from a JSON value."
+
+    enum_type: type[E]
+
+    def __init__(self, enum_type: type[E]) -> None:
+        self.enum_type = enum_type
+
+    def parse(self, data: JsonType) -> E:
+        return self.enum_type(data)
+
+
+class CustomDeserializer(Deserializer[T]):
+    "Uses the `from_json` class method in class to de-serialize the object from JSON."
+
+    converter: Callable[[JsonType], T]
+
+    def __init__(self, converter: Callable[[JsonType], T]) -> None:
+        self.converter = converter
+
+    def parse(self, data: JsonType) -> T:
+        return self.converter(data)
+
+
+class FieldDeserializer(abc.ABC, Generic[T, R]):
+    """
+    Deserializes a JSON property into a Python object field.
+
+    :param property_name: The name of the JSON property to read from a JSON `object`.
+    :param field_name: The name of the field in a Python class to write data to.
+    :param parser: A compatible deserializer that can handle the field's type.
+    """
+
+    property_name: str
+    field_name: str
+    parser: Deserializer[T]
+
+    def __init__(self, property_name: str, field_name: str, parser: Deserializer[T]) -> None:
+        self.property_name = property_name
+        self.field_name = field_name
+        self.parser = parser
+
+    @abc.abstractmethod
+    def parse_field(self, data: dict[str, JsonType]) -> R: ...
+
+
+class RequiredFieldDeserializer(FieldDeserializer[T, T]):
+    "Deserializes a JSON property into a mandatory Python object field."
+
+    def parse_field(self, data: dict[str, JsonType]) -> T:
+        if self.property_name not in data:
+            raise JsonKeyError(f"missing required property `{self.property_name}` from JSON object: {data}")
+
+        return self.parser.parse(data[self.property_name])
+
+
+class OptionalFieldDeserializer(FieldDeserializer[T, Optional[T]]):
+    "Deserializes a JSON property into an optional Python object field with a default value of `None`."
+
+    def parse_field(self, data: dict[str, JsonType]) -> T | None:
+        value = data.get(self.property_name)
+        if value is not None:
+            return self.parser.parse(value)
+        else:
+            return None
+
+
+class DefaultFieldDeserializer(FieldDeserializer[T, T]):
+    "Deserializes a JSON property into a Python object field with an explicit default value."
+
+    default_value: T
+
+    def __init__(
+        self,
+        property_name: str,
+        field_name: str,
+        parser: Deserializer,
+        default_value: T,
+    ) -> None:
+        super().__init__(property_name, field_name, parser)
+        self.default_value = default_value
+
+    def parse_field(self, data: dict[str, JsonType]) -> T:
+        value = data.get(self.property_name)
+        if value is not None:
+            return self.parser.parse(value)
+        else:
+            return self.default_value
+
+
+class DefaultFactoryFieldDeserializer(FieldDeserializer[T, T]):
+    "Deserializes a JSON property into an optional Python object field with an explicit default value factory."
+
+    default_factory: Callable[[], T]
+
+    def __init__(
+        self,
+        property_name: str,
+        field_name: str,
+        parser: Deserializer[T],
+        default_factory: Callable[[], T],
+    ) -> None:
+        super().__init__(property_name, field_name, parser)
+        self.default_factory = default_factory
+
+    def parse_field(self, data: dict[str, JsonType]) -> T:
+        value = data.get(self.property_name)
+        if value is not None:
+            return self.parser.parse(value)
+        else:
+            return self.default_factory()
+
+
+class ClassDeserializer(Deserializer[T]):
+    "Base class for de-serializing class-like types such as data classes, named tuples and regular classes."
+
+    class_type: type
+    property_parsers: list[FieldDeserializer]
+    property_fields: set[str]
+
+    def __init__(self, class_type: type[T]) -> None:
+        self.class_type = class_type
+
+    def assign(self, property_parsers: list[FieldDeserializer]) -> None:
+        self.property_parsers = property_parsers
+        self.property_fields = set(property_parser.property_name for property_parser in property_parsers)
+
+    def parse(self, data: JsonType) -> T:
+        if not isinstance(data, dict):
+            type_name = python_type_to_str(self.class_type)
+            raise JsonTypeError(f"`type `{type_name}` expects JSON `object` data but instead received: {data}")
+
+        object_data: dict[str, JsonType] = typing.cast(dict[str, JsonType], data)
+
+        field_values = {}
+        for property_parser in self.property_parsers:
+            field_values[property_parser.field_name] = property_parser.parse_field(object_data)
+
+        if not self.property_fields.issuperset(object_data):
+            unassigned_names = [name for name in object_data if name not in self.property_fields]
+            raise JsonKeyError(f"unrecognized fields in JSON object: {unassigned_names}")
+
+        return self.create(**field_values)
+
+    def create(self, **field_values: Any) -> T:
+        "Instantiates an object with a collection of property values."
+
+        obj: T = create_object(self.class_type)
+
+        # use `setattr` on newly created object instance
+        for field_name, field_value in field_values.items():
+            setattr(obj, field_name, field_value)
+        return obj
+
+
+class NamedTupleDeserializer(ClassDeserializer[NamedTuple]):
+    "De-serializes a named tuple from a JSON `object`."
+
+    def build(self, context: ModuleType | None) -> None:
+        property_parsers: list[FieldDeserializer] = [
+            RequiredFieldDeserializer(field_name, field_name, _get_deserializer(field_type, context))
+            for field_name, field_type in get_resolved_hints(self.class_type).items()
+        ]
+        super().assign(property_parsers)
+
+    def create(self, **field_values: Any) -> NamedTuple:
+        # mypy fails to deduce that this class returns NamedTuples only, hence the `ignore` directive
+        return self.class_type(**field_values)  # type: ignore[no-any-return]
+
+
+class DataclassDeserializer(ClassDeserializer[T]):
+    "De-serializes a data class from a JSON `object`."
+
+    def __init__(self, class_type: type[T]) -> None:
+        if not dataclasses.is_dataclass(class_type):
+            raise TypeError("expected: data-class type")
+        super().__init__(class_type)  # type: ignore[arg-type]
+
+    def build(self, context: ModuleType | None) -> None:
+        property_parsers: list[FieldDeserializer] = []
+        resolved_hints = get_resolved_hints(self.class_type)
+        for field in dataclasses.fields(self.class_type):
+            field_type = resolved_hints[field.name]
+            property_name = python_field_to_json_property(field.name, field_type)
+
+            is_optional = is_type_optional(field_type)
+            has_default = field.default is not dataclasses.MISSING
+            has_default_factory = field.default_factory is not dataclasses.MISSING
+
+            if is_optional:
+                required_type: type[T] = unwrap_optional_type(field_type)
+            else:
+                required_type = field_type
+
+            parser = _get_deserializer(required_type, context)
+
+            if has_default:
+                field_parser: FieldDeserializer = DefaultFieldDeserializer(
+                    property_name, field.name, parser, field.default
+                )
+            elif has_default_factory:
+                default_factory = typing.cast(Callable[[], Any], field.default_factory)
+                field_parser = DefaultFactoryFieldDeserializer(property_name, field.name, parser, default_factory)
+            elif is_optional:
+                field_parser = OptionalFieldDeserializer(property_name, field.name, parser)
+            else:
+                field_parser = RequiredFieldDeserializer(property_name, field.name, parser)
+
+            property_parsers.append(field_parser)
+
+        super().assign(property_parsers)
+
+
+class FrozenDataclassDeserializer(DataclassDeserializer[T]):
+    "De-serializes a frozen data class from a JSON `object`."
+
+    def create(self, **field_values: Any) -> T:
+        "Instantiates an object with a collection of property values."
+
+        # create object instance without calling `__init__`
+        obj: T = create_object(self.class_type)
+
+        # can't use `setattr` on frozen dataclasses, pass member variable values to `__init__`
+        obj.__init__(**field_values)  # type: ignore
+        return obj
+
+
+class TypedClassDeserializer(ClassDeserializer[T]):
+    "De-serializes a class with type annotations from a JSON `object` by iterating over class properties."
+
+    def build(self, context: ModuleType | None) -> None:
+        property_parsers: list[FieldDeserializer] = []
+        for field_name, field_type in get_resolved_hints(self.class_type).items():
+            property_name = python_field_to_json_property(field_name, field_type)
+
+            is_optional = is_type_optional(field_type)
+
+            if is_optional:
+                required_type: type[T] = unwrap_optional_type(field_type)
+            else:
+                required_type = field_type
+
+            parser = _get_deserializer(required_type, context)
+
+            if is_optional:
+                field_parser: FieldDeserializer = OptionalFieldDeserializer(property_name, field_name, parser)
+            else:
+                field_parser = RequiredFieldDeserializer(property_name, field_name, parser)
+
+            property_parsers.append(field_parser)
+
+        super().assign(property_parsers)
+
+
+def create_deserializer(typ: TypeLike, context: ModuleType | None = None) -> Deserializer:
+    """
+    Creates a de-serializer engine to produce a Python object from an object obtained from a JSON string.
+
+    When de-serializing a JSON object into a Python object, the following transformations are applied:
+
+    * Fundamental types are parsed as `bool`, `int`, `float` or `str`.
+    * Date and time types are parsed from the ISO 8601 format with time zone into the corresponding Python type
+      `datetime`, `date` or `time`.
+    * Byte arrays are read from a string with Base64 encoding into a `bytes` instance.
+    * UUIDs are extracted from a UUID string compliant with RFC 4122 into a `uuid.UUID` instance.
+    * Enumerations are instantiated with a lookup on enumeration value.
+    * Containers (e.g. `list`, `dict`, `set`, `tuple`) are parsed recursively.
+    * Complex objects with properties (including data class types) are populated from dictionaries of key-value pairs
+      using reflection (enumerating type annotations).
+
+    :raises TypeError: A de-serializer engine cannot be constructed for the input type.
+    """
+
+    if context is None:
+        if isinstance(typ, type):
+            context = sys.modules[typ.__module__]
+
+    return _get_deserializer(typ, context)
+
+
+_CACHE: dict[tuple[str, str], Deserializer] = {}
+
+
+def _get_deserializer(typ: TypeLike, context: ModuleType | None) -> Deserializer:
+    "Creates or re-uses a de-serializer engine to parse an object obtained from a JSON string."
+
+    cache_key = None
+
+    if isinstance(typ, (str, typing.ForwardRef)):
+        if context is None:
+            raise TypeError(f"missing context for evaluating type: {typ}")
+
+        if isinstance(typ, str):
+            if hasattr(context, typ):
+                cache_key = (context.__name__, typ)
+        elif isinstance(typ, typing.ForwardRef):
+            if hasattr(context, typ.__forward_arg__):
+                cache_key = (context.__name__, typ.__forward_arg__)
+
+        typ = evaluate_type(typ, context)
+
+    typ = unwrap_annotated_type(typ) if is_type_annotated(typ) else typ
+
+    if isinstance(typ, type) and typing.get_origin(typ) is None:
+        cache_key = (typ.__module__, typ.__name__)
+
+    if cache_key is not None:
+        deserializer = _CACHE.get(cache_key)
+        if deserializer is None:
+            deserializer = _create_deserializer(typ)
+
+            # store de-serializer immediately in cache to avoid stack overflow for recursive types
+            _CACHE[cache_key] = deserializer
+
+            if isinstance(typ, type):
+                # use type's own module as context for evaluating member types
+                context = sys.modules[typ.__module__]
+
+            # create any de-serializers this de-serializer is depending on
+            deserializer.build(context)
+    else:
+        # special forms are not always hashable, create a new de-serializer every time
+        deserializer = _create_deserializer(typ)
+        deserializer.build(context)
+
+    return deserializer
+
+
+def _create_deserializer(typ: TypeLike) -> Deserializer:
+    "Creates a de-serializer engine to parse an object obtained from a JSON string."
+
+    # check for well-known types
+    if typ is type(None):
+        return NoneDeserializer()
+    elif typ is bool:
+        return BoolDeserializer()
+    elif typ is int:
+        return IntDeserializer()
+    elif typ is float:
+        return FloatDeserializer()
+    elif typ is str:
+        return StringDeserializer()
+    elif typ is bytes:
+        return BytesDeserializer()
+    elif typ is datetime.datetime:
+        return DateTimeDeserializer()
+    elif typ is datetime.date:
+        return DateDeserializer()
+    elif typ is datetime.time:
+        return TimeDeserializer()
+    elif typ is uuid.UUID:
+        return UUIDDeserializer()
+    elif typ is ipaddress.IPv4Address:
+        return IPv4Deserializer()
+    elif typ is ipaddress.IPv6Address:
+        return IPv6Deserializer()
+
+    # dynamically-typed collection types
+    if typ is list:
+        raise TypeError("explicit item type required: use `List[T]` instead of `list`")
+    if typ is dict:
+        raise TypeError("explicit key and value types required: use `Dict[K, V]` instead of `dict`")
+    if typ is set:
+        raise TypeError("explicit member type required: use `Set[T]` instead of `set`")
+    if typ is tuple:
+        raise TypeError("explicit item type list required: use `Tuple[T, ...]` instead of `tuple`")
+
+    # generic types (e.g. list, dict, set, etc.)
+    origin_type = typing.get_origin(typ)
+    if origin_type is list:
+        (list_item_type,) = typing.get_args(typ)  # unpack single tuple element
+        return ListDeserializer(list_item_type)
+    elif origin_type is dict:
+        key_type, value_type = typing.get_args(typ)
+        return DictDeserializer(key_type, value_type)
+    elif origin_type is set:
+        (set_member_type,) = typing.get_args(typ)  # unpack single tuple element
+        return SetDeserializer(set_member_type)
+    elif origin_type is tuple:
+        return TupleDeserializer(typing.get_args(typ))
+    elif origin_type is Union:
+        union_args = typing.get_args(typ)
+        if get_discriminating_properties(union_args):
+            return TaggedUnionDeserializer(union_args)
+        else:
+            return UnionDeserializer(union_args)
+    elif origin_type is Literal:
+        return LiteralDeserializer(typing.get_args(typ))
+
+    if not inspect.isclass(typ):
+        if is_dataclass_instance(typ):
+            raise TypeError(f"dataclass type expected but got instance: {typ}")
+        else:
+            raise TypeError(f"unable to de-serialize unrecognized type: {typ}")
+
+    if issubclass(typ, enum.Enum):
+        return EnumDeserializer(typ)
+
+    if is_named_tuple_type(typ):
+        return NamedTupleDeserializer(typ)
+
+    # check if object has custom serialization method
+    convert_func = getattr(typ, "from_json", None)
+    if callable(convert_func):
+        return CustomDeserializer(convert_func)
+
+    if is_dataclass_type(typ):
+        dataclass_params = getattr(typ, "__dataclass_params__", None)
+        if dataclass_params is not None and dataclass_params.frozen:
+            return FrozenDataclassDeserializer(typ)
+        else:
+            return DataclassDeserializer(typ)
+
+    return TypedClassDeserializer(typ)

src/llama_stack_api/strong_typing/docstring.py

@@ -0,0 +1,410 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+import builtins
+import collections.abc
+import dataclasses
+import inspect
+import re
+import sys
+import types
+import typing
+from collections.abc import Callable
+from dataclasses import dataclass
+from io import StringIO
+from typing import Any, Protocol, TypeVar
+
+if sys.version_info >= (3, 10):
+    from typing import TypeGuard
+else:
+    from typing import TypeGuard
+
+from .inspection import (
+    DataclassInstance,
+    get_class_properties,
+    get_signature,
+    is_dataclass_type,
+    is_type_enum,
+)
+
+T = TypeVar("T")
+
+
+@dataclass
+class DocstringParam:
+    """
+    A parameter declaration in a parameter block.
+
+    :param name: The name of the parameter.
+    :param description: The description text for the parameter.
+    """
+
+    name: str
+    description: str
+    param_type: type | str = inspect.Signature.empty
+
+    def __str__(self) -> str:
+        return f":param {self.name}: {self.description}"
+
+
+@dataclass
+class DocstringReturns:
+    """
+    A `returns` declaration extracted from a docstring.
+
+    :param description: The description text for the return value.
+    """
+
+    description: str
+    return_type: type = inspect.Signature.empty
+
+    def __str__(self) -> str:
+        return f":returns: {self.description}"
+
+
+@dataclass
+class DocstringRaises:
+    """
+    A `raises` declaration extracted from a docstring.
+
+    :param typename: The type name of the exception raised.
+    :param description: The description associated with the exception raised.
+    """
+
+    typename: str
+    description: str
+    raise_type: type = inspect.Signature.empty
+
+    def __str__(self) -> str:
+        return f":raises {self.typename}: {self.description}"
+
+
+@dataclass
+class Docstring:
+    """
+    Represents the documentation string (a.k.a. docstring) for a type such as a (data) class or function.
+
+    A docstring is broken down into the following components:
+    * A short description, which is the first block of text in the documentation string, and ends with a double
+      newline or a parameter block.
+    * A long description, which is the optional block of text following the short description, and ends with
+      a parameter block.
+    * A parameter block of named parameter and description string pairs in ReST-style.
+    * A `returns` declaration, which adds explanation to the return value.
+    * A `raises` declaration, which adds explanation to the exception type raised by the function on error.
+
+    When the docstring is attached to a data class, it is understood as the documentation string of the class
+    `__init__` method.
+
+    :param short_description: The short description text parsed from a docstring.
+    :param long_description: The long description text parsed from a docstring.
+    :param params: The parameter block extracted from a docstring.
+    :param returns: The returns declaration extracted from a docstring.
+    """
+
+    short_description: str | None = None
+    long_description: str | None = None
+    params: dict[str, DocstringParam] = dataclasses.field(default_factory=dict)
+    returns: DocstringReturns | None = None
+    raises: dict[str, DocstringRaises] = dataclasses.field(default_factory=dict)
+
+    @property
+    def full_description(self) -> str | None:
+        if self.short_description and self.long_description:
+            return f"{self.short_description}\n\n{self.long_description}"
+        elif self.short_description:
+            return self.short_description
+        else:
+            return None
+
+    def __str__(self) -> str:
+        output = StringIO()
+
+        has_description = self.short_description or self.long_description
+        has_blocks = self.params or self.returns or self.raises
+
+        if has_description:
+            if self.short_description and self.long_description:
+                output.write(self.short_description)
+                output.write("\n\n")
+                output.write(self.long_description)
+            elif self.short_description:
+                output.write(self.short_description)
+
+        if has_blocks:
+            if has_description:
+                output.write("\n")
+
+            for param in self.params.values():
+                output.write("\n")
+                output.write(str(param))
+            if self.returns:
+                output.write("\n")
+                output.write(str(self.returns))
+            for raises in self.raises.values():
+                output.write("\n")
+                output.write(str(raises))
+
+        s = output.getvalue()
+        output.close()
+        return s
+
+
+def is_exception(member: object) -> TypeGuard[type[BaseException]]:
+    return isinstance(member, type) and issubclass(member, BaseException)
+
+
+def get_exceptions(module: types.ModuleType) -> dict[str, type[BaseException]]:
+    "Returns all exception classes declared in a module."
+
+    return {name: class_type for name, class_type in inspect.getmembers(module, is_exception)}
+
+
+class SupportsDoc(Protocol):
+    __doc__: str | None
+
+
+def _maybe_unwrap_async_iterator(t):
+    origin_type = typing.get_origin(t)
+    if origin_type is collections.abc.AsyncIterator:
+        return typing.get_args(t)[0]
+    return t
+
+
+def parse_type(typ: SupportsDoc) -> Docstring:
+    """
+    Parse the docstring of a type into its components.
+
+    :param typ: The type whose documentation string to parse.
+    :returns: Components of the documentation string.
+    """
+    # Use docstring from the iterator origin type for streaming apis
+    typ = _maybe_unwrap_async_iterator(typ)
+
+    doc = get_docstring(typ)
+    if doc is None:
+        return Docstring()
+
+    docstring = parse_text(doc)
+    check_docstring(typ, docstring)
+
+    # assign parameter and return types
+    if is_dataclass_type(typ):
+        properties = dict(get_class_properties(typing.cast(type, typ)))
+
+        for name, param in docstring.params.items():
+            param.param_type = properties[name]
+
+    elif inspect.isfunction(typ):
+        signature = get_signature(typ)
+        for name, param in docstring.params.items():
+            param.param_type = signature.parameters[name].annotation
+        if docstring.returns:
+            docstring.returns.return_type = signature.return_annotation
+
+    # assign exception types
+    defining_module = inspect.getmodule(typ)
+    if defining_module:
+        context: dict[str, type] = {}
+        context.update(get_exceptions(builtins))
+        context.update(get_exceptions(defining_module))
+        for exc_name, exc in docstring.raises.items():
+            raise_type = context.get(exc_name)
+            if raise_type is None:
+                type_name = getattr(typ, "__qualname__", None) or getattr(typ, "__name__", None) or None
+                raise TypeError(
+                    f"doc-string exception type `{exc_name}` is not an exception defined in the context of `{type_name}`"
+                )
+
+            exc.raise_type = raise_type
+
+    return docstring
+
+
+def parse_text(text: str) -> Docstring:
+    """
+    Parse a ReST-style docstring into its components.
+
+    :param text: The documentation string to parse, typically acquired as `type.__doc__`.
+    :returns: Components of the documentation string.
+    """
+
+    if not text:
+        return Docstring()
+
+    # find block that starts object metadata block (e.g. `:param p:` or `:returns:`)
+    text = inspect.cleandoc(text)
+    match = re.search("^:", text, flags=re.MULTILINE)
+    if match:
+        desc_chunk = text[: match.start()]
+        meta_chunk = text[match.start() :]  # noqa: E203
+    else:
+        desc_chunk = text
+        meta_chunk = ""
+
+    # split description text into short and long description
+    parts = desc_chunk.split("\n\n", 1)
+
+    # ensure short description has no newlines
+    short_description = parts[0].strip().replace("\n", " ") or None
+
+    # ensure long description preserves its structure (e.g. preformatted text)
+    if len(parts) > 1:
+        long_description = parts[1].strip() or None
+    else:
+        long_description = None
+
+    params: dict[str, DocstringParam] = {}
+    raises: dict[str, DocstringRaises] = {}
+    returns = None
+    for match in re.finditer(r"(^:.*?)(?=^:|\Z)", meta_chunk, flags=re.DOTALL | re.MULTILINE):
+        chunk = match.group(0)
+        if not chunk:
+            continue
+
+        args_chunk, desc_chunk = chunk.lstrip(":").split(":", 1)
+        args = args_chunk.split()
+        desc = re.sub(r"\s+", " ", desc_chunk.strip())
+
+        if len(args) > 0:
+            kw = args[0]
+            if len(args) == 2:
+                if kw == "param":
+                    params[args[1]] = DocstringParam(
+                        name=args[1],
+                        description=desc,
+                    )
+                elif kw == "raise" or kw == "raises":
+                    raises[args[1]] = DocstringRaises(
+                        typename=args[1],
+                        description=desc,
+                    )
+
+            elif len(args) == 1:
+                if kw == "return" or kw == "returns":
+                    returns = DocstringReturns(description=desc)
+
+    return Docstring(
+        long_description=long_description,
+        short_description=short_description,
+        params=params,
+        returns=returns,
+        raises=raises,
+    )
+
+
+def has_default_docstring(typ: SupportsDoc) -> bool:
+    "Check if class has the auto-generated string assigned by @dataclass."
+
+    if not isinstance(typ, type):
+        return False
+
+    if is_dataclass_type(typ):
+        return typ.__doc__ is not None and re.match(f"^{re.escape(typ.__name__)}[(].*[)]$", typ.__doc__) is not None
+
+    if is_type_enum(typ):
+        return typ.__doc__ is not None and typ.__doc__ == "An enumeration."
+
+    return False
+
+
+def has_docstring(typ: SupportsDoc) -> bool:
+    "Check if class has a documentation string other than the auto-generated string assigned by @dataclass."
+
+    if has_default_docstring(typ):
+        return False
+
+    return bool(typ.__doc__)
+
+
+def get_docstring(typ: SupportsDoc) -> str | None:
+    if typ.__doc__ is None:
+        return None
+
+    if has_default_docstring(typ):
+        return None
+
+    return typ.__doc__
+
+
+def check_docstring(typ: SupportsDoc, docstring: Docstring, strict: bool = False) -> None:
+    """
+    Verifies the doc-string of a type.
+
+    :raises TypeError: Raised on a mismatch between doc-string parameters, and function or type signature.
+    """
+
+    if is_dataclass_type(typ):
+        check_dataclass_docstring(typ, docstring, strict)
+    elif inspect.isfunction(typ):
+        check_function_docstring(typ, docstring, strict)
+
+
+def check_dataclass_docstring(typ: type[DataclassInstance], docstring: Docstring, strict: bool = False) -> None:
+    """
+    Verifies the doc-string of a data-class type.
+
+    :param strict: Whether to check if all data-class members have doc-strings.
+    :raises TypeError: Raised on a mismatch between doc-string parameters and data-class members.
+    """
+
+    if not is_dataclass_type(typ):
+        raise TypeError("not a data-class type")
+
+    properties = dict(get_class_properties(typ))
+    class_name = typ.__name__
+
+    for name in docstring.params:
+        if name not in properties:
+            raise TypeError(f"doc-string parameter `{name}` is not a member of the data-class `{class_name}`")
+
+    if not strict:
+        return
+
+    for name in properties:
+        if name not in docstring.params:
+            raise TypeError(f"member `{name}` in data-class `{class_name}` is missing its doc-string")
+
+
+def check_function_docstring(fn: Callable[..., Any], docstring: Docstring, strict: bool = False) -> None:
+    """
+    Verifies the doc-string of a function or member function.
+
+    :param strict: Whether to check if all function parameters and the return type have doc-strings.
+    :raises TypeError: Raised on a mismatch between doc-string parameters and function signature.
+    """
+
+    signature = get_signature(fn)
+    func_name = fn.__qualname__
+
+    for name in docstring.params:
+        if name not in signature.parameters:
+            raise TypeError(f"doc-string parameter `{name}` is absent from signature of function `{func_name}`")
+
+    if docstring.returns is not None and signature.return_annotation is inspect.Signature.empty:
+        raise TypeError(f"doc-string has returns description in function `{func_name}` with no return type annotation")
+
+    if not strict:
+        return
+
+    for name, param in signature.parameters.items():
+        # ignore `self` in member function signatures
+        if name == "self" and (
+            param.kind is inspect.Parameter.POSITIONAL_ONLY or param.kind is inspect.Parameter.POSITIONAL_OR_KEYWORD
+        ):
+            continue
+
+        if name not in docstring.params:
+            raise TypeError(f"function parameter `{name}` in `{func_name}` is missing its doc-string")
+
+    if signature.return_annotation is not inspect.Signature.empty and docstring.returns is None:
+        raise TypeError(f"function `{func_name}` has no returns description in its doc-string")

src/llama_stack_api/strong_typing/exception.py

@@ -0,0 +1,23 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+
+class JsonKeyError(Exception):
+    "Raised when deserialization for a class or union type has failed because a matching member was not found."
+
+
+class JsonValueError(Exception):
+    "Raised when (de)serialization of data has failed due to invalid value."
+
+
+class JsonTypeError(Exception):
+    "Raised when deserialization of data has failed due to a type mismatch."

src/llama_stack_api/strong_typing/mapping.py

@@ -0,0 +1,39 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+import keyword
+
+from .auxiliary import Alias
+from .inspection import get_annotation
+
+
+def python_field_to_json_property(python_id: str, python_type: object | None = None) -> str:
+    """
+    Map a Python field identifier to a JSON property name.
+
+    Authors may use an underscore appended at the end of a Python identifier as per PEP 8 if it clashes with a Python
+    keyword: e.g. `in` would become `in_` and `from` would become `from_`. Remove these suffixes when exporting to JSON.
+
+    Authors may supply an explicit alias with the type annotation `Alias`, e.g. `Annotated[MyType, Alias("alias")]`.
+    """
+
+    if python_type is not None:
+        alias = get_annotation(python_type, Alias)
+        if alias:
+            return alias.name
+
+    if python_id.endswith("_"):
+        id = python_id[:-1]
+        if keyword.iskeyword(id):
+            return id
+
+    return python_id

src/llama_stack_api/strong_typing/name.py

@@ -0,0 +1,188 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+import typing
+from typing import Any, Literal, Union
+
+from .auxiliary import _auxiliary_types
+from .inspection import (
+    TypeLike,
+    is_generic_dict,
+    is_generic_list,
+    is_generic_sequence,
+    is_type_optional,
+    is_type_union,
+    unwrap_generic_dict,
+    unwrap_generic_list,
+    unwrap_generic_sequence,
+    unwrap_optional_type,
+    unwrap_union_types,
+)
+
+
+class TypeFormatter:
+    """
+    Type formatter.
+
+    :param use_union_operator: Whether to emit union types as `X | Y` as per PEP 604.
+    """
+
+    use_union_operator: bool
+
+    def __init__(self, use_union_operator: bool = False) -> None:
+        self.use_union_operator = use_union_operator
+
+    def union_to_str(self, data_type_args: tuple[TypeLike, ...]) -> str:
+        if self.use_union_operator:
+            return " | ".join(self.python_type_to_str(t) for t in data_type_args)
+        else:
+            if len(data_type_args) == 2 and type(None) in data_type_args:
+                # Optional[T] is represented as Union[T, None]
+                origin_name = "Optional"
+                data_type_args = tuple(t for t in data_type_args if t is not type(None))
+            else:
+                origin_name = "Union"
+
+            args = ", ".join(self.python_type_to_str(t) for t in data_type_args)
+            return f"{origin_name}[{args}]"
+
+    def plain_type_to_str(self, data_type: TypeLike) -> str:
+        "Returns the string representation of a Python type without metadata."
+
+        # return forward references as the annotation string
+        if isinstance(data_type, typing.ForwardRef):
+            fwd: typing.ForwardRef = data_type
+            return fwd.__forward_arg__
+        elif isinstance(data_type, str):
+            return data_type
+
+        origin = typing.get_origin(data_type)
+        if origin is not None:
+            data_type_args = typing.get_args(data_type)
+
+            if origin is dict:  # Dict[T]
+                origin_name = "Dict"
+            elif origin is list:  # List[T]
+                origin_name = "List"
+            elif origin is set:  # Set[T]
+                origin_name = "Set"
+            elif origin is Union:
+                return self.union_to_str(data_type_args)
+            elif origin is Literal:
+                args = ", ".join(repr(arg) for arg in data_type_args)
+                return f"Literal[{args}]"
+            else:
+                origin_name = origin.__name__
+
+            args = ", ".join(self.python_type_to_str(t) for t in data_type_args)
+            return f"{origin_name}[{args}]"
+
+        return data_type.__name__
+
+    def python_type_to_str(self, data_type: TypeLike) -> str:
+        "Returns the string representation of a Python type."
+
+        if data_type is type(None):
+            return "None"
+
+        # use compact name for alias types
+        name = _auxiliary_types.get(data_type)
+        if name is not None:
+            return name
+
+        metadata = getattr(data_type, "__metadata__", None)
+        if metadata is not None:
+            # type is Annotated[T, ...]
+            metatuple: tuple[Any, ...] = metadata
+            arg = typing.get_args(data_type)[0]
+
+            # check for auxiliary types with user-defined annotations
+            metaset = set(metatuple)
+            for auxiliary_type, auxiliary_name in _auxiliary_types.items():
+                auxiliary_arg = typing.get_args(auxiliary_type)[0]
+                if arg is not auxiliary_arg:
+                    continue
+
+                auxiliary_metatuple: tuple[Any, ...] | None = getattr(auxiliary_type, "__metadata__", None)
+                if auxiliary_metatuple is None:
+                    continue
+
+                if metaset.issuperset(auxiliary_metatuple):
+                    # type is an auxiliary type with extra annotations
+                    auxiliary_args = ", ".join(repr(m) for m in metatuple if m not in auxiliary_metatuple)
+                    return f"Annotated[{auxiliary_name}, {auxiliary_args}]"
+
+            # type is an annotated type
+            args = ", ".join(repr(m) for m in metatuple)
+            return f"Annotated[{self.plain_type_to_str(arg)}, {args}]"
+        else:
+            # type is a regular type
+            return self.plain_type_to_str(data_type)
+
+
+def python_type_to_str(data_type: TypeLike, use_union_operator: bool = False) -> str:
+    """
+    Returns the string representation of a Python type.
+
+    :param use_union_operator: Whether to emit union types as `X | Y` as per PEP 604.
+    """
+
+    fmt = TypeFormatter(use_union_operator)
+    return fmt.python_type_to_str(data_type)
+
+
+def python_type_to_name(data_type: TypeLike, force: bool = False) -> str:
+    """
+    Returns the short name of a Python type.
+
+    :param force: Whether to produce a name for composite types such as generics.
+    """
+
+    # use compact name for alias types
+    name = _auxiliary_types.get(data_type)
+    if name is not None:
+        return name
+
+    # unwrap annotated types
+    metadata = getattr(data_type, "__metadata__", None)
+    if metadata is not None:
+        # type is Annotated[T, ...]
+        arg = typing.get_args(data_type)[0]
+        return python_type_to_name(arg, force=force)
+
+    if force:
+        # generic types
+        if is_type_optional(data_type, strict=True):
+            inner_name = python_type_to_name(unwrap_optional_type(data_type), force=True)
+            return f"Optional__{inner_name}"
+        elif is_generic_list(data_type):
+            item_name = python_type_to_name(unwrap_generic_list(data_type), force=True)
+            return f"List__{item_name}"
+        elif is_generic_sequence(data_type):
+            # Treat Sequence the same as List for schema generation purposes
+            item_name = python_type_to_name(unwrap_generic_sequence(data_type), force=True)
+            return f"List__{item_name}"
+        elif is_generic_dict(data_type):
+            key_type, value_type = unwrap_generic_dict(data_type)
+            key_name = python_type_to_name(key_type, force=True)
+            value_name = python_type_to_name(value_type, force=True)
+            return f"Dict__{key_name}__{value_name}"
+        elif is_type_union(data_type):
+            member_types = unwrap_union_types(data_type)
+            member_names = "__".join(python_type_to_name(member_type, force=True) for member_type in member_types)
+            return f"Union__{member_names}"
+
+    # named system or user-defined type
+    if hasattr(data_type, "__name__") and not typing.get_args(data_type):
+        return data_type.__name__
+
+    raise TypeError(f"cannot assign a simple name to type: {data_type}")

src/llama_stack_api/strong_typing/schema.py

@@ -0,0 +1,791 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+import collections.abc
+import dataclasses
+import datetime
+import decimal
+import enum
+import functools
+import inspect
+import json
+import types
+import typing
+import uuid
+from collections.abc import Callable
+from copy import deepcopy
+from typing import (
+    Annotated,
+    Any,
+    ClassVar,
+    Literal,
+    TypeVar,
+    Union,
+    overload,
+)
+
+import jsonschema
+
+from . import docstring
+from .auxiliary import (
+    Alias,
+    IntegerRange,
+    MaxLength,
+    MinLength,
+    Precision,
+    get_auxiliary_format,
+)
+from .core import JsonArray, JsonObject, JsonType, Schema, StrictJsonType
+from .inspection import (
+    TypeLike,
+    enum_value_types,
+    get_annotation,
+    get_class_properties,
+    is_type_enum,
+    is_type_like,
+    is_type_optional,
+    unwrap_optional_type,
+)
+from .name import python_type_to_name
+from .serialization import object_to_json
+
+# determines the maximum number of distinct enum members up to which a Dict[EnumType, Any] is converted into a JSON
+# schema with explicitly listed properties (rather than employing a pattern constraint on property names)
+OBJECT_ENUM_EXPANSION_LIMIT = 4
+
+
+T = TypeVar("T")
+
+
+def get_class_docstrings(data_type: type) -> tuple[str | None, str | None]:
+    docstr = docstring.parse_type(data_type)
+
+    # check if class has a doc-string other than the auto-generated string assigned by @dataclass
+    if docstring.has_default_docstring(data_type):
+        return None, None
+
+    return docstr.short_description, docstr.long_description
+
+
+def get_class_property_docstrings(
+    data_type: type, transform_fun: Callable[[type, str, str], str] | None = None
+) -> dict[str, str]:
+    """
+    Extracts the documentation strings associated with the properties of a composite type.
+
+    :param data_type: The object whose properties to iterate over.
+    :param transform_fun: An optional function that maps a property documentation string to a custom tailored string.
+    :returns: A dictionary mapping property names to descriptions.
+    """
+
+    result: dict[str, str] = {}
+    # Only try to get MRO if data_type is actually a class
+    # Special types like Literal, Union, etc. don't have MRO
+    if not inspect.isclass(data_type):
+        return result
+
+    for base in inspect.getmro(data_type):
+        docstr = docstring.parse_type(base)
+        for param in docstr.params.values():
+            if param.name in result:
+                continue
+
+            if transform_fun:
+                description = transform_fun(data_type, param.name, param.description)
+            else:
+                description = param.description
+
+            result[param.name] = description
+    return result
+
+
+def docstring_to_schema(data_type: type) -> Schema:
+    short_description, long_description = get_class_docstrings(data_type)
+    schema: Schema = {
+        "title": python_type_to_name(data_type, force=True),
+    }
+
+    description = "\n".join(filter(None, [short_description, long_description]))
+    if description:
+        schema["description"] = description
+    return schema
+
+
+def id_from_ref(data_type: typing.ForwardRef | str | type) -> str:
+    "Extracts the name of a possibly forward-referenced type."
+
+    if isinstance(data_type, typing.ForwardRef):
+        forward_type: typing.ForwardRef = data_type
+        return forward_type.__forward_arg__
+    elif isinstance(data_type, str):
+        return data_type
+    else:
+        return data_type.__name__
+
+
+def type_from_ref(data_type: typing.ForwardRef | str | type) -> tuple[str, type]:
+    "Creates a type from a forward reference."
+
+    if isinstance(data_type, typing.ForwardRef):
+        forward_type: typing.ForwardRef = data_type
+        true_type = eval(forward_type.__forward_code__)
+        return forward_type.__forward_arg__, true_type
+    elif isinstance(data_type, str):
+        true_type = eval(data_type)
+        return data_type, true_type
+    else:
+        return data_type.__name__, data_type
+
+
+@dataclasses.dataclass
+class TypeCatalogEntry:
+    schema: Schema | None
+    identifier: str
+    examples: JsonType | None = None
+
+
+class TypeCatalog:
+    "Maintains an association of well-known Python types to their JSON schema."
+
+    _by_type: dict[TypeLike, TypeCatalogEntry]
+    _by_name: dict[str, TypeCatalogEntry]
+
+    def __init__(self) -> None:
+        self._by_type = {}
+        self._by_name = {}
+
+    def __contains__(self, data_type: TypeLike) -> bool:
+        if isinstance(data_type, typing.ForwardRef):
+            fwd: typing.ForwardRef = data_type
+            name = fwd.__forward_arg__
+            return name in self._by_name
+        else:
+            return data_type in self._by_type
+
+    def add(
+        self,
+        data_type: TypeLike,
+        schema: Schema | None,
+        identifier: str,
+        examples: list[JsonType] | None = None,
+    ) -> None:
+        if isinstance(data_type, typing.ForwardRef):
+            raise TypeError("forward references cannot be used to register a type")
+
+        if data_type in self._by_type:
+            raise ValueError(f"type {data_type} is already registered in the catalog")
+
+        entry = TypeCatalogEntry(schema, identifier, examples)
+        self._by_type[data_type] = entry
+        self._by_name[identifier] = entry
+
+    def get(self, data_type: TypeLike) -> TypeCatalogEntry:
+        if isinstance(data_type, typing.ForwardRef):
+            fwd: typing.ForwardRef = data_type
+            name = fwd.__forward_arg__
+            return self._by_name[name]
+        else:
+            return self._by_type[data_type]
+
+
+@dataclasses.dataclass
+class SchemaOptions:
+    definitions_path: str = "#/definitions/"
+    use_descriptions: bool = True
+    use_examples: bool = True
+    property_description_fun: Callable[[type, str, str], str] | None = None
+
+
+class JsonSchemaGenerator:
+    "Creates a JSON schema with user-defined type definitions."
+
+    type_catalog: ClassVar[TypeCatalog] = TypeCatalog()
+    types_used: dict[str, TypeLike]
+    options: SchemaOptions
+
+    def __init__(self, options: SchemaOptions | None = None):
+        if options is None:
+            self.options = SchemaOptions()
+        else:
+            self.options = options
+        self.types_used = {}
+
+    @functools.singledispatchmethod
+    def _metadata_to_schema(self, arg: object) -> Schema:
+        # unrecognized annotation
+        return {}
+
+    @_metadata_to_schema.register
+    def _(self, arg: IntegerRange) -> Schema:
+        return {"minimum": arg.minimum, "maximum": arg.maximum}
+
+    @_metadata_to_schema.register
+    def _(self, arg: Precision) -> Schema:
+        return {
+            "multipleOf": 10 ** (-arg.decimal_digits),
+            "exclusiveMinimum": -(10**arg.integer_digits),
+            "exclusiveMaximum": (10**arg.integer_digits),
+        }
+
+    @_metadata_to_schema.register
+    def _(self, arg: MinLength) -> Schema:
+        return {"minLength": arg.value}
+
+    @_metadata_to_schema.register
+    def _(self, arg: MaxLength) -> Schema:
+        return {"maxLength": arg.value}
+
+    def _with_metadata(self, type_schema: Schema, metadata: tuple[Any, ...] | None) -> Schema:
+        if metadata:
+            for m in metadata:
+                type_schema.update(self._metadata_to_schema(m))
+        return type_schema
+
+    def _simple_type_to_schema(self, typ: TypeLike, json_schema_extra: dict | None = None) -> Schema | None:
+        """
+        Returns the JSON schema associated with a simple, unrestricted type.
+
+        :returns: The schema for a simple type, or `None`.
+        """
+
+        if typ is type(None):
+            return {"type": "null"}
+        elif typ is bool:
+            return {"type": "boolean"}
+        elif typ is int:
+            return {"type": "integer"}
+        elif typ is float:
+            return {"type": "number"}
+        elif typ is str:
+            if json_schema_extra and "contentEncoding" in json_schema_extra:
+                return {
+                    "type": "string",
+                    "contentEncoding": json_schema_extra["contentEncoding"],
+                }
+            return {"type": "string"}
+        elif typ is bytes:
+            return {"type": "string", "contentEncoding": "base64"}
+        elif typ is datetime.datetime:
+            # 2018-11-13T20:20:39+00:00
+            return {
+                "type": "string",
+                "format": "date-time",
+            }
+        elif typ is datetime.date:
+            # 2018-11-13
+            return {"type": "string", "format": "date"}
+        elif typ is datetime.time:
+            # 20:20:39+00:00
+            return {"type": "string", "format": "time"}
+        elif typ is decimal.Decimal:
+            return {"type": "number"}
+        elif typ is uuid.UUID:
+            # f81d4fae-7dec-11d0-a765-00a0c91e6bf6
+            return {"type": "string", "format": "uuid"}
+        elif typ is Any:
+            return {
+                "oneOf": [
+                    {"type": "null"},
+                    {"type": "boolean"},
+                    {"type": "number"},
+                    {"type": "string"},
+                    {"type": "array"},
+                    {"type": "object"},
+                ]
+            }
+        elif typ is JsonObject:
+            return {"type": "object"}
+        elif typ is JsonArray:
+            return {"type": "array"}
+        else:
+            # not a simple type
+            return None
+
+    def type_to_schema(
+        self,
+        data_type: TypeLike,
+        force_expand: bool = False,
+        json_schema_extra: dict | None = None,
+    ) -> Schema:
+        common_info = {}
+        if json_schema_extra and "deprecated" in json_schema_extra:
+            common_info["deprecated"] = json_schema_extra["deprecated"]
+        return self._type_to_schema(data_type, force_expand, json_schema_extra) | common_info
+
+    def _type_to_schema(
+        self,
+        data_type: TypeLike,
+        force_expand: bool = False,
+        json_schema_extra: dict | None = None,
+    ) -> Schema:
+        """
+        Returns the JSON schema associated with a type.
+
+        :param data_type: The Python type whose JSON schema to return.
+        :param force_expand: Forces a JSON schema to be returned even if the type is registered in the catalog of known types.
+        :returns: The JSON schema associated with the type.
+        """
+
+        # short-circuit for common simple types
+        schema = self._simple_type_to_schema(data_type, json_schema_extra)
+        if schema is not None:
+            return schema
+
+        # types registered in the type catalog of well-known types
+        type_catalog = JsonSchemaGenerator.type_catalog
+        if not force_expand and data_type in type_catalog:
+            # user-defined type
+            identifier = type_catalog.get(data_type).identifier
+            self.types_used.setdefault(identifier, data_type)
+            return {"$ref": f"{self.options.definitions_path}{identifier}"}
+
+        # unwrap annotated types
+        metadata = getattr(data_type, "__metadata__", None)
+        if metadata is not None:
+            # type is Annotated[T, ...]
+            typ = typing.get_args(data_type)[0]
+            schema = self._simple_type_to_schema(typ)
+            if schema is not None:
+                # recognize well-known auxiliary types
+                fmt = get_auxiliary_format(data_type)
+                if fmt is not None:
+                    schema.update({"format": fmt})
+                    return schema
+                else:
+                    return self._with_metadata(schema, metadata)
+
+        else:
+            # type is a regular type
+            typ = data_type
+
+        if isinstance(typ, typing.ForwardRef) or isinstance(typ, str):
+            if force_expand:
+                identifier, true_type = type_from_ref(typ)
+                return self.type_to_schema(true_type, force_expand=True)
+            else:
+                try:
+                    identifier, true_type = type_from_ref(typ)
+                    self.types_used[identifier] = true_type
+                except NameError:
+                    identifier = id_from_ref(typ)
+
+                return {"$ref": f"{self.options.definitions_path}{identifier}"}
+
+        if is_type_enum(typ):
+            enum_type: type[enum.Enum] = typ
+            value_types = enum_value_types(enum_type)
+            if len(value_types) != 1:
+                raise ValueError(
+                    f"enumerations must have a consistent member value type but several types found: {value_types}"
+                )
+            enum_value_type = value_types.pop()
+
+            enum_schema: Schema
+            if enum_value_type is bool or enum_value_type is int or enum_value_type is float or enum_value_type is str:
+                if enum_value_type is bool:
+                    enum_schema_type = "boolean"
+                elif enum_value_type is int:
+                    enum_schema_type = "integer"
+                elif enum_value_type is float:
+                    enum_schema_type = "number"
+                elif enum_value_type is str:
+                    enum_schema_type = "string"
+
+                enum_schema = {
+                    "type": enum_schema_type,
+                    "enum": [object_to_json(e.value) for e in enum_type],
+                }
+                if self.options.use_descriptions:
+                    enum_schema.update(docstring_to_schema(typ))
+                return enum_schema
+            else:
+                enum_schema = self.type_to_schema(enum_value_type)
+                if self.options.use_descriptions:
+                    enum_schema.update(docstring_to_schema(typ))
+                return enum_schema
+
+        origin_type = typing.get_origin(typ)
+        if origin_type is list:
+            (list_type,) = typing.get_args(typ)  # unpack single tuple element
+            return {"type": "array", "items": self.type_to_schema(list_type)}
+        elif origin_type is collections.abc.Sequence:
+            # Treat Sequence the same as list for JSON schema (both are arrays)
+            (sequence_type,) = typing.get_args(typ)  # unpack single tuple element
+            return {"type": "array", "items": self.type_to_schema(sequence_type)}
+        elif origin_type is dict:
+            key_type, value_type = typing.get_args(typ)
+            if not (key_type is str or key_type is int or is_type_enum(key_type)):
+                raise ValueError("`dict` with key type not coercible to `str` is not supported")
+
+            dict_schema: Schema
+            value_schema = self.type_to_schema(value_type)
+            if is_type_enum(key_type):
+                enum_values = [str(e.value) for e in key_type]
+                if len(enum_values) > OBJECT_ENUM_EXPANSION_LIMIT:
+                    dict_schema = {
+                        "propertyNames": {"pattern": "^(" + "|".join(enum_values) + ")$"},
+                        "additionalProperties": value_schema,
+                    }
+                else:
+                    dict_schema = {
+                        "properties": dict.fromkeys(enum_values, value_schema),
+                        "additionalProperties": False,
+                    }
+            else:
+                dict_schema = {"additionalProperties": value_schema}
+
+            schema = {"type": "object"}
+            schema.update(dict_schema)
+            return schema
+        elif origin_type is set:
+            (set_type,) = typing.get_args(typ)  # unpack single tuple element
+            return {
+                "type": "array",
+                "items": self.type_to_schema(set_type),
+                "uniqueItems": True,
+            }
+        elif origin_type is tuple:
+            args = typing.get_args(typ)
+            return {
+                "type": "array",
+                "minItems": len(args),
+                "maxItems": len(args),
+                "prefixItems": [self.type_to_schema(member_type) for member_type in args],
+            }
+        elif origin_type in (Union, types.UnionType):
+            discriminator = None
+            if typing.get_origin(data_type) is Annotated:
+                discriminator = typing.get_args(data_type)[1].discriminator
+            ret: Schema = {"oneOf": [self.type_to_schema(union_type) for union_type in typing.get_args(typ)]}
+            if discriminator:
+                # for each union type, we need to read the value of the discriminator
+                mapping: dict[str, JsonType] = {}
+                for union_type in typing.get_args(typ):
+                    props = self.type_to_schema(union_type, force_expand=True)["properties"]
+                    # mypy is confused here because JsonType allows multiple types, some of them
+                    # not indexable (bool?) or not indexable by string (list?). The correctness of
+                    # types depends on correct model definitions. Hence multiple ignore statements below.
+                    discriminator_value = props[discriminator]["default"]  # type: ignore[index,call-overload]
+                    mapping[discriminator_value] = self.type_to_schema(union_type)["$ref"]  # type: ignore[index]
+
+                ret["discriminator"] = {
+                    "propertyName": discriminator,
+                    "mapping": mapping,
+                }
+            return ret
+        elif origin_type is Literal:
+            literal_args = typing.get_args(typ)
+            if len(literal_args) == 1:
+                (literal_value,) = literal_args
+                schema = self.type_to_schema(type(literal_value))
+                schema["const"] = literal_value
+                return schema
+            elif len(literal_args) > 1:
+                first_value = literal_args[0]
+                schema = self.type_to_schema(type(first_value))
+                schema["enum"] = list(literal_args)
+                return schema
+            else:
+                return {"enum": []}
+        elif origin_type is type:
+            (concrete_type,) = typing.get_args(typ)  # unpack single tuple element
+            return {"const": self.type_to_schema(concrete_type, force_expand=True)}
+        elif origin_type is collections.abc.AsyncIterator:
+            (concrete_type,) = typing.get_args(typ)
+            return self.type_to_schema(concrete_type)
+
+        # dictionary of class attributes
+        members = dict(inspect.getmembers(typ, lambda a: not inspect.isroutine(a)))
+
+        property_docstrings = get_class_property_docstrings(typ, self.options.property_description_fun)
+        properties: dict[str, Schema] = {}
+        required: list[str] = []
+        for property_name, property_type in get_class_properties(typ):
+            # rename property if an alias name is specified
+            alias = get_annotation(property_type, Alias)
+            if alias:
+                output_name = alias.name
+            else:
+                output_name = property_name
+
+            defaults = {}
+            json_schema_extra = None
+            if "model_fields" in members:
+                f = members["model_fields"]
+                defaults = {k: finfo.default for k, finfo in f.items()}
+                if output_name in f:
+                    finfo = f[output_name]
+                    json_schema_extra = finfo.json_schema_extra or {}
+                    if finfo.deprecated:
+                        json_schema_extra["deprecated"] = True
+
+            if is_type_optional(property_type):
+                optional_type: type = unwrap_optional_type(property_type)
+                property_def = self.type_to_schema(optional_type, json_schema_extra=json_schema_extra)
+            else:
+                property_def = self.type_to_schema(property_type, json_schema_extra=json_schema_extra)
+                required.append(output_name)
+
+            # check if attribute has a default value initializer
+            if defaults.get(property_name) is not None:
+                def_value = defaults[property_name]
+                # check if value can be directly represented in JSON
+                if isinstance(
+                    def_value,
+                    (
+                        bool,
+                        int,
+                        float,
+                        str,
+                        enum.Enum,
+                        datetime.datetime,
+                        datetime.date,
+                        datetime.time,
+                    ),
+                ):
+                    property_def["default"] = object_to_json(def_value)
+
+            # add property docstring if available
+            property_doc = property_docstrings.get(property_name)
+            if property_doc:
+                # print(output_name, property_doc)
+                property_def.pop("title", None)
+                property_def["description"] = property_doc
+
+            properties[output_name] = property_def
+
+        schema = {"type": "object"}
+        if len(properties) > 0:
+            schema["properties"] = typing.cast(JsonType, properties)
+            schema["additionalProperties"] = False
+        if len(required) > 0:
+            schema["required"] = typing.cast(JsonType, required)
+        if self.options.use_descriptions:
+            schema.update(docstring_to_schema(typ))
+        return schema
+
+    def _type_to_schema_with_lookup(self, data_type: TypeLike) -> Schema:
+        """
+        Returns the JSON schema associated with a type that may be registered in the catalog of known types.
+
+        :param data_type: The type whose JSON schema we seek.
+        :returns: The JSON schema associated with the type.
+        """
+
+        entry = JsonSchemaGenerator.type_catalog.get(data_type)
+        if entry.schema is None:
+            type_schema = self.type_to_schema(data_type, force_expand=True)
+        else:
+            type_schema = deepcopy(entry.schema)
+
+        # add descriptive text (if present)
+        if self.options.use_descriptions:
+            if isinstance(data_type, type) and not isinstance(data_type, typing.ForwardRef):
+                type_schema.update(docstring_to_schema(data_type))
+
+        # add example (if present)
+        if self.options.use_examples and entry.examples:
+            type_schema["examples"] = entry.examples
+
+        return type_schema
+
+    def classdef_to_schema(self, data_type: TypeLike, force_expand: bool = False) -> tuple[Schema, dict[str, Schema]]:
+        """
+        Returns the JSON schema associated with a type and any nested types.
+
+        :param data_type: The type whose JSON schema to return.
+        :param force_expand: True if a full JSON schema is to be returned even for well-known types; false if a schema
+        reference is to be used for well-known types.
+        :returns: A tuple of the JSON schema, and a mapping between nested type names and their corresponding schema.
+        """
+
+        if not is_type_like(data_type):
+            raise TypeError(f"expected a type-like object but got: {data_type}")
+
+        self.types_used = {}
+        try:
+            type_schema = self.type_to_schema(data_type, force_expand=force_expand)
+
+            types_defined: dict[str, Schema] = {}
+            while len(self.types_used) > len(types_defined):
+                # make a snapshot copy; original collection is going to be modified
+                types_undefined = {
+                    sub_name: sub_type
+                    for sub_name, sub_type in self.types_used.items()
+                    if sub_name not in types_defined
+                }
+
+                # expand undefined types, which may lead to additional types to be defined
+                for sub_name, sub_type in types_undefined.items():
+                    types_defined[sub_name] = self._type_to_schema_with_lookup(sub_type)
+
+            type_definitions = dict(sorted(types_defined.items()))
+        finally:
+            self.types_used = {}
+
+        return type_schema, type_definitions
+
+
+class Validator(enum.Enum):
+    "Defines constants for JSON schema standards."
+
+    Draft7 = jsonschema.Draft7Validator
+    Draft201909 = jsonschema.Draft201909Validator
+    Draft202012 = jsonschema.Draft202012Validator
+    Latest = jsonschema.Draft202012Validator
+
+
+def classdef_to_schema(
+    data_type: TypeLike,
+    options: SchemaOptions | None = None,
+    validator: Validator = Validator.Latest,
+) -> Schema:
+    """
+    Returns the JSON schema corresponding to the given type.
+
+    :param data_type: The Python type used to generate the JSON schema
+    :returns: A JSON object that you can serialize to a JSON string with json.dump or json.dumps
+    :raises TypeError: Indicates that the generated JSON schema does not validate against the desired meta-schema.
+    """
+
+    # short-circuit with an error message when passing invalid data
+    if not is_type_like(data_type):
+        raise TypeError(f"expected a type-like object but got: {data_type}")
+
+    generator = JsonSchemaGenerator(options)
+    type_schema, type_definitions = generator.classdef_to_schema(data_type)
+
+    class_schema: Schema = {}
+    if type_definitions:
+        class_schema["definitions"] = typing.cast(JsonType, type_definitions)
+    class_schema.update(type_schema)
+
+    validator_id = validator.value.META_SCHEMA["$id"]
+    try:
+        validator.value.check_schema(class_schema)
+    except jsonschema.exceptions.SchemaError:
+        raise TypeError(f"schema does not validate against meta-schema <{validator_id}>")
+
+    schema = {"$schema": validator_id}
+    schema.update(class_schema)
+    return schema
+
+
+def validate_object(data_type: TypeLike, json_dict: JsonType) -> None:
+    """
+    Validates if the JSON dictionary object conforms to the expected type.
+
+    :param data_type: The type to match against.
+    :param json_dict: A JSON object obtained with `json.load` or `json.loads`.
+    :raises jsonschema.exceptions.ValidationError: Indicates that the JSON object cannot represent the type.
+    """
+
+    schema_dict = classdef_to_schema(data_type)
+    jsonschema.validate(json_dict, schema_dict, format_checker=jsonschema.FormatChecker())
+
+
+def print_schema(data_type: type) -> None:
+    """Pretty-prints the JSON schema corresponding to the type."""
+
+    s = classdef_to_schema(data_type)
+    print(json.dumps(s, indent=4))
+
+
+def get_schema_identifier(data_type: type) -> str | None:
+    if data_type in JsonSchemaGenerator.type_catalog:
+        return JsonSchemaGenerator.type_catalog.get(data_type).identifier
+    else:
+        return None
+
+
+def register_schema(
+    data_type: T,
+    schema: Schema | None = None,
+    name: str | None = None,
+    examples: list[JsonType] | None = None,
+) -> T:
+    """
+    Associates a type with a JSON schema definition.
+
+    :param data_type: The type to associate with a JSON schema.
+    :param schema: The schema to associate the type with. Derived automatically if omitted.
+    :param name: The name used for looking uo the type. Determined automatically if omitted.
+    :returns: The input type.
+    """
+
+    JsonSchemaGenerator.type_catalog.add(
+        data_type,
+        schema,
+        name if name is not None else python_type_to_name(data_type),
+        examples,
+    )
+    return data_type
+
+
+@overload
+def json_schema_type(cls: type[T], /) -> type[T]: ...
+
+
+@overload
+def json_schema_type(cls: None, *, schema: Schema | None = None) -> Callable[[type[T]], type[T]]: ...
+
+
+def json_schema_type(
+    cls: type[T] | None = None,
+    *,
+    schema: Schema | None = None,
+    examples: list[JsonType] | None = None,
+) -> type[T] | Callable[[type[T]], type[T]]:
+    """Decorator to add user-defined schema definition to a class."""
+
+    def wrap(cls: type[T]) -> type[T]:
+        return register_schema(cls, schema, examples=examples)
+
+    # see if decorator is used as @json_schema_type or @json_schema_type()
+    if cls is None:
+        # called with parentheses
+        return wrap
+    else:
+        # called as @json_schema_type without parentheses
+        return wrap(cls)
+
+
+register_schema(JsonObject, name="JsonObject")
+register_schema(JsonArray, name="JsonArray")
+
+register_schema(
+    JsonType,
+    name="JsonType",
+    examples=[
+        {
+            "property1": None,
+            "property2": True,
+            "property3": 64,
+            "property4": "string",
+            "property5": ["item"],
+            "property6": {"key": "value"},
+        }
+    ],
+)
+register_schema(
+    StrictJsonType,
+    name="StrictJsonType",
+    examples=[
+        {
+            "property1": True,
+            "property2": 64,
+            "property3": "string",
+            "property4": ["item"],
+            "property5": {"key": "value"},
+        }
+    ],
+)

src/llama_stack_api/strong_typing/serialization.py

@@ -0,0 +1,97 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+import inspect
+import json
+import sys
+from types import ModuleType
+from typing import Any, TextIO, TypeVar
+
+from .core import JsonType
+from .deserializer import create_deserializer
+from .inspection import TypeLike
+from .serializer import create_serializer
+
+T = TypeVar("T")
+
+
+def object_to_json(obj: Any) -> JsonType:
+    """
+    Converts a Python object to a representation that can be exported to JSON.
+
+    * Fundamental types (e.g. numeric types) are written as is.
+    * Date and time types are serialized in the ISO 8601 format with time zone.
+    * A byte array is written as a string with Base64 encoding.
+    * UUIDs are written as a UUID string.
+    * Enumerations are written as their value.
+    * Containers (e.g. `list`, `dict`, `set`, `tuple`) are exported recursively.
+    * Objects with properties (including data class types) are converted to a dictionaries of key-value pairs.
+    """
+
+    typ: type = type(obj)
+    generator = create_serializer(typ)
+    return generator.generate(obj)
+
+
+def json_to_object(typ: TypeLike, data: JsonType, *, context: ModuleType | None = None) -> object:
+    """
+    Creates an object from a representation that has been de-serialized from JSON.
+
+    When de-serializing a JSON object into a Python object, the following transformations are applied:
+
+    * Fundamental types are parsed as `bool`, `int`, `float` or `str`.
+    * Date and time types are parsed from the ISO 8601 format with time zone into the corresponding Python type
+      `datetime`, `date` or `time`
+    * A byte array is read from a string with Base64 encoding into a `bytes` instance.
+    * UUIDs are extracted from a UUID string into a `uuid.UUID` instance.
+    * Enumerations are instantiated with a lookup on enumeration value.
+    * Containers (e.g. `list`, `dict`, `set`, `tuple`) are parsed recursively.
+    * Complex objects with properties (including data class types) are populated from dictionaries of key-value pairs
+      using reflection (enumerating type annotations).
+
+    :raises TypeError: A de-serializing engine cannot be constructed for the input type.
+    :raises JsonKeyError: Deserialization for a class or union type has failed because a matching member was not found.
+    :raises JsonTypeError: Deserialization for data has failed due to a type mismatch.
+    """
+
+    # use caller context for evaluating types if no context is supplied
+    if context is None:
+        this_frame = inspect.currentframe()
+        if this_frame is not None:
+            caller_frame = this_frame.f_back
+            del this_frame
+
+            if caller_frame is not None:
+                try:
+                    context = sys.modules[caller_frame.f_globals["__name__"]]
+                finally:
+                    del caller_frame
+
+    parser = create_deserializer(typ, context)
+    return parser.parse(data)
+
+
+def json_dump_string(json_object: JsonType) -> str:
+    "Dump an object as a JSON string with a compact representation."
+
+    return json.dumps(json_object, ensure_ascii=False, check_circular=False, separators=(",", ":"))
+
+
+def json_dump(json_object: JsonType, file: TextIO) -> None:
+    json.dump(
+        json_object,
+        file,
+        ensure_ascii=False,
+        check_circular=False,
+        separators=(",", ":"),
+    )
+    file.write("\n")

src/llama_stack_api/strong_typing/serializer.py

@@ -0,0 +1,494 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+import abc
+import base64
+import datetime
+import enum
+import functools
+import inspect
+import ipaddress
+import sys
+import typing
+import uuid
+from collections.abc import Callable
+from types import FunctionType, MethodType, ModuleType
+from typing import (
+    Any,
+    Generic,
+    Literal,
+    NamedTuple,
+    TypeVar,
+    Union,
+)
+
+from .core import JsonType
+from .exception import JsonTypeError, JsonValueError
+from .inspection import (
+    TypeLike,
+    enum_value_types,
+    evaluate_type,
+    get_class_properties,
+    get_resolved_hints,
+    is_dataclass_type,
+    is_named_tuple_type,
+    is_reserved_property,
+    is_type_annotated,
+    is_type_enum,
+    unwrap_annotated_type,
+)
+from .mapping import python_field_to_json_property
+
+T = TypeVar("T")
+
+
+class Serializer(abc.ABC, Generic[T]):
+    @abc.abstractmethod
+    def generate(self, data: T) -> JsonType: ...
+
+
+class NoneSerializer(Serializer[None]):
+    def generate(self, data: None) -> None:
+        # can be directly represented in JSON
+        return None
+
+
+class BoolSerializer(Serializer[bool]):
+    def generate(self, data: bool) -> bool:
+        # can be directly represented in JSON
+        return data
+
+
+class IntSerializer(Serializer[int]):
+    def generate(self, data: int) -> int:
+        # can be directly represented in JSON
+        return data
+
+
+class FloatSerializer(Serializer[float]):
+    def generate(self, data: float) -> float:
+        # can be directly represented in JSON
+        return data
+
+
+class StringSerializer(Serializer[str]):
+    def generate(self, data: str) -> str:
+        # can be directly represented in JSON
+        return data
+
+
+class BytesSerializer(Serializer[bytes]):
+    def generate(self, data: bytes) -> str:
+        return base64.b64encode(data).decode("ascii")
+
+
+class DateTimeSerializer(Serializer[datetime.datetime]):
+    def generate(self, obj: datetime.datetime) -> str:
+        if obj.tzinfo is None:
+            raise JsonValueError(f"timestamp lacks explicit time zone designator: {obj}")
+        fmt = obj.isoformat()
+        if fmt.endswith("+00:00"):
+            fmt = f"{fmt[:-6]}Z"  # Python's isoformat() does not support military time zones like "Zulu" for UTC
+        return fmt
+
+
+class DateSerializer(Serializer[datetime.date]):
+    def generate(self, obj: datetime.date) -> str:
+        return obj.isoformat()
+
+
+class TimeSerializer(Serializer[datetime.time]):
+    def generate(self, obj: datetime.time) -> str:
+        return obj.isoformat()
+
+
+class UUIDSerializer(Serializer[uuid.UUID]):
+    def generate(self, obj: uuid.UUID) -> str:
+        return str(obj)
+
+
+class IPv4Serializer(Serializer[ipaddress.IPv4Address]):
+    def generate(self, obj: ipaddress.IPv4Address) -> str:
+        return str(obj)
+
+
+class IPv6Serializer(Serializer[ipaddress.IPv6Address]):
+    def generate(self, obj: ipaddress.IPv6Address) -> str:
+        return str(obj)
+
+
+class EnumSerializer(Serializer[enum.Enum]):
+    def generate(self, obj: enum.Enum) -> int | str:
+        value = obj.value
+        if isinstance(value, int):
+            return value
+        return str(value)
+
+
+class UntypedListSerializer(Serializer[list]):
+    def generate(self, obj: list) -> list[JsonType]:
+        return [object_to_json(item) for item in obj]
+
+
+class UntypedDictSerializer(Serializer[dict]):
+    def generate(self, obj: dict) -> dict[str, JsonType]:
+        if obj and isinstance(next(iter(obj.keys())), enum.Enum):
+            iterator = ((key.value, object_to_json(value)) for key, value in obj.items())
+        else:
+            iterator = ((str(key), object_to_json(value)) for key, value in obj.items())
+        return dict(iterator)
+
+
+class UntypedSetSerializer(Serializer[set]):
+    def generate(self, obj: set) -> list[JsonType]:
+        return [object_to_json(item) for item in obj]
+
+
+class UntypedTupleSerializer(Serializer[tuple]):
+    def generate(self, obj: tuple) -> list[JsonType]:
+        return [object_to_json(item) for item in obj]
+
+
+class TypedCollectionSerializer(Serializer, Generic[T]):
+    generator: Serializer[T]
+
+    def __init__(self, item_type: type[T], context: ModuleType | None) -> None:
+        self.generator = _get_serializer(item_type, context)
+
+
+class TypedListSerializer(TypedCollectionSerializer[T]):
+    def generate(self, obj: list[T]) -> list[JsonType]:
+        return [self.generator.generate(item) for item in obj]
+
+
+class TypedStringDictSerializer(TypedCollectionSerializer[T]):
+    def __init__(self, value_type: type[T], context: ModuleType | None) -> None:
+        super().__init__(value_type, context)
+
+    def generate(self, obj: dict[str, T]) -> dict[str, JsonType]:
+        return {key: self.generator.generate(value) for key, value in obj.items()}
+
+
+class TypedEnumDictSerializer(TypedCollectionSerializer[T]):
+    def __init__(
+        self,
+        key_type: type[enum.Enum],
+        value_type: type[T],
+        context: ModuleType | None,
+    ) -> None:
+        super().__init__(value_type, context)
+
+        value_types = enum_value_types(key_type)
+        if len(value_types) != 1:
+            raise JsonTypeError(
+                f"invalid key type, enumerations must have a consistent member value type but several types found: {value_types}"
+            )
+
+        value_type = value_types.pop()
+        if value_type is not str:
+            raise JsonTypeError("invalid enumeration key type, expected `enum.Enum` with string values")
+
+    def generate(self, obj: dict[enum.Enum, T]) -> dict[str, JsonType]:
+        return {key.value: self.generator.generate(value) for key, value in obj.items()}
+
+
+class TypedSetSerializer(TypedCollectionSerializer[T]):
+    def generate(self, obj: set[T]) -> JsonType:
+        return [self.generator.generate(item) for item in obj]
+
+
+class TypedTupleSerializer(Serializer[tuple]):
+    item_generators: tuple[Serializer, ...]
+
+    def __init__(self, item_types: tuple[type, ...], context: ModuleType | None) -> None:
+        self.item_generators = tuple(_get_serializer(item_type, context) for item_type in item_types)
+
+    def generate(self, obj: tuple) -> list[JsonType]:
+        return [item_generator.generate(item) for item_generator, item in zip(self.item_generators, obj, strict=False)]
+
+
+class CustomSerializer(Serializer):
+    converter: Callable[[object], JsonType]
+
+    def __init__(self, converter: Callable[[object], JsonType]) -> None:
+        self.converter = converter
+
+    def generate(self, obj: object) -> JsonType:
+        return self.converter(obj)
+
+
+class FieldSerializer(Generic[T]):
+    """
+    Serializes a Python object field into a JSON property.
+
+    :param field_name: The name of the field in a Python class to read data from.
+    :param property_name: The name of the JSON property to write to a JSON `object`.
+    :param generator: A compatible serializer that can handle the field's type.
+    """
+
+    field_name: str
+    property_name: str
+    generator: Serializer
+
+    def __init__(self, field_name: str, property_name: str, generator: Serializer[T]) -> None:
+        self.field_name = field_name
+        self.property_name = property_name
+        self.generator = generator
+
+    def generate_field(self, obj: object, object_dict: dict[str, JsonType]) -> None:
+        value = getattr(obj, self.field_name)
+        if value is not None:
+            object_dict[self.property_name] = self.generator.generate(value)
+
+
+class TypedClassSerializer(Serializer[T]):
+    property_generators: list[FieldSerializer]
+
+    def __init__(self, class_type: type[T], context: ModuleType | None) -> None:
+        self.property_generators = [
+            FieldSerializer(
+                field_name,
+                python_field_to_json_property(field_name, field_type),
+                _get_serializer(field_type, context),
+            )
+            for field_name, field_type in get_class_properties(class_type)
+        ]
+
+    def generate(self, obj: T) -> dict[str, JsonType]:
+        object_dict: dict[str, JsonType] = {}
+        for property_generator in self.property_generators:
+            property_generator.generate_field(obj, object_dict)
+
+        return object_dict
+
+
+class TypedNamedTupleSerializer(TypedClassSerializer[NamedTuple]):
+    def __init__(self, class_type: type[NamedTuple], context: ModuleType | None) -> None:
+        super().__init__(class_type, context)
+
+
+class DataclassSerializer(TypedClassSerializer[T]):
+    def __init__(self, class_type: type[T], context: ModuleType | None) -> None:
+        super().__init__(class_type, context)
+
+
+class UnionSerializer(Serializer):
+    def generate(self, obj: Any) -> JsonType:
+        return object_to_json(obj)
+
+
+class LiteralSerializer(Serializer):
+    generator: Serializer
+
+    def __init__(self, values: tuple[Any, ...], context: ModuleType | None) -> None:
+        literal_type_tuple = tuple(type(value) for value in values)
+        literal_type_set = set(literal_type_tuple)
+        if len(literal_type_set) != 1:
+            value_names = ", ".join(repr(value) for value in values)
+            raise TypeError(
+                f"type `Literal[{value_names}]` expects consistent literal value types but got: {literal_type_tuple}"
+            )
+
+        literal_type = literal_type_set.pop()
+        self.generator = _get_serializer(literal_type, context)
+
+    def generate(self, obj: Any) -> JsonType:
+        return self.generator.generate(obj)
+
+
+class UntypedNamedTupleSerializer(Serializer):
+    fields: dict[str, str]
+
+    def __init__(self, class_type: type[NamedTuple]) -> None:
+        # named tuples are also instances of tuple
+        self.fields = {}
+        field_names: tuple[str, ...] = class_type._fields
+        for field_name in field_names:
+            self.fields[field_name] = python_field_to_json_property(field_name)
+
+    def generate(self, obj: NamedTuple) -> JsonType:
+        object_dict = {}
+        for field_name, property_name in self.fields.items():
+            value = getattr(obj, field_name)
+            object_dict[property_name] = object_to_json(value)
+
+        return object_dict
+
+
+class UntypedClassSerializer(Serializer):
+    def generate(self, obj: object) -> JsonType:
+        # iterate over object attributes to get a standard representation
+        object_dict = {}
+        for name in dir(obj):
+            if is_reserved_property(name):
+                continue
+
+            value = getattr(obj, name)
+            if value is None:
+                continue
+
+            # filter instance methods
+            if inspect.ismethod(value):
+                continue
+
+            object_dict[python_field_to_json_property(name)] = object_to_json(value)
+
+        return object_dict
+
+
+def create_serializer(typ: TypeLike, context: ModuleType | None = None) -> Serializer:
+    """
+    Creates a serializer engine to produce an object that can be directly converted into a JSON string.
+
+    When serializing a Python object into a JSON object, the following transformations are applied:
+
+    * Fundamental types (`bool`, `int`, `float` or `str`) are returned as-is.
+    * Date and time types (`datetime`, `date` or `time`) produce an ISO 8601 format string with time zone
+      (ending with `Z` for UTC).
+    * Byte arrays (`bytes`) are written as a string with Base64 encoding.
+    * UUIDs (`uuid.UUID`) are written as a UUID string as per RFC 4122.
+    * Enumerations yield their enumeration value.
+    * Containers (e.g. `list`, `dict`, `set`, `tuple`) are processed recursively.
+    * Complex objects with properties (including data class types) generate dictionaries of key-value pairs.
+
+    :raises TypeError: A serializer engine cannot be constructed for the input type.
+    """
+
+    if context is None:
+        if isinstance(typ, type):
+            context = sys.modules[typ.__module__]
+
+    return _get_serializer(typ, context)
+
+
+def _get_serializer(typ: TypeLike, context: ModuleType | None) -> Serializer:
+    if isinstance(typ, (str, typing.ForwardRef)):
+        if context is None:
+            raise TypeError(f"missing context for evaluating type: {typ}")
+
+        typ = evaluate_type(typ, context)
+
+    if isinstance(typ, type):
+        return _fetch_serializer(typ)
+    else:
+        # special forms are not always hashable
+        return _create_serializer(typ, context)
+
+
+@functools.cache
+def _fetch_serializer(typ: type) -> Serializer:
+    context = sys.modules[typ.__module__]
+    return _create_serializer(typ, context)
+
+
+def _create_serializer(typ: TypeLike, context: ModuleType | None) -> Serializer:
+    # check for well-known types
+    if typ is type(None):
+        return NoneSerializer()
+    elif typ is bool:
+        return BoolSerializer()
+    elif typ is int:
+        return IntSerializer()
+    elif typ is float:
+        return FloatSerializer()
+    elif typ is str:
+        return StringSerializer()
+    elif typ is bytes:
+        return BytesSerializer()
+    elif typ is datetime.datetime:
+        return DateTimeSerializer()
+    elif typ is datetime.date:
+        return DateSerializer()
+    elif typ is datetime.time:
+        return TimeSerializer()
+    elif typ is uuid.UUID:
+        return UUIDSerializer()
+    elif typ is ipaddress.IPv4Address:
+        return IPv4Serializer()
+    elif typ is ipaddress.IPv6Address:
+        return IPv6Serializer()
+
+    # dynamically-typed collection types
+    if typ is list:
+        return UntypedListSerializer()
+    elif typ is dict:
+        return UntypedDictSerializer()
+    elif typ is set:
+        return UntypedSetSerializer()
+    elif typ is tuple:
+        return UntypedTupleSerializer()
+
+    # generic types (e.g. list, dict, set, etc.)
+    origin_type = typing.get_origin(typ)
+    if origin_type is list:
+        (list_item_type,) = typing.get_args(typ)  # unpack single tuple element
+        return TypedListSerializer(list_item_type, context)
+    elif origin_type is dict:
+        key_type, value_type = typing.get_args(typ)
+        if key_type is str:
+            return TypedStringDictSerializer(value_type, context)
+        elif issubclass(key_type, enum.Enum):
+            return TypedEnumDictSerializer(key_type, value_type, context)
+    elif origin_type is set:
+        (set_member_type,) = typing.get_args(typ)  # unpack single tuple element
+        return TypedSetSerializer(set_member_type, context)
+    elif origin_type is tuple:
+        return TypedTupleSerializer(typing.get_args(typ), context)
+    elif origin_type is Union:
+        return UnionSerializer()
+    elif origin_type is Literal:
+        return LiteralSerializer(typing.get_args(typ), context)
+
+    if is_type_annotated(typ):
+        return create_serializer(unwrap_annotated_type(typ))
+
+    # check if object has custom serialization method
+    convert_func = getattr(typ, "to_json", None)
+    if callable(convert_func):
+        return CustomSerializer(convert_func)
+
+    if is_type_enum(typ):
+        return EnumSerializer()
+    if is_dataclass_type(typ):
+        return DataclassSerializer(typ, context)
+    if is_named_tuple_type(typ):
+        if getattr(typ, "__annotations__", None):
+            return TypedNamedTupleSerializer(typ, context)
+        else:
+            return UntypedNamedTupleSerializer(typ)
+
+    # fail early if caller passes an object with an exotic type
+    if not isinstance(typ, type) or typ is FunctionType or typ is MethodType or typ is type or typ is ModuleType:
+        raise TypeError(f"object of type {typ} cannot be represented in JSON")
+
+    if get_resolved_hints(typ):
+        return TypedClassSerializer(typ, context)
+    else:
+        return UntypedClassSerializer()
+
+
+def object_to_json(obj: Any) -> JsonType:
+    """
+    Converts a Python object to a representation that can be exported to JSON.
+
+    * Fundamental types (e.g. numeric types) are written as is.
+    * Date and time types are serialized in the ISO 8601 format with time zone.
+    * A byte array is written as a string with Base64 encoding.
+    * UUIDs are written as a UUID string.
+    * Enumerations are written as their value.
+    * Containers (e.g. `list`, `dict`, `set`, `tuple`) are exported recursively.
+    * Objects with properties (including data class types) are converted to a dictionaries of key-value pairs.
+    """
+
+    typ: type = type(obj)
+    generator = create_serializer(typ)
+    return generator.generate(obj)

src/llama_stack_api/strong_typing/slots.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.
+
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+class SlotsMeta(type):
+    def __new__(cls: type[T], name: str, bases: tuple[type, ...], ns: dict[str, Any]) -> T:
+        # caller may have already provided slots, in which case just retain them and keep going
+        slots: tuple[str, ...] = ns.get("__slots__", ())
+
+        # add fields with type annotations to slots
+        annotations: dict[str, Any] = ns.get("__annotations__", {})
+        members = tuple(member for member in annotations.keys() if member not in slots)
+
+        # assign slots
+        ns["__slots__"] = slots + tuple(members)
+        return super().__new__(cls, name, bases, ns)  # type: ignore
+
+
+class Slots(metaclass=SlotsMeta):
+    pass

src/llama_stack_api/strong_typing/topological.py

@@ -0,0 +1,90 @@
+# 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.
+
+"""
+Type-safe data interchange for Python data classes.
+
+:see: https://github.com/hunyadi/strong_typing
+"""
+
+from collections.abc import Callable, Iterable
+from typing import TypeVar
+
+from .inspection import TypeCollector
+
+T = TypeVar("T")
+
+
+def topological_sort(graph: dict[T, set[T]]) -> list[T]:
+    """
+    Performs a topological sort of a graph.
+
+    Nodes with no outgoing edges are first. Nodes with no incoming edges are last.
+    The topological ordering is not unique.
+
+    :param graph: A dictionary of mappings from nodes to adjacent nodes. Keys and set members must be hashable.
+    :returns: The list of nodes in topological order.
+    """
+
+    # empty list that will contain the sorted nodes (in reverse order)
+    ordered: list[T] = []
+
+    seen: dict[T, bool] = {}
+
+    def _visit(n: T) -> None:
+        status = seen.get(n)
+        if status is not None:
+            if status:  # node has a permanent mark
+                return
+            else:  # node has a temporary mark
+                raise RuntimeError(f"cycle detected in graph for node {n}")
+
+        seen[n] = False  # apply temporary mark
+        for m in graph[n]:  # visit all adjacent nodes
+            if m != n:  # ignore self-referencing nodes
+                _visit(m)
+
+        seen[n] = True  # apply permanent mark
+        ordered.append(n)
+
+    for n in graph.keys():
+        _visit(n)
+
+    return ordered
+
+
+def type_topological_sort(
+    types: Iterable[type],
+    dependency_fn: Callable[[type], Iterable[type]] | None = None,
+) -> list[type]:
+    """
+    Performs a topological sort of a list of types.
+
+    Types that don't depend on other types (i.e. fundamental types) are first. Types on which no other types depend
+    are last. The topological ordering is not unique.
+
+    :param types: A list of types (simple or composite).
+    :param dependency_fn: Returns a list of additional dependencies for a class (e.g. classes referenced by a foreign key).
+    :returns: The list of types in topological order.
+    """
+
+    if not all(isinstance(typ, type) for typ in types):
+        raise TypeError("expected a list of types")
+
+    collector = TypeCollector()
+    collector.traverse_all(types)
+    graph = collector.graph
+
+    if dependency_fn:
+        new_types: set[type] = set()
+        for source_type, references in graph.items():
+            dependent_types = dependency_fn(source_type)
+            references.update(dependent_types)
+            new_types.update(dependent_types)
+        for new_type in new_types:
+            graph[new_type] = set()
+
+    return topological_sort(graph)

src/llama_stack_api/tools.py

@@ -0,0 +1,217 @@
+# 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 Enum
+from typing import Any, Literal, Protocol
+
+from pydantic import BaseModel
+from typing_extensions import runtime_checkable
+
+from llama_stack_api.common.content_types import URL, InterleavedContent
+from llama_stack_api.common.tracing import telemetry_traceable
+from llama_stack_api.resource import Resource, ResourceType
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+
+@json_schema_type
+class ToolDef(BaseModel):
+    """Tool definition used in runtime contexts.
+
+    :param name: Name of the tool
+    :param description: (Optional) Human-readable description of what the tool does
+    :param input_schema: (Optional) JSON Schema for tool inputs (MCP inputSchema)
+    :param output_schema: (Optional) JSON Schema for tool outputs (MCP outputSchema)
+    :param metadata: (Optional) Additional metadata about the tool
+    :param toolgroup_id: (Optional) ID of the tool group this tool belongs to
+    """
+
+    toolgroup_id: str | None = None
+    name: str
+    description: str | None = None
+    input_schema: dict[str, Any] | None = None
+    output_schema: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@json_schema_type
+class ToolGroupInput(BaseModel):
+    """Input data for registering a tool group.
+
+    :param toolgroup_id: Unique identifier for the tool group
+    :param provider_id: ID of the provider that will handle this tool group
+    :param args: (Optional) Additional arguments to pass to the provider
+    :param mcp_endpoint: (Optional) Model Context Protocol endpoint for remote tools
+    """
+
+    toolgroup_id: str
+    provider_id: str
+    args: dict[str, Any] | None = None
+    mcp_endpoint: URL | None = None
+
+
+@json_schema_type
+class ToolGroup(Resource):
+    """A group of related tools managed together.
+
+    :param type: Type of resource, always 'tool_group'
+    :param mcp_endpoint: (Optional) Model Context Protocol endpoint for remote tools
+    :param args: (Optional) Additional arguments for the tool group
+    """
+
+    type: Literal[ResourceType.tool_group] = ResourceType.tool_group
+    mcp_endpoint: URL | None = None
+    args: dict[str, Any] | None = None
+
+
+@json_schema_type
+class ToolInvocationResult(BaseModel):
+    """Result of a tool invocation.
+
+    :param content: (Optional) The output content from the tool execution
+    :param error_message: (Optional) Error message if the tool execution failed
+    :param error_code: (Optional) Numeric error code if the tool execution failed
+    :param metadata: (Optional) Additional metadata about the tool execution
+    """
+
+    content: InterleavedContent | None = None
+    error_message: str | None = None
+    error_code: int | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class ToolStore(Protocol):
+    async def get_tool(self, tool_name: str) -> ToolDef: ...
+    async def get_tool_group(self, toolgroup_id: str) -> ToolGroup: ...
+
+
+class ListToolGroupsResponse(BaseModel):
+    """Response containing a list of tool groups.
+
+    :param data: List of tool groups
+    """
+
+    data: list[ToolGroup]
+
+
+class ListToolDefsResponse(BaseModel):
+    """Response containing a list of tool definitions.
+
+    :param data: List of tool definitions
+    """
+
+    data: list[ToolDef]
+
+
+@runtime_checkable
+@telemetry_traceable
+class ToolGroups(Protocol):
+    @webmethod(route="/toolgroups", method="POST", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def register_tool_group(
+        self,
+        toolgroup_id: str,
+        provider_id: str,
+        mcp_endpoint: URL | None = None,
+        args: dict[str, Any] | None = None,
+    ) -> None:
+        """Register a tool group.
+
+        :param toolgroup_id: The ID of the tool group to register.
+        :param provider_id: The ID of the provider to use for the tool group.
+        :param mcp_endpoint: The MCP endpoint to use for the tool group.
+        :param args: A dictionary of arguments to pass to the tool group.
+        """
+        ...
+
+    @webmethod(route="/toolgroups/{toolgroup_id:path}", method="GET", level=LLAMA_STACK_API_V1)
+    async def get_tool_group(
+        self,
+        toolgroup_id: str,
+    ) -> ToolGroup:
+        """Get a tool group by its ID.
+
+        :param toolgroup_id: The ID of the tool group to get.
+        :returns: A ToolGroup.
+        """
+        ...
+
+    @webmethod(route="/toolgroups", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_tool_groups(self) -> ListToolGroupsResponse:
+        """List tool groups with optional provider.
+
+        :returns: A ListToolGroupsResponse.
+        """
+        ...
+
+    @webmethod(route="/tools", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_tools(self, toolgroup_id: str | None = None) -> ListToolDefsResponse:
+        """List tools with optional tool group.
+
+        :param toolgroup_id: The ID of the tool group to list tools for.
+        :returns: A ListToolDefsResponse.
+        """
+        ...
+
+    @webmethod(route="/tools/{tool_name:path}", method="GET", level=LLAMA_STACK_API_V1)
+    async def get_tool(
+        self,
+        tool_name: str,
+    ) -> ToolDef:
+        """Get a tool by its name.
+
+        :param tool_name: The name of the tool to get.
+        :returns: A ToolDef.
+        """
+        ...
+
+    @webmethod(route="/toolgroups/{toolgroup_id:path}", method="DELETE", level=LLAMA_STACK_API_V1, deprecated=True)
+    async def unregister_toolgroup(
+        self,
+        toolgroup_id: str,
+    ) -> None:
+        """Unregister a tool group.
+
+        :param toolgroup_id: The ID of the tool group to unregister.
+        """
+        ...
+
+
+class SpecialToolGroup(Enum):
+    """Special tool groups with predefined functionality.
+
+    :cvar rag_tool: Retrieval-Augmented Generation tool group for document search and retrieval
+    """
+
+    rag_tool = "rag_tool"
+
+
+@runtime_checkable
+@telemetry_traceable
+class ToolRuntime(Protocol):
+    tool_store: ToolStore | None = None
+
+    # TODO: This needs to be renamed once OPEN API generator name conflict issue is fixed.
+    @webmethod(route="/tool-runtime/list-tools", method="GET", level=LLAMA_STACK_API_V1)
+    async def list_runtime_tools(
+        self, tool_group_id: str | None = None, mcp_endpoint: URL | None = None
+    ) -> ListToolDefsResponse:
+        """List all tools in the runtime.
+
+        :param tool_group_id: The ID of the tool group to list tools for.
+        :param mcp_endpoint: The MCP endpoint to use for the tool group.
+        :returns: A ListToolDefsResponse.
+        """
+        ...
+
+    @webmethod(route="/tool-runtime/invoke", method="POST", level=LLAMA_STACK_API_V1)
+    async def invoke_tool(self, tool_name: str, kwargs: dict[str, Any]) -> ToolInvocationResult:
+        """Run a tool with the given arguments.
+
+        :param tool_name: The name of the tool to invoke.
+        :param kwargs: A dictionary of arguments to pass to the tool.
+        :returns: A ToolInvocationResult.
+        """
+        ...

src/llama_stack_api/uv.lock

@@ -0,0 +1,498 @@
+version = 1
+revision = 3
+requires-python = ">=3.12"
+
+[[package]]
+name = "annotated-types"
+version = "0.7.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ee/67/531ea369ba64dcff5ec9c3402f9f51bf748cec26dde048a2f973a4eea7f5/annotated_types-0.7.0.tar.gz", hash = "sha256:aff07c09a53a08bc8cfccb9c85b05f1aa9a2a6f23728d790723543408344ce89", size = 16081, upload-time = "2024-05-20T21:33:25.928Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/78/b6/6307fbef88d9b5ee7421e68d78a9f162e0da4900bc5f5793f6d3d0e34fb8/annotated_types-0.7.0-py3-none-any.whl", hash = "sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc8131bcb4eebe8849b8e5c773f3a1c582a53", size = 13643, upload-time = "2024-05-20T21:33:24.1Z" },
+]
+
+[[package]]
+name = "attrs"
+version = "25.4.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6b/5c/685e6633917e101e5dcb62b9dd76946cbb57c26e133bae9e0cd36033c0a9/attrs-25.4.0.tar.gz", hash = "sha256:16d5969b87f0859ef33a48b35d55ac1be6e42ae49d5e853b597db70c35c57e11", size = 934251, upload-time = "2025-10-06T13:54:44.725Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3a/2a/7cc015f5b9f5db42b7d48157e23356022889fc354a2813c15934b7cb5c0e/attrs-25.4.0-py3-none-any.whl", hash = "sha256:adcf7e2a1fb3b36ac48d97835bb6d8ade15b8dcce26aba8bf1d14847b57a3373", size = 67615, upload-time = "2025-10-06T13:54:43.17Z" },
+]
+
+[[package]]
+name = "certifi"
+version = "2025.11.12"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/a2/8c/58f469717fa48465e4a50c014a0400602d3c437d7c0c468e17ada824da3a/certifi-2025.11.12.tar.gz", hash = "sha256:d8ab5478f2ecd78af242878415affce761ca6bc54a22a27e026d7c25357c3316", size = 160538, upload-time = "2025-11-12T02:54:51.517Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/70/7d/9bc192684cea499815ff478dfcdc13835ddf401365057044fb721ec6bddb/certifi-2025.11.12-py3-none-any.whl", hash = "sha256:97de8790030bbd5c2d96b7ec782fc2f7820ef8dba6db909ccf95449f2d062d4b", size = 159438, upload-time = "2025-11-12T02:54:49.735Z" },
+]
+
+[[package]]
+name = "charset-normalizer"
+version = "3.4.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/13/69/33ddede1939fdd074bce5434295f38fae7136463422fe4fd3e0e89b98062/charset_normalizer-3.4.4.tar.gz", hash = "sha256:94537985111c35f28720e43603b8e7b43a6ecfb2ce1d3058bbe955b73404e21a", size = 129418, upload-time = "2025-10-14T04:42:32.879Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f3/85/1637cd4af66fa687396e757dec650f28025f2a2f5a5531a3208dc0ec43f2/charset_normalizer-3.4.4-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:0a98e6759f854bd25a58a73fa88833fba3b7c491169f86ce1180c948ab3fd394", size = 208425, upload-time = "2025-10-14T04:40:53.353Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/6a/04130023fef2a0d9c62d0bae2649b69f7b7d8d24ea5536feef50551029df/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b5b290ccc2a263e8d185130284f8501e3e36c5e02750fc6b6bdeb2e9e96f1e25", size = 148162, upload-time = "2025-10-14T04:40:54.558Z" },
+    { url = "https://files.pythonhosted.org/packages/78/29/62328d79aa60da22c9e0b9a66539feae06ca0f5a4171ac4f7dc285b83688/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:74bb723680f9f7a6234dcf67aea57e708ec1fbdf5699fb91dfd6f511b0a320ef", size = 144558, upload-time = "2025-10-14T04:40:55.677Z" },
+    { url = "https://files.pythonhosted.org/packages/86/bb/b32194a4bf15b88403537c2e120b817c61cd4ecffa9b6876e941c3ee38fe/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:f1e34719c6ed0b92f418c7c780480b26b5d9c50349e9a9af7d76bf757530350d", size = 161497, upload-time = "2025-10-14T04:40:57.217Z" },
+    { url = "https://files.pythonhosted.org/packages/19/89/a54c82b253d5b9b111dc74aca196ba5ccfcca8242d0fb64146d4d3183ff1/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:2437418e20515acec67d86e12bf70056a33abdacb5cb1655042f6538d6b085a8", size = 159240, upload-time = "2025-10-14T04:40:58.358Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/10/d20b513afe03acc89ec33948320a5544d31f21b05368436d580dec4e234d/charset_normalizer-3.4.4-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:11d694519d7f29d6cd09f6ac70028dba10f92f6cdd059096db198c283794ac86", size = 153471, upload-time = "2025-10-14T04:40:59.468Z" },
+    { url = "https://files.pythonhosted.org/packages/61/fa/fbf177b55bdd727010f9c0a3c49eefa1d10f960e5f09d1d887bf93c2e698/charset_normalizer-3.4.4-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:ac1c4a689edcc530fc9d9aa11f5774b9e2f33f9a0c6a57864e90908f5208d30a", size = 150864, upload-time = "2025-10-14T04:41:00.623Z" },
+    { url = "https://files.pythonhosted.org/packages/05/12/9fbc6a4d39c0198adeebbde20b619790e9236557ca59fc40e0e3cebe6f40/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:21d142cc6c0ec30d2efee5068ca36c128a30b0f2c53c1c07bd78cb6bc1d3be5f", size = 150647, upload-time = "2025-10-14T04:41:01.754Z" },
+    { url = "https://files.pythonhosted.org/packages/ad/1f/6a9a593d52e3e8c5d2b167daf8c6b968808efb57ef4c210acb907c365bc4/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:5dbe56a36425d26d6cfb40ce79c314a2e4dd6211d51d6d2191c00bed34f354cc", size = 145110, upload-time = "2025-10-14T04:41:03.231Z" },
+    { url = "https://files.pythonhosted.org/packages/30/42/9a52c609e72471b0fc54386dc63c3781a387bb4fe61c20231a4ebcd58bdd/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:5bfbb1b9acf3334612667b61bd3002196fe2a1eb4dd74d247e0f2a4d50ec9bbf", size = 162839, upload-time = "2025-10-14T04:41:04.715Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/5b/c0682bbf9f11597073052628ddd38344a3d673fda35a36773f7d19344b23/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:d055ec1e26e441f6187acf818b73564e6e6282709e9bcb5b63f5b23068356a15", size = 150667, upload-time = "2025-10-14T04:41:05.827Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/24/a41afeab6f990cf2daf6cb8c67419b63b48cf518e4f56022230840c9bfb2/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:af2d8c67d8e573d6de5bc30cdb27e9b95e49115cd9baad5ddbd1a6207aaa82a9", size = 160535, upload-time = "2025-10-14T04:41:06.938Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/e5/6a4ce77ed243c4a50a1fecca6aaaab419628c818a49434be428fe24c9957/charset_normalizer-3.4.4-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:780236ac706e66881f3b7f2f32dfe90507a09e67d1d454c762cf642e6e1586e0", size = 154816, upload-time = "2025-10-14T04:41:08.101Z" },
+    { url = "https://files.pythonhosted.org/packages/a8/ef/89297262b8092b312d29cdb2517cb1237e51db8ecef2e9af5edbe7b683b1/charset_normalizer-3.4.4-cp312-cp312-win32.whl", hash = "sha256:5833d2c39d8896e4e19b689ffc198f08ea58116bee26dea51e362ecc7cd3ed26", size = 99694, upload-time = "2025-10-14T04:41:09.23Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/2d/1e5ed9dd3b3803994c155cd9aacb60c82c331bad84daf75bcb9c91b3295e/charset_normalizer-3.4.4-cp312-cp312-win_amd64.whl", hash = "sha256:a79cfe37875f822425b89a82333404539ae63dbdddf97f84dcbc3d339aae9525", size = 107131, upload-time = "2025-10-14T04:41:10.467Z" },
+    { url = "https://files.pythonhosted.org/packages/d0/d9/0ed4c7098a861482a7b6a95603edce4c0d9db2311af23da1fb2b75ec26fc/charset_normalizer-3.4.4-cp312-cp312-win_arm64.whl", hash = "sha256:376bec83a63b8021bb5c8ea75e21c4ccb86e7e45ca4eb81146091b56599b80c3", size = 100390, upload-time = "2025-10-14T04:41:11.915Z" },
+    { url = "https://files.pythonhosted.org/packages/97/45/4b3a1239bbacd321068ea6e7ac28875b03ab8bc0aa0966452db17cd36714/charset_normalizer-3.4.4-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:e1f185f86a6f3403aa2420e815904c67b2f9ebc443f045edd0de921108345794", size = 208091, upload-time = "2025-10-14T04:41:13.346Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/62/73a6d7450829655a35bb88a88fca7d736f9882a27eacdca2c6d505b57e2e/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6b39f987ae8ccdf0d2642338faf2abb1862340facc796048b604ef14919e55ed", size = 147936, upload-time = "2025-10-14T04:41:14.461Z" },
+    { url = "https://files.pythonhosted.org/packages/89/c5/adb8c8b3d6625bef6d88b251bbb0d95f8205831b987631ab0c8bb5d937c2/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:3162d5d8ce1bb98dd51af660f2121c55d0fa541b46dff7bb9b9f86ea1d87de72", size = 144180, upload-time = "2025-10-14T04:41:15.588Z" },
+    { url = "https://files.pythonhosted.org/packages/91/ed/9706e4070682d1cc219050b6048bfd293ccf67b3d4f5a4f39207453d4b99/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:81d5eb2a312700f4ecaa977a8235b634ce853200e828fbadf3a9c50bab278328", size = 161346, upload-time = "2025-10-14T04:41:16.738Z" },
+    { url = "https://files.pythonhosted.org/packages/d5/0d/031f0d95e4972901a2f6f09ef055751805ff541511dc1252ba3ca1f80cf5/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5bd2293095d766545ec1a8f612559f6b40abc0eb18bb2f5d1171872d34036ede", size = 158874, upload-time = "2025-10-14T04:41:17.923Z" },
+    { url = "https://files.pythonhosted.org/packages/f5/83/6ab5883f57c9c801ce5e5677242328aa45592be8a00644310a008d04f922/charset_normalizer-3.4.4-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a8a8b89589086a25749f471e6a900d3f662d1d3b6e2e59dcecf787b1cc3a1894", size = 153076, upload-time = "2025-10-14T04:41:19.106Z" },
+    { url = "https://files.pythonhosted.org/packages/75/1e/5ff781ddf5260e387d6419959ee89ef13878229732732ee73cdae01800f2/charset_normalizer-3.4.4-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:bc7637e2f80d8530ee4a78e878bce464f70087ce73cf7c1caf142416923b98f1", size = 150601, upload-time = "2025-10-14T04:41:20.245Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/57/71be810965493d3510a6ca79b90c19e48696fb1ff964da319334b12677f0/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f8bf04158c6b607d747e93949aa60618b61312fe647a6369f88ce2ff16043490", size = 150376, upload-time = "2025-10-14T04:41:21.398Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/d5/c3d057a78c181d007014feb7e9f2e65905a6c4ef182c0ddf0de2924edd65/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:554af85e960429cf30784dd47447d5125aaa3b99a6f0683589dbd27e2f45da44", size = 144825, upload-time = "2025-10-14T04:41:22.583Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/8c/d0406294828d4976f275ffbe66f00266c4b3136b7506941d87c00cab5272/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:74018750915ee7ad843a774364e13a3db91682f26142baddf775342c3f5b1133", size = 162583, upload-time = "2025-10-14T04:41:23.754Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/24/e2aa1f18c8f15c4c0e932d9287b8609dd30ad56dbe41d926bd846e22fb8d/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:c0463276121fdee9c49b98908b3a89c39be45d86d1dbaa22957e38f6321d4ce3", size = 150366, upload-time = "2025-10-14T04:41:25.27Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/5b/1e6160c7739aad1e2df054300cc618b06bf784a7a164b0f238360721ab86/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:362d61fd13843997c1c446760ef36f240cf81d3ebf74ac62652aebaf7838561e", size = 160300, upload-time = "2025-10-14T04:41:26.725Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/10/f882167cd207fbdd743e55534d5d9620e095089d176d55cb22d5322f2afd/charset_normalizer-3.4.4-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9a26f18905b8dd5d685d6d07b0cdf98a79f3c7a918906af7cc143ea2e164c8bc", size = 154465, upload-time = "2025-10-14T04:41:28.322Z" },
+    { url = "https://files.pythonhosted.org/packages/89/66/c7a9e1b7429be72123441bfdbaf2bc13faab3f90b933f664db506dea5915/charset_normalizer-3.4.4-cp313-cp313-win32.whl", hash = "sha256:9b35f4c90079ff2e2edc5b26c0c77925e5d2d255c42c74fdb70fb49b172726ac", size = 99404, upload-time = "2025-10-14T04:41:29.95Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/26/b9924fa27db384bdcd97ab83b4f0a8058d96ad9626ead570674d5e737d90/charset_normalizer-3.4.4-cp313-cp313-win_amd64.whl", hash = "sha256:b435cba5f4f750aa6c0a0d92c541fb79f69a387c91e61f1795227e4ed9cece14", size = 107092, upload-time = "2025-10-14T04:41:31.188Z" },
+    { url = "https://files.pythonhosted.org/packages/af/8f/3ed4bfa0c0c72a7ca17f0380cd9e4dd842b09f664e780c13cff1dcf2ef1b/charset_normalizer-3.4.4-cp313-cp313-win_arm64.whl", hash = "sha256:542d2cee80be6f80247095cc36c418f7bddd14f4a6de45af91dfad36d817bba2", size = 100408, upload-time = "2025-10-14T04:41:32.624Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/35/7051599bd493e62411d6ede36fd5af83a38f37c4767b92884df7301db25d/charset_normalizer-3.4.4-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:da3326d9e65ef63a817ecbcc0df6e94463713b754fe293eaa03da99befb9a5bd", size = 207746, upload-time = "2025-10-14T04:41:33.773Z" },
+    { url = "https://files.pythonhosted.org/packages/10/9a/97c8d48ef10d6cd4fcead2415523221624bf58bcf68a802721a6bc807c8f/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8af65f14dc14a79b924524b1e7fffe304517b2bff5a58bf64f30b98bbc5079eb", size = 147889, upload-time = "2025-10-14T04:41:34.897Z" },
+    { url = "https://files.pythonhosted.org/packages/10/bf/979224a919a1b606c82bd2c5fa49b5c6d5727aa47b4312bb27b1734f53cd/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:74664978bb272435107de04e36db5a9735e78232b85b77d45cfb38f758efd33e", size = 143641, upload-time = "2025-10-14T04:41:36.116Z" },
+    { url = "https://files.pythonhosted.org/packages/ba/33/0ad65587441fc730dc7bd90e9716b30b4702dc7b617e6ba4997dc8651495/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:752944c7ffbfdd10c074dc58ec2d5a8a4cd9493b314d367c14d24c17684ddd14", size = 160779, upload-time = "2025-10-14T04:41:37.229Z" },
+    { url = "https://files.pythonhosted.org/packages/67/ed/331d6b249259ee71ddea93f6f2f0a56cfebd46938bde6fcc6f7b9a3d0e09/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:d1f13550535ad8cff21b8d757a3257963e951d96e20ec82ab44bc64aeb62a191", size = 159035, upload-time = "2025-10-14T04:41:38.368Z" },
+    { url = "https://files.pythonhosted.org/packages/67/ff/f6b948ca32e4f2a4576aa129d8bed61f2e0543bf9f5f2b7fc3758ed005c9/charset_normalizer-3.4.4-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ecaae4149d99b1c9e7b88bb03e3221956f68fd6d50be2ef061b2381b61d20838", size = 152542, upload-time = "2025-10-14T04:41:39.862Z" },
+    { url = "https://files.pythonhosted.org/packages/16/85/276033dcbcc369eb176594de22728541a925b2632f9716428c851b149e83/charset_normalizer-3.4.4-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:cb6254dc36b47a990e59e1068afacdcd02958bdcce30bb50cc1700a8b9d624a6", size = 149524, upload-time = "2025-10-14T04:41:41.319Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/f2/6a2a1f722b6aba37050e626530a46a68f74e63683947a8acff92569f979a/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:c8ae8a0f02f57a6e61203a31428fa1d677cbe50c93622b4149d5c0f319c1d19e", size = 150395, upload-time = "2025-10-14T04:41:42.539Z" },
+    { url = "https://files.pythonhosted.org/packages/60/bb/2186cb2f2bbaea6338cad15ce23a67f9b0672929744381e28b0592676824/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:47cc91b2f4dd2833fddaedd2893006b0106129d4b94fdb6af1f4ce5a9965577c", size = 143680, upload-time = "2025-10-14T04:41:43.661Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/a5/bf6f13b772fbb2a90360eb620d52ed8f796f3c5caee8398c3b2eb7b1c60d/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:82004af6c302b5d3ab2cfc4cc5f29db16123b1a8417f2e25f9066f91d4411090", size = 162045, upload-time = "2025-10-14T04:41:44.821Z" },
+    { url = "https://files.pythonhosted.org/packages/df/c5/d1be898bf0dc3ef9030c3825e5d3b83f2c528d207d246cbabe245966808d/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:2b7d8f6c26245217bd2ad053761201e9f9680f8ce52f0fcd8d0755aeae5b2152", size = 149687, upload-time = "2025-10-14T04:41:46.442Z" },
+    { url = "https://files.pythonhosted.org/packages/a5/42/90c1f7b9341eef50c8a1cb3f098ac43b0508413f33affd762855f67a410e/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:799a7a5e4fb2d5898c60b640fd4981d6a25f1c11790935a44ce38c54e985f828", size = 160014, upload-time = "2025-10-14T04:41:47.631Z" },
+    { url = "https://files.pythonhosted.org/packages/76/be/4d3ee471e8145d12795ab655ece37baed0929462a86e72372fd25859047c/charset_normalizer-3.4.4-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:99ae2cffebb06e6c22bdc25801d7b30f503cc87dbd283479e7b606f70aff57ec", size = 154044, upload-time = "2025-10-14T04:41:48.81Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/6f/8f7af07237c34a1defe7defc565a9bc1807762f672c0fde711a4b22bf9c0/charset_normalizer-3.4.4-cp314-cp314-win32.whl", hash = "sha256:f9d332f8c2a2fcbffe1378594431458ddbef721c1769d78e2cbc06280d8155f9", size = 99940, upload-time = "2025-10-14T04:41:49.946Z" },
+    { url = "https://files.pythonhosted.org/packages/4b/51/8ade005e5ca5b0d80fb4aff72a3775b325bdc3d27408c8113811a7cbe640/charset_normalizer-3.4.4-cp314-cp314-win_amd64.whl", hash = "sha256:8a6562c3700cce886c5be75ade4a5db4214fda19fede41d9792d100288d8f94c", size = 107104, upload-time = "2025-10-14T04:41:51.051Z" },
+    { url = "https://files.pythonhosted.org/packages/da/5f/6b8f83a55bb8278772c5ae54a577f3099025f9ade59d0136ac24a0df4bde/charset_normalizer-3.4.4-cp314-cp314-win_arm64.whl", hash = "sha256:de00632ca48df9daf77a2c65a484531649261ec9f25489917f09e455cb09ddb2", size = 100743, upload-time = "2025-10-14T04:41:52.122Z" },
+    { url = "https://files.pythonhosted.org/packages/0a/4c/925909008ed5a988ccbb72dcc897407e5d6d3bd72410d69e051fc0c14647/charset_normalizer-3.4.4-py3-none-any.whl", hash = "sha256:7a32c560861a02ff789ad905a2fe94e3f840803362c84fecf1851cb4cf3dc37f", size = 53402, upload-time = "2025-10-14T04:42:31.76Z" },
+]
+
+[[package]]
+name = "googleapis-common-protos"
+version = "1.72.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "protobuf" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e5/7b/adfd75544c415c487b33061fe7ae526165241c1ea133f9a9125a56b39fd8/googleapis_common_protos-1.72.0.tar.gz", hash = "sha256:e55a601c1b32b52d7a3e65f43563e2aa61bcd737998ee672ac9b951cd49319f5", size = 147433, upload-time = "2025-11-06T18:29:24.087Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c4/ab/09169d5a4612a5f92490806649ac8d41e3ec9129c636754575b3553f4ea4/googleapis_common_protos-1.72.0-py3-none-any.whl", hash = "sha256:4299c5a82d5ae1a9702ada957347726b167f9f8d1fc352477702a1e851ff4038", size = 297515, upload-time = "2025-11-06T18:29:13.14Z" },
+]
+
+[[package]]
+name = "idna"
+version = "3.11"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/6f/6d/0703ccc57f3a7233505399edb88de3cbd678da106337b9fcde432b65ed60/idna-3.11.tar.gz", hash = "sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902", size = 194582, upload-time = "2025-10-12T14:55:20.501Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl", hash = "sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea", size = 71008, upload-time = "2025-10-12T14:55:18.883Z" },
+]
+
+[[package]]
+name = "importlib-metadata"
+version = "8.7.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "zipp" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/76/66/650a33bd90f786193e4de4b3ad86ea60b53c89b669a5c7be931fac31cdb0/importlib_metadata-8.7.0.tar.gz", hash = "sha256:d13b81ad223b890aa16c5471f2ac3056cf76c5f10f82d6f9292f0b415f389000", size = 56641, upload-time = "2025-04-27T15:29:01.736Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/20/b0/36bd937216ec521246249be3bf9855081de4c5e06a0c9b4219dbeda50373/importlib_metadata-8.7.0-py3-none-any.whl", hash = "sha256:e5dd1551894c77868a30651cef00984d50e1002d06942a7101d34870c5f02afd", size = 27656, upload-time = "2025-04-27T15:29:00.214Z" },
+]
+
+[[package]]
+name = "jsonschema"
+version = "4.25.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "jsonschema-specifications" },
+    { name = "referencing" },
+    { name = "rpds-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/74/69/f7185de793a29082a9f3c7728268ffb31cb5095131a9c139a74078e27336/jsonschema-4.25.1.tar.gz", hash = "sha256:e4a9655ce0da0c0b67a085847e00a3a51449e1157f4f75e9fb5aa545e122eb85", size = 357342, upload-time = "2025-08-18T17:03:50.038Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/bf/9c/8c95d856233c1f82500c2450b8c68576b4cf1c871db3afac5c34ff84e6fd/jsonschema-4.25.1-py3-none-any.whl", hash = "sha256:3fba0169e345c7175110351d456342c364814cfcf3b964ba4587f22915230a63", size = 90040, upload-time = "2025-08-18T17:03:48.373Z" },
+]
+
+[[package]]
+name = "jsonschema-specifications"
+version = "2025.9.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "referencing" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/74/a633ee74eb36c44aa6d1095e7cc5569bebf04342ee146178e2d36600708b/jsonschema_specifications-2025.9.1.tar.gz", hash = "sha256:b540987f239e745613c7a9176f3edb72b832a4ac465cf02712288397832b5e8d", size = 32855, upload-time = "2025-09-08T01:34:59.186Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" },
+]
+
+[[package]]
+name = "llama-stack-api"
+version = "0.4.0.dev0"
+source = { editable = "." }
+dependencies = [
+    { name = "jsonschema" },
+    { name = "opentelemetry-exporter-otlp-proto-http" },
+    { name = "opentelemetry-sdk" },
+    { name = "pydantic" },
+]
+
+[package.metadata]
+requires-dist = [
+    { name = "jsonschema" },
+    { name = "opentelemetry-exporter-otlp-proto-http", specifier = ">=1.30.0" },
+    { name = "opentelemetry-sdk", specifier = ">=1.30.0" },
+    { name = "pydantic", specifier = ">=2.11.9" },
+]
+
+[[package]]
+name = "opentelemetry-api"
+version = "1.38.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "importlib-metadata" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/08/d8/0f354c375628e048bd0570645b310797299754730079853095bf000fba69/opentelemetry_api-1.38.0.tar.gz", hash = "sha256:f4c193b5e8acb0912b06ac5b16321908dd0843d75049c091487322284a3eea12", size = 65242, upload-time = "2025-10-16T08:35:50.25Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/ae/a2/d86e01c28300bd41bab8f18afd613676e2bd63515417b77636fc1add426f/opentelemetry_api-1.38.0-py3-none-any.whl", hash = "sha256:2891b0197f47124454ab9f0cf58f3be33faca394457ac3e09daba13ff50aa582", size = 65947, upload-time = "2025-10-16T08:35:30.23Z" },
+]
+
+[[package]]
+name = "opentelemetry-exporter-otlp-proto-common"
+version = "1.38.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-proto" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/83/dd4660f2956ff88ed071e9e0e36e830df14b8c5dc06722dbde1841accbe8/opentelemetry_exporter_otlp_proto_common-1.38.0.tar.gz", hash = "sha256:e333278afab4695aa8114eeb7bf4e44e65c6607d54968271a249c180b2cb605c", size = 20431, upload-time = "2025-10-16T08:35:53.285Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a7/9e/55a41c9601191e8cd8eb626b54ee6827b9c9d4a46d736f32abc80d8039fc/opentelemetry_exporter_otlp_proto_common-1.38.0-py3-none-any.whl", hash = "sha256:03cb76ab213300fe4f4c62b7d8f17d97fcfd21b89f0b5ce38ea156327ddda74a", size = 18359, upload-time = "2025-10-16T08:35:34.099Z" },
+]
+
+[[package]]
+name = "opentelemetry-exporter-otlp-proto-http"
+version = "1.38.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "googleapis-common-protos" },
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-exporter-otlp-proto-common" },
+    { name = "opentelemetry-proto" },
+    { name = "opentelemetry-sdk" },
+    { name = "requests" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/81/0a/debcdfb029fbd1ccd1563f7c287b89a6f7bef3b2902ade56797bfd020854/opentelemetry_exporter_otlp_proto_http-1.38.0.tar.gz", hash = "sha256:f16bd44baf15cbe07633c5112ffc68229d0edbeac7b37610be0b2def4e21e90b", size = 17282, upload-time = "2025-10-16T08:35:54.422Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e5/77/154004c99fb9f291f74aa0822a2f5bbf565a72d8126b3a1b63ed8e5f83c7/opentelemetry_exporter_otlp_proto_http-1.38.0-py3-none-any.whl", hash = "sha256:84b937305edfc563f08ec69b9cb2298be8188371217e867c1854d77198d0825b", size = 19579, upload-time = "2025-10-16T08:35:36.269Z" },
+]
+
+[[package]]
+name = "opentelemetry-proto"
+version = "1.38.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "protobuf" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/51/14/f0c4f0f6371b9cb7f9fa9ee8918bfd59ac7040c7791f1e6da32a1839780d/opentelemetry_proto-1.38.0.tar.gz", hash = "sha256:88b161e89d9d372ce723da289b7da74c3a8354a8e5359992be813942969ed468", size = 46152, upload-time = "2025-10-16T08:36:01.612Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b6/6a/82b68b14efca5150b2632f3692d627afa76b77378c4999f2648979409528/opentelemetry_proto-1.38.0-py3-none-any.whl", hash = "sha256:b6ebe54d3217c42e45462e2a1ae28c3e2bf2ec5a5645236a490f55f45f1a0a18", size = 72535, upload-time = "2025-10-16T08:35:45.749Z" },
+]
+
+[[package]]
+name = "opentelemetry-sdk"
+version = "1.38.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "opentelemetry-semantic-conventions" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/85/cb/f0eee1445161faf4c9af3ba7b848cc22a50a3d3e2515051ad8628c35ff80/opentelemetry_sdk-1.38.0.tar.gz", hash = "sha256:93df5d4d871ed09cb4272305be4d996236eedb232253e3ab864c8620f051cebe", size = 171942, upload-time = "2025-10-16T08:36:02.257Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2f/2e/e93777a95d7d9c40d270a371392b6d6f1ff170c2a3cb32d6176741b5b723/opentelemetry_sdk-1.38.0-py3-none-any.whl", hash = "sha256:1c66af6564ecc1553d72d811a01df063ff097cdc82ce188da9951f93b8d10f6b", size = 132349, upload-time = "2025-10-16T08:35:46.995Z" },
+]
+
+[[package]]
+name = "opentelemetry-semantic-conventions"
+version = "0.59b0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "opentelemetry-api" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/40/bc/8b9ad3802cd8ac6583a4eb7de7e5d7db004e89cb7efe7008f9c8a537ee75/opentelemetry_semantic_conventions-0.59b0.tar.gz", hash = "sha256:7a6db3f30d70202d5bf9fa4b69bc866ca6a30437287de6c510fb594878aed6b0", size = 129861, upload-time = "2025-10-16T08:36:03.346Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/24/7d/c88d7b15ba8fe5c6b8f93be50fc11795e9fc05386c44afaf6b76fe191f9b/opentelemetry_semantic_conventions-0.59b0-py3-none-any.whl", hash = "sha256:35d3b8833ef97d614136e253c1da9342b4c3c083bbaf29ce31d572a1c3825eed", size = 207954, upload-time = "2025-10-16T08:35:48.054Z" },
+]
+
+[[package]]
+name = "protobuf"
+version = "6.33.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/0a/03/a1440979a3f74f16cab3b75b0da1a1a7f922d56a8ddea96092391998edc0/protobuf-6.33.1.tar.gz", hash = "sha256:97f65757e8d09870de6fd973aeddb92f85435607235d20b2dfed93405d00c85b", size = 443432, upload-time = "2025-11-13T16:44:18.895Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/06/f1/446a9bbd2c60772ca36556bac8bfde40eceb28d9cc7838755bc41e001d8f/protobuf-6.33.1-cp310-abi3-win32.whl", hash = "sha256:f8d3fdbc966aaab1d05046d0240dd94d40f2a8c62856d41eaa141ff64a79de6b", size = 425593, upload-time = "2025-11-13T16:44:06.275Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/79/8780a378c650e3df849b73de8b13cf5412f521ca2ff9b78a45c247029440/protobuf-6.33.1-cp310-abi3-win_amd64.whl", hash = "sha256:923aa6d27a92bf44394f6abf7ea0500f38769d4b07f4be41cb52bd8b1123b9ed", size = 436883, upload-time = "2025-11-13T16:44:09.222Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/93/26213ff72b103ae55bb0d73e7fb91ea570ef407c3ab4fd2f1f27cac16044/protobuf-6.33.1-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:fe34575f2bdde76ac429ec7b570235bf0c788883e70aee90068e9981806f2490", size = 427522, upload-time = "2025-11-13T16:44:10.475Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/32/df4a35247923393aa6b887c3b3244a8c941c32a25681775f96e2b418f90e/protobuf-6.33.1-cp39-abi3-manylinux2014_aarch64.whl", hash = "sha256:f8adba2e44cde2d7618996b3fc02341f03f5bc3f2748be72dc7b063319276178", size = 324445, upload-time = "2025-11-13T16:44:11.869Z" },
+    { url = "https://files.pythonhosted.org/packages/8e/d0/d796e419e2ec93d2f3fa44888861c3f88f722cde02b7c3488fcc6a166820/protobuf-6.33.1-cp39-abi3-manylinux2014_s390x.whl", hash = "sha256:0f4cf01222c0d959c2b399142deb526de420be8236f22c71356e2a544e153c53", size = 339161, upload-time = "2025-11-13T16:44:12.778Z" },
+    { url = "https://files.pythonhosted.org/packages/1d/2a/3c5f05a4af06649547027d288747f68525755de692a26a7720dced3652c0/protobuf-6.33.1-cp39-abi3-manylinux2014_x86_64.whl", hash = "sha256:8fd7d5e0eb08cd5b87fd3df49bc193f5cfd778701f47e11d127d0afc6c39f1d1", size = 323171, upload-time = "2025-11-13T16:44:14.035Z" },
+    { url = "https://files.pythonhosted.org/packages/08/b4/46310463b4f6ceef310f8348786f3cff181cea671578e3d9743ba61a459e/protobuf-6.33.1-py3-none-any.whl", hash = "sha256:d595a9fd694fdeb061a62fbe10eb039cc1e444df81ec9bb70c7fc59ebcb1eafa", size = 170477, upload-time = "2025-11-13T16:44:17.633Z" },
+]
+
+[[package]]
+name = "pydantic"
+version = "2.12.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-types" },
+    { name = "pydantic-core" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/96/ad/a17bc283d7d81837c061c49e3eaa27a45991759a1b7eae1031921c6bd924/pydantic-2.12.4.tar.gz", hash = "sha256:0f8cb9555000a4b5b617f66bfd2566264c4984b27589d3b845685983e8ea85ac", size = 821038, upload-time = "2025-11-05T10:50:08.59Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/82/2f/e68750da9b04856e2a7ec56fc6f034a5a79775e9b9a81882252789873798/pydantic-2.12.4-py3-none-any.whl", hash = "sha256:92d3d202a745d46f9be6df459ac5a064fdaa3c1c4cd8adcfa332ccf3c05f871e", size = 463400, upload-time = "2025-11-05T10:50:06.732Z" },
+]
+
+[[package]]
+name = "pydantic-core"
+version = "2.41.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/71/70/23b021c950c2addd24ec408e9ab05d59b035b39d97cdc1130e1bce647bb6/pydantic_core-2.41.5.tar.gz", hash = "sha256:08daa51ea16ad373ffd5e7606252cc32f07bc72b28284b6bc9c6df804816476e", size = 460952, upload-time = "2025-11-04T13:43:49.098Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/5f/5d/5f6c63eebb5afee93bcaae4ce9a898f3373ca23df3ccaef086d0233a35a7/pydantic_core-2.41.5-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:f41a7489d32336dbf2199c8c0a215390a751c5b014c2c1c5366e817202e9cdf7", size = 2110990, upload-time = "2025-11-04T13:39:58.079Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/32/9c2e8ccb57c01111e0fd091f236c7b371c1bccea0fa85247ac55b1e2b6b6/pydantic_core-2.41.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:070259a8818988b9a84a449a2a7337c7f430a22acc0859c6b110aa7212a6d9c0", size = 1896003, upload-time = "2025-11-04T13:39:59.956Z" },
+    { url = "https://files.pythonhosted.org/packages/68/b8/a01b53cb0e59139fbc9e4fda3e9724ede8de279097179be4ff31f1abb65a/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e96cea19e34778f8d59fe40775a7a574d95816eb150850a85a7a4c8f4b94ac69", size = 1919200, upload-time = "2025-11-04T13:40:02.241Z" },
+    { url = "https://files.pythonhosted.org/packages/38/de/8c36b5198a29bdaade07b5985e80a233a5ac27137846f3bc2d3b40a47360/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ed2e99c456e3fadd05c991f8f437ef902e00eedf34320ba2b0842bd1c3ca3a75", size = 2052578, upload-time = "2025-11-04T13:40:04.401Z" },
+    { url = "https://files.pythonhosted.org/packages/00/b5/0e8e4b5b081eac6cb3dbb7e60a65907549a1ce035a724368c330112adfdd/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:65840751b72fbfd82c3c640cff9284545342a4f1eb1586ad0636955b261b0b05", size = 2208504, upload-time = "2025-11-04T13:40:06.072Z" },
+    { url = "https://files.pythonhosted.org/packages/77/56/87a61aad59c7c5b9dc8caad5a41a5545cba3810c3e828708b3d7404f6cef/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e536c98a7626a98feb2d3eaf75944ef6f3dbee447e1f841eae16f2f0a72d8ddc", size = 2335816, upload-time = "2025-11-04T13:40:07.835Z" },
+    { url = "https://files.pythonhosted.org/packages/0d/76/941cc9f73529988688a665a5c0ecff1112b3d95ab48f81db5f7606f522d3/pydantic_core-2.41.5-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:eceb81a8d74f9267ef4081e246ffd6d129da5d87e37a77c9bde550cb04870c1c", size = 2075366, upload-time = "2025-11-04T13:40:09.804Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/43/ebef01f69baa07a482844faaa0a591bad1ef129253ffd0cdaa9d8a7f72d3/pydantic_core-2.41.5-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d38548150c39b74aeeb0ce8ee1d8e82696f4a4e16ddc6de7b1d8823f7de4b9b5", size = 2171698, upload-time = "2025-11-04T13:40:12.004Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/87/41f3202e4193e3bacfc2c065fab7706ebe81af46a83d3e27605029c1f5a6/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:c23e27686783f60290e36827f9c626e63154b82b116d7fe9adba1fda36da706c", size = 2132603, upload-time = "2025-11-04T13:40:13.868Z" },
+    { url = "https://files.pythonhosted.org/packages/49/7d/4c00df99cb12070b6bccdef4a195255e6020a550d572768d92cc54dba91a/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_armv7l.whl", hash = "sha256:482c982f814460eabe1d3bb0adfdc583387bd4691ef00b90575ca0d2b6fe2294", size = 2329591, upload-time = "2025-11-04T13:40:15.672Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/6a/ebf4b1d65d458f3cda6a7335d141305dfa19bdc61140a884d165a8a1bbc7/pydantic_core-2.41.5-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:bfea2a5f0b4d8d43adf9d7b8bf019fb46fdd10a2e5cde477fbcb9d1fa08c68e1", size = 2319068, upload-time = "2025-11-04T13:40:17.532Z" },
+    { url = "https://files.pythonhosted.org/packages/49/3b/774f2b5cd4192d5ab75870ce4381fd89cf218af999515baf07e7206753f0/pydantic_core-2.41.5-cp312-cp312-win32.whl", hash = "sha256:b74557b16e390ec12dca509bce9264c3bbd128f8a2c376eaa68003d7f327276d", size = 1985908, upload-time = "2025-11-04T13:40:19.309Z" },
+    { url = "https://files.pythonhosted.org/packages/86/45/00173a033c801cacf67c190fef088789394feaf88a98a7035b0e40d53dc9/pydantic_core-2.41.5-cp312-cp312-win_amd64.whl", hash = "sha256:1962293292865bca8e54702b08a4f26da73adc83dd1fcf26fbc875b35d81c815", size = 2020145, upload-time = "2025-11-04T13:40:21.548Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/22/91fbc821fa6d261b376a3f73809f907cec5ca6025642c463d3488aad22fb/pydantic_core-2.41.5-cp312-cp312-win_arm64.whl", hash = "sha256:1746d4a3d9a794cacae06a5eaaccb4b8643a131d45fbc9af23e353dc0a5ba5c3", size = 1976179, upload-time = "2025-11-04T13:40:23.393Z" },
+    { url = "https://files.pythonhosted.org/packages/87/06/8806241ff1f70d9939f9af039c6c35f2360cf16e93c2ca76f184e76b1564/pydantic_core-2.41.5-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:941103c9be18ac8daf7b7adca8228f8ed6bb7a1849020f643b3a14d15b1924d9", size = 2120403, upload-time = "2025-11-04T13:40:25.248Z" },
+    { url = "https://files.pythonhosted.org/packages/94/02/abfa0e0bda67faa65fef1c84971c7e45928e108fe24333c81f3bfe35d5f5/pydantic_core-2.41.5-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:112e305c3314f40c93998e567879e887a3160bb8689ef3d2c04b6cc62c33ac34", size = 1896206, upload-time = "2025-11-04T13:40:27.099Z" },
+    { url = "https://files.pythonhosted.org/packages/15/df/a4c740c0943e93e6500f9eb23f4ca7ec9bf71b19e608ae5b579678c8d02f/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0cbaad15cb0c90aa221d43c00e77bb33c93e8d36e0bf74760cd00e732d10a6a0", size = 1919307, upload-time = "2025-11-04T13:40:29.806Z" },
+    { url = "https://files.pythonhosted.org/packages/9a/e3/6324802931ae1d123528988e0e86587c2072ac2e5394b4bc2bc34b61ff6e/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:03ca43e12fab6023fc79d28ca6b39b05f794ad08ec2feccc59a339b02f2b3d33", size = 2063258, upload-time = "2025-11-04T13:40:33.544Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/d4/2230d7151d4957dd79c3044ea26346c148c98fbf0ee6ebd41056f2d62ab5/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:dc799088c08fa04e43144b164feb0c13f9a0bc40503f8df3e9fde58a3c0c101e", size = 2214917, upload-time = "2025-11-04T13:40:35.479Z" },
+    { url = "https://files.pythonhosted.org/packages/e6/9f/eaac5df17a3672fef0081b6c1bb0b82b33ee89aa5cec0d7b05f52fd4a1fa/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:97aeba56665b4c3235a0e52b2c2f5ae9cd071b8a8310ad27bddb3f7fb30e9aa2", size = 2332186, upload-time = "2025-11-04T13:40:37.436Z" },
+    { url = "https://files.pythonhosted.org/packages/cf/4e/35a80cae583a37cf15604b44240e45c05e04e86f9cfd766623149297e971/pydantic_core-2.41.5-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:406bf18d345822d6c21366031003612b9c77b3e29ffdb0f612367352aab7d586", size = 2073164, upload-time = "2025-11-04T13:40:40.289Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/e3/f6e262673c6140dd3305d144d032f7bd5f7497d3871c1428521f19f9efa2/pydantic_core-2.41.5-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:b93590ae81f7010dbe380cdeab6f515902ebcbefe0b9327cc4804d74e93ae69d", size = 2179146, upload-time = "2025-11-04T13:40:42.809Z" },
+    { url = "https://files.pythonhosted.org/packages/75/c7/20bd7fc05f0c6ea2056a4565c6f36f8968c0924f19b7d97bbfea55780e73/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:01a3d0ab748ee531f4ea6c3e48ad9dac84ddba4b0d82291f87248f2f9de8d740", size = 2137788, upload-time = "2025-11-04T13:40:44.752Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/8d/34318ef985c45196e004bc46c6eab2eda437e744c124ef0dbe1ff2c9d06b/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_armv7l.whl", hash = "sha256:6561e94ba9dacc9c61bce40e2d6bdc3bfaa0259d3ff36ace3b1e6901936d2e3e", size = 2340133, upload-time = "2025-11-04T13:40:46.66Z" },
+    { url = "https://files.pythonhosted.org/packages/9c/59/013626bf8c78a5a5d9350d12e7697d3d4de951a75565496abd40ccd46bee/pydantic_core-2.41.5-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:915c3d10f81bec3a74fbd4faebe8391013ba61e5a1a8d48c4455b923bdda7858", size = 2324852, upload-time = "2025-11-04T13:40:48.575Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/d9/c248c103856f807ef70c18a4f986693a46a8ffe1602e5d361485da502d20/pydantic_core-2.41.5-cp313-cp313-win32.whl", hash = "sha256:650ae77860b45cfa6e2cdafc42618ceafab3a2d9a3811fcfbd3bbf8ac3c40d36", size = 1994679, upload-time = "2025-11-04T13:40:50.619Z" },
+    { url = "https://files.pythonhosted.org/packages/9e/8b/341991b158ddab181cff136acd2552c9f35bd30380422a639c0671e99a91/pydantic_core-2.41.5-cp313-cp313-win_amd64.whl", hash = "sha256:79ec52ec461e99e13791ec6508c722742ad745571f234ea6255bed38c6480f11", size = 2019766, upload-time = "2025-11-04T13:40:52.631Z" },
+    { url = "https://files.pythonhosted.org/packages/73/7d/f2f9db34af103bea3e09735bb40b021788a5e834c81eedb541991badf8f5/pydantic_core-2.41.5-cp313-cp313-win_arm64.whl", hash = "sha256:3f84d5c1b4ab906093bdc1ff10484838aca54ef08de4afa9de0f5f14d69639cd", size = 1981005, upload-time = "2025-11-04T13:40:54.734Z" },
+    { url = "https://files.pythonhosted.org/packages/ea/28/46b7c5c9635ae96ea0fbb779e271a38129df2550f763937659ee6c5dbc65/pydantic_core-2.41.5-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:3f37a19d7ebcdd20b96485056ba9e8b304e27d9904d233d7b1015db320e51f0a", size = 2119622, upload-time = "2025-11-04T13:40:56.68Z" },
+    { url = "https://files.pythonhosted.org/packages/74/1a/145646e5687e8d9a1e8d09acb278c8535ebe9e972e1f162ed338a622f193/pydantic_core-2.41.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1d1d9764366c73f996edd17abb6d9d7649a7eb690006ab6adbda117717099b14", size = 1891725, upload-time = "2025-11-04T13:40:58.807Z" },
+    { url = "https://files.pythonhosted.org/packages/23/04/e89c29e267b8060b40dca97bfc64a19b2a3cf99018167ea1677d96368273/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:25e1c2af0fce638d5f1988b686f3b3ea8cd7de5f244ca147c777769e798a9cd1", size = 1915040, upload-time = "2025-11-04T13:41:00.853Z" },
+    { url = "https://files.pythonhosted.org/packages/84/a3/15a82ac7bd97992a82257f777b3583d3e84bdb06ba6858f745daa2ec8a85/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:506d766a8727beef16b7adaeb8ee6217c64fc813646b424d0804d67c16eddb66", size = 2063691, upload-time = "2025-11-04T13:41:03.504Z" },
+    { url = "https://files.pythonhosted.org/packages/74/9b/0046701313c6ef08c0c1cf0e028c67c770a4e1275ca73131563c5f2a310a/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:4819fa52133c9aa3c387b3328f25c1facc356491e6135b459f1de698ff64d869", size = 2213897, upload-time = "2025-11-04T13:41:05.804Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/cd/6bac76ecd1b27e75a95ca3a9a559c643b3afcd2dd62086d4b7a32a18b169/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2b761d210c9ea91feda40d25b4efe82a1707da2ef62901466a42492c028553a2", size = 2333302, upload-time = "2025-11-04T13:41:07.809Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/d2/ef2074dc020dd6e109611a8be4449b98cd25e1b9b8a303c2f0fca2f2bcf7/pydantic_core-2.41.5-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:22f0fb8c1c583a3b6f24df2470833b40207e907b90c928cc8d3594b76f874375", size = 2064877, upload-time = "2025-11-04T13:41:09.827Z" },
+    { url = "https://files.pythonhosted.org/packages/18/66/e9db17a9a763d72f03de903883c057b2592c09509ccfe468187f2a2eef29/pydantic_core-2.41.5-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2782c870e99878c634505236d81e5443092fba820f0373997ff75f90f68cd553", size = 2180680, upload-time = "2025-11-04T13:41:12.379Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/9e/3ce66cebb929f3ced22be85d4c2399b8e85b622db77dad36b73c5387f8f8/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:0177272f88ab8312479336e1d777f6b124537d47f2123f89cb37e0accea97f90", size = 2138960, upload-time = "2025-11-04T13:41:14.627Z" },
+    { url = "https://files.pythonhosted.org/packages/a6/62/205a998f4327d2079326b01abee48e502ea739d174f0a89295c481a2272e/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:63510af5e38f8955b8ee5687740d6ebf7c2a0886d15a6d65c32814613681bc07", size = 2339102, upload-time = "2025-11-04T13:41:16.868Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/0d/f05e79471e889d74d3d88f5bd20d0ed189ad94c2423d81ff8d0000aab4ff/pydantic_core-2.41.5-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:e56ba91f47764cc14f1daacd723e3e82d1a89d783f0f5afe9c364b8bb491ccdb", size = 2326039, upload-time = "2025-11-04T13:41:18.934Z" },
+    { url = "https://files.pythonhosted.org/packages/ec/e1/e08a6208bb100da7e0c4b288eed624a703f4d129bde2da475721a80cab32/pydantic_core-2.41.5-cp314-cp314-win32.whl", hash = "sha256:aec5cf2fd867b4ff45b9959f8b20ea3993fc93e63c7363fe6851424c8a7e7c23", size = 1995126, upload-time = "2025-11-04T13:41:21.418Z" },
+    { url = "https://files.pythonhosted.org/packages/48/5d/56ba7b24e9557f99c9237e29f5c09913c81eeb2f3217e40e922353668092/pydantic_core-2.41.5-cp314-cp314-win_amd64.whl", hash = "sha256:8e7c86f27c585ef37c35e56a96363ab8de4e549a95512445b85c96d3e2f7c1bf", size = 2015489, upload-time = "2025-11-04T13:41:24.076Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/bb/f7a190991ec9e3e0ba22e4993d8755bbc4a32925c0b5b42775c03e8148f9/pydantic_core-2.41.5-cp314-cp314-win_arm64.whl", hash = "sha256:e672ba74fbc2dc8eea59fb6d4aed6845e6905fc2a8afe93175d94a83ba2a01a0", size = 1977288, upload-time = "2025-11-04T13:41:26.33Z" },
+    { url = "https://files.pythonhosted.org/packages/92/ed/77542d0c51538e32e15afe7899d79efce4b81eee631d99850edc2f5e9349/pydantic_core-2.41.5-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:8566def80554c3faa0e65ac30ab0932b9e3a5cd7f8323764303d468e5c37595a", size = 2120255, upload-time = "2025-11-04T13:41:28.569Z" },
+    { url = "https://files.pythonhosted.org/packages/bb/3d/6913dde84d5be21e284439676168b28d8bbba5600d838b9dca99de0fad71/pydantic_core-2.41.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b80aa5095cd3109962a298ce14110ae16b8c1aece8b72f9dafe81cf597ad80b3", size = 1863760, upload-time = "2025-11-04T13:41:31.055Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/f0/e5e6b99d4191da102f2b0eb9687aaa7f5bea5d9964071a84effc3e40f997/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:3006c3dd9ba34b0c094c544c6006cc79e87d8612999f1a5d43b769b89181f23c", size = 1878092, upload-time = "2025-11-04T13:41:33.21Z" },
+    { url = "https://files.pythonhosted.org/packages/71/48/36fb760642d568925953bcc8116455513d6e34c4beaa37544118c36aba6d/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:72f6c8b11857a856bcfa48c86f5368439f74453563f951e473514579d44aa612", size = 2053385, upload-time = "2025-11-04T13:41:35.508Z" },
+    { url = "https://files.pythonhosted.org/packages/20/25/92dc684dd8eb75a234bc1c764b4210cf2646479d54b47bf46061657292a8/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5cb1b2f9742240e4bb26b652a5aeb840aa4b417c7748b6f8387927bc6e45e40d", size = 2218832, upload-time = "2025-11-04T13:41:37.732Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/09/f53e0b05023d3e30357d82eb35835d0f6340ca344720a4599cd663dca599/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bd3d54f38609ff308209bd43acea66061494157703364ae40c951f83ba99a1a9", size = 2327585, upload-time = "2025-11-04T13:41:40Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/4e/2ae1aa85d6af35a39b236b1b1641de73f5a6ac4d5a7509f77b814885760c/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2ff4321e56e879ee8d2a879501c8e469414d948f4aba74a2d4593184eb326660", size = 2041078, upload-time = "2025-11-04T13:41:42.323Z" },
+    { url = "https://files.pythonhosted.org/packages/cd/13/2e215f17f0ef326fc72afe94776edb77525142c693767fc347ed6288728d/pydantic_core-2.41.5-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d0d2568a8c11bf8225044aa94409e21da0cb09dcdafe9ecd10250b2baad531a9", size = 2173914, upload-time = "2025-11-04T13:41:45.221Z" },
+    { url = "https://files.pythonhosted.org/packages/02/7a/f999a6dcbcd0e5660bc348a3991c8915ce6599f4f2c6ac22f01d7a10816c/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:a39455728aabd58ceabb03c90e12f71fd30fa69615760a075b9fec596456ccc3", size = 2129560, upload-time = "2025-11-04T13:41:47.474Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/b1/6c990ac65e3b4c079a4fb9f5b05f5b013afa0f4ed6780a3dd236d2cbdc64/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:239edca560d05757817c13dc17c50766136d21f7cd0fac50295499ae24f90fdf", size = 2329244, upload-time = "2025-11-04T13:41:49.992Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/02/3c562f3a51afd4d88fff8dffb1771b30cfdfd79befd9883ee094f5b6c0d8/pydantic_core-2.41.5-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:2a5e06546e19f24c6a96a129142a75cee553cc018ffee48a460059b1185f4470", size = 2331955, upload-time = "2025-11-04T13:41:54.079Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/96/5fb7d8c3c17bc8c62fdb031c47d77a1af698f1d7a406b0f79aaa1338f9ad/pydantic_core-2.41.5-cp314-cp314t-win32.whl", hash = "sha256:b4ececa40ac28afa90871c2cc2b9ffd2ff0bf749380fbdf57d165fd23da353aa", size = 1988906, upload-time = "2025-11-04T13:41:56.606Z" },
+    { url = "https://files.pythonhosted.org/packages/22/ed/182129d83032702912c2e2d8bbe33c036f342cc735737064668585dac28f/pydantic_core-2.41.5-cp314-cp314t-win_amd64.whl", hash = "sha256:80aa89cad80b32a912a65332f64a4450ed00966111b6615ca6816153d3585a8c", size = 1981607, upload-time = "2025-11-04T13:41:58.889Z" },
+    { url = "https://files.pythonhosted.org/packages/9f/ed/068e41660b832bb0b1aa5b58011dea2a3fe0ba7861ff38c4d4904c1c1a99/pydantic_core-2.41.5-cp314-cp314t-win_arm64.whl", hash = "sha256:35b44f37a3199f771c3eaa53051bc8a70cd7b54f333531c59e29fd4db5d15008", size = 1974769, upload-time = "2025-11-04T13:42:01.186Z" },
+    { url = "https://files.pythonhosted.org/packages/09/32/59b0c7e63e277fa7911c2fc70ccfb45ce4b98991e7ef37110663437005af/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:7da7087d756b19037bc2c06edc6c170eeef3c3bafcb8f532ff17d64dc427adfd", size = 2110495, upload-time = "2025-11-04T13:42:49.689Z" },
+    { url = "https://files.pythonhosted.org/packages/aa/81/05e400037eaf55ad400bcd318c05bb345b57e708887f07ddb2d20e3f0e98/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:aabf5777b5c8ca26f7824cb4a120a740c9588ed58df9b2d196ce92fba42ff8dc", size = 1915388, upload-time = "2025-11-04T13:42:52.215Z" },
+    { url = "https://files.pythonhosted.org/packages/6e/0d/e3549b2399f71d56476b77dbf3cf8937cec5cd70536bdc0e374a421d0599/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c007fe8a43d43b3969e8469004e9845944f1a80e6acd47c150856bb87f230c56", size = 1942879, upload-time = "2025-11-04T13:42:56.483Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/07/34573da085946b6a313d7c42f82f16e8920bfd730665de2d11c0c37a74b5/pydantic_core-2.41.5-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:76d0819de158cd855d1cbb8fcafdf6f5cf1eb8e470abe056d5d161106e38062b", size = 2139017, upload-time = "2025-11-04T13:42:59.471Z" },
+]
+
+[[package]]
+name = "referencing"
+version = "0.37.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "rpds-py" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/22/f5/df4e9027acead3ecc63e50fe1e36aca1523e1719559c499951bb4b53188f/referencing-0.37.0.tar.gz", hash = "sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8", size = 78036, upload-time = "2025-10-13T15:30:48.871Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" },
+]
+
+[[package]]
+name = "requests"
+version = "2.32.5"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "certifi" },
+    { name = "charset-normalizer" },
+    { name = "idna" },
+    { name = "urllib3" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c9/74/b3ff8e6c8446842c3f5c837e9c3dfcfe2018ea6ecef224c710c85ef728f4/requests-2.32.5.tar.gz", hash = "sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf", size = 134517, upload-time = "2025-08-18T20:46:02.573Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/1e/db/4254e3eabe8020b458f1a747140d32277ec7a271daf1d235b70dc0b4e6e3/requests-2.32.5-py3-none-any.whl", hash = "sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6", size = 64738, upload-time = "2025-08-18T20:46:00.542Z" },
+]
+
+[[package]]
+name = "rpds-py"
+version = "0.28.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/48/dc/95f074d43452b3ef5d06276696ece4b3b5d696e7c9ad7173c54b1390cd70/rpds_py-0.28.0.tar.gz", hash = "sha256:abd4df20485a0983e2ca334a216249b6186d6e3c1627e106651943dbdb791aea", size = 27419, upload-time = "2025-10-22T22:24:29.327Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b8/5c/6c3936495003875fe7b14f90ea812841a08fca50ab26bd840e924097d9c8/rpds_py-0.28.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:6b4f28583a4f247ff60cd7bdda83db8c3f5b05a7a82ff20dd4b078571747708f", size = 366439, upload-time = "2025-10-22T22:22:04.525Z" },
+    { url = "https://files.pythonhosted.org/packages/56/f9/a0f1ca194c50aa29895b442771f036a25b6c41a35e4f35b1a0ea713bedae/rpds_py-0.28.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:d678e91b610c29c4b3d52a2c148b641df2b4676ffe47c59f6388d58b99cdc424", size = 348170, upload-time = "2025-10-22T22:22:06.397Z" },
+    { url = "https://files.pythonhosted.org/packages/18/ea/42d243d3a586beb72c77fa5def0487daf827210069a95f36328e869599ea/rpds_py-0.28.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e819e0e37a44a78e1383bf1970076e2ccc4dc8c2bbaa2f9bd1dc987e9afff628", size = 378838, upload-time = "2025-10-22T22:22:07.932Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/78/3de32e18a94791af8f33601402d9d4f39613136398658412a4e0b3047327/rpds_py-0.28.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:5ee514e0f0523db5d3fb171f397c54875dbbd69760a414dccf9d4d7ad628b5bd", size = 393299, upload-time = "2025-10-22T22:22:09.435Z" },
+    { url = "https://files.pythonhosted.org/packages/13/7e/4bdb435afb18acea2eb8a25ad56b956f28de7c59f8a1d32827effa0d4514/rpds_py-0.28.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5f3fa06d27fdcee47f07a39e02862da0100cb4982508f5ead53ec533cd5fe55e", size = 518000, upload-time = "2025-10-22T22:22:11.326Z" },
+    { url = "https://files.pythonhosted.org/packages/31/d0/5f52a656875cdc60498ab035a7a0ac8f399890cc1ee73ebd567bac4e39ae/rpds_py-0.28.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:46959ef2e64f9e4a41fc89aa20dbca2b85531f9a72c21099a3360f35d10b0d5a", size = 408746, upload-time = "2025-10-22T22:22:13.143Z" },
+    { url = "https://files.pythonhosted.org/packages/3e/cd/49ce51767b879cde77e7ad9fae164ea15dce3616fe591d9ea1df51152706/rpds_py-0.28.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8455933b4bcd6e83fde3fefc987a023389c4b13f9a58c8d23e4b3f6d13f78c84", size = 386379, upload-time = "2025-10-22T22:22:14.602Z" },
+    { url = "https://files.pythonhosted.org/packages/6a/99/e4e1e1ee93a98f72fc450e36c0e4d99c35370220e815288e3ecd2ec36a2a/rpds_py-0.28.0-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:ad50614a02c8c2962feebe6012b52f9802deec4263946cddea37aaf28dd25a66", size = 401280, upload-time = "2025-10-22T22:22:16.063Z" },
+    { url = "https://files.pythonhosted.org/packages/61/35/e0c6a57488392a8b319d2200d03dad2b29c0db9996f5662c3b02d0b86c02/rpds_py-0.28.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:e5deca01b271492553fdb6c7fd974659dce736a15bae5dad7ab8b93555bceb28", size = 412365, upload-time = "2025-10-22T22:22:17.504Z" },
+    { url = "https://files.pythonhosted.org/packages/ff/6a/841337980ea253ec797eb084665436007a1aad0faac1ba097fb906c5f69c/rpds_py-0.28.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:735f8495a13159ce6a0d533f01e8674cec0c57038c920495f87dcb20b3ddb48a", size = 559573, upload-time = "2025-10-22T22:22:19.108Z" },
+    { url = "https://files.pythonhosted.org/packages/e7/5e/64826ec58afd4c489731f8b00729c5f6afdb86f1df1df60bfede55d650bb/rpds_py-0.28.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:961ca621ff10d198bbe6ba4957decca61aa2a0c56695384c1d6b79bf61436df5", size = 583973, upload-time = "2025-10-22T22:22:20.768Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/ee/44d024b4843f8386a4eeaa4c171b3d31d55f7177c415545fd1a24c249b5d/rpds_py-0.28.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:2374e16cc9131022e7d9a8f8d65d261d9ba55048c78f3b6e017971a4f5e6353c", size = 553800, upload-time = "2025-10-22T22:22:22.25Z" },
+    { url = "https://files.pythonhosted.org/packages/7d/89/33e675dccff11a06d4d85dbb4d1865f878d5020cbb69b2c1e7b2d3f82562/rpds_py-0.28.0-cp312-cp312-win32.whl", hash = "sha256:d15431e334fba488b081d47f30f091e5d03c18527c325386091f31718952fe08", size = 216954, upload-time = "2025-10-22T22:22:24.105Z" },
+    { url = "https://files.pythonhosted.org/packages/af/36/45f6ebb3210887e8ee6dbf1bc710ae8400bb417ce165aaf3024b8360d999/rpds_py-0.28.0-cp312-cp312-win_amd64.whl", hash = "sha256:a410542d61fc54710f750d3764380b53bf09e8c4edbf2f9141a82aa774a04f7c", size = 227844, upload-time = "2025-10-22T22:22:25.551Z" },
+    { url = "https://files.pythonhosted.org/packages/57/91/f3fb250d7e73de71080f9a221d19bd6a1c1eb0d12a1ea26513f6c1052ad6/rpds_py-0.28.0-cp312-cp312-win_arm64.whl", hash = "sha256:1f0cfd1c69e2d14f8c892b893997fa9a60d890a0c8a603e88dca4955f26d1edd", size = 217624, upload-time = "2025-10-22T22:22:26.914Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/03/ce566d92611dfac0085c2f4b048cd53ed7c274a5c05974b882a908d540a2/rpds_py-0.28.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:e9e184408a0297086f880556b6168fa927d677716f83d3472ea333b42171ee3b", size = 366235, upload-time = "2025-10-22T22:22:28.397Z" },
+    { url = "https://files.pythonhosted.org/packages/00/34/1c61da1b25592b86fd285bd7bd8422f4c9d748a7373b46126f9ae792a004/rpds_py-0.28.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:edd267266a9b0448f33dc465a97cfc5d467594b600fe28e7fa2f36450e03053a", size = 348241, upload-time = "2025-10-22T22:22:30.171Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/00/ed1e28616848c61c493a067779633ebf4b569eccaacf9ccbdc0e7cba2b9d/rpds_py-0.28.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:85beb8b3f45e4e32f6802fb6cd6b17f615ef6c6a52f265371fb916fae02814aa", size = 378079, upload-time = "2025-10-22T22:22:31.644Z" },
+    { url = "https://files.pythonhosted.org/packages/11/b2/ccb30333a16a470091b6e50289adb4d3ec656fd9951ba8c5e3aaa0746a67/rpds_py-0.28.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:d2412be8d00a1b895f8ad827cc2116455196e20ed994bb704bf138fe91a42724", size = 393151, upload-time = "2025-10-22T22:22:33.453Z" },
+    { url = "https://files.pythonhosted.org/packages/8c/d0/73e2217c3ee486d555cb84920597480627d8c0240ff3062005c6cc47773e/rpds_py-0.28.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:cf128350d384b777da0e68796afdcebc2e9f63f0e9f242217754e647f6d32491", size = 517520, upload-time = "2025-10-22T22:22:34.949Z" },
+    { url = "https://files.pythonhosted.org/packages/c4/91/23efe81c700427d0841a4ae7ea23e305654381831e6029499fe80be8a071/rpds_py-0.28.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:a2036d09b363aa36695d1cc1a97b36865597f4478470b0697b5ee9403f4fe399", size = 408699, upload-time = "2025-10-22T22:22:36.584Z" },
+    { url = "https://files.pythonhosted.org/packages/ca/ee/a324d3198da151820a326c1f988caaa4f37fc27955148a76fff7a2d787a9/rpds_py-0.28.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b8e1e9be4fa6305a16be628959188e4fd5cd6f1b0e724d63c6d8b2a8adf74ea6", size = 385720, upload-time = "2025-10-22T22:22:38.014Z" },
+    { url = "https://files.pythonhosted.org/packages/19/ad/e68120dc05af8b7cab4a789fccd8cdcf0fe7e6581461038cc5c164cd97d2/rpds_py-0.28.0-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:0a403460c9dd91a7f23fc3188de6d8977f1d9603a351d5db6cf20aaea95b538d", size = 401096, upload-time = "2025-10-22T22:22:39.869Z" },
+    { url = "https://files.pythonhosted.org/packages/99/90/c1e070620042459d60df6356b666bb1f62198a89d68881816a7ed121595a/rpds_py-0.28.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:d7366b6553cdc805abcc512b849a519167db8f5e5c3472010cd1228b224265cb", size = 411465, upload-time = "2025-10-22T22:22:41.395Z" },
+    { url = "https://files.pythonhosted.org/packages/68/61/7c195b30d57f1b8d5970f600efee72a4fad79ec829057972e13a0370fd24/rpds_py-0.28.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:5b43c6a3726efd50f18d8120ec0551241c38785b68952d240c45ea553912ac41", size = 558832, upload-time = "2025-10-22T22:22:42.871Z" },
+    { url = "https://files.pythonhosted.org/packages/b0/3d/06f3a718864773f69941d4deccdf18e5e47dd298b4628062f004c10f3b34/rpds_py-0.28.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:0cb7203c7bc69d7c1585ebb33a2e6074492d2fc21ad28a7b9d40457ac2a51ab7", size = 583230, upload-time = "2025-10-22T22:22:44.877Z" },
+    { url = "https://files.pythonhosted.org/packages/66/df/62fc783781a121e77fee9a21ead0a926f1b652280a33f5956a5e7833ed30/rpds_py-0.28.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:7a52a5169c664dfb495882adc75c304ae1d50df552fbd68e100fdc719dee4ff9", size = 553268, upload-time = "2025-10-22T22:22:46.441Z" },
+    { url = "https://files.pythonhosted.org/packages/84/85/d34366e335140a4837902d3dea89b51f087bd6a63c993ebdff59e93ee61d/rpds_py-0.28.0-cp313-cp313-win32.whl", hash = "sha256:2e42456917b6687215b3e606ab46aa6bca040c77af7df9a08a6dcfe8a4d10ca5", size = 217100, upload-time = "2025-10-22T22:22:48.342Z" },
+    { url = "https://files.pythonhosted.org/packages/3c/1c/f25a3f3752ad7601476e3eff395fe075e0f7813fbb9862bd67c82440e880/rpds_py-0.28.0-cp313-cp313-win_amd64.whl", hash = "sha256:e0a0311caedc8069d68fc2bf4c9019b58a2d5ce3cd7cb656c845f1615b577e1e", size = 227759, upload-time = "2025-10-22T22:22:50.219Z" },
+    { url = "https://files.pythonhosted.org/packages/e0/d6/5f39b42b99615b5bc2f36ab90423ea404830bdfee1c706820943e9a645eb/rpds_py-0.28.0-cp313-cp313-win_arm64.whl", hash = "sha256:04c1b207ab8b581108801528d59ad80aa83bb170b35b0ddffb29c20e411acdc1", size = 217326, upload-time = "2025-10-22T22:22:51.647Z" },
+    { url = "https://files.pythonhosted.org/packages/5c/8b/0c69b72d1cee20a63db534be0df271effe715ef6c744fdf1ff23bb2b0b1c/rpds_py-0.28.0-cp313-cp313t-macosx_10_12_x86_64.whl", hash = "sha256:f296ea3054e11fc58ad42e850e8b75c62d9a93a9f981ad04b2e5ae7d2186ff9c", size = 355736, upload-time = "2025-10-22T22:22:53.211Z" },
+    { url = "https://files.pythonhosted.org/packages/f7/6d/0c2ee773cfb55c31a8514d2cece856dd299170a49babd50dcffb15ddc749/rpds_py-0.28.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:5a7306c19b19005ad98468fcefeb7100b19c79fc23a5f24a12e06d91181193fa", size = 342677, upload-time = "2025-10-22T22:22:54.723Z" },
+    { url = "https://files.pythonhosted.org/packages/e2/1c/22513ab25a27ea205144414724743e305e8153e6abe81833b5e678650f5a/rpds_py-0.28.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:e5d9b86aa501fed9862a443c5c3116f6ead8bc9296185f369277c42542bd646b", size = 371847, upload-time = "2025-10-22T22:22:56.295Z" },
+    { url = "https://files.pythonhosted.org/packages/60/07/68e6ccdb4b05115ffe61d31afc94adef1833d3a72f76c9632d4d90d67954/rpds_py-0.28.0-cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e5bbc701eff140ba0e872691d573b3d5d30059ea26e5785acba9132d10c8c31d", size = 381800, upload-time = "2025-10-22T22:22:57.808Z" },
+    { url = "https://files.pythonhosted.org/packages/73/bf/6d6d15df80781d7f9f368e7c1a00caf764436518c4877fb28b029c4624af/rpds_py-0.28.0-cp313-cp313t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9a5690671cd672a45aa8616d7374fdf334a1b9c04a0cac3c854b1136e92374fe", size = 518827, upload-time = "2025-10-22T22:22:59.826Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/d3/2decbb2976cc452cbf12a2b0aaac5f1b9dc5dd9d1f7e2509a3ee00421249/rpds_py-0.28.0-cp313-cp313t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9f1d92ecea4fa12f978a367c32a5375a1982834649cdb96539dcdc12e609ab1a", size = 399471, upload-time = "2025-10-22T22:23:01.968Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/2c/f30892f9e54bd02e5faca3f6a26d6933c51055e67d54818af90abed9748e/rpds_py-0.28.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8d252db6b1a78d0a3928b6190156042d54c93660ce4d98290d7b16b5296fb7cc", size = 377578, upload-time = "2025-10-22T22:23:03.52Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/5d/3bce97e5534157318f29ac06bf2d279dae2674ec12f7cb9c12739cee64d8/rpds_py-0.28.0-cp313-cp313t-manylinux_2_31_riscv64.whl", hash = "sha256:d61b355c3275acb825f8777d6c4505f42b5007e357af500939d4a35b19177259", size = 390482, upload-time = "2025-10-22T22:23:05.391Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/f0/886bd515ed457b5bd93b166175edb80a0b21a210c10e993392127f1e3931/rpds_py-0.28.0-cp313-cp313t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:acbe5e8b1026c0c580d0321c8aae4b0a1e1676861d48d6e8c6586625055b606a", size = 402447, upload-time = "2025-10-22T22:23:06.93Z" },
+    { url = "https://files.pythonhosted.org/packages/42/b5/71e8777ac55e6af1f4f1c05b47542a1eaa6c33c1cf0d300dca6a1c6e159a/rpds_py-0.28.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:8aa23b6f0fc59b85b4c7d89ba2965af274346f738e8d9fc2455763602e62fd5f", size = 552385, upload-time = "2025-10-22T22:23:08.557Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/cb/6ca2d70cbda5a8e36605e7788c4aa3bea7c17d71d213465a5a675079b98d/rpds_py-0.28.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:7b14b0c680286958817c22d76fcbca4800ddacef6f678f3a7c79a1fe7067fe37", size = 575642, upload-time = "2025-10-22T22:23:10.348Z" },
+    { url = "https://files.pythonhosted.org/packages/4a/d4/407ad9960ca7856d7b25c96dcbe019270b5ffdd83a561787bc682c797086/rpds_py-0.28.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:bcf1d210dfee61a6c86551d67ee1031899c0fdbae88b2d44a569995d43797712", size = 544507, upload-time = "2025-10-22T22:23:12.434Z" },
+    { url = "https://files.pythonhosted.org/packages/51/31/2f46fe0efcac23fbf5797c6b6b7e1c76f7d60773e525cb65fcbc582ee0f2/rpds_py-0.28.0-cp313-cp313t-win32.whl", hash = "sha256:3aa4dc0fdab4a7029ac63959a3ccf4ed605fee048ba67ce89ca3168da34a1342", size = 205376, upload-time = "2025-10-22T22:23:13.979Z" },
+    { url = "https://files.pythonhosted.org/packages/92/e4/15947bda33cbedfc134490a41841ab8870a72a867a03d4969d886f6594a2/rpds_py-0.28.0-cp313-cp313t-win_amd64.whl", hash = "sha256:7b7d9d83c942855e4fdcfa75d4f96f6b9e272d42fffcb72cd4bb2577db2e2907", size = 215907, upload-time = "2025-10-22T22:23:15.5Z" },
+    { url = "https://files.pythonhosted.org/packages/08/47/ffe8cd7a6a02833b10623bf765fbb57ce977e9a4318ca0e8cf97e9c3d2b3/rpds_py-0.28.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:dcdcb890b3ada98a03f9f2bb108489cdc7580176cb73b4f2d789e9a1dac1d472", size = 353830, upload-time = "2025-10-22T22:23:17.03Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/9f/890f36cbd83a58491d0d91ae0db1702639edb33fb48eeb356f80ecc6b000/rpds_py-0.28.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:f274f56a926ba2dc02976ca5b11c32855cbd5925534e57cfe1fda64e04d1add2", size = 341819, upload-time = "2025-10-22T22:23:18.57Z" },
+    { url = "https://files.pythonhosted.org/packages/09/e3/921eb109f682aa24fb76207698fbbcf9418738f35a40c21652c29053f23d/rpds_py-0.28.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4fe0438ac4a29a520ea94c8c7f1754cdd8feb1bc490dfda1bfd990072363d527", size = 373127, upload-time = "2025-10-22T22:23:20.216Z" },
+    { url = "https://files.pythonhosted.org/packages/23/13/bce4384d9f8f4989f1a9599c71b7a2d877462e5fd7175e1f69b398f729f4/rpds_py-0.28.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:8a358a32dd3ae50e933347889b6af9a1bdf207ba5d1a3f34e1a38cd3540e6733", size = 382767, upload-time = "2025-10-22T22:23:21.787Z" },
+    { url = "https://files.pythonhosted.org/packages/23/e1/579512b2d89a77c64ccef5a0bc46a6ef7f72ae0cf03d4b26dcd52e57ee0a/rpds_py-0.28.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e80848a71c78aa328fefaba9c244d588a342c8e03bda518447b624ea64d1ff56", size = 517585, upload-time = "2025-10-22T22:23:23.699Z" },
+    { url = "https://files.pythonhosted.org/packages/62/3c/ca704b8d324a2591b0b0adcfcaadf9c862375b11f2f667ac03c61b4fd0a6/rpds_py-0.28.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:f586db2e209d54fe177e58e0bc4946bea5fb0102f150b1b2f13de03e1f0976f8", size = 399828, upload-time = "2025-10-22T22:23:25.713Z" },
+    { url = "https://files.pythonhosted.org/packages/da/37/e84283b9e897e3adc46b4c88bb3f6ec92a43bd4d2f7ef5b13459963b2e9c/rpds_py-0.28.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5ae8ee156d6b586e4292491e885d41483136ab994e719a13458055bec14cf370", size = 375509, upload-time = "2025-10-22T22:23:27.32Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/c2/a980beab869d86258bf76ec42dec778ba98151f253a952b02fe36d72b29c/rpds_py-0.28.0-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:a805e9b3973f7e27f7cab63a6b4f61d90f2e5557cff73b6e97cd5b8540276d3d", size = 392014, upload-time = "2025-10-22T22:23:29.332Z" },
+    { url = "https://files.pythonhosted.org/packages/da/b5/b1d3c5f9d3fa5aeef74265f9c64de3c34a0d6d5cd3c81c8b17d5c8f10ed4/rpds_py-0.28.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:5d3fd16b6dc89c73a4da0b4ac8b12a7ecc75b2864b95c9e5afed8003cb50a728", size = 402410, upload-time = "2025-10-22T22:23:31.14Z" },
+    { url = "https://files.pythonhosted.org/packages/74/ae/cab05ff08dfcc052afc73dcb38cbc765ffc86f94e966f3924cd17492293c/rpds_py-0.28.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:6796079e5d24fdaba6d49bda28e2c47347e89834678f2bc2c1b4fc1489c0fb01", size = 553593, upload-time = "2025-10-22T22:23:32.834Z" },
+    { url = "https://files.pythonhosted.org/packages/70/80/50d5706ea2a9bfc9e9c5f401d91879e7c790c619969369800cde202da214/rpds_py-0.28.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:76500820c2af232435cbe215e3324c75b950a027134e044423f59f5b9a1ba515", size = 576925, upload-time = "2025-10-22T22:23:34.47Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/12/85a57d7a5855a3b188d024b099fd09c90db55d32a03626d0ed16352413ff/rpds_py-0.28.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:bbdc5640900a7dbf9dd707fe6388972f5bbd883633eb68b76591044cfe346f7e", size = 542444, upload-time = "2025-10-22T22:23:36.093Z" },
+    { url = "https://files.pythonhosted.org/packages/6c/65/10643fb50179509150eb94d558e8837c57ca8b9adc04bd07b98e57b48f8c/rpds_py-0.28.0-cp314-cp314-win32.whl", hash = "sha256:adc8aa88486857d2b35d75f0640b949759f79dc105f50aa2c27816b2e0dd749f", size = 207968, upload-time = "2025-10-22T22:23:37.638Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/84/0c11fe4d9aaea784ff4652499e365963222481ac647bcd0251c88af646eb/rpds_py-0.28.0-cp314-cp314-win_amd64.whl", hash = "sha256:66e6fa8e075b58946e76a78e69e1a124a21d9a48a5b4766d15ba5b06869d1fa1", size = 218876, upload-time = "2025-10-22T22:23:39.179Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/e0/3ab3b86ded7bb18478392dc3e835f7b754cd446f62f3fc96f4fe2aca78f6/rpds_py-0.28.0-cp314-cp314-win_arm64.whl", hash = "sha256:a6fe887c2c5c59413353b7c0caff25d0e566623501ccfff88957fa438a69377d", size = 212506, upload-time = "2025-10-22T22:23:40.755Z" },
+    { url = "https://files.pythonhosted.org/packages/51/ec/d5681bb425226c3501eab50fc30e9d275de20c131869322c8a1729c7b61c/rpds_py-0.28.0-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:7a69df082db13c7070f7b8b1f155fa9e687f1d6aefb7b0e3f7231653b79a067b", size = 355433, upload-time = "2025-10-22T22:23:42.259Z" },
+    { url = "https://files.pythonhosted.org/packages/be/ec/568c5e689e1cfb1ea8b875cffea3649260955f677fdd7ddc6176902d04cd/rpds_py-0.28.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:b1cde22f2c30ebb049a9e74c5374994157b9b70a16147d332f89c99c5960737a", size = 342601, upload-time = "2025-10-22T22:23:44.372Z" },
+    { url = "https://files.pythonhosted.org/packages/32/fe/51ada84d1d2a1d9d8f2c902cfddd0133b4a5eb543196ab5161d1c07ed2ad/rpds_py-0.28.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5338742f6ba7a51012ea470bd4dc600a8c713c0c72adaa0977a1b1f4327d6592", size = 372039, upload-time = "2025-10-22T22:23:46.025Z" },
+    { url = "https://files.pythonhosted.org/packages/07/c1/60144a2f2620abade1a78e0d91b298ac2d9b91bc08864493fa00451ef06e/rpds_py-0.28.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e1460ebde1bcf6d496d80b191d854adedcc619f84ff17dc1c6d550f58c9efbba", size = 382407, upload-time = "2025-10-22T22:23:48.098Z" },
+    { url = "https://files.pythonhosted.org/packages/45/ed/091a7bbdcf4038a60a461df50bc4c82a7ed6d5d5e27649aab61771c17585/rpds_py-0.28.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e3eb248f2feba84c692579257a043a7699e28a77d86c77b032c1d9fbb3f0219c", size = 518172, upload-time = "2025-10-22T22:23:50.16Z" },
+    { url = "https://files.pythonhosted.org/packages/54/dd/02cc90c2fd9c2ef8016fd7813bfacd1c3a1325633ec8f244c47b449fc868/rpds_py-0.28.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:bd3bbba5def70b16cd1c1d7255666aad3b290fbf8d0fe7f9f91abafb73611a91", size = 399020, upload-time = "2025-10-22T22:23:51.81Z" },
+    { url = "https://files.pythonhosted.org/packages/ab/81/5d98cc0329bbb911ccecd0b9e19fbf7f3a5de8094b4cda5e71013b2dd77e/rpds_py-0.28.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:3114f4db69ac5a1f32e7e4d1cbbe7c8f9cf8217f78e6e002cedf2d54c2a548ed", size = 377451, upload-time = "2025-10-22T22:23:53.711Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/07/4d5bcd49e3dfed2d38e2dcb49ab6615f2ceb9f89f5a372c46dbdebb4e028/rpds_py-0.28.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:4b0cb8a906b1a0196b863d460c0222fb8ad0f34041568da5620f9799b83ccf0b", size = 390355, upload-time = "2025-10-22T22:23:55.299Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/79/9f14ba9010fee74e4f40bf578735cfcbb91d2e642ffd1abe429bb0b96364/rpds_py-0.28.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:cf681ac76a60b667106141e11a92a3330890257e6f559ca995fbb5265160b56e", size = 403146, upload-time = "2025-10-22T22:23:56.929Z" },
+    { url = "https://files.pythonhosted.org/packages/39/4c/f08283a82ac141331a83a40652830edd3a4a92c34e07e2bbe00baaea2f5f/rpds_py-0.28.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:1e8ee6413cfc677ce8898d9cde18cc3a60fc2ba756b0dec5b71eb6eb21c49fa1", size = 552656, upload-time = "2025-10-22T22:23:58.62Z" },
+    { url = "https://files.pythonhosted.org/packages/61/47/d922fc0666f0dd8e40c33990d055f4cc6ecff6f502c2d01569dbed830f9b/rpds_py-0.28.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:b3072b16904d0b5572a15eb9d31c1954e0d3227a585fc1351aa9878729099d6c", size = 576782, upload-time = "2025-10-22T22:24:00.312Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/0c/5bafdd8ccf6aa9d3bfc630cfece457ff5b581af24f46a9f3590f790e3df2/rpds_py-0.28.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:b670c30fd87a6aec281c3c9896d3bae4b205fd75d79d06dc87c2503717e46092", size = 544671, upload-time = "2025-10-22T22:24:02.297Z" },
+    { url = "https://files.pythonhosted.org/packages/2c/37/dcc5d8397caa924988693519069d0beea077a866128719351a4ad95e82fc/rpds_py-0.28.0-cp314-cp314t-win32.whl", hash = "sha256:8014045a15b4d2b3476f0a287fcc93d4f823472d7d1308d47884ecac9e612be3", size = 205749, upload-time = "2025-10-22T22:24:03.848Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/69/64d43b21a10d72b45939a28961216baeb721cc2a430f5f7c3bfa21659a53/rpds_py-0.28.0-cp314-cp314t-win_amd64.whl", hash = "sha256:7a4e59c90d9c27c561eb3160323634a9ff50b04e4f7820600a2beb0ac90db578", size = 216233, upload-time = "2025-10-22T22:24:05.471Z" },
+]
+
+[[package]]
+name = "typing-extensions"
+version = "4.15.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/72/94/1a15dd82efb362ac84269196e94cf00f187f7ed21c242792a923cdb1c61f/typing_extensions-4.15.0.tar.gz", hash = "sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466", size = 109391, upload-time = "2025-08-25T13:49:26.313Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl", hash = "sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548", size = 44614, upload-time = "2025-08-25T13:49:24.86Z" },
+]
+
+[[package]]
+name = "typing-inspection"
+version = "0.4.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/55/e3/70399cb7dd41c10ac53367ae42139cf4b1ca5f36bb3dc6c9d33acdb43655/typing_inspection-0.4.2.tar.gz", hash = "sha256:ba561c48a67c5958007083d386c3295464928b01faa735ab8547c5692e87f464", size = 75949, upload-time = "2025-10-01T02:14:41.687Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" },
+]
+
+[[package]]
+name = "urllib3"
+version = "2.5.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/15/22/9ee70a2574a4f4599c47dd506532914ce044817c7752a79b6a51286319bc/urllib3-2.5.0.tar.gz", hash = "sha256:3fc47733c7e419d4bc3f6b3dc2b4f890bb743906a30d56ba4a5bfa4bbff92760", size = 393185, upload-time = "2025-06-18T14:07:41.644Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a7/c2/fe1e52489ae3122415c51f387e221dd0773709bad6c6cdaa599e8a2c5185/urllib3-2.5.0-py3-none-any.whl", hash = "sha256:e6b01673c0fa6a13e374b50871808eb3bf7046c4b125b216f6bf1cc604cff0dc", size = 129795, upload-time = "2025-06-18T14:07:40.39Z" },
+]
+
+[[package]]
+name = "zipp"
+version = "3.23.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e3/02/0f2892c661036d50ede074e376733dca2ae7c6eb617489437771209d4180/zipp-3.23.0.tar.gz", hash = "sha256:a07157588a12518c9d4034df3fbbee09c814741a33ff63c05fa29d26a2404166", size = 25547, upload-time = "2025-06-08T17:06:39.4Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2e/54/647ade08bf0db230bfea292f893923872fd20be6ac6f53b2b936ba839d75/zipp-3.23.0-py3-none-any.whl", hash = "sha256:071652d6115ed432f5ce1d34c336c0adfd6a884660d1e9712a256d3d3bd4b14e", size = 10276, upload-time = "2025-06-08T17:06:38.034Z" },
+]

src/llama_stack_api/vector_io.py

@@ -0,0 +1,872 @@
+# 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.
+# 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, Any, Literal, Protocol, runtime_checkable
+
+from fastapi import Body, Query
+from pydantic import BaseModel, Field
+
+from llama_stack_api.common.tracing import telemetry_traceable
+from llama_stack_api.inference import InterleavedContent
+from llama_stack_api.schema_utils import json_schema_type, webmethod
+from llama_stack_api.strong_typing.schema import register_schema
+from llama_stack_api.vector_stores import VectorStore
+from llama_stack_api.version import LLAMA_STACK_API_V1
+
+
+@json_schema_type
+class ChunkMetadata(BaseModel):
+    """
+    `ChunkMetadata` is backend metadata for a `Chunk` that is used to store additional information about the chunk that
+        will not be used in the context during inference, but is required for backend functionality. The `ChunkMetadata`
+        is set during chunk creation in `MemoryToolRuntimeImpl().insert()`and is not expected to change after.
+        Use `Chunk.metadata` for metadata that will be used in the context during inference.
+    :param chunk_id: The ID of the chunk. If not set, it will be generated based on the document ID and content.
+    :param document_id: The ID of the document this chunk belongs to.
+    :param source: The source of the content, such as a URL, file path, or other identifier.
+    :param created_timestamp: An optional timestamp indicating when the chunk was created.
+    :param updated_timestamp: An optional timestamp indicating when the chunk was last updated.
+    :param chunk_window: The window of the chunk, which can be used to group related chunks together.
+    :param chunk_tokenizer: The tokenizer used to create the chunk. Default is Tiktoken.
+    :param chunk_embedding_model: The embedding model used to create the chunk's embedding.
+    :param chunk_embedding_dimension: The dimension of the embedding vector for the chunk.
+    :param content_token_count: The number of tokens in the content of the chunk.
+    :param metadata_token_count: The number of tokens in the metadata of the chunk.
+    """
+
+    chunk_id: str | None = None
+    document_id: str | None = None
+    source: str | None = None
+    created_timestamp: int | None = None
+    updated_timestamp: int | None = None
+    chunk_window: str | None = None
+    chunk_tokenizer: str | None = None
+    chunk_embedding_model: str | None = None
+    chunk_embedding_dimension: int | None = None
+    content_token_count: int | None = None
+    metadata_token_count: int | None = None
+
+
+@json_schema_type
+class Chunk(BaseModel):
+    """
+    A chunk of content that can be inserted into a vector database.
+    :param content: The content of the chunk, which can be interleaved text, images, or other types.
+    :param chunk_id: Unique identifier for the chunk. Must be provided explicitly.
+    :param metadata: Metadata associated with the chunk that will be used in the model context during inference.
+    :param embedding: Optional embedding for the chunk. If not provided, it will be computed later.
+    :param chunk_metadata: Metadata for the chunk that will NOT be used in the context during inference.
+        The `chunk_metadata` is required backend functionality.
+    """
+
+    content: InterleavedContent
+    chunk_id: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    embedding: list[float] | None = None
+    chunk_metadata: ChunkMetadata | None = None
+
+    @property
+    def document_id(self) -> str | None:
+        """Returns the document_id from either metadata or chunk_metadata, with metadata taking precedence."""
+        # Check metadata first (takes precedence)
+        doc_id = self.metadata.get("document_id")
+        if doc_id is not None:
+            if not isinstance(doc_id, str):
+                raise TypeError(f"metadata['document_id'] must be a string, got {type(doc_id).__name__}: {doc_id!r}")
+            return doc_id
+
+        # Fall back to chunk_metadata if available (Pydantic ensures type safety)
+        if self.chunk_metadata is not None:
+            return self.chunk_metadata.document_id
+
+        return None
+
+
+@json_schema_type
+class QueryChunksResponse(BaseModel):
+    """Response from querying chunks in a vector database.
+
+    :param chunks: List of content chunks returned from the query
+    :param scores: Relevance scores corresponding to each returned chunk
+    """
+
+    chunks: list[Chunk]
+    scores: list[float]
+
+
+@json_schema_type
+class VectorStoreFileCounts(BaseModel):
+    """File processing status counts for a vector store.
+
+    :param completed: Number of files that have been successfully processed
+    :param cancelled: Number of files that had their processing cancelled
+    :param failed: Number of files that failed to process
+    :param in_progress: Number of files currently being processed
+    :param total: Total number of files in the vector store
+    """
+
+    completed: int
+    cancelled: int
+    failed: int
+    in_progress: int
+    total: int
+
+
+# TODO: rename this as OpenAIVectorStore
+@json_schema_type
+class VectorStoreObject(BaseModel):
+    """OpenAI Vector Store object.
+
+    :param id: Unique identifier for the vector store
+    :param object: Object type identifier, always "vector_store"
+    :param created_at: Timestamp when the vector store was created
+    :param name: (Optional) Name of the vector store
+    :param usage_bytes: Storage space used by the vector store in bytes
+    :param file_counts: File processing status counts for the vector store
+    :param status: Current status of the vector store
+    :param expires_after: (Optional) Expiration policy for the vector store
+    :param expires_at: (Optional) Timestamp when the vector store will expire
+    :param last_active_at: (Optional) Timestamp of last activity on the vector store
+    :param metadata: Set of key-value pairs that can be attached to the vector store
+    """
+
+    id: str
+    object: str = "vector_store"
+    created_at: int
+    name: str | None = None
+    usage_bytes: int = 0
+    file_counts: VectorStoreFileCounts
+    status: str = "completed"
+    expires_after: dict[str, Any] | None = None
+    expires_at: int | None = None
+    last_active_at: int | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+@json_schema_type
+class VectorStoreCreateRequest(BaseModel):
+    """Request to create a vector store.
+
+    :param name: (Optional) Name for the vector store
+    :param file_ids: List of file IDs to include in the vector store
+    :param expires_after: (Optional) Expiration policy for the vector store
+    :param chunking_strategy: (Optional) Strategy for splitting files into chunks
+    :param metadata: Set of key-value pairs that can be attached to the vector store
+    """
+
+    name: str | None = None
+    file_ids: list[str] = Field(default_factory=list)
+    expires_after: dict[str, Any] | None = None
+    chunking_strategy: dict[str, Any] | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+@json_schema_type
+class VectorStoreModifyRequest(BaseModel):
+    """Request to modify a vector store.
+
+    :param name: (Optional) Updated name for the vector store
+    :param expires_after: (Optional) Updated expiration policy for the vector store
+    :param metadata: (Optional) Updated set of key-value pairs for the vector store
+    """
+
+    name: str | None = None
+    expires_after: dict[str, Any] | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@json_schema_type
+class VectorStoreListResponse(BaseModel):
+    """Response from listing vector stores.
+
+    :param object: Object type identifier, always "list"
+    :param data: List of vector store objects
+    :param first_id: (Optional) ID of the first vector store in the list for pagination
+    :param last_id: (Optional) ID of the last vector store in the list for pagination
+    :param has_more: Whether there are more vector stores available beyond this page
+    """
+
+    object: str = "list"
+    data: list[VectorStoreObject]
+    first_id: str | None = None
+    last_id: str | None = None
+    has_more: bool = False
+
+
+@json_schema_type
+class VectorStoreSearchRequest(BaseModel):
+    """Request to search a vector store.
+
+    :param query: Search query as a string or list of strings
+    :param filters: (Optional) Filters based on file attributes to narrow search results
+    :param max_num_results: Maximum number of results to return, defaults to 10
+    :param ranking_options: (Optional) Options for ranking and filtering search results
+    :param rewrite_query: Whether to rewrite the query for better vector search performance
+    """
+
+    query: str | list[str]
+    filters: dict[str, Any] | None = None
+    max_num_results: int = 10
+    ranking_options: dict[str, Any] | None = None
+    rewrite_query: bool = False
+
+
+@json_schema_type
+class VectorStoreContent(BaseModel):
+    """Content item from a vector store file or search result.
+
+    :param type: Content type, currently only "text" is supported
+    :param text: The actual text content
+    :param embedding: Optional embedding vector for this content chunk
+    :param chunk_metadata: Optional chunk metadata
+    :param metadata: Optional user-defined metadata
+    """
+
+    type: Literal["text"]
+    text: str
+    embedding: list[float] | None = None
+    chunk_metadata: ChunkMetadata | None = None
+    metadata: dict[str, Any] | None = None
+
+
+@json_schema_type
+class VectorStoreSearchResponse(BaseModel):
+    """Response from searching a vector store.
+
+    :param file_id: Unique identifier of the file containing the result
+    :param filename: Name of the file containing the result
+    :param score: Relevance score for this search result
+    :param attributes: (Optional) Key-value attributes associated with the file
+    :param content: List of content items matching the search query
+    """
+
+    file_id: str
+    filename: str
+    score: float
+    attributes: dict[str, str | float | bool] | None = None
+    content: list[VectorStoreContent]
+
+
+@json_schema_type
+class VectorStoreSearchResponsePage(BaseModel):
+    """Paginated response from searching a vector store.
+
+    :param object: Object type identifier for the search results page
+    :param search_query: The original search query that was executed
+    :param data: List of search result objects
+    :param has_more: Whether there are more results available beyond this page
+    :param next_page: (Optional) Token for retrieving the next page of results
+    """
+
+    object: str = "vector_store.search_results.page"
+    search_query: list[str]
+    data: list[VectorStoreSearchResponse]
+    has_more: bool = False
+    next_page: str | None = None
+
+
+@json_schema_type
+class VectorStoreDeleteResponse(BaseModel):
+    """Response from deleting a vector store.
+
+    :param id: Unique identifier of the deleted vector store
+    :param object: Object type identifier for the deletion response
+    :param deleted: Whether the deletion operation was successful
+    """
+
+    id: str
+    object: str = "vector_store.deleted"
+    deleted: bool = True
+
+
+@json_schema_type
+class VectorStoreFileContentResponse(BaseModel):
+    """Represents the parsed content of a vector store file.
+
+    :param object: The object type, which is always `vector_store.file_content.page`
+    :param data: Parsed content of the file
+    :param has_more: Indicates if there are more content pages to fetch
+    :param next_page: The token for the next page, if any
+    """
+
+    object: Literal["vector_store.file_content.page"] = "vector_store.file_content.page"
+    data: list[VectorStoreContent]
+    has_more: bool = False
+    next_page: str | None = None
+
+
+@json_schema_type
+class VectorStoreChunkingStrategyAuto(BaseModel):
+    """Automatic chunking strategy for vector store files.
+
+    :param type: Strategy type, always "auto" for automatic chunking
+    """
+
+    type: Literal["auto"] = "auto"
+
+
+@json_schema_type
+class VectorStoreChunkingStrategyStaticConfig(BaseModel):
+    """Configuration for static chunking strategy.
+
+    :param chunk_overlap_tokens: Number of tokens to overlap between adjacent chunks
+    :param max_chunk_size_tokens: Maximum number of tokens per chunk, must be between 100 and 4096
+    """
+
+    chunk_overlap_tokens: int = 400
+    max_chunk_size_tokens: int = Field(800, ge=100, le=4096)
+
+
+@json_schema_type
+class VectorStoreChunkingStrategyStatic(BaseModel):
+    """Static chunking strategy with configurable parameters.
+
+    :param type: Strategy type, always "static" for static chunking
+    :param static: Configuration parameters for the static chunking strategy
+    """
+
+    type: Literal["static"] = "static"
+    static: VectorStoreChunkingStrategyStaticConfig
+
+
+VectorStoreChunkingStrategy = Annotated[
+    VectorStoreChunkingStrategyAuto | VectorStoreChunkingStrategyStatic,
+    Field(discriminator="type"),
+]
+register_schema(VectorStoreChunkingStrategy, name="VectorStoreChunkingStrategy")
+
+
+class SearchRankingOptions(BaseModel):
+    """Options for ranking and filtering search results.
+
+    :param ranker: (Optional) Name of the ranking algorithm to use
+    :param score_threshold: (Optional) Minimum relevance score threshold for results
+    """
+
+    ranker: str | None = None
+    # NOTE: OpenAI File Search Tool requires threshold to be between 0 and 1, however
+    # we don't guarantee that the score is between 0 and 1, so will leave this unconstrained
+    # and let the provider handle it
+    score_threshold: float | None = Field(default=0.0)
+
+
+@json_schema_type
+class VectorStoreFileLastError(BaseModel):
+    """Error information for failed vector store file processing.
+
+    :param code: Error code indicating the type of failure
+    :param message: Human-readable error message describing the failure
+    """
+
+    code: Literal["server_error"] | Literal["rate_limit_exceeded"]
+    message: str
+
+
+VectorStoreFileStatus = Literal["completed"] | Literal["in_progress"] | Literal["cancelled"] | Literal["failed"]
+register_schema(VectorStoreFileStatus, name="VectorStoreFileStatus")
+
+
+@json_schema_type
+class VectorStoreFileObject(BaseModel):
+    """OpenAI Vector Store File object.
+
+    :param id: Unique identifier for the file
+    :param object: Object type identifier, always "vector_store.file"
+    :param attributes: Key-value attributes associated with the file
+    :param chunking_strategy: Strategy used for splitting the file into chunks
+    :param created_at: Timestamp when the file was added to the vector store
+    :param last_error: (Optional) Error information if file processing failed
+    :param status: Current processing status of the file
+    :param usage_bytes: Storage space used by this file in bytes
+    :param vector_store_id: ID of the vector store containing this file
+    """
+
+    id: str
+    object: str = "vector_store.file"
+    attributes: dict[str, Any] = Field(default_factory=dict)
+    chunking_strategy: VectorStoreChunkingStrategy
+    created_at: int
+    last_error: VectorStoreFileLastError | None = None
+    status: VectorStoreFileStatus
+    usage_bytes: int = 0
+    vector_store_id: str
+
+
+@json_schema_type
+class VectorStoreListFilesResponse(BaseModel):
+    """Response from listing files in a vector store.
+
+    :param object: Object type identifier, always "list"
+    :param data: List of vector store file objects
+    :param first_id: (Optional) ID of the first file in the list for pagination
+    :param last_id: (Optional) ID of the last file in the list for pagination
+    :param has_more: Whether there are more files available beyond this page
+    """
+
+    object: str = "list"
+    data: list[VectorStoreFileObject]
+    first_id: str | None = None
+    last_id: str | None = None
+    has_more: bool = False
+
+
+@json_schema_type
+class VectorStoreFileDeleteResponse(BaseModel):
+    """Response from deleting a vector store file.
+
+    :param id: Unique identifier of the deleted file
+    :param object: Object type identifier for the deletion response
+    :param deleted: Whether the deletion operation was successful
+    """
+
+    id: str
+    object: str = "vector_store.file.deleted"
+    deleted: bool = True
+
+
+@json_schema_type
+class VectorStoreFileBatchObject(BaseModel):
+    """OpenAI Vector Store File Batch object.
+
+    :param id: Unique identifier for the file batch
+    :param object: Object type identifier, always "vector_store.file_batch"
+    :param created_at: Timestamp when the file batch was created
+    :param vector_store_id: ID of the vector store containing the file batch
+    :param status: Current processing status of the file batch
+    :param file_counts: File processing status counts for the batch
+    """
+
+    id: str
+    object: str = "vector_store.file_batch"
+    created_at: int
+    vector_store_id: str
+    status: VectorStoreFileStatus
+    file_counts: VectorStoreFileCounts
+
+
+@json_schema_type
+class VectorStoreFilesListInBatchResponse(BaseModel):
+    """Response from listing files in a vector store file batch.
+
+    :param object: Object type identifier, always "list"
+    :param data: List of vector store file objects in the batch
+    :param first_id: (Optional) ID of the first file in the list for pagination
+    :param last_id: (Optional) ID of the last file in the list for pagination
+    :param has_more: Whether there are more files available beyond this page
+    """
+
+    object: str = "list"
+    data: list[VectorStoreFileObject]
+    first_id: str | None = None
+    last_id: str | None = None
+    has_more: bool = False
+
+
+# extra_body can be accessed via .model_extra
+@json_schema_type
+class OpenAICreateVectorStoreRequestWithExtraBody(BaseModel, extra="allow"):
+    """Request to create a vector store with extra_body support.
+
+    :param name: (Optional) A name for the vector store
+    :param file_ids: List of file IDs to include in the vector store
+    :param expires_after: (Optional) Expiration policy for the vector store
+    :param chunking_strategy: (Optional) Strategy for splitting files into chunks
+    :param metadata: Set of key-value pairs that can be attached to the vector store
+    """
+
+    name: str | None = None
+    file_ids: list[str] | None = None
+    expires_after: dict[str, Any] | None = None
+    chunking_strategy: VectorStoreChunkingStrategy | None = None
+    metadata: dict[str, Any] | None = None
+
+
+# extra_body can be accessed via .model_extra
+@json_schema_type
+class OpenAICreateVectorStoreFileBatchRequestWithExtraBody(BaseModel, extra="allow"):
+    """Request to create a vector store file batch with extra_body support.
+
+    :param file_ids: A list of File IDs that the vector store should use
+    :param attributes: (Optional) Key-value attributes to store with the files
+    :param chunking_strategy: (Optional) The chunking strategy used to chunk the file(s). Defaults to auto
+    """
+
+    file_ids: list[str]
+    attributes: dict[str, Any] | None = None
+    chunking_strategy: VectorStoreChunkingStrategy | None = None
+
+
+class VectorStoreTable(Protocol):
+    def get_vector_store(self, vector_store_id: str) -> VectorStore | None: ...
+
+
+@runtime_checkable
+@telemetry_traceable
+class VectorIO(Protocol):
+    vector_store_table: VectorStoreTable | None = None
+
+    # this will just block now until chunks are inserted, but it should
+    # probably return a Job instance which can be polled for completion
+    # TODO: rename vector_store_id to vector_store_id once Stainless is working
+    @webmethod(route="/vector-io/insert", method="POST", level=LLAMA_STACK_API_V1)
+    async def insert_chunks(
+        self,
+        vector_store_id: str,
+        chunks: list[Chunk],
+        ttl_seconds: int | None = None,
+    ) -> None:
+        """Insert chunks into a vector database.
+
+        :param vector_store_id: The identifier of the vector database to insert the chunks into.
+        :param chunks: The chunks to insert. Each `Chunk` should contain content which can be interleaved text, images, or other types.
+            `metadata`: `dict[str, Any]` and `embedding`: `List[float]` are optional.
+            If `metadata` is provided, you configure how Llama Stack formats the chunk during generation.
+            If `embedding` is not provided, it will be computed later.
+        :param ttl_seconds: The time to live of the chunks.
+        """
+        ...
+
+    # TODO: rename vector_store_id to vector_store_id once Stainless is working
+    @webmethod(route="/vector-io/query", method="POST", level=LLAMA_STACK_API_V1)
+    async def query_chunks(
+        self,
+        vector_store_id: str,
+        query: InterleavedContent,
+        params: dict[str, Any] | None = None,
+    ) -> QueryChunksResponse:
+        """Query chunks from a vector database.
+
+        :param vector_store_id: The identifier of the vector database to query.
+        :param query: The query to search for.
+        :param params: The parameters of the query.
+        :returns: A QueryChunksResponse.
+        """
+        ...
+
+    # OpenAI Vector Stores API endpoints
+    @webmethod(route="/vector_stores", method="POST", level=LLAMA_STACK_API_V1)
+    async def openai_create_vector_store(
+        self,
+        params: Annotated[OpenAICreateVectorStoreRequestWithExtraBody, Body(...)],
+    ) -> VectorStoreObject:
+        """Creates a vector store.
+
+        Generate an OpenAI-compatible vector store with the given parameters.
+        :returns: A VectorStoreObject representing the created vector store.
+        """
+        ...
+
+    @webmethod(route="/vector_stores", method="GET", level=LLAMA_STACK_API_V1)
+    async def openai_list_vector_stores(
+        self,
+        limit: int | None = 20,
+        order: str | None = "desc",
+        after: str | None = None,
+        before: str | None = None,
+    ) -> VectorStoreListResponse:
+        """Returns a list of vector stores.
+
+        :param limit: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
+        :param order: Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
+        :param after: A cursor for use in pagination. `after` is an object ID that defines your place in the list.
+        :param before: A cursor for use in pagination. `before` is an object ID that defines your place in the list.
+        :returns: A VectorStoreListResponse containing the list of vector stores.
+        """
+        ...
+
+    @webmethod(route="/vector_stores/{vector_store_id}", method="GET", level=LLAMA_STACK_API_V1)
+    async def openai_retrieve_vector_store(
+        self,
+        vector_store_id: str,
+    ) -> VectorStoreObject:
+        """Retrieves a vector store.
+
+        :param vector_store_id: The ID of the vector store to retrieve.
+        :returns: A VectorStoreObject representing the vector store.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}",
+        method="POST",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_update_vector_store(
+        self,
+        vector_store_id: str,
+        name: str | None = None,
+        expires_after: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> VectorStoreObject:
+        """Updates a vector store.
+
+        :param vector_store_id: The ID of the vector store to update.
+        :param name: The name of the vector store.
+        :param expires_after: The expiration policy for a vector store.
+        :param metadata: Set of 16 key-value pairs that can be attached to an object.
+        :returns: A VectorStoreObject representing the updated vector store.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}",
+        method="DELETE",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_delete_vector_store(
+        self,
+        vector_store_id: str,
+    ) -> VectorStoreDeleteResponse:
+        """Delete a vector store.
+
+        :param vector_store_id: The ID of the vector store to delete.
+        :returns: A VectorStoreDeleteResponse indicating the deletion status.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/search",
+        method="POST",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_search_vector_store(
+        self,
+        vector_store_id: str,
+        query: str | list[str],
+        filters: dict[str, Any] | None = None,
+        max_num_results: int | None = 10,
+        ranking_options: SearchRankingOptions | None = None,
+        rewrite_query: bool | None = False,
+        search_mode: (
+            str | None
+        ) = "vector",  # Using str instead of Literal due to OpenAPI schema generator limitations
+    ) -> VectorStoreSearchResponsePage:
+        """Search for chunks in a vector store.
+
+        Searches a vector store for relevant chunks based on a query and optional file attribute filters.
+
+        :param vector_store_id: The ID of the vector store to search.
+        :param query: The query string or array for performing the search.
+        :param filters: Filters based on file attributes to narrow the search results.
+        :param max_num_results: Maximum number of results to return (1 to 50 inclusive, default 10).
+        :param ranking_options: Ranking options for fine-tuning the search results.
+        :param rewrite_query: Whether to rewrite the natural language query for vector search (default false)
+        :param search_mode: The search mode to use - "keyword", "vector", or "hybrid" (default "vector")
+        :returns: A VectorStoreSearchResponse containing the search results.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/files",
+        method="POST",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_attach_file_to_vector_store(
+        self,
+        vector_store_id: str,
+        file_id: str,
+        attributes: dict[str, Any] | None = None,
+        chunking_strategy: VectorStoreChunkingStrategy | None = None,
+    ) -> VectorStoreFileObject:
+        """Attach a file to a vector store.
+
+        :param vector_store_id: The ID of the vector store to attach the file to.
+        :param file_id: The ID of the file to attach to the vector store.
+        :param attributes: The key-value attributes stored with the file, which can be used for filtering.
+        :param chunking_strategy: The chunking strategy to use for the file.
+        :returns: A VectorStoreFileObject representing the attached file.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/files",
+        method="GET",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_list_files_in_vector_store(
+        self,
+        vector_store_id: str,
+        limit: int | None = 20,
+        order: str | None = "desc",
+        after: str | None = None,
+        before: str | None = None,
+        filter: VectorStoreFileStatus | None = None,
+    ) -> VectorStoreListFilesResponse:
+        """List files in a vector store.
+
+        :param vector_store_id: The ID of the vector store to list files from.
+        :param limit: (Optional) A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
+        :param order: (Optional) Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
+        :param after: (Optional) A cursor for use in pagination. `after` is an object ID that defines your place in the list.
+        :param before: (Optional) A cursor for use in pagination. `before` is an object ID that defines your place in the list.
+        :param filter: (Optional) Filter by file status to only return files with the specified status.
+        :returns: A VectorStoreListFilesResponse containing the list of files.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/files/{file_id}",
+        method="GET",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_retrieve_vector_store_file(
+        self,
+        vector_store_id: str,
+        file_id: str,
+    ) -> VectorStoreFileObject:
+        """Retrieves a vector store file.
+
+        :param vector_store_id: The ID of the vector store containing the file to retrieve.
+        :param file_id: The ID of the file to retrieve.
+        :returns: A VectorStoreFileObject representing the file.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/files/{file_id}/content",
+        method="GET",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_retrieve_vector_store_file_contents(
+        self,
+        vector_store_id: str,
+        file_id: str,
+        include_embeddings: Annotated[bool | None, Query(default=False)] = False,
+        include_metadata: Annotated[bool | None, Query(default=False)] = False,
+    ) -> VectorStoreFileContentResponse:
+        """Retrieves the contents of a vector store file.
+
+        :param vector_store_id: The ID of the vector store containing the file to retrieve.
+        :param file_id: The ID of the file to retrieve.
+        :param include_embeddings: Whether to include embedding vectors in the response.
+        :param include_metadata: Whether to include chunk metadata in the response.
+        :returns: File contents, optionally with embeddings and metadata based on query parameters.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/files/{file_id}",
+        method="POST",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_update_vector_store_file(
+        self,
+        vector_store_id: str,
+        file_id: str,
+        attributes: dict[str, Any],
+    ) -> VectorStoreFileObject:
+        """Updates a vector store file.
+
+        :param vector_store_id: The ID of the vector store containing the file to update.
+        :param file_id: The ID of the file to update.
+        :param attributes: The updated key-value attributes to store with the file.
+        :returns: A VectorStoreFileObject representing the updated file.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/files/{file_id}",
+        method="DELETE",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_delete_vector_store_file(
+        self,
+        vector_store_id: str,
+        file_id: str,
+    ) -> VectorStoreFileDeleteResponse:
+        """Delete a vector store file.
+
+        :param vector_store_id: The ID of the vector store containing the file to delete.
+        :param file_id: The ID of the file to delete.
+        :returns: A VectorStoreFileDeleteResponse indicating the deletion status.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/file_batches",
+        method="POST",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_create_vector_store_file_batch(
+        self,
+        vector_store_id: str,
+        params: Annotated[OpenAICreateVectorStoreFileBatchRequestWithExtraBody, Body(...)],
+    ) -> VectorStoreFileBatchObject:
+        """Create a vector store file batch.
+
+        Generate an OpenAI-compatible vector store file batch for the given vector store.
+        :param vector_store_id: The ID of the vector store to create the file batch for.
+        :returns: A VectorStoreFileBatchObject representing the created file batch.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/file_batches/{batch_id}",
+        method="GET",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_retrieve_vector_store_file_batch(
+        self,
+        batch_id: str,
+        vector_store_id: str,
+    ) -> VectorStoreFileBatchObject:
+        """Retrieve a vector store file batch.
+
+        :param batch_id: The ID of the file batch to retrieve.
+        :param vector_store_id: The ID of the vector store containing the file batch.
+        :returns: A VectorStoreFileBatchObject representing the file batch.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/file_batches/{batch_id}/files",
+        method="GET",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_list_files_in_vector_store_file_batch(
+        self,
+        batch_id: str,
+        vector_store_id: str,
+        after: str | None = None,
+        before: str | None = None,
+        filter: str | None = None,
+        limit: int | None = 20,
+        order: str | None = "desc",
+    ) -> VectorStoreFilesListInBatchResponse:
+        """Returns a list of vector store files in a batch.
+
+        :param batch_id: The ID of the file batch to list files from.
+        :param vector_store_id: The ID of the vector store containing the file batch.
+        :param after: A cursor for use in pagination. `after` is an object ID that defines your place in the list.
+        :param before: A cursor for use in pagination. `before` is an object ID that defines your place in the list.
+        :param filter: Filter by file status. One of in_progress, completed, failed, cancelled.
+        :param limit: A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
+        :param order: Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order.
+        :returns: A VectorStoreFilesListInBatchResponse containing the list of files in the batch.
+        """
+        ...
+
+    @webmethod(
+        route="/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel",
+        method="POST",
+        level=LLAMA_STACK_API_V1,
+    )
+    async def openai_cancel_vector_store_file_batch(
+        self,
+        batch_id: str,
+        vector_store_id: str,
+    ) -> VectorStoreFileBatchObject:
+        """Cancels a vector store file batch.
+
+        :param batch_id: The ID of the file batch to cancel.
+        :param vector_store_id: The ID of the vector store containing the file batch.
+        :returns: A VectorStoreFileBatchObject representing the cancelled file batch.
+        """
+        ...

src/llama_stack_api/vector_stores.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 Literal
+
+from pydantic import BaseModel
+
+from llama_stack_api.resource import Resource, ResourceType
+
+
+# Internal resource type for storing the vector store routing and other information
+class VectorStore(Resource):
+    """Vector database resource for storing and querying vector embeddings.
+
+    :param type: Type of resource, always 'vector_store' for vector stores
+    :param embedding_model: Name of the embedding model to use for vector generation
+    :param embedding_dimension: Dimension of the embedding vectors
+    """
+
+    type: Literal[ResourceType.vector_store] = ResourceType.vector_store
+
+    embedding_model: str
+    embedding_dimension: int
+    vector_store_name: str | None = None
+
+    @property
+    def vector_store_id(self) -> str:
+        return self.identifier
+
+    @property
+    def provider_vector_store_id(self) -> str | None:
+        return self.provider_resource_id
+
+
+class VectorStoreInput(BaseModel):
+    """Input parameters for creating or configuring a vector database.
+
+    :param vector_store_id: Unique identifier for the vector store
+    :param embedding_model: Name of the embedding model to use for vector generation
+    :param embedding_dimension: Dimension of the embedding vectors
+    :param provider_vector_store_id: (Optional) Provider-specific identifier for the vector store
+    """
+
+    vector_store_id: str
+    embedding_model: str
+    embedding_dimension: int
+    provider_id: str | None = None
+    provider_vector_store_id: str | None = None

src/llama_stack_api/version.py

@@ -0,0 +1,9 @@
+# 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.
+
+LLAMA_STACK_API_V1 = "v1"
+LLAMA_STACK_API_V1BETA = "v1beta"
+LLAMA_STACK_API_V1ALPHA = "v1alpha"