Merge branch 'main' into remove-authorization-from-provider-data

.pre-commit-config.yaml

@@ -42,7 +42,6 @@ repos:
     hooks:
     -   id: ruff
         args: [ --fix ]
-        exclude: ^(src/llama_stack_api/strong_typing/.*)$
     -   id: ruff-format
 
 -   repo: https://github.com/adamchainz/blacken-docs
@@ -106,16 +105,16 @@ repos:
         language: python
         pass_filenames: false
         require_serial: true
-        files: ^src/llama_stack/providers/.*$
+        files: ^src/llama_stack/providers/.*$|^scripts/run_openapi_generator.sh$
       - id: openapi-codegen
         name: API Spec Codegen
         additional_dependencies:
           - uv==0.7.8
-        entry: sh -c './scripts/uv-run-with-index.sh run ./docs/openapi_generator/run_openapi_generator.sh > /dev/null'
+        entry: sh -c './scripts/uv-run-with-index.sh run scripts/run_openapi_generator.sh'
         language: python
         pass_filenames: false
         require_serial: true
-        files: ^src/llama_stack/apis/|^docs/openapi_generator/
+        files: ^src/llama_stack_api/.*$
       - id: check-workflows-use-hashes
         name: Check GitHub Actions use SHA-pinned actions
         entry: ./scripts/check-workflows-use-hashes.sh

CONTRIBUTING.md

@@ -231,7 +231,7 @@ npm run serve
 If you modify or add new API endpoints, update the API documentation accordingly. You can do this by running the following command:
 
 ```bash
-uv run ./docs/openapi_generator/run_openapi_generator.sh
+uv run ./scripts/run_openapi_generator.sh
 ```
 
 The generated API schema will be available in `docs/static/`. Make sure to review the changes before committing.

client-sdks/stainless/README.md

@@ -5,4 +5,4 @@ These are the source-of-truth configuration files used to generate the Stainless
 
 A small side note: notice the `.yml` suffixes since Stainless uses that suffix typically for its configuration files.
 
-These files go hand-in-hand. As of now, only the `openapi.yml` file is automatically generated using the `run_openapi_generator.sh` script.
+These files go hand-in-hand. As of now, only the `openapi.yml` file is automatically generated using the `scripts/run_openapi_generator.sh` script.

client-sdks/stainless/config.yml

@@ -115,9 +115,6 @@ resources:
       sampling_params: SamplingParams
       scoring_result: ScoringResult
       system_message: SystemMessage
-      query_result: RAGQueryResult
-      document: RAGDocument
-      query_config: RAGQueryConfig
   toolgroups:
     models:
       tool_group: ToolGroup
@@ -143,11 +140,6 @@ resources:
         endpoint: get /v1/tool-runtime/list-tools
         paginated: false
       invoke_tool: post /v1/tool-runtime/invoke
-    subresources:
-      rag_tool:
-        methods:
-          insert: post /v1/tool-runtime/rag-tool/insert
-          query: post /v1/tool-runtime/rag-tool/query
 
   responses:
     models:
@@ -173,6 +165,7 @@ resources:
           list:
             type: http
             endpoint: get /v1/responses/{response_id}/input_items
+            paginated: false
 
   prompts:
     models:
@@ -220,6 +213,9 @@ resources:
           create:
             type: http
             endpoint: post /v1/conversations/{conversation_id}/items
+          delete:
+            type: http
+            endpoint: delete /v1/conversations/{conversation_id}/items/{item_id}
 
   inspect:
     models:
@@ -252,6 +248,7 @@ resources:
           list:
             type: http
             endpoint: get /v1/chat/completions
+            paginated: false
           retrieve:
             type: http
             endpoint: get /v1/chat/completions/{completion_id}
@@ -375,6 +372,7 @@ resources:
         endpoint: get /v1/scoring-functions
         paginated: false
       register: post /v1/scoring-functions
+      unregister: delete /v1/scoring-functions/{scoring_fn_id}
     models:
       scoring_fn: ScoringFn
       scoring_fn_params: ScoringFnParams
@@ -392,6 +390,13 @@ resources:
       list_files_response: ListOpenAIFileResponse
       delete_file_response: OpenAIFileDeleteResponse
 
+  batches:
+    methods:
+      create: post /v1/batches
+      list: get /v1/batches
+      retrieve: get /v1/batches/{batch_id}
+      cancel: post /v1/batches/{batch_id}/cancel
+
   alpha:
     subresources:
       inference:
@@ -423,6 +428,7 @@ resources:
             endpoint: get /v1alpha/eval/benchmarks
             paginated: false
           register: post /v1alpha/eval/benchmarks
+          unregister: delete /v1alpha/eval/benchmarks/{benchmark_id}
         models:
           benchmark: Benchmark
           list_benchmarks_response: ListBenchmarksResponse
@@ -519,7 +525,7 @@ readme:
       params: &ref_0 {}
     headline:
       type: request
-      endpoint: post /v1/models
+      endpoint: get /v1/models
       params: *ref_0
     pagination:
       type: request

docs/openapi_generator/README.md

@@ -1 +0,0 @@
-The RFC Specification (OpenAPI format) is generated from the set of API endpoints located in `llama_stack.core/server/endpoints.py` using the `generate.py` utility.

docs/openapi_generator/generate.py

@@ -1,134 +0,0 @@
-# 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 found in the
-# LICENSE file in the root directory of this source tree.
-
-from datetime import datetime
-from pathlib import Path
-import sys
-import fire
-import ruamel.yaml as yaml
-
-from llama_stack_api import LLAMA_STACK_API_V1 # noqa: E402
-from llama_stack.core.stack import LlamaStack  # noqa: E402
-
-from .pyopenapi.options import Options  # noqa: E402
-from .pyopenapi.specification import Info, Server  # noqa: E402
-from .pyopenapi.utility import Specification, validate_api  # noqa: E402
-
-
-def str_presenter(dumper, data):
-    if data.startswith(f"/{LLAMA_STACK_API_V1}") or data.startswith(
-        "#/components/schemas/"
-    ):
-        style = None
-    else:
-        style = ">" if "\n" in data or len(data) > 40 else None
-    return dumper.represent_scalar("tag:yaml.org,2002:str", data, style=style)
-
-
-def generate_spec(output_dir: Path, stability_filter: str = None, main_spec: bool = False, combined_spec: bool = False):
-    """Generate OpenAPI spec with optional stability filtering."""
-
-    if combined_spec:
-        # Special case for combined stable + experimental APIs
-        title_suffix = " - Stable & Experimental APIs"
-        filename_prefix = "stainless-"
-        description_suffix = "\n\n**🔗 COMBINED**: This specification includes both stable production-ready APIs and experimental pre-release APIs. Use stable APIs for production deployments and experimental APIs for testing new features."
-        # Use the special "stainless" filter to include stable + experimental APIs
-        stability_filter = "stainless"
-    elif stability_filter:
-        title_suffix = {
-            "stable": " - Stable APIs" if not main_spec else "",
-            "experimental": " - Experimental APIs",
-            "deprecated": " - Deprecated APIs"
-        }.get(stability_filter, f" - {stability_filter.title()} APIs")
-
-        # Use main spec filename for stable when main_spec=True
-        if main_spec and stability_filter == "stable":
-            filename_prefix = ""
-        else:
-            filename_prefix = f"{stability_filter}-"
-
-        description_suffix = {
-            "stable": "\n\n**✅ STABLE**: Production-ready APIs with backward compatibility guarantees.",
-            "experimental": "\n\n**🧪 EXPERIMENTAL**: Pre-release APIs (v1alpha, v1beta) that may change before becoming stable.",
-            "deprecated": "\n\n**⚠️ DEPRECATED**: Legacy APIs that may be removed in future versions. Use for migration reference only."
-        }.get(stability_filter, "")
-    else:
-        title_suffix = ""
-        filename_prefix = ""
-        description_suffix = ""
-
-    spec = Specification(
-        LlamaStack,
-        Options(
-            server=Server(url="http://any-hosted-llama-stack.com"),
-            info=Info(
-                title=f"Llama Stack Specification{title_suffix}",
-                version=LLAMA_STACK_API_V1,
-                description=f"""This is the specification of the Llama Stack that provides
-                a set of endpoints and their corresponding interfaces that are tailored to
-                best leverage Llama Models.{description_suffix}""",
-            ),
-            include_standard_error_responses=True,
-            stability_filter=stability_filter,  # Pass the filter to the generator
-        ),
-    )
-
-    yaml_filename = f"{filename_prefix}llama-stack-spec.yaml"
-
-    with open(output_dir / yaml_filename, "w", encoding="utf-8") as fp:
-        y = yaml.YAML()
-        y.default_flow_style = False
-        y.block_seq_indent = 2
-        y.map_indent = 2
-        y.sequence_indent = 4
-        y.sequence_dash_offset = 2
-        y.width = 80
-        y.allow_unicode = True
-        y.representer.add_representer(str, str_presenter)
-
-        y.dump(
-            spec.get_json(),
-            fp,
-        )
-
-def main(output_dir: str):
-    output_dir = Path(output_dir)
-    if not output_dir.exists():
-        raise ValueError(f"Directory {output_dir} does not exist")
-
-    # Validate API protocols before generating spec
-    return_type_errors = validate_api()
-    if return_type_errors:
-        print("\nAPI Method Return Type Validation Errors:\n")
-        for error in return_type_errors:
-            print(error, file=sys.stderr)
-        sys.exit(1)
-
-    now = str(datetime.now())
-    print(f"Converting the spec to YAML (openapi.yaml) and HTML (openapi.html) at {now}")
-    print("")
-
-    # Generate main spec as stable APIs (llama-stack-spec.yaml)
-    print("Generating main specification (stable APIs)...")
-    generate_spec(output_dir, "stable", main_spec=True)
-
-    print("Generating other stability-filtered specifications...")
-    generate_spec(output_dir, "experimental")
-    generate_spec(output_dir, "deprecated")
-
-    print("Generating combined stable + experimental specification...")
-    generate_spec(output_dir, combined_spec=True)
-
-
-if __name__ == "__main__":
-    fire.Fire(main)

docs/openapi_generator/pyopenapi/README.md

@@ -1 +0,0 @@
-This is forked from https://github.com/hunyadi/pyopenapi

docs/openapi_generator/pyopenapi/operations.py

@@ -1,459 +0,0 @@
-# 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 collections.abc
-import enum
-import inspect
-import typing
-from dataclasses import dataclass
-from typing import Any, Callable, Dict, Iterable, Iterator, List, Optional, Tuple, Union
-
-from termcolor import colored
-
-from typing import get_origin, get_args
-
-from fastapi import UploadFile
-from fastapi.params import File, Form
-from typing import Annotated
-
-from llama_stack_api import (
-    ExtraBodyField,
-    LLAMA_STACK_API_V1,
-    LLAMA_STACK_API_V1ALPHA,
-    LLAMA_STACK_API_V1BETA,
-    get_signature,
-)
-
-
-def split_prefix(
-    s: str, sep: str, prefix: Union[str, Iterable[str]]
-) -> Tuple[Optional[str], str]:
-    """
-    Recognizes a prefix at the beginning of a string.
-
-    :param s: The string to check.
-    :param sep: A separator between (one of) the prefix(es) and the rest of the string.
-    :param prefix: A string or a set of strings to identify as a prefix.
-    :return: A tuple of the recognized prefix (if any) and the rest of the string excluding the separator (or the entire string).
-    """
-
-    if isinstance(prefix, str):
-        if s.startswith(prefix + sep):
-            return prefix, s[len(prefix) + len(sep) :]
-        else:
-            return None, s
-
-    for p in prefix:
-        if s.startswith(p + sep):
-            return p, s[len(p) + len(sep) :]
-
-    return None, s
-
-
-def _get_annotation_type(annotation: Union[type, str], callable: Callable) -> type:
-    "Maps a stringized reference to a type, as if using `from __future__ import annotations`."
-
-    if isinstance(annotation, str):
-        return eval(annotation, callable.__globals__)
-    else:
-        return annotation
-
-
-class HTTPMethod(enum.Enum):
-    "HTTP method used to invoke an endpoint operation."
-
-    GET = "GET"
-    POST = "POST"
-    PUT = "PUT"
-    DELETE = "DELETE"
-    PATCH = "PATCH"
-
-
-OperationParameter = Tuple[str, type]
-
-
-class ValidationError(TypeError):
-    pass
-
-
-@dataclass
-class EndpointOperation:
-    """
-    Type information and metadata associated with an endpoint operation.
-
-    "param defining_class: The most specific class that defines the endpoint operation.
-    :param name: The short name of the endpoint operation.
-    :param func_name: The name of the function to invoke when the operation is triggered.
-    :param func_ref: The callable to invoke when the operation is triggered.
-    :param route: A custom route string assigned to the operation.
-    :param path_params: Parameters of the operation signature that are passed in the path component of the URL string.
-    :param query_params: Parameters of the operation signature that are passed in the query string as `key=value` pairs.
-    :param request_params: The parameter that corresponds to the data transmitted in the request body.
-    :param multipart_params: Parameters that indicate multipart/form-data request body.
-    :param extra_body_params: Parameters that arrive via extra_body and are documented but not in SDK.
-    :param event_type: The Python type of the data that is transmitted out-of-band (e.g. via websockets) while the operation is in progress.
-    :param response_type: The Python type of the data that is transmitted in the response body.
-    :param http_method: The HTTP method used to invoke the endpoint such as POST, GET or PUT.
-    :param public: True if the operation can be invoked without prior authentication.
-    :param request_examples: Sample requests that the operation might take.
-    :param response_examples: Sample responses that the operation might produce.
-    """
-
-    defining_class: type
-    name: str
-    func_name: str
-    func_ref: Callable[..., Any]
-    route: Optional[str]
-    path_params: List[OperationParameter]
-    query_params: List[OperationParameter]
-    request_params: Optional[OperationParameter]
-    multipart_params: List[OperationParameter]
-    extra_body_params: List[tuple[str, type, str | None]]
-    event_type: Optional[type]
-    response_type: type
-    http_method: HTTPMethod
-    public: bool
-    request_examples: Optional[List[Any]] = None
-    response_examples: Optional[List[Any]] = None
-
-    def get_route(self, webmethod) -> str:
-        api_level = webmethod.level
-
-        if self.route is not None:
-            return "/".join(["", api_level, self.route.lstrip("/")])
-
-        route_parts = ["", api_level, self.name]
-        for param_name, _ in self.path_params:
-            route_parts.append("{" + param_name + "}")
-        return "/".join(route_parts)
-
-
-class _FormatParameterExtractor:
-    "A visitor to exract parameters in a format string."
-
-    keys: List[str]
-
-    def __init__(self) -> None:
-        self.keys = []
-
-    def __getitem__(self, key: str) -> None:
-        self.keys.append(key)
-        return None
-
-
-def _get_route_parameters(route: str) -> List[str]:
-    extractor = _FormatParameterExtractor()
-    # Replace all occurrences of ":path" with empty string
-    route = route.replace(":path", "")
-    route.format_map(extractor)
-    return extractor.keys
-
-
-def _get_endpoint_functions(
-    endpoint: type, prefixes: List[str]
-) -> Iterator[Tuple[str, str, str, Callable]]:
-    if not inspect.isclass(endpoint):
-        raise ValueError(f"object is not a class type: {endpoint}")
-
-    functions = inspect.getmembers(endpoint, inspect.isfunction)
-    for func_name, func_ref in functions:
-        webmethods = []
-
-        # Check for multiple webmethods (stacked decorators)
-        if hasattr(func_ref, "__webmethods__"):
-            webmethods = func_ref.__webmethods__
-
-        if not webmethods:
-            continue
-
-        for webmethod in webmethods:
-            print(f"Processing {colored(func_name, 'white')}...")
-            operation_name = func_name
-
-            if webmethod.method == "GET":
-                prefix = "get"
-            elif webmethod.method == "DELETE":
-                prefix = "delete"
-            elif webmethod.method == "POST":
-                prefix = "post"
-            elif operation_name.startswith("get_") or operation_name.endswith("/get"):
-                prefix = "get"
-            elif (
-                operation_name.startswith("delete_")
-                or operation_name.startswith("remove_")
-                or operation_name.endswith("/delete")
-                or operation_name.endswith("/remove")
-            ):
-                prefix = "delete"
-            else:
-                # by default everything else is a POST
-                prefix = "post"
-
-            yield prefix, operation_name, func_name, func_ref
-
-
-def _get_defining_class(member_fn: str, derived_cls: type) -> type:
-    "Find the class in which a member function is first defined in a class inheritance hierarchy."
-
-    # iterate in reverse member resolution order to find most specific class first
-    for cls in reversed(inspect.getmro(derived_cls)):
-        for name, _ in inspect.getmembers(cls, inspect.isfunction):
-            if name == member_fn:
-                return cls
-
-    raise ValidationError(
-        f"cannot find defining class for {member_fn} in {derived_cls}"
-    )
-
-
-def get_endpoint_operations(
-    endpoint: type, use_examples: bool = True
-) -> List[EndpointOperation]:
-    """
-    Extracts a list of member functions in a class eligible for HTTP interface binding.
-
-    These member functions are expected to have a signature like
-    ```
-    async def get_object(self, uuid: str, version: int) -> Object:
-        ...
-    ```
-    where the prefix `get_` translates to an HTTP GET, `object` corresponds to the name of the endpoint operation,
-    `uuid` and `version` are mapped to route path elements in "/object/{uuid}/{version}", and `Object` becomes
-    the response payload type, transmitted as an object serialized to JSON.
-
-    If the member function has a composite class type in the argument list, it becomes the request payload type,
-    and the caller is expected to provide the data as serialized JSON in an HTTP POST request.
-
-    :param endpoint: A class with member functions that can be mapped to an HTTP endpoint.
-    :param use_examples: Whether to return examples associated with member functions.
-    """
-
-    result = []
-
-    for prefix, operation_name, func_name, func_ref in _get_endpoint_functions(
-        endpoint,
-        [
-            "create",
-            "delete",
-            "do",
-            "get",
-            "post",
-            "put",
-            "remove",
-            "set",
-            "update",
-        ],
-    ):
-        # Get all webmethods for this function
-        webmethods = getattr(func_ref, "__webmethods__", [])
-
-        # Create one EndpointOperation for each webmethod
-        for webmethod in webmethods:
-            route = webmethod.route
-            route_params = _get_route_parameters(route) if route is not None else None
-            public = webmethod.public
-            request_examples = webmethod.request_examples
-            response_examples = webmethod.response_examples
-
-            # inspect function signature for path and query parameters, and request/response payload type
-            signature = get_signature(func_ref)
-
-            path_params = []
-            query_params = []
-            request_params = []
-            multipart_params = []
-            extra_body_params = []
-
-            for param_name, parameter in signature.parameters.items():
-                param_type = _get_annotation_type(parameter.annotation, func_ref)
-
-                # omit "self" for instance methods
-                if param_name == "self" and param_type is inspect.Parameter.empty:
-                    continue
-
-                # check if all parameters have explicit type
-                if parameter.annotation is inspect.Parameter.empty:
-                    raise ValidationError(
-                        f"parameter '{param_name}' in function '{func_name}' has no type annotation"
-                    )
-
-                # Check if this is an extra_body parameter
-                is_extra_body, extra_body_desc = _is_extra_body_param(param_type)
-                if is_extra_body:
-                    # Store in a separate list for documentation
-                    extra_body_params.append((param_name, param_type, extra_body_desc))
-                    continue  # Skip adding to request_params
-
-                is_multipart = _is_multipart_param(param_type)
-
-                if prefix in ["get", "delete"]:
-                    if route_params is not None and param_name in route_params:
-                        path_params.append((param_name, param_type))
-                    else:
-                        query_params.append((param_name, param_type))
-                else:
-                    if route_params is not None and param_name in route_params:
-                        path_params.append((param_name, param_type))
-                    elif is_multipart:
-                        multipart_params.append((param_name, param_type))
-                    else:
-                        request_params.append((param_name, param_type))
-
-            # check if function has explicit return type
-            if signature.return_annotation is inspect.Signature.empty:
-                raise ValidationError(
-                    f"function '{func_name}' has no return type annotation"
-                )
-
-            return_type = _get_annotation_type(signature.return_annotation, func_ref)
-
-            # operations that produce events are labeled as Generator[YieldType, SendType, ReturnType]
-            # where YieldType is the event type, SendType is None, and ReturnType is the immediate response type to the request
-            if typing.get_origin(return_type) is collections.abc.Generator:
-                event_type, send_type, response_type = typing.get_args(return_type)
-                if send_type is not type(None):
-                    raise ValidationError(
-                        f"function '{func_name}' has a return type Generator[Y,S,R] and therefore looks like an event but has an explicit send type"
-                    )
-            else:
-                event_type = None
-
-                def process_type(t):
-                    if typing.get_origin(t) is collections.abc.AsyncIterator:
-                        # NOTE(ashwin): this is SSE and there is no way to represent it. either we make it a List
-                        # or the item type. I am choosing it to be the latter
-                        args = typing.get_args(t)
-                        return args[0]
-                    elif typing.get_origin(t) is typing.Union:
-                        types = [process_type(a) for a in typing.get_args(t)]
-                        return typing._UnionGenericAlias(typing.Union, tuple(types))
-                    else:
-                        return t
-
-                response_type = process_type(return_type)
-
-                if prefix in ["delete", "remove"]:
-                    http_method = HTTPMethod.DELETE
-                elif prefix == "post":
-                    http_method = HTTPMethod.POST
-                elif prefix == "get":
-                    http_method = HTTPMethod.GET
-                elif prefix == "set":
-                    http_method = HTTPMethod.PUT
-                elif prefix == "update":
-                    http_method = HTTPMethod.PATCH
-                else:
-                    raise ValidationError(f"unknown prefix {prefix}")
-
-            # Create an EndpointOperation for this specific webmethod
-            operation = EndpointOperation(
-                defining_class=_get_defining_class(func_name, endpoint),
-                name=operation_name,
-                func_name=func_name,
-                func_ref=func_ref,
-                route=route,
-                path_params=path_params,
-                query_params=query_params,
-                request_params=request_params,
-                multipart_params=multipart_params,
-                extra_body_params=extra_body_params,
-                event_type=event_type,
-                response_type=response_type,
-                http_method=http_method,
-                public=public,
-                request_examples=request_examples if use_examples else None,
-                response_examples=response_examples if use_examples else None,
-            )
-
-            # Store the specific webmethod with this operation
-            operation.webmethod = webmethod
-            result.append(operation)
-
-    if not result:
-        raise ValidationError(f"no eligible endpoint operations in type {endpoint}")
-
-    return result
-
-
-def get_endpoint_events(endpoint: type) -> Dict[str, type]:
-    results = {}
-
-    for decl in typing.get_type_hints(endpoint).values():
-        # check if signature is Callable[...]
-        origin = typing.get_origin(decl)
-        if origin is None or not issubclass(origin, Callable):  # type: ignore
-            continue
-
-        # check if signature is Callable[[...], Any]
-        args = typing.get_args(decl)
-        if len(args) != 2:
-            continue
-        params_type, return_type = args
-        if not isinstance(params_type, list):
-            continue
-
-        # check if signature is Callable[[...], None]
-        if not issubclass(return_type, type(None)):
-            continue
-
-        # check if signature is Callable[[EventType], None]
-        if len(params_type) != 1:
-            continue
-
-        param_type = params_type[0]
-        results[param_type.__name__] = param_type
-
-    return results
-
-
-def _is_multipart_param(param_type: type) -> bool:
-    """
-    Check if a parameter type indicates multipart form data.
-
-    Returns True if the type is:
-    - UploadFile
-    - Annotated[UploadFile, File()]
-    - Annotated[str, Form()]
-    - Annotated[Any, File()]
-    - Annotated[Any, Form()]
-    """
-    if param_type is UploadFile:
-        return True
-
-    # Check for Annotated types
-    origin = get_origin(param_type)
-    if origin is None:
-        return False
-
-    if origin is Annotated:
-        args = get_args(param_type)
-        if len(args) < 2:
-            return False
-
-        # Check the annotations for File() or Form()
-        for annotation in args[1:]:
-            if isinstance(annotation, (File, Form)):
-                return True
-    return False
-
-
-def _is_extra_body_param(param_type: type) -> tuple[bool, str | None]:
-    """
-    Check if parameter is marked as coming from extra_body.
-
-    Returns:
-        (is_extra_body, description): Tuple of boolean and optional description
-    """
-    origin = get_origin(param_type)
-    if origin is Annotated:
-        args = get_args(param_type)
-        for annotation in args[1:]:
-            if isinstance(annotation, ExtraBodyField):
-                return True, annotation.description
-            # Also check by type name for cases where import matters
-            if type(annotation).__name__ == 'ExtraBodyField':
-                return True, getattr(annotation, 'description', None)
-    return False, None

docs/openapi_generator/pyopenapi/options.py

@@ -1,78 +0,0 @@
-# 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 dataclasses
-from dataclasses import dataclass
-from http import HTTPStatus
-from typing import Callable, ClassVar, Dict, List, Optional, Tuple, Union
-
-from .specification import (
-    Info,
-    SecurityScheme,
-    SecuritySchemeAPI,
-    SecuritySchemeHTTP,
-    SecuritySchemeOpenIDConnect,
-    Server,
-)
-
-HTTPStatusCode = Union[HTTPStatus, int, str]
-
-
-@dataclass
-class Options:
-    """
-    :param server: Base URL for the API endpoint.
-    :param info: Meta-information for the endpoint specification.
-    :param version: OpenAPI specification version as a tuple of major, minor, revision.
-    :param default_security_scheme: Security scheme to apply to endpoints, unless overridden on a per-endpoint basis.
-    :param extra_types: Extra types in addition to those found in operation signatures. Use a dictionary to group related types.
-    :param use_examples: Whether to emit examples for operations.
-    :param success_responses: Associates operation response types with HTTP status codes.
-    :param error_responses: Associates error response types with HTTP status codes.
-    :param error_wrapper: True if errors are encapsulated in an error object wrapper.
-    :param property_description_fun: Custom transformation function to apply to class property documentation strings.
-    :param captions: User-defined captions for sections such as "Operations" or "Types", and (if applicable) groups of extra types.
-    :param include_standard_error_responses: Whether to include standard error responses (400, 429, 500, 503) in all operations.
-    """
-
-    server: Server
-    info: Info
-    version: Tuple[int, int, int] = (3, 1, 0)
-    default_security_scheme: Optional[SecurityScheme] = None
-    extra_types: Union[List[type], Dict[str, List[type]], None] = None
-    use_examples: bool = True
-    success_responses: Dict[type, HTTPStatusCode] = dataclasses.field(
-        default_factory=dict
-    )
-    error_responses: Dict[type, HTTPStatusCode] = dataclasses.field(
-        default_factory=dict
-    )
-    error_wrapper: bool = False
-    property_description_fun: Optional[Callable[[type, str, str], str]] = None
-    captions: Optional[Dict[str, str]] = None
-    include_standard_error_responses: bool = True
-    stability_filter: Optional[str] = None
-
-    default_captions: ClassVar[Dict[str, str]] = {
-        "Operations": "Operations",
-        "Types": "Types",
-        "Events": "Events",
-        "AdditionalTypes": "Additional types",
-    }
-
-    def map(self, id: str) -> str:
-        "Maps a language-neutral placeholder string to language-dependent text."
-
-        if self.captions is not None:
-            caption = self.captions.get(id)
-            if caption is not None:
-                return caption
-
-        caption = self.__class__.default_captions.get(id)
-        if caption is not None:
-            return caption
-
-        raise KeyError(f"no caption found for ID: {id}")

docs/openapi_generator/pyopenapi/specification.py

@@ -1,269 +0,0 @@
-# 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 dataclasses
-import enum
-from dataclasses import dataclass
-from typing import Any, ClassVar, Dict, List, Optional, Union
-
-from llama_stack_api import JsonType, Schema, StrictJsonType
-
-URL = str
-
-
-@dataclass
-class Ref:
-    ref_type: ClassVar[str]
-    id: str
-
-    def to_json(self) -> StrictJsonType:
-        return {"$ref": f"#/components/{self.ref_type}/{self.id}"}
-
-
-@dataclass
-class SchemaRef(Ref):
-    ref_type: ClassVar[str] = "schemas"
-
-
-SchemaOrRef = Union[Schema, SchemaRef]
-
-
-@dataclass
-class ResponseRef(Ref):
-    ref_type: ClassVar[str] = "responses"
-
-
-@dataclass
-class ParameterRef(Ref):
-    ref_type: ClassVar[str] = "parameters"
-
-
-@dataclass
-class ExampleRef(Ref):
-    ref_type: ClassVar[str] = "examples"
-
-
-@dataclass
-class Contact:
-    name: Optional[str] = None
-    url: Optional[URL] = None
-    email: Optional[str] = None
-
-
-@dataclass
-class License:
-    name: str
-    url: Optional[URL] = None
-
-
-@dataclass
-class Info:
-    title: str
-    version: str
-    description: Optional[str] = None
-    termsOfService: Optional[str] = None
-    contact: Optional[Contact] = None
-    license: Optional[License] = None
-
-
-@dataclass
-class MediaType:
-    schema: Optional[SchemaOrRef] = None
-    example: Optional[Any] = None
-    examples: Optional[Dict[str, Union["Example", ExampleRef]]] = None
-
-
-@dataclass
-class RequestBody:
-    content: Dict[str, MediaType | Dict[str, Any]]
-    description: Optional[str] = None
-    required: Optional[bool] = None
-
-
-@dataclass
-class Response:
-    description: str
-    content: Optional[Dict[str, MediaType]] = None
-
-
-class ParameterLocation(enum.Enum):
-    Query = "query"
-    Header = "header"
-    Path = "path"
-    Cookie = "cookie"
-
-
-@dataclass
-class Parameter:
-    name: str
-    in_: ParameterLocation
-    description: Optional[str] = None
-    required: Optional[bool] = None
-    schema: Optional[SchemaOrRef] = None
-    example: Optional[Any] = None
-
-
-@dataclass
-class ExtraBodyParameter:
-    """Represents a parameter that arrives via extra_body in the request."""
-    name: str
-    schema: SchemaOrRef
-    description: Optional[str] = None
-    required: Optional[bool] = None
-
-
-@dataclass
-class Operation:
-    responses: Dict[str, Union[Response, ResponseRef]]
-    tags: Optional[List[str]] = None
-    summary: Optional[str] = None
-    description: Optional[str] = None
-    operationId: Optional[str] = None
-    parameters: Optional[List[Parameter]] = None
-    requestBody: Optional[RequestBody] = None
-    callbacks: Optional[Dict[str, "Callback"]] = None
-    security: Optional[List["SecurityRequirement"]] = None
-    deprecated: Optional[bool] = None
-    extraBodyParameters: Optional[List[ExtraBodyParameter]] = None
-
-
-@dataclass
-class PathItem:
-    summary: Optional[str] = None
-    description: Optional[str] = None
-    get: Optional[Operation] = None
-    put: Optional[Operation] = None
-    post: Optional[Operation] = None
-    delete: Optional[Operation] = None
-    options: Optional[Operation] = None
-    head: Optional[Operation] = None
-    patch: Optional[Operation] = None
-    trace: Optional[Operation] = None
-
-    def update(self, other: "PathItem") -> None:
-        "Merges another instance of this class into this object."
-
-        for field in dataclasses.fields(self.__class__):
-            value = getattr(other, field.name)
-            if value is not None:
-                setattr(self, field.name, value)
-
-
-# maps run-time expressions such as "$request.body#/url" to path items
-Callback = Dict[str, PathItem]
-
-
-@dataclass
-class Example:
-    summary: Optional[str] = None
-    description: Optional[str] = None
-    value: Optional[Any] = None
-    externalValue: Optional[URL] = None
-
-
-@dataclass
-class Server:
-    url: URL
-    description: Optional[str] = None
-
-
-class SecuritySchemeType(enum.Enum):
-    ApiKey = "apiKey"
-    HTTP = "http"
-    OAuth2 = "oauth2"
-    OpenIDConnect = "openIdConnect"
-
-
-@dataclass
-class SecurityScheme:
-    type: SecuritySchemeType
-    description: str
-
-
-@dataclass(init=False)
-class SecuritySchemeAPI(SecurityScheme):
-    name: str
-    in_: ParameterLocation
-
-    def __init__(self, description: str, name: str, in_: ParameterLocation) -> None:
-        super().__init__(SecuritySchemeType.ApiKey, description)
-        self.name = name
-        self.in_ = in_
-
-
-@dataclass(init=False)
-class SecuritySchemeHTTP(SecurityScheme):
-    scheme: str
-    bearerFormat: Optional[str] = None
-
-    def __init__(
-        self, description: str, scheme: str, bearerFormat: Optional[str] = None
-    ) -> None:
-        super().__init__(SecuritySchemeType.HTTP, description)
-        self.scheme = scheme
-        self.bearerFormat = bearerFormat
-
-
-@dataclass(init=False)
-class SecuritySchemeOpenIDConnect(SecurityScheme):
-    openIdConnectUrl: str
-
-    def __init__(self, description: str, openIdConnectUrl: str) -> None:
-        super().__init__(SecuritySchemeType.OpenIDConnect, description)
-        self.openIdConnectUrl = openIdConnectUrl
-
-
-@dataclass
-class Components:
-    schemas: Optional[Dict[str, Schema]] = None
-    responses: Optional[Dict[str, Response]] = None
-    parameters: Optional[Dict[str, Parameter]] = None
-    examples: Optional[Dict[str, Example]] = None
-    requestBodies: Optional[Dict[str, RequestBody]] = None
-    securitySchemes: Optional[Dict[str, SecurityScheme]] = None
-    callbacks: Optional[Dict[str, Callback]] = None
-
-
-SecurityScope = str
-SecurityRequirement = Dict[str, List[SecurityScope]]
-
-
-@dataclass
-class Tag:
-    name: str
-    description: Optional[str] = None
-    displayName: Optional[str] = None
-
-
-@dataclass
-class TagGroup:
-    """
-    A ReDoc extension to provide information about groups of tags.
-
-    Exposed via the vendor-specific property "x-tagGroups" of the top-level object.
-    """
-
-    name: str
-    tags: List[str]
-
-
-@dataclass
-class Document:
-    """
-    This class is a Python dataclass adaptation of the OpenAPI Specification.
-
-    For details, see <https://swagger.io/specification/>
-    """
-
-    openapi: str
-    info: Info
-    servers: List[Server]
-    paths: Dict[str, PathItem]
-    jsonSchemaDialect: Optional[str] = None
-    components: Optional[Components] = None
-    security: Optional[List[SecurityRequirement]] = None
-    tags: Optional[List[Tag]] = None
-    tagGroups: Optional[List[TagGroup]] = None

docs/openapi_generator/pyopenapi/template.html

@@ -1,41 +0,0 @@
-<!DOCTYPE html>
-<html>
-
-<head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>OpenAPI specification</title>
-    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
-    <script type="module" src="https://cdn.jsdelivr.net/npm/@stoplight/elements/web-components.min.js"></script>
-    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@stoplight/elements/styles.min.css">
-    <style>
-        body {
-            margin: 0;
-            padding: 0;
-            height: 100vh;
-        }
-
-        elements-api {
-            height: 100%;
-        }
-    </style>
-</head>
-
-<body>
-    <elements-api id="openapi-container" router="hash" layout="sidebar" hideExport="true"
-        hideInternal="true"></elements-api>
-
-    <script>
-        document.addEventListener("DOMContentLoaded", function () {
-            const spec = { /* OPENAPI_SPECIFICATION */ };
-            const element = document.getElementById("openapi-container");
-            element.apiDescriptionDocument = spec;
-
-            if (spec.info && spec.info.title) {
-                document.title = spec.info.title;
-            }
-        });
-    </script>
-</body>
-
-</html>

docs/openapi_generator/pyopenapi/utility.py

@@ -1,287 +0,0 @@
-# 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 json
-import typing
-import inspect
-from pathlib import Path
-from typing import Any, List, Optional, TextIO, Union, get_type_hints, get_origin, get_args
-
-from pydantic import BaseModel
-from llama_stack_api import StrictJsonType, is_unwrapped_body_param, object_to_json
-from llama_stack.core.resolver import api_protocol_map
-
-from .generator import Generator
-from .options import Options
-from .specification import Document
-
-THIS_DIR = Path(__file__).parent
-
-
-class Specification:
-    document: Document
-
-    def __init__(self, endpoint: type, options: Options):
-        generator = Generator(endpoint, options)
-        self.document = generator.generate()
-
-    def get_json(self) -> StrictJsonType:
-        """
-        Returns the OpenAPI specification as a Python data type (e.g. `dict` for an object, `list` for an array).
-
-        The result can be serialized to a JSON string with `json.dump` or `json.dumps`.
-        """
-
-        json_doc = typing.cast(StrictJsonType, object_to_json(self.document))
-
-        if isinstance(json_doc, dict):
-            # rename vendor-specific properties
-            tag_groups = json_doc.pop("tagGroups", None)
-            if tag_groups:
-                json_doc["x-tagGroups"] = tag_groups
-            tags = json_doc.get("tags")
-            if tags and isinstance(tags, list):
-                for tag in tags:
-                    if not isinstance(tag, dict):
-                        continue
-
-                    display_name = tag.pop("displayName", None)
-                    if display_name:
-                        tag["x-displayName"] = display_name
-
-            # Handle operations to rename extraBodyParameters -> x-llama-stack-extra-body-params
-            paths = json_doc.get("paths", {})
-            for path_item in paths.values():
-                if isinstance(path_item, dict):
-                    for method in ["get", "post", "put", "delete", "patch"]:
-                        operation = path_item.get(method)
-                        if operation and isinstance(operation, dict):
-                            extra_body_params = operation.pop("extraBodyParameters", None)
-                            if extra_body_params:
-                                operation["x-llama-stack-extra-body-params"] = extra_body_params
-
-        return json_doc
-
-    def get_json_string(self, pretty_print: bool = False) -> str:
-        """
-        Returns the OpenAPI specification as a JSON string.
-
-        :param pretty_print: Whether to use line indents to beautify the output.
-        """
-
-        json_doc = self.get_json()
-        if pretty_print:
-            return json.dumps(
-                json_doc, check_circular=False, ensure_ascii=False, indent=4
-            )
-        else:
-            return json.dumps(
-                json_doc,
-                check_circular=False,
-                ensure_ascii=False,
-                separators=(",", ":"),
-            )
-
-    def write_json(self, f: TextIO, pretty_print: bool = False) -> None:
-        """
-        Writes the OpenAPI specification to a file as a JSON string.
-
-        :param pretty_print: Whether to use line indents to beautify the output.
-        """
-
-        json_doc = self.get_json()
-        if pretty_print:
-            json.dump(
-                json_doc,
-                f,
-                check_circular=False,
-                ensure_ascii=False,
-                indent=4,
-            )
-        else:
-            json.dump(
-                json_doc,
-                f,
-                check_circular=False,
-                ensure_ascii=False,
-                separators=(",", ":"),
-            )
-
-    def write_html(self, f: TextIO, pretty_print: bool = False) -> None:
-        """
-        Creates a stand-alone HTML page for the OpenAPI specification with ReDoc.
-
-        :param pretty_print: Whether to use line indents to beautify the JSON string in the HTML file.
-        """
-
-        path = THIS_DIR / "template.html"
-        with path.open(encoding="utf-8", errors="strict") as html_template_file:
-            html_template = html_template_file.read()
-
-        html = html_template.replace(
-            "{ /* OPENAPI_SPECIFICATION */ }",
-            self.get_json_string(pretty_print=pretty_print),
-        )
-
-        f.write(html)
-
-def is_optional_type(type_: Any) -> bool:
-    """Check if a type is Optional."""
-    origin = get_origin(type_)
-    args = get_args(type_)
-    return origin is Optional or (origin is Union and type(None) in args)
-
-
-def _validate_api_method_return_type(method) -> str | None:
-    hints = get_type_hints(method)
-
-    if 'return' not in hints:
-        return "has no return type annotation"
-
-    return_type = hints['return']
-    if is_optional_type(return_type):
-        return "returns Optional type where a return value is mandatory"
-
-
-def _validate_api_method_doesnt_return_list(method) -> str | None:
-    hints = get_type_hints(method)
-
-    if 'return' not in hints:
-        return "has no return type annotation"
-
-    return_type = hints['return']
-    if get_origin(return_type) is list:
-        return "returns a list where a PaginatedResponse or List*Response object is expected"
-
-
-def _validate_api_delete_method_returns_none(method) -> str | None:
-    hints = get_type_hints(method)
-
-    if 'return' not in hints:
-        return "has no return type annotation"
-
-    return_type = hints['return']
-
-    # Allow OpenAI endpoints to return response objects since they follow OpenAI specification
-    method_name = getattr(method, '__name__', '')
-    if method_name.__contains__('openai_'):
-        return None
-
-    if return_type is not None and return_type is not type(None):
-        return "does not return None where None is mandatory"
-
-
-def _validate_list_parameters_contain_data(method) -> str | None:
-    hints = get_type_hints(method)
-
-    if 'return' not in hints:
-        return "has no return type annotation"
-
-    return_type = hints['return']
-    if not inspect.isclass(return_type):
-        return
-
-    if not return_type.__name__.startswith('List'):
-        return
-
-    if 'data' not in return_type.model_fields:
-        return "does not have a mandatory data attribute containing the list of objects"
-
-
-def _validate_has_ellipsis(method) -> str | None:
-    source = inspect.getsource(method)
-    if "..." not in source and not "NotImplementedError" in source:
-        return "does not contain ellipsis (...) in its implementation"
-
-def _validate_has_return_in_docstring(method) -> str | None:
-    source = inspect.getsource(method)
-    return_type = method.__annotations__.get('return')
-    if return_type is not None and return_type != type(None) and ":returns:" not in source:
-        return "does not have a ':returns:' in its docstring"
-
-def _validate_has_params_in_docstring(method) -> str | None:
-    source = inspect.getsource(method)
-    sig = inspect.signature(method)
-
-    params_list = [p for p in sig.parameters.values() if p.name != "self"]
-    if len(params_list) == 1:
-        param = params_list[0]
-        param_type = param.annotation
-        if is_unwrapped_body_param(param_type):
-            return
-
-    # Only check if the method has more than one parameter
-    if len(sig.parameters) > 1 and ":param" not in source:
-        return "does not have a ':param' in its docstring"
-
-def _validate_has_no_return_none_in_docstring(method) -> str | None:
-    source = inspect.getsource(method)
-    return_type = method.__annotations__.get('return')
-    if return_type is None and ":returns: None" in source:
-        return "has a ':returns: None' in its docstring which is redundant for None-returning functions"
-
-def _validate_docstring_lines_end_with_dot(method) -> str | None:
-    docstring = inspect.getdoc(method)
-    if docstring is None:
-        return None
-
-    lines = docstring.split('\n')
-    for line in lines:
-        line = line.strip()
-        if line and not any(line.endswith(char) for char in '.:{}[]()",'):
-            return f"docstring line '{line}' does not end with a valid character: . : {{ }} [ ] ( ) , \""
-
-_VALIDATORS = {
-    "GET": [
-        _validate_api_method_return_type,
-        _validate_list_parameters_contain_data,
-        _validate_api_method_doesnt_return_list,
-        _validate_has_ellipsis,
-        _validate_has_return_in_docstring,
-        _validate_has_params_in_docstring,
-        _validate_docstring_lines_end_with_dot,
-    ],
-    "DELETE": [
-        _validate_api_delete_method_returns_none,
-        _validate_has_ellipsis,
-        _validate_has_return_in_docstring,
-        _validate_has_params_in_docstring,
-        _validate_has_no_return_none_in_docstring
-    ],
-    "POST": [
-        _validate_has_ellipsis,
-        _validate_has_return_in_docstring,
-        _validate_has_params_in_docstring,
-        _validate_has_no_return_none_in_docstring,
-        _validate_docstring_lines_end_with_dot,
-    ],
-}
-
-
-def _get_methods_by_type(protocol, method_type: str):
-    members = inspect.getmembers(protocol, predicate=inspect.isfunction)
-    return {
-        method_name: method
-        for method_name, method in members
-        if (webmethod := getattr(method, '__webmethod__', None))
-        if webmethod and webmethod.method == method_type
-    }
-
-
-def validate_api() -> List[str]:
-    """Validate the API protocols."""
-    errors = []
-    protocols = api_protocol_map()
-
-    for target, validators in _VALIDATORS.items():
-        for protocol_name, protocol in protocols.items():
-            for validator in validators:
-                for method_name, method in _get_methods_by_type(protocol, target).items():
-                    err = validator(method)
-                    if err:
-                        errors.append(f"Method {protocol_name}.{method_name} {err}")
-
-    return errors

docs/openapi_generator/run_openapi_generator.sh

@@ -1,34 +0,0 @@
-#!/bin/bash
-
-# 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.
-
-PYTHONPATH=${PYTHONPATH:-}
-THIS_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
-
-set -euo pipefail
-
-missing_packages=()
-
-check_package() {
-    if ! pip show "$1" &>/dev/null; then
-        missing_packages+=("$1")
-    fi
-}
-
-if [ ${#missing_packages[@]} -ne 0 ]; then
-    echo "Error: The following package(s) are not installed:"
-    printf " - %s\n" "${missing_packages[@]}"
-    echo "Please install them using:"
-    echo "pip install ${missing_packages[*]}"
-    exit 1
-fi
-
-stack_dir=$(dirname $(dirname $THIS_DIR))
-PYTHONPATH=$PYTHONPATH:$stack_dir \
-  python -m docs.openapi_generator.generate $(dirname $THIS_DIR)/static
-
-cp $stack_dir/docs/static/stainless-llama-stack-spec.yaml $stack_dir/client-sdks/stainless/openapi.yml

pyproject.toml

@@ -50,6 +50,7 @@ dependencies = [
     "aiosqlite>=0.21.0",                              # server - for metadata store
     "asyncpg",                                        # for metadata store
     "sqlalchemy[asyncio]>=2.0.41",                    # server - for conversations
+    "pyyaml>=6.0.2",
     "starlette>=0.49.1",
 ]
 
@@ -73,6 +74,7 @@ dev = [
     "mypy",
     "pre-commit>=4.4.0",
     "ruamel.yaml",                   # needed for openapi generator
+    "openapi-spec-validator>=0.7.2",
 ]
 # Type checking dependencies - includes type stubs and optional runtime dependencies
 # needed for complete mypy coverage across all optional features
@@ -182,7 +184,12 @@ install-wheel-from-presigned = "llama_stack.cli.scripts.run:install_wheel_from_p
 
 [tool.setuptools.packages.find]
 where = ["src"]
-include = ["llama_stack", "llama_stack.*", "llama_stack_api", "llama_stack_api.*"]
+include = [
+    "llama_stack",
+    "llama_stack.*",
+    "llama_stack_api",
+    "llama_stack_api.*",
+]
 
 [[tool.uv.index]]
 name = "pytorch-cpu"
@@ -249,7 +256,9 @@ unfixable = [
 # Ignore the following errors for the following files
 [tool.ruff.lint.per-file-ignores]
 "tests/**/*.py" = ["DTZ"] # Ignore datetime rules for tests
-"src/llama_stack/providers/inline/scoring/basic/utils/ifeval_utils.py" = ["RUF001"]
+"src/llama_stack/providers/inline/scoring/basic/utils/ifeval_utils.py" = [
+    "RUF001",
+]
 "src/llama_stack/providers/inline/scoring/basic/scoring_fn/fn_defs/regex_parser_multiple_choice_answer.py" = [
     "RUF001",
     "PLE2515",
@@ -341,7 +350,6 @@ exclude = [
     "^src/llama_stack/providers/utils/telemetry/dataset_mixin\\.py$",
     "^src/llama_stack/providers/utils/telemetry/trace_protocol\\.py$",
     "^src/llama_stack/providers/utils/telemetry/tracing\\.py$",
-    "^src/llama_stack_api/strong_typing/auxiliary\\.py$",
     "^src/llama_stack/distributions/template\\.py$",
 ]
 

scripts/openapi_generator/__init__.py

@@ -0,0 +1,16 @@
+# 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.
+
+"""
+OpenAPI generator module for Llama Stack.
+
+This module provides functionality to generate OpenAPI specifications
+from FastAPI applications.
+"""
+
+from .main import generate_openapi_spec, main
+
+__all__ = ["generate_openapi_spec", "main"]

scripts/openapi_generator/__main__.py

@@ -3,3 +3,12 @@
 #
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
+
+"""
+Entry point for running the openapi_generator module as a package.
+"""
+
+from .main import main
+
+if __name__ == "__main__":
+    main()

scripts/openapi_generator/_legacy_order.py

@@ -0,0 +1,502 @@
+# 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.
+
+"""
+Temporary ordering helpers extracted from origin/main client-sdks/stainless/openapi.yml.
+
+These lists help the new generator match the previous ordering so that diffs
+remain readable while we debug schema content regressions. Remove once stable.
+"""
+
+LEGACY_PATH_ORDER = [
+    "/v1/batches",
+    "/v1/batches/{batch_id}",
+    "/v1/batches/{batch_id}/cancel",
+    "/v1/chat/completions",
+    "/v1/chat/completions/{completion_id}",
+    "/v1/completions",
+    "/v1/conversations",
+    "/v1/conversations/{conversation_id}",
+    "/v1/conversations/{conversation_id}/items",
+    "/v1/conversations/{conversation_id}/items/{item_id}",
+    "/v1/embeddings",
+    "/v1/files",
+    "/v1/files/{file_id}",
+    "/v1/files/{file_id}/content",
+    "/v1/health",
+    "/v1/inspect/routes",
+    "/v1/models",
+    "/v1/models/{model_id}",
+    "/v1/moderations",
+    "/v1/prompts",
+    "/v1/prompts/{prompt_id}",
+    "/v1/prompts/{prompt_id}/set-default-version",
+    "/v1/prompts/{prompt_id}/versions",
+    "/v1/providers",
+    "/v1/providers/{provider_id}",
+    "/v1/responses",
+    "/v1/responses/{response_id}",
+    "/v1/responses/{response_id}/input_items",
+    "/v1/safety/run-shield",
+    "/v1/scoring-functions",
+    "/v1/scoring-functions/{scoring_fn_id}",
+    "/v1/scoring/score",
+    "/v1/scoring/score-batch",
+    "/v1/shields",
+    "/v1/shields/{identifier}",
+    "/v1/tool-runtime/invoke",
+    "/v1/tool-runtime/list-tools",
+    "/v1/toolgroups",
+    "/v1/toolgroups/{toolgroup_id}",
+    "/v1/tools",
+    "/v1/tools/{tool_name}",
+    "/v1/vector-io/insert",
+    "/v1/vector-io/query",
+    "/v1/vector_stores",
+    "/v1/vector_stores/{vector_store_id}",
+    "/v1/vector_stores/{vector_store_id}/file_batches",
+    "/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}",
+    "/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/cancel",
+    "/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/files",
+    "/v1/vector_stores/{vector_store_id}/files",
+    "/v1/vector_stores/{vector_store_id}/files/{file_id}",
+    "/v1/vector_stores/{vector_store_id}/files/{file_id}/content",
+    "/v1/vector_stores/{vector_store_id}/search",
+    "/v1/version",
+    "/v1beta/datasetio/append-rows/{dataset_id}",
+    "/v1beta/datasetio/iterrows/{dataset_id}",
+    "/v1beta/datasets",
+    "/v1beta/datasets/{dataset_id}",
+    "/v1alpha/eval/benchmarks",
+    "/v1alpha/eval/benchmarks/{benchmark_id}",
+    "/v1alpha/eval/benchmarks/{benchmark_id}/evaluations",
+    "/v1alpha/eval/benchmarks/{benchmark_id}/jobs",
+    "/v1alpha/eval/benchmarks/{benchmark_id}/jobs/{job_id}",
+    "/v1alpha/eval/benchmarks/{benchmark_id}/jobs/{job_id}/result",
+    "/v1alpha/inference/rerank",
+    "/v1alpha/post-training/job/artifacts",
+    "/v1alpha/post-training/job/cancel",
+    "/v1alpha/post-training/job/status",
+    "/v1alpha/post-training/jobs",
+    "/v1alpha/post-training/preference-optimize",
+    "/v1alpha/post-training/supervised-fine-tune",
+]
+
+LEGACY_SCHEMA_ORDER = [
+    "Error",
+    "ListBatchesResponse",
+    "CreateBatchRequest",
+    "Batch",
+    "Order",
+    "ListOpenAIChatCompletionResponse",
+    "OpenAIAssistantMessageParam",
+    "OpenAIChatCompletionContentPartImageParam",
+    "OpenAIChatCompletionContentPartParam",
+    "OpenAIChatCompletionContentPartTextParam",
+    "OpenAIChatCompletionToolCall",
+    "OpenAIChatCompletionToolCallFunction",
+    "OpenAIChatCompletionUsage",
+    "OpenAIChoice",
+    "OpenAIChoiceLogprobs",
+    "OpenAIDeveloperMessageParam",
+    "OpenAIFile",
+    "OpenAIFileFile",
+    "OpenAIImageURL",
+    "OpenAIMessageParam",
+    "OpenAISystemMessageParam",
+    "OpenAITokenLogProb",
+    "OpenAIToolMessageParam",
+    "OpenAITopLogProb",
+    "OpenAIUserMessageParam",
+    "OpenAIJSONSchema",
+    "OpenAIResponseFormatJSONObject",
+    "OpenAIResponseFormatJSONSchema",
+    "OpenAIResponseFormatParam",
+    "OpenAIResponseFormatText",
+    "OpenAIChatCompletionRequestWithExtraBody",
+    "OpenAIChatCompletion",
+    "OpenAIChatCompletionChunk",
+    "OpenAIChoiceDelta",
+    "OpenAIChunkChoice",
+    "OpenAICompletionWithInputMessages",
+    "OpenAICompletionRequestWithExtraBody",
+    "OpenAICompletion",
+    "OpenAICompletionChoice",
+    "ConversationItem",
+    "OpenAIResponseAnnotationCitation",
+    "OpenAIResponseAnnotationContainerFileCitation",
+    "OpenAIResponseAnnotationFileCitation",
+    "OpenAIResponseAnnotationFilePath",
+    "OpenAIResponseAnnotations",
+    "OpenAIResponseContentPartRefusal",
+    "OpenAIResponseInputFunctionToolCallOutput",
+    "OpenAIResponseInputMessageContent",
+    "OpenAIResponseInputMessageContentFile",
+    "OpenAIResponseInputMessageContentImage",
+    "OpenAIResponseInputMessageContentText",
+    "OpenAIResponseMCPApprovalRequest",
+    "OpenAIResponseMCPApprovalResponse",
+    "OpenAIResponseMessage",
+    "OpenAIResponseOutputMessageContent",
+    "OpenAIResponseOutputMessageContentOutputText",
+    "OpenAIResponseOutputMessageFileSearchToolCall",
+    "OpenAIResponseOutputMessageFunctionToolCall",
+    "OpenAIResponseOutputMessageMCPCall",
+    "OpenAIResponseOutputMessageMCPListTools",
+    "OpenAIResponseOutputMessageWebSearchToolCall",
+    "CreateConversationRequest",
+    "Conversation",
+    "UpdateConversationRequest",
+    "ConversationDeletedResource",
+    "ConversationItemList",
+    "AddItemsRequest",
+    "ConversationItemDeletedResource",
+    "OpenAIEmbeddingsRequestWithExtraBody",
+    "OpenAIEmbeddingData",
+    "OpenAIEmbeddingUsage",
+    "OpenAIEmbeddingsResponse",
+    "OpenAIFilePurpose",
+    "ListOpenAIFileResponse",
+    "OpenAIFileObject",
+    "ExpiresAfter",
+    "OpenAIFileDeleteResponse",
+    "Response",
+    "HealthInfo",
+    "RouteInfo",
+    "ListRoutesResponse",
+    "OpenAIModel",
+    "OpenAIListModelsResponse",
+    "Model",
+    "ModelType",
+    "RunModerationRequest",
+    "ModerationObject",
+    "ModerationObjectResults",
+    "Prompt",
+    "ListPromptsResponse",
+    "CreatePromptRequest",
+    "UpdatePromptRequest",
+    "SetDefaultVersionRequest",
+    "ProviderInfo",
+    "ListProvidersResponse",
+    "ListOpenAIResponseObject",
+    "OpenAIResponseError",
+    "OpenAIResponseInput",
+    "OpenAIResponseInputToolFileSearch",
+    "OpenAIResponseInputToolFunction",
+    "OpenAIResponseInputToolWebSearch",
+    "OpenAIResponseObjectWithInput",
+    "OpenAIResponseOutput",
+    "OpenAIResponsePrompt",
+    "OpenAIResponseText",
+    "OpenAIResponseTool",
+    "OpenAIResponseToolMCP",
+    "OpenAIResponseUsage",
+    "ResponseGuardrailSpec",
+    "OpenAIResponseInputTool",
+    "OpenAIResponseInputToolMCP",
+    "CreateOpenaiResponseRequest",
+    "OpenAIResponseObject",
+    "OpenAIResponseContentPartOutputText",
+    "OpenAIResponseContentPartReasoningSummary",
+    "OpenAIResponseContentPartReasoningText",
+    "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",
+    "OpenAIDeleteResponseObject",
+    "ListOpenAIResponseInputItem",
+    "RunShieldRequest",
+    "RunShieldResponse",
+    "SafetyViolation",
+    "ViolationLevel",
+    "AggregationFunctionType",
+    "ArrayType",
+    "BasicScoringFnParams",
+    "BooleanType",
+    "ChatCompletionInputType",
+    "CompletionInputType",
+    "JsonType",
+    "LLMAsJudgeScoringFnParams",
+    "NumberType",
+    "ObjectType",
+    "RegexParserScoringFnParams",
+    "ScoringFn",
+    "ScoringFnParams",
+    "ScoringFnParamsType",
+    "StringType",
+    "UnionType",
+    "ListScoringFunctionsResponse",
+    "ScoreRequest",
+    "ScoreResponse",
+    "ScoringResult",
+    "ScoreBatchRequest",
+    "ScoreBatchResponse",
+    "Shield",
+    "ListShieldsResponse",
+    "InvokeToolRequest",
+    "ImageContentItem",
+    "InterleavedContent",
+    "InterleavedContentItem",
+    "TextContentItem",
+    "ToolInvocationResult",
+    "URL",
+    "ToolDef",
+    "ListToolDefsResponse",
+    "ToolGroup",
+    "ListToolGroupsResponse",
+    "Chunk",
+    "ChunkMetadata",
+    "InsertChunksRequest",
+    "QueryChunksRequest",
+    "QueryChunksResponse",
+    "VectorStoreFileCounts",
+    "VectorStoreListResponse",
+    "VectorStoreObject",
+    "VectorStoreChunkingStrategy",
+    "VectorStoreChunkingStrategyAuto",
+    "VectorStoreChunkingStrategyStatic",
+    "VectorStoreChunkingStrategyStaticConfig",
+    "OpenAICreateVectorStoreRequestWithExtraBody",
+    "OpenaiUpdateVectorStoreRequest",
+    "VectorStoreDeleteResponse",
+    "OpenAICreateVectorStoreFileBatchRequestWithExtraBody",
+    "VectorStoreFileBatchObject",
+    "VectorStoreFileStatus",
+    "VectorStoreFileLastError",
+    "VectorStoreFileObject",
+    "VectorStoreFilesListInBatchResponse",
+    "VectorStoreListFilesResponse",
+    "OpenaiAttachFileToVectorStoreRequest",
+    "OpenaiUpdateVectorStoreFileRequest",
+    "VectorStoreFileDeleteResponse",
+    "bool",
+    "VectorStoreContent",
+    "VectorStoreFileContentResponse",
+    "OpenaiSearchVectorStoreRequest",
+    "VectorStoreSearchResponse",
+    "VectorStoreSearchResponsePage",
+    "VersionInfo",
+    "AppendRowsRequest",
+    "PaginatedResponse",
+    "Dataset",
+    "RowsDataSource",
+    "URIDataSource",
+    "ListDatasetsResponse",
+    "Benchmark",
+    "ListBenchmarksResponse",
+    "BenchmarkConfig",
+    "GreedySamplingStrategy",
+    "ModelCandidate",
+    "SamplingParams",
+    "SystemMessage",
+    "TopKSamplingStrategy",
+    "TopPSamplingStrategy",
+    "EvaluateRowsRequest",
+    "EvaluateResponse",
+    "RunEvalRequest",
+    "Job",
+    "RerankRequest",
+    "RerankData",
+    "RerankResponse",
+    "Checkpoint",
+    "PostTrainingJobArtifactsResponse",
+    "PostTrainingMetric",
+    "CancelTrainingJobRequest",
+    "PostTrainingJobStatusResponse",
+    "ListPostTrainingJobsResponse",
+    "DPOAlignmentConfig",
+    "DPOLossType",
+    "DataConfig",
+    "DatasetFormat",
+    "EfficiencyConfig",
+    "OptimizerConfig",
+    "OptimizerType",
+    "TrainingConfig",
+    "PreferenceOptimizeRequest",
+    "PostTrainingJob",
+    "AlgorithmConfig",
+    "LoraFinetuningConfig",
+    "QATFinetuningConfig",
+    "SupervisedFineTuneRequest",
+    "RegisterModelRequest",
+    "ParamType",
+    "RegisterScoringFunctionRequest",
+    "RegisterShieldRequest",
+    "RegisterToolGroupRequest",
+    "DataSource",
+    "RegisterDatasetRequest",
+    "RegisterBenchmarkRequest",
+]
+
+LEGACY_RESPONSE_ORDER = ["BadRequest400", "TooManyRequests429", "InternalServerError500", "DefaultError"]
+
+LEGACY_TAGS = [
+    {
+        "description": "APIs for creating and interacting with agentic systems.",
+        "name": "Agents",
+        "x-displayName": "Agents",
+    },
+    {
+        "description": "The API is designed to allow use of openai client libraries for seamless integration.\n"
+        "\n"
+        "This API provides the following extensions:\n"
+        " - idempotent batch creation\n"
+        "\n"
+        "Note: This API is currently under active development and may undergo changes.",
+        "name": "Batches",
+        "x-displayName": "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.",
+    },
+    {"description": "", "name": "Benchmarks"},
+    {
+        "description": "Protocol for conversation management operations.",
+        "name": "Conversations",
+        "x-displayName": "Conversations",
+    },
+    {"description": "", "name": "DatasetIO"},
+    {"description": "", "name": "Datasets"},
+    {
+        "description": "Llama Stack Evaluation API for running evaluations on model and agent candidates.",
+        "name": "Eval",
+        "x-displayName": "Evaluations",
+    },
+    {
+        "description": "This API is used to upload documents that can be used with other Llama Stack APIs.",
+        "name": "Files",
+        "x-displayName": "Files",
+    },
+    {
+        "description": "Llama Stack Inference API for generating completions, chat completions, and embeddings.\n"
+        "\n"
+        "This API provides the raw interface to the underlying models. Three kinds of models are supported:\n"
+        '- LLM models: these models generate "raw" and "chat" (conversational) completions.\n'
+        "- Embedding models: these models generate embeddings to be used for semantic search.\n"
+        "- Rerank models: these models reorder the documents based on their relevance to a query.",
+        "name": "Inference",
+        "x-displayName": "Inference",
+    },
+    {
+        "description": "APIs for inspecting the Llama Stack service, including health status, available API routes with "
+        "methods and implementing providers.",
+        "name": "Inspect",
+        "x-displayName": "Inspect",
+    },
+    {"description": "", "name": "Models"},
+    {"description": "", "name": "PostTraining (Coming Soon)"},
+    {"description": "Protocol for prompt management operations.", "name": "Prompts", "x-displayName": "Prompts"},
+    {
+        "description": "Providers API for inspecting, listing, and modifying providers and their configurations.",
+        "name": "Providers",
+        "x-displayName": "Providers",
+    },
+    {"description": "OpenAI-compatible Moderations API.", "name": "Safety", "x-displayName": "Safety"},
+    {"description": "", "name": "Scoring"},
+    {"description": "", "name": "ScoringFunctions"},
+    {"description": "", "name": "Shields"},
+    {"description": "", "name": "ToolGroups"},
+    {"description": "", "name": "ToolRuntime"},
+    {"description": "", "name": "VectorIO"},
+]
+
+LEGACY_TAG_ORDER = [
+    "Agents",
+    "Batches",
+    "Benchmarks",
+    "Conversations",
+    "DatasetIO",
+    "Datasets",
+    "Eval",
+    "Files",
+    "Inference",
+    "Inspect",
+    "Models",
+    "PostTraining (Coming Soon)",
+    "Prompts",
+    "Providers",
+    "Safety",
+    "Scoring",
+    "ScoringFunctions",
+    "Shields",
+    "ToolGroups",
+    "ToolRuntime",
+    "VectorIO",
+]
+
+LEGACY_TAG_GROUPS = [
+    {
+        "name": "Operations",
+        "tags": [
+            "Agents",
+            "Batches",
+            "Benchmarks",
+            "Conversations",
+            "DatasetIO",
+            "Datasets",
+            "Eval",
+            "Files",
+            "Inference",
+            "Inspect",
+            "Models",
+            "PostTraining (Coming Soon)",
+            "Prompts",
+            "Providers",
+            "Safety",
+            "Scoring",
+            "ScoringFunctions",
+            "Shields",
+            "ToolGroups",
+            "ToolRuntime",
+            "VectorIO",
+        ],
+    }
+]
+
+LEGACY_SECURITY = [{"Default": []}]
+
+LEGACY_OPERATION_KEYS = [
+    "responses",
+    "tags",
+    "summary",
+    "description",
+    "operationId",
+    "parameters",
+    "requestBody",
+    "deprecated",
+]

scripts/openapi_generator/app.py

@@ -0,0 +1,91 @@
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+"""
+FastAPI app creation for OpenAPI generation.
+"""
+
+import inspect
+from typing import Any
+
+from fastapi import FastAPI
+
+from llama_stack.core.resolver import api_protocol_map
+from llama_stack_api import Api
+
+from .state import _protocol_methods_cache
+
+
+def _get_protocol_method(api: Api, method_name: str) -> Any | None:
+    """
+    Get a protocol method function by API and method name.
+    Uses caching to avoid repeated lookups.
+
+    Args:
+        api: The API enum
+        method_name: The method name (function name)
+
+    Returns:
+        The function object, or None if not found
+    """
+    global _protocol_methods_cache
+
+    if _protocol_methods_cache is None:
+        _protocol_methods_cache = {}
+        protocols = api_protocol_map()
+        from llama_stack_api.tools import SpecialToolGroup, ToolRuntime
+
+        toolgroup_protocols = {
+            SpecialToolGroup.rag_tool: ToolRuntime,
+        }
+
+        for api_key, protocol in protocols.items():
+            method_map: dict[str, Any] = {}
+            protocol_methods = inspect.getmembers(protocol, predicate=inspect.isfunction)
+            for name, method in protocol_methods:
+                method_map[name] = method
+
+            # Handle tool_runtime special case
+            if api_key == Api.tool_runtime:
+                for tool_group, sub_protocol in toolgroup_protocols.items():
+                    sub_protocol_methods = inspect.getmembers(sub_protocol, predicate=inspect.isfunction)
+                    for name, method in sub_protocol_methods:
+                        if hasattr(method, "__webmethod__"):
+                            method_map[f"{tool_group.value}.{name}"] = method
+
+            _protocol_methods_cache[api_key] = method_map
+
+    return _protocol_methods_cache.get(api, {}).get(method_name)
+
+
+def create_llama_stack_app() -> FastAPI:
+    """
+    Create a FastAPI app that represents the Llama Stack API.
+    This uses the existing route discovery system to automatically find all routes.
+    """
+    app = FastAPI(
+        title="Llama Stack API",
+        description="A comprehensive API for building and deploying AI applications",
+        version="1.0.0",
+        servers=[
+            {"url": "http://any-hosted-llama-stack.com"},
+        ],
+    )
+
+    # Get all API routes
+    from llama_stack.core.server.routes import get_all_api_routes
+
+    api_routes = get_all_api_routes()
+
+    # Create FastAPI routes from the discovered routes
+    from . import endpoints
+
+    for api, routes in api_routes.items():
+        for route, webmethod in routes:
+            # Convert the route to a FastAPI endpoint
+            endpoints._create_fastapi_endpoint(app, route, webmethod, api)
+
+    return app

scripts/openapi_generator/endpoints.py

@@ -0,0 +1,657 @@
+# 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.
+
+"""
+Endpoint generation logic for FastAPI OpenAPI generation.
+"""
+
+import inspect
+import re
+import types
+import typing
+from typing import Annotated, Any, get_args, get_origin
+
+from fastapi import FastAPI
+from pydantic import Field, create_model
+
+from llama_stack.log import get_logger
+from llama_stack_api import Api
+from llama_stack_api.schema_utils import get_registered_schema_info
+
+from . import app as app_module
+from .state import _extra_body_fields, register_dynamic_model
+
+logger = get_logger(name=__name__, category="core")
+
+
+def _to_pascal_case(segment: str) -> str:
+    tokens = re.findall(r"[A-Za-z]+|\d+", segment)
+    return "".join(token.capitalize() for token in tokens if token)
+
+
+def _compose_request_model_name(api: Api, method_name: str, variant: str | None = None) -> str:
+    """Generate a deterministic model name from the protocol method."""
+
+    def _to_pascal_from_snake(value: str) -> str:
+        return "".join(segment.capitalize() for segment in value.split("_") if segment)
+
+    base_name = _to_pascal_from_snake(method_name)
+    if not base_name:
+        base_name = _to_pascal_case(api.value)
+    base_name = f"{base_name}Request"
+    if variant:
+        base_name = f"{base_name}{variant}"
+    return base_name
+
+
+def _extract_path_parameters(path: str) -> list[dict[str, Any]]:
+    """Extract path parameters from a URL path and return them as OpenAPI parameter definitions."""
+    matches = re.findall(r"\{([^}:]+)(?::[^}]+)?\}", path)
+    return [
+        {
+            "name": param_name,
+            "in": "path",
+            "required": True,
+            "schema": {"type": "string"},
+            "description": f"Path parameter: {param_name}",
+        }
+        for param_name in matches
+    ]
+
+
+def _create_endpoint_with_request_model(
+    request_model: type, response_model: type | None, operation_description: str | None
+):
+    """Create an endpoint function with a request body model."""
+
+    async def endpoint(request: request_model) -> response_model:
+        return response_model() if response_model else {}
+
+    if operation_description:
+        endpoint.__doc__ = operation_description
+    return endpoint
+
+
+def _build_field_definitions(query_parameters: list[tuple[str, type, Any]], use_any: bool = False) -> dict[str, tuple]:
+    """Build field definitions for a Pydantic model from query parameters."""
+    from typing import Any
+
+    field_definitions = {}
+    for param_name, param_type, default_value in query_parameters:
+        if use_any:
+            field_definitions[param_name] = (Any, ... if default_value is inspect.Parameter.empty else default_value)
+            continue
+
+        base_type = param_type
+        extracted_field = None
+        if get_origin(param_type) is Annotated:
+            args = get_args(param_type)
+            if args:
+                base_type = args[0]
+                for arg in args[1:]:
+                    if isinstance(arg, Field):
+                        extracted_field = arg
+                        break
+
+        try:
+            if extracted_field:
+                field_definitions[param_name] = (base_type, extracted_field)
+            else:
+                field_definitions[param_name] = (
+                    base_type,
+                    ... if default_value is inspect.Parameter.empty else default_value,
+                )
+        except (TypeError, ValueError):
+            field_definitions[param_name] = (Any, ... if default_value is inspect.Parameter.empty else default_value)
+
+    # Ensure all parameters are included
+    expected_params = {name for name, _, _ in query_parameters}
+    missing = expected_params - set(field_definitions.keys())
+    if missing:
+        for param_name, _, default_value in query_parameters:
+            if param_name in missing:
+                field_definitions[param_name] = (
+                    Any,
+                    ... if default_value is inspect.Parameter.empty else default_value,
+                )
+
+    return field_definitions
+
+
+def _create_dynamic_request_model(
+    api: Api,
+    webmethod,
+    method_name: str,
+    http_method: str,
+    query_parameters: list[tuple[str, type, Any]],
+    use_any: bool = False,
+    variant_suffix: str | None = None,
+) -> type | None:
+    """Create a dynamic Pydantic model for request body."""
+    try:
+        field_definitions = _build_field_definitions(query_parameters, use_any)
+        if not field_definitions:
+            return None
+        model_name = _compose_request_model_name(api, method_name, variant_suffix or None)
+        request_model = create_model(model_name, **field_definitions)
+        return register_dynamic_model(model_name, request_model)
+    except Exception:
+        return None
+
+
+def _build_signature_params(
+    query_parameters: list[tuple[str, type, Any]],
+) -> tuple[list[inspect.Parameter], dict[str, type]]:
+    """Build signature parameters and annotations from query parameters."""
+    signature_params = []
+    param_annotations = {}
+    for param_name, param_type, default_value in query_parameters:
+        param_annotations[param_name] = param_type
+        signature_params.append(
+            inspect.Parameter(
+                param_name,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=default_value if default_value is not inspect.Parameter.empty else inspect.Parameter.empty,
+                annotation=param_type,
+            )
+        )
+    return signature_params, param_annotations
+
+
+def _extract_operation_description_from_docstring(api: Api, method_name: str) -> str | None:
+    """Extract operation description from the actual function docstring."""
+    func = app_module._get_protocol_method(api, method_name)
+    if not func or not func.__doc__:
+        return None
+
+    doc_lines = func.__doc__.split("\n")
+    description_lines = []
+    metadata_markers = (":param", ":type", ":return", ":returns", ":raises", ":exception", ":yield", ":yields", ":cvar")
+
+    for line in doc_lines:
+        if line.strip().startswith(metadata_markers):
+            break
+        description_lines.append(line)
+
+    description = "\n".join(description_lines).strip()
+    return description if description else None
+
+
+def _extract_response_description_from_docstring(webmethod, response_model, api: Api, method_name: str) -> str:
+    """Extract response description from the actual function docstring."""
+    func = app_module._get_protocol_method(api, method_name)
+    if not func or not func.__doc__:
+        return "Successful Response"
+    for line in func.__doc__.split("\n"):
+        if line.strip().startswith(":returns:"):
+            if desc := line.strip()[9:].strip():
+                return desc
+    return "Successful Response"
+
+
+def _get_tag_from_api(api: Api) -> str:
+    """Extract a tag name from the API enum for API grouping."""
+    return api.value.replace("_", " ").title()
+
+
+def _is_file_or_form_param(param_type: Any) -> bool:
+    """Check if a parameter type is annotated with File() or Form()."""
+    if get_origin(param_type) is Annotated:
+        args = get_args(param_type)
+        if len(args) > 1:
+            # Check metadata for File or Form
+            for metadata in args[1:]:
+                # Check if it's a File or Form instance
+                if hasattr(metadata, "__class__"):
+                    class_name = metadata.__class__.__name__
+                    if class_name in ("File", "Form"):
+                        return True
+    return False
+
+
+def _is_extra_body_field(metadata_item: Any) -> bool:
+    """Check if a metadata item is an ExtraBodyField instance."""
+    from llama_stack_api.schema_utils import ExtraBodyField
+
+    return isinstance(metadata_item, ExtraBodyField)
+
+
+def _is_async_iterator_type(type_obj: Any) -> bool:
+    """Check if a type is AsyncIterator or AsyncIterable."""
+    from collections.abc import AsyncIterable, AsyncIterator
+
+    origin = get_origin(type_obj)
+    if origin is None:
+        # Check if it's the class itself
+        return type_obj in (AsyncIterator, AsyncIterable) or (
+            hasattr(type_obj, "__origin__") and type_obj.__origin__ in (AsyncIterator, AsyncIterable)
+        )
+    return origin in (AsyncIterator, AsyncIterable)
+
+
+def _extract_response_models_from_union(union_type: Any) -> tuple[type | None, type | None]:
+    """
+    Extract non-streaming and streaming response models from a union type.
+
+    Returns:
+        tuple: (non_streaming_model, streaming_model)
+    """
+    non_streaming_model = None
+    streaming_model = None
+
+    args = get_args(union_type)
+    for arg in args:
+        # Check if it's an AsyncIterator
+        if _is_async_iterator_type(arg):
+            # Extract the type argument from AsyncIterator[T]
+            iterator_args = get_args(arg)
+            if iterator_args:
+                inner_type = iterator_args[0]
+                # Check if the inner type is a registered schema (union type)
+                # or a Pydantic model
+                if hasattr(inner_type, "model_json_schema"):
+                    streaming_model = inner_type
+                else:
+                    # Might be a registered schema - check if it's registered
+                    if get_registered_schema_info(inner_type):
+                        # We'll need to look this up later, but for now store the type
+                        streaming_model = inner_type
+        elif hasattr(arg, "model_json_schema"):
+            # Non-streaming Pydantic model
+            if non_streaming_model is None:
+                non_streaming_model = arg
+
+    return non_streaming_model, streaming_model
+
+
+def _find_models_for_endpoint(
+    webmethod, api: Api, method_name: str, is_post_put: bool = False
+) -> tuple[type | None, type | None, list[tuple[str, type, Any]], list[inspect.Parameter], type | None, str | None]:
+    """
+    Find appropriate request and response models for an endpoint by analyzing the actual function signature.
+    This uses the protocol function to determine the correct models dynamically.
+
+    Args:
+        webmethod: The webmethod metadata
+        api: The API enum for looking up the function
+        method_name: The method name (function name)
+        is_post_put: Whether this is a POST, PUT, or PATCH request (GET requests should never have request bodies)
+
+    Returns:
+        tuple: (request_model, response_model, query_parameters, file_form_params, streaming_response_model, response_schema_name)
+        where query_parameters is a list of (name, type, default_value) tuples
+        and file_form_params is a list of inspect.Parameter objects for File()/Form() params
+        and streaming_response_model is the model for streaming responses (AsyncIterator content)
+    """
+    route_descriptor = f"{webmethod.method or 'UNKNOWN'} {webmethod.route}"
+    try:
+        # Get the function from the protocol
+        func = app_module._get_protocol_method(api, method_name)
+        if not func:
+            logger.warning("No protocol method for %s.%s (%s)", api, method_name, route_descriptor)
+            return None, None, [], [], None, None
+
+        # Analyze the function signature
+        sig = inspect.signature(func)
+
+        # Find request model and collect all body parameters
+        request_model = None
+        query_parameters = []
+        file_form_params = []
+        path_params = set()
+        extra_body_params = []
+        response_schema_name = None
+
+        # Extract path parameters from the route
+        if webmethod and hasattr(webmethod, "route"):
+            path_matches = re.findall(r"\{([^}:]+)(?::[^}]+)?\}", webmethod.route)
+            path_params = set(path_matches)
+
+        for param_name, param in sig.parameters.items():
+            if param_name == "self":
+                continue
+
+            # Skip *args and **kwargs parameters - these are not real API parameters
+            if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+                continue
+
+            # Check if this is a path parameter
+            if param_name in path_params:
+                # Path parameters are handled separately, skip them
+                continue
+
+            # Check if it's a File() or Form() parameter - these need special handling
+            param_type = param.annotation
+            if _is_file_or_form_param(param_type):
+                # File() and Form() parameters must be in the function signature directly
+                # They cannot be part of a Pydantic model
+                file_form_params.append(param)
+                continue
+
+            # Check for ExtraBodyField in Annotated types
+            is_extra_body = False
+            extra_body_description = None
+            if get_origin(param_type) is Annotated:
+                args = get_args(param_type)
+                base_type = args[0] if args else param_type
+                metadata = args[1:] if len(args) > 1 else []
+
+                # Check if any metadata item is an ExtraBodyField
+                for metadata_item in metadata:
+                    if _is_extra_body_field(metadata_item):
+                        is_extra_body = True
+                        extra_body_description = metadata_item.description
+                        break
+
+                if is_extra_body:
+                    # Store as extra body parameter - exclude from request model
+                    extra_body_params.append((param_name, base_type, extra_body_description))
+                    continue
+
+            # Check if it's a Pydantic model (for POST/PUT requests)
+            if hasattr(param_type, "model_json_schema"):
+                # Collect all body parameters including Pydantic models
+                # We'll decide later whether to use a single model or create a combined one
+                query_parameters.append((param_name, param_type, param.default))
+            elif get_origin(param_type) is Annotated:
+                # Handle Annotated types - get the base type
+                args = get_args(param_type)
+                if args and hasattr(args[0], "model_json_schema"):
+                    # Collect Pydantic models from Annotated types
+                    query_parameters.append((param_name, args[0], param.default))
+                else:
+                    # Regular annotated parameter (but not File/Form, already handled above)
+                    query_parameters.append((param_name, param_type, param.default))
+            else:
+                # This is likely a body parameter for POST/PUT or query parameter for GET
+                # Store the parameter info for later use
+                # Preserve inspect.Parameter.empty to distinguish "no default" from "default=None"
+                default_value = param.default
+
+                # Extract the base type from union types (e.g., str | None -> str)
+                # Also make it safe for FastAPI to avoid forward reference issues
+                query_parameters.append((param_name, param_type, default_value))
+
+        # Store extra body fields for later use in post-processing
+        # We'll store them when the endpoint is created, as we need the full path
+        # For now, attach to the function for later retrieval
+        if extra_body_params:
+            func._extra_body_params = extra_body_params  # type: ignore
+
+        # If there's exactly one body parameter and it's a Pydantic model, use it directly
+        # Otherwise, we'll create a combined request model from all parameters
+        # BUT: For GET requests, never create a request body - all parameters should be query parameters
+        if is_post_put and len(query_parameters) == 1:
+            param_name, param_type, default_value = query_parameters[0]
+            if hasattr(param_type, "model_json_schema"):
+                request_model = param_type
+                query_parameters = []  # Clear query_parameters so we use the single model
+
+        # Find response model from return annotation
+        # Also detect streaming response models (AsyncIterator)
+        response_model = None
+        streaming_response_model = None
+        return_annotation = sig.return_annotation
+        if return_annotation != inspect.Signature.empty:
+            origin = get_origin(return_annotation)
+            if hasattr(return_annotation, "model_json_schema"):
+                response_model = return_annotation
+            elif origin is Annotated:
+                # Handle Annotated return types
+                args = get_args(return_annotation)
+                if args:
+                    # Check if the first argument is a Pydantic model
+                    if hasattr(args[0], "model_json_schema"):
+                        response_model = args[0]
+                    else:
+                        # Check if the first argument is a union type
+                        inner_origin = get_origin(args[0])
+                        if inner_origin is not None and (
+                            inner_origin is types.UnionType or inner_origin is typing.Union
+                        ):
+                            response_model, streaming_response_model = _extract_response_models_from_union(args[0])
+            elif origin is not None and (origin is types.UnionType or origin is typing.Union):
+                # Handle union types - extract both non-streaming and streaming models
+                response_model, streaming_response_model = _extract_response_models_from_union(return_annotation)
+            else:
+                try:
+                    from fastapi import Response as FastAPIResponse
+                except ImportError:
+                    fastapi_response_cls = None
+                else:
+                    fastapi_response_cls = FastAPIResponse
+                try:
+                    from starlette.responses import Response as StarletteResponse
+                except ImportError:
+                    starlette_response_cls = None
+                else:
+                    starlette_response_cls = StarletteResponse
+
+                response_types = tuple(t for t in (fastapi_response_cls, starlette_response_cls) if t is not None)
+                if response_types and any(return_annotation is t for t in response_types):
+                    response_schema_name = "Response"
+
+        return (
+            request_model,
+            response_model,
+            query_parameters,
+            file_form_params,
+            streaming_response_model,
+            response_schema_name,
+        )
+
+    except Exception as exc:
+        logger.warning(
+            "Failed to analyze endpoint %s.%s (%s): %s", api, method_name, route_descriptor, exc, exc_info=True
+        )
+        return None, None, [], [], None, None
+
+
+def _create_fastapi_endpoint(app: FastAPI, route, webmethod, api: Api):
+    """Create a FastAPI endpoint from a discovered route and webmethod."""
+    path = route.path
+    raw_methods = route.methods or set()
+    method_list = sorted({method.upper() for method in raw_methods if method and method.upper() != "HEAD"})
+    if not method_list:
+        method_list = ["GET"]
+    primary_method = method_list[0]
+    name = route.name
+    fastapi_path = path.replace("{", "{").replace("}", "}")
+    is_post_put = any(method in ["POST", "PUT", "PATCH"] for method in method_list)
+
+    (
+        request_model,
+        response_model,
+        query_parameters,
+        file_form_params,
+        streaming_response_model,
+        response_schema_name,
+    ) = _find_models_for_endpoint(webmethod, api, name, is_post_put)
+    operation_description = _extract_operation_description_from_docstring(api, name)
+    response_description = _extract_response_description_from_docstring(webmethod, response_model, api, name)
+
+    # Retrieve and store extra body fields for this endpoint
+    func = app_module._get_protocol_method(api, name)
+    extra_body_params = getattr(func, "_extra_body_params", []) if func else []
+    if extra_body_params:
+        for method in method_list:
+            key = (fastapi_path, method.upper())
+            _extra_body_fields[key] = extra_body_params
+
+    if is_post_put and not request_model and not file_form_params and query_parameters:
+        request_model = _create_dynamic_request_model(
+            api, webmethod, name, primary_method, query_parameters, use_any=False
+        )
+        if not request_model:
+            request_model = _create_dynamic_request_model(
+                api, webmethod, name, primary_method, query_parameters, use_any=True, variant_suffix="Loose"
+            )
+        if request_model:
+            query_parameters = []
+
+    if file_form_params and is_post_put:
+        signature_params = list(file_form_params)
+        param_annotations = {param.name: param.annotation for param in file_form_params}
+        for param_name, param_type, default_value in query_parameters:
+            signature_params.append(
+                inspect.Parameter(
+                    param_name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    default=default_value if default_value is not inspect.Parameter.empty else inspect.Parameter.empty,
+                    annotation=param_type,
+                )
+            )
+            param_annotations[param_name] = param_type
+
+        async def file_form_endpoint():
+            return response_model() if response_model else {}
+
+        if operation_description:
+            file_form_endpoint.__doc__ = operation_description
+        file_form_endpoint.__signature__ = inspect.Signature(signature_params)
+        file_form_endpoint.__annotations__ = param_annotations
+        endpoint_func = file_form_endpoint
+    elif request_model and response_model:
+        endpoint_func = _create_endpoint_with_request_model(request_model, response_model, operation_description)
+    elif request_model:
+        endpoint_func = _create_endpoint_with_request_model(request_model, None, operation_description)
+    elif response_model and query_parameters:
+        if is_post_put:
+            request_model = _create_dynamic_request_model(
+                api, webmethod, name, primary_method, query_parameters, use_any=False
+            )
+            if not request_model:
+                request_model = _create_dynamic_request_model(
+                    api, webmethod, name, primary_method, query_parameters, use_any=True, variant_suffix="Loose"
+                )
+
+            if request_model:
+                endpoint_func = _create_endpoint_with_request_model(
+                    request_model, response_model, operation_description
+                )
+            else:
+
+                async def empty_endpoint() -> response_model:
+                    return response_model() if response_model else {}
+
+                if operation_description:
+                    empty_endpoint.__doc__ = operation_description
+                endpoint_func = empty_endpoint
+        else:
+            sorted_params = sorted(query_parameters, key=lambda x: (x[2] is not inspect.Parameter.empty, x[0]))
+            signature_params, param_annotations = _build_signature_params(sorted_params)
+
+            async def query_endpoint():
+                return response_model()
+
+            if operation_description:
+                query_endpoint.__doc__ = operation_description
+            query_endpoint.__signature__ = inspect.Signature(signature_params)
+            query_endpoint.__annotations__ = param_annotations
+            endpoint_func = query_endpoint
+    elif response_model:
+
+        async def response_only_endpoint() -> response_model:
+            return response_model()
+
+        if operation_description:
+            response_only_endpoint.__doc__ = operation_description
+        endpoint_func = response_only_endpoint
+    elif query_parameters:
+        signature_params, param_annotations = _build_signature_params(query_parameters)
+
+        async def params_only_endpoint():
+            return {}
+
+        if operation_description:
+            params_only_endpoint.__doc__ = operation_description
+        params_only_endpoint.__signature__ = inspect.Signature(signature_params)
+        params_only_endpoint.__annotations__ = param_annotations
+        endpoint_func = params_only_endpoint
+    else:
+        # Endpoint with no parameters and no response model
+        # If we have a response_model from the function signature, use it even if _find_models_for_endpoint didn't find it
+        # This can happen if there was an exception during model finding
+        if response_model is None:
+            # Try to get response model directly from the function signature as a fallback
+            func = app_module._get_protocol_method(api, name)
+            if func:
+                try:
+                    sig = inspect.signature(func)
+                    return_annotation = sig.return_annotation
+                    if return_annotation != inspect.Signature.empty:
+                        if hasattr(return_annotation, "model_json_schema"):
+                            response_model = return_annotation
+                        elif get_origin(return_annotation) is Annotated:
+                            args = get_args(return_annotation)
+                            if args and hasattr(args[0], "model_json_schema"):
+                                response_model = args[0]
+                except Exception:
+                    pass
+
+        if response_model:
+
+            async def no_params_endpoint() -> response_model:
+                return response_model() if response_model else {}
+        else:
+
+            async def no_params_endpoint():
+                return {}
+
+        if operation_description:
+            no_params_endpoint.__doc__ = operation_description
+        endpoint_func = no_params_endpoint
+
+    # Build response content with both application/json and text/event-stream if streaming
+    response_content: dict[str, Any] = {}
+    if response_model:
+        response_content["application/json"] = {"schema": {"$ref": f"#/components/schemas/{response_model.__name__}"}}
+    elif response_schema_name:
+        response_content["application/json"] = {"schema": {"$ref": f"#/components/schemas/{response_schema_name}"}}
+    if streaming_response_model:
+        # Get the schema name for the streaming model
+        # It might be a registered schema or a Pydantic model
+        streaming_schema_name = None
+        # Check if it's a registered schema first (before checking __name__)
+        # because registered schemas might be Annotated types
+        if schema_info := get_registered_schema_info(streaming_response_model):
+            streaming_schema_name = schema_info.name
+        elif hasattr(streaming_response_model, "__name__"):
+            streaming_schema_name = streaming_response_model.__name__
+
+        if streaming_schema_name:
+            response_content["text/event-stream"] = {
+                "schema": {"$ref": f"#/components/schemas/{streaming_schema_name}"}
+            }
+
+    # If no content types, use empty schema
+    # Add the endpoint to the FastAPI app
+    is_deprecated = webmethod.deprecated or False
+    route_kwargs = {
+        "name": name,
+        "tags": [_get_tag_from_api(api)],
+        "deprecated": is_deprecated,
+        "responses": {
+            400: {"$ref": "#/components/responses/BadRequest400"},
+            429: {"$ref": "#/components/responses/TooManyRequests429"},
+            500: {"$ref": "#/components/responses/InternalServerError500"},
+            "default": {"$ref": "#/components/responses/DefaultError"},
+        },
+    }
+    success_response: dict[str, Any] = {"description": response_description}
+    if response_content:
+        success_response["content"] = response_content
+    route_kwargs["responses"][200] = success_response
+
+    # FastAPI needs response_model parameter to properly generate OpenAPI spec
+    # Use the non-streaming response model if available
+    if response_model:
+        route_kwargs["response_model"] = response_model
+
+    method_map = {"GET": app.get, "POST": app.post, "PUT": app.put, "DELETE": app.delete, "PATCH": app.patch}
+    for method in method_list:
+        if handler := method_map.get(method):
+            handler(fastapi_path, **route_kwargs)(endpoint_func)

scripts/openapi_generator/main.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+# 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.
+
+"""
+Main entry point for the FastAPI OpenAPI generator.
+"""
+
+import copy
+from pathlib import Path
+from typing import Any
+
+import yaml
+from fastapi.openapi.utils import get_openapi
+
+from . import app, schema_collection, schema_filtering, schema_transforms, state
+
+
+def generate_openapi_spec(output_dir: str) -> dict[str, Any]:
+    """
+    Generate OpenAPI specification using FastAPI's built-in method.
+
+    Args:
+        output_dir: Directory to save the generated files
+
+    Returns:
+        The generated OpenAPI specification as a dictionary
+    """
+    state.reset_generator_state()
+    # Create the FastAPI app
+    fastapi_app = app.create_llama_stack_app()
+
+    # Generate the OpenAPI schema
+    openapi_schema = get_openapi(
+        title=fastapi_app.title,
+        version=fastapi_app.version,
+        description=fastapi_app.description,
+        routes=fastapi_app.routes,
+        servers=fastapi_app.servers,
+    )
+
+    # Set OpenAPI version to 3.1.0
+    openapi_schema["openapi"] = "3.1.0"
+
+    # Add standard error responses
+    openapi_schema = schema_transforms._add_error_responses(openapi_schema)
+
+    # Ensure all @json_schema_type decorated models are included
+    openapi_schema = schema_collection._ensure_json_schema_types_included(openapi_schema)
+
+    # Fix $ref references to point to components/schemas instead of $defs
+    openapi_schema = schema_transforms._fix_ref_references(openapi_schema)
+
+    # Fix path parameter resolution issues
+    openapi_schema = schema_transforms._fix_path_parameters(openapi_schema)
+
+    # Eliminate $defs section entirely for oasdiff compatibility
+    openapi_schema = schema_transforms._eliminate_defs_section(openapi_schema)
+
+    # Clean descriptions in schema definitions by removing docstring metadata
+    openapi_schema = schema_transforms._clean_schema_descriptions(openapi_schema)
+    openapi_schema = schema_transforms._normalize_empty_responses(openapi_schema)
+
+    # Remove query parameters from POST/PUT/PATCH endpoints that have a request body
+    # FastAPI sometimes infers parameters as query params even when they should be in the request body
+    openapi_schema = schema_transforms._remove_query_params_from_body_endpoints(openapi_schema)
+
+    # Add x-llama-stack-extra-body-params extension for ExtraBodyField parameters
+    openapi_schema = schema_transforms._add_extra_body_params_extension(openapi_schema)
+
+    # Remove request bodies from GET endpoints (GET requests should never have request bodies)
+    # This must run AFTER _add_extra_body_params_extension to ensure any request bodies
+    # that FastAPI incorrectly added to GET endpoints are removed
+    openapi_schema = schema_transforms._remove_request_bodies_from_get_endpoints(openapi_schema)
+
+    # Extract duplicate union types to shared schema references
+    openapi_schema = schema_transforms._extract_duplicate_union_types(openapi_schema)
+
+    # Split into stable (v1 only), experimental (v1alpha + v1beta), deprecated, and combined (stainless) specs
+    # Each spec needs its own deep copy of the full schema to avoid cross-contamination
+    stable_schema = schema_filtering._filter_schema_by_version(
+        copy.deepcopy(openapi_schema), stable_only=True, exclude_deprecated=True
+    )
+    experimental_schema = schema_filtering._filter_schema_by_version(
+        copy.deepcopy(openapi_schema), stable_only=False, exclude_deprecated=True
+    )
+    deprecated_schema = schema_filtering._filter_deprecated_schema(copy.deepcopy(openapi_schema))
+    combined_schema = schema_filtering._filter_combined_schema(copy.deepcopy(openapi_schema))
+
+    # Apply duplicate union extraction to combined schema (used by Stainless)
+    combined_schema = schema_transforms._extract_duplicate_union_types(combined_schema)
+
+    base_description = (
+        "This is the specification of the Llama Stack that provides\n"
+        "                    a set of endpoints and their corresponding interfaces that are\n"
+        "    tailored to\n"
+        "                    best leverage Llama Models."
+    )
+
+    schema_configs = [
+        (
+            stable_schema,
+            "Llama Stack Specification",
+            "**✅ STABLE**: Production-ready APIs with backward compatibility guarantees.",
+        ),
+        (
+            experimental_schema,
+            "Llama Stack Specification - Experimental APIs",
+            "**🧪 EXPERIMENTAL**: Pre-release APIs (v1alpha, v1beta) that may change before\n    becoming stable.",
+        ),
+        (
+            deprecated_schema,
+            "Llama Stack Specification - Deprecated APIs",
+            "**⚠️ DEPRECATED**: Legacy APIs that may be removed in future versions. Use for\n    migration reference only.",
+        ),
+        (
+            combined_schema,
+            "Llama Stack Specification - Stable & Experimental APIs",
+            "**🔗 COMBINED**: This specification includes both stable production-ready APIs\n    and experimental pre-release APIs. Use stable APIs for production deployments\n    and experimental APIs for testing new features.",
+        ),
+    ]
+
+    for schema, title, description_suffix in schema_configs:
+        if "info" not in schema:
+            schema["info"] = {}
+        schema["info"].update(
+            {
+                "title": title,
+                "version": "v1",
+                "description": f"{base_description}\n\n    {description_suffix}",
+            }
+        )
+
+    schemas_to_validate = [
+        (stable_schema, "Stable schema"),
+        (experimental_schema, "Experimental schema"),
+        (deprecated_schema, "Deprecated schema"),
+        (combined_schema, "Combined (stainless) schema"),
+    ]
+
+    for schema, _ in schemas_to_validate:
+        schema_transforms._fix_schema_issues(schema)
+        schema_transforms._apply_legacy_sorting(schema)
+
+    print("\nValidating generated schemas...")
+    failed_schemas = [
+        name for schema, name in schemas_to_validate if not schema_transforms.validate_openapi_schema(schema, name)
+    ]
+    if failed_schemas:
+        raise ValueError(f"Invalid schemas: {', '.join(failed_schemas)}")
+
+    # Ensure output directory exists
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    # Save the stable specification
+    yaml_path = output_path / "llama-stack-spec.yaml"
+    schema_transforms._write_yaml_file(yaml_path, stable_schema)
+    # Post-process the YAML file to remove $defs section and fix references
+    with open(yaml_path) as f:
+        yaml_content = f.read()
+
+    if "  $defs:" in yaml_content or "#/$defs/" in yaml_content:
+        # Use string replacement to fix references directly
+        if "#/$defs/" in yaml_content:
+            yaml_content = yaml_content.replace("#/$defs/", "#/components/schemas/")
+
+        # Parse the YAML content
+        yaml_data = yaml.safe_load(yaml_content)
+
+        # Move $defs to components/schemas if it exists
+        if "$defs" in yaml_data:
+            if "components" not in yaml_data:
+                yaml_data["components"] = {}
+            if "schemas" not in yaml_data["components"]:
+                yaml_data["components"]["schemas"] = {}
+
+            # Move all $defs to components/schemas
+            for def_name, def_schema in yaml_data["$defs"].items():
+                yaml_data["components"]["schemas"][def_name] = def_schema
+
+            # Remove the $defs section
+            del yaml_data["$defs"]
+
+        # Write the modified YAML back
+        schema_transforms._write_yaml_file(yaml_path, yaml_data)
+
+    print(f"Generated YAML (stable): {yaml_path}")
+
+    experimental_yaml_path = output_path / "experimental-llama-stack-spec.yaml"
+    schema_transforms._write_yaml_file(experimental_yaml_path, experimental_schema)
+    print(f"Generated YAML (experimental): {experimental_yaml_path}")
+
+    deprecated_yaml_path = output_path / "deprecated-llama-stack-spec.yaml"
+    schema_transforms._write_yaml_file(deprecated_yaml_path, deprecated_schema)
+    print(f"Generated YAML (deprecated): {deprecated_yaml_path}")
+
+    # Generate combined (stainless) spec
+    stainless_yaml_path = output_path / "stainless-llama-stack-spec.yaml"
+    schema_transforms._write_yaml_file(stainless_yaml_path, combined_schema)
+    print(f"Generated YAML (stainless/combined): {stainless_yaml_path}")
+
+    return stable_schema
+
+
+def main():
+    """Main entry point for the FastAPI OpenAPI generator."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Generate OpenAPI specification using FastAPI")
+    parser.add_argument("output_dir", help="Output directory for generated files")
+
+    args = parser.parse_args()
+
+    print("Generating OpenAPI specification using FastAPI...")
+    print(f"Output directory: {args.output_dir}")
+
+    try:
+        openapi_schema = generate_openapi_spec(output_dir=args.output_dir)
+
+        print("\nOpenAPI specification generated successfully!")
+        print(f"Schemas: {len(openapi_schema.get('components', {}).get('schemas', {}))}")
+        print(f"Paths: {len(openapi_schema.get('paths', {}))}")
+        operation_count = sum(
+            1
+            for path_info in openapi_schema.get("paths", {}).values()
+            for method in ["get", "post", "put", "delete", "patch"]
+            if method in path_info
+        )
+        print(f"Operations: {operation_count}")
+
+    except Exception as e:
+        print(f"Error generating OpenAPI specification: {e}")
+        raise
+
+
+if __name__ == "__main__":
+    main()

scripts/openapi_generator/schema_collection.py

@@ -0,0 +1,131 @@
+# 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.
+
+"""
+Schema discovery and collection for OpenAPI generation.
+"""
+
+import importlib
+from typing import Any
+
+
+def _ensure_components_schemas(openapi_schema: dict[str, Any]) -> None:
+    """Ensure components.schemas exists in the schema."""
+    if "components" not in openapi_schema:
+        openapi_schema["components"] = {}
+    if "schemas" not in openapi_schema["components"]:
+        openapi_schema["components"]["schemas"] = {}
+
+
+def _load_extra_schema_modules() -> None:
+    """
+    Import modules outside llama_stack_api that use schema_utils to register schemas.
+
+    The API package already imports its submodules via __init__, but server-side modules
+    like telemetry need to be imported explicitly so their decorator side effects run.
+    """
+    extra_modules = [
+        "llama_stack.core.telemetry.telemetry",
+    ]
+    for module_name in extra_modules:
+        try:
+            importlib.import_module(module_name)
+        except ImportError:
+            continue
+
+
+def _extract_and_fix_defs(schema: dict[str, Any], openapi_schema: dict[str, Any]) -> None:
+    """
+    Extract $defs from a schema, move them to components/schemas, and fix references.
+    This handles both TypeAdapter-generated schemas and model_json_schema() schemas.
+    """
+    if "$defs" in schema:
+        defs = schema.pop("$defs")
+        for def_name, def_schema in defs.items():
+            if def_name not in openapi_schema["components"]["schemas"]:
+                openapi_schema["components"]["schemas"][def_name] = def_schema
+                # Recursively handle $defs in nested schemas
+                _extract_and_fix_defs(def_schema, openapi_schema)
+
+        # Fix any references in the main schema that point to $defs
+        def fix_refs_in_schema(obj: Any) -> None:
+            if isinstance(obj, dict):
+                if "$ref" in obj and obj["$ref"].startswith("#/$defs/"):
+                    obj["$ref"] = obj["$ref"].replace("#/$defs/", "#/components/schemas/")
+                for value in obj.values():
+                    fix_refs_in_schema(value)
+            elif isinstance(obj, list):
+                for item in obj:
+                    fix_refs_in_schema(item)
+
+        fix_refs_in_schema(schema)
+
+
+def _ensure_json_schema_types_included(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Ensure all registered schemas (decorated, explicit, and dynamic) are included in the OpenAPI schema.
+    Relies on llama_stack_api's registry instead of recursively importing every module.
+    """
+    _ensure_components_schemas(openapi_schema)
+
+    from pydantic import TypeAdapter
+
+    from llama_stack_api.schema_utils import (
+        iter_dynamic_schema_types,
+        iter_json_schema_types,
+        iter_registered_schema_types,
+    )
+
+    # Import extra modules (e.g., telemetry) whose schema registrations live outside llama_stack_api
+    _load_extra_schema_modules()
+
+    # Handle explicitly registered schemas first (union types, Annotated structs, etc.)
+    for registration_info in iter_registered_schema_types():
+        schema_type = registration_info.type
+        schema_name = registration_info.name
+        if schema_name not in openapi_schema["components"]["schemas"]:
+            try:
+                adapter = TypeAdapter(schema_type)
+                schema = adapter.json_schema(ref_template="#/components/schemas/{model}")
+                _extract_and_fix_defs(schema, openapi_schema)
+                openapi_schema["components"]["schemas"][schema_name] = schema
+            except Exception as e:
+                print(f"Warning: Failed to generate schema for registered type {schema_name}: {e}")
+                import traceback
+
+                traceback.print_exc()
+                continue
+
+    # Add @json_schema_type decorated models
+    for model in iter_json_schema_types():
+        schema_name = getattr(model, "_llama_stack_schema_name", None) or getattr(model, "__name__", None)
+        if not schema_name:
+            continue
+        if schema_name not in openapi_schema["components"]["schemas"]:
+            try:
+                if hasattr(model, "model_json_schema"):
+                    schema = model.model_json_schema(ref_template="#/components/schemas/{model}")
+                else:
+                    adapter = TypeAdapter(model)
+                    schema = adapter.json_schema(ref_template="#/components/schemas/{model}")
+                _extract_and_fix_defs(schema, openapi_schema)
+                openapi_schema["components"]["schemas"][schema_name] = schema
+            except Exception as e:
+                print(f"Warning: Failed to generate schema for {schema_name}: {e}")
+                continue
+
+    # Include any dynamic models generated while building endpoints
+    for model in iter_dynamic_schema_types():
+        try:
+            schema_name = model.__name__
+            if schema_name not in openapi_schema["components"]["schemas"]:
+                schema = model.model_json_schema(ref_template="#/components/schemas/{model}")
+                _extract_and_fix_defs(schema, openapi_schema)
+                openapi_schema["components"]["schemas"][schema_name] = schema
+        except Exception:
+            continue
+
+    return openapi_schema

scripts/openapi_generator/schema_filtering.py

@@ -0,0 +1,297 @@
+# 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.
+
+"""
+Schema filtering and version filtering for OpenAPI generation.
+"""
+
+from typing import Any
+
+from llama_stack_api.schema_utils import iter_json_schema_types, iter_registered_schema_types
+from llama_stack_api.version import (
+    LLAMA_STACK_API_V1,
+    LLAMA_STACK_API_V1ALPHA,
+    LLAMA_STACK_API_V1BETA,
+)
+
+
+def _get_all_json_schema_type_names() -> set[str]:
+    """Collect schema names from @json_schema_type-decorated models."""
+    schema_names = set()
+    for model in iter_json_schema_types():
+        schema_name = getattr(model, "_llama_stack_schema_name", None) or getattr(model, "__name__", None)
+        if schema_name:
+            schema_names.add(schema_name)
+    return schema_names
+
+
+def _get_explicit_schema_names(openapi_schema: dict[str, Any]) -> set[str]:
+    """Schema names to keep even if not referenced by a path."""
+    registered_schema_names = {info.name for info in iter_registered_schema_types()}
+    json_schema_type_names = _get_all_json_schema_type_names()
+    return registered_schema_names | json_schema_type_names
+
+
+def _find_schema_refs_in_object(obj: Any) -> set[str]:
+    """
+    Recursively find all schema references ($ref) in an object.
+    """
+    refs = set()
+
+    if isinstance(obj, dict):
+        for key, value in obj.items():
+            if key == "$ref" and isinstance(value, str) and value.startswith("#/components/schemas/"):
+                schema_name = value.split("/")[-1]
+                refs.add(schema_name)
+            else:
+                refs.update(_find_schema_refs_in_object(value))
+    elif isinstance(obj, list):
+        for item in obj:
+            refs.update(_find_schema_refs_in_object(item))
+
+    return refs
+
+
+def _add_transitive_references(
+    referenced_schemas: set[str], all_schemas: dict[str, Any], initial_schemas: set[str] | None = None
+) -> set[str]:
+    """Add transitive references for given schemas."""
+    if initial_schemas:
+        referenced_schemas.update(initial_schemas)
+        additional_schemas = set()
+        for schema_name in initial_schemas:
+            if schema_name in all_schemas:
+                additional_schemas.update(_find_schema_refs_in_object(all_schemas[schema_name]))
+    else:
+        additional_schemas = set()
+        for schema_name in referenced_schemas:
+            if schema_name in all_schemas:
+                additional_schemas.update(_find_schema_refs_in_object(all_schemas[schema_name]))
+
+    while additional_schemas:
+        new_schemas = additional_schemas - referenced_schemas
+        if not new_schemas:
+            break
+        referenced_schemas.update(new_schemas)
+        additional_schemas = set()
+        for schema_name in new_schemas:
+            if schema_name in all_schemas:
+                additional_schemas.update(_find_schema_refs_in_object(all_schemas[schema_name]))
+
+    return referenced_schemas
+
+
+def _find_schemas_referenced_by_paths(filtered_paths: dict[str, Any], openapi_schema: dict[str, Any]) -> set[str]:
+    """
+    Find all schemas that are referenced by the filtered paths.
+    This recursively traverses the path definitions to find all $ref references.
+    """
+    referenced_schemas = set()
+
+    # Traverse all filtered paths
+    for _, path_item in filtered_paths.items():
+        if not isinstance(path_item, dict):
+            continue
+
+        # Check each HTTP method in the path
+        for method in ["get", "post", "put", "delete", "patch", "head", "options"]:
+            if method in path_item:
+                operation = path_item[method]
+                if isinstance(operation, dict):
+                    # Find all schema references in this operation
+                    referenced_schemas.update(_find_schema_refs_in_object(operation))
+
+    # Also check the responses section for schema references
+    if "components" in openapi_schema and "responses" in openapi_schema["components"]:
+        referenced_schemas.update(_find_schema_refs_in_object(openapi_schema["components"]["responses"]))
+
+    # Also include schemas that are referenced by other schemas (transitive references)
+    # This ensures we include all dependencies
+    all_schemas = openapi_schema.get("components", {}).get("schemas", {})
+    additional_schemas = set()
+
+    for schema_name in referenced_schemas:
+        if schema_name in all_schemas:
+            additional_schemas.update(_find_schema_refs_in_object(all_schemas[schema_name]))
+
+    # Keep adding transitive references until no new ones are found
+    while additional_schemas:
+        new_schemas = additional_schemas - referenced_schemas
+        if not new_schemas:
+            break
+        referenced_schemas.update(new_schemas)
+        additional_schemas = set()
+        for schema_name in new_schemas:
+            if schema_name in all_schemas:
+                additional_schemas.update(_find_schema_refs_in_object(all_schemas[schema_name]))
+
+    return referenced_schemas
+
+
+def _filter_schemas_by_references(
+    filtered_schema: dict[str, Any], filtered_paths: dict[str, Any], openapi_schema: dict[str, Any]
+) -> dict[str, Any]:
+    """Filter schemas to only include ones referenced by filtered paths and explicit schemas."""
+    if "components" not in filtered_schema or "schemas" not in filtered_schema["components"]:
+        return filtered_schema
+
+    referenced_schemas = _find_schemas_referenced_by_paths(filtered_paths, openapi_schema)
+    all_schemas = openapi_schema.get("components", {}).get("schemas", {})
+    explicit_names = _get_explicit_schema_names(openapi_schema)
+    referenced_schemas = _add_transitive_references(referenced_schemas, all_schemas, explicit_names)
+
+    filtered_schemas = {
+        name: schema for name, schema in filtered_schema["components"]["schemas"].items() if name in referenced_schemas
+    }
+    filtered_schema["components"]["schemas"] = filtered_schemas
+
+    if "components" in openapi_schema and "$defs" in openapi_schema["components"]:
+        if "components" not in filtered_schema:
+            filtered_schema["components"] = {}
+        filtered_schema["components"]["$defs"] = openapi_schema["components"]["$defs"]
+
+    return filtered_schema
+
+
+def _path_starts_with_version(path: str, version: str) -> bool:
+    """Check if a path starts with a specific API version prefix."""
+    return path.startswith(f"/{version}/")
+
+
+def _is_stable_path(path: str) -> bool:
+    """Check if a path is a stable v1 path (not v1alpha or v1beta)."""
+    return (
+        _path_starts_with_version(path, LLAMA_STACK_API_V1)
+        and not _path_starts_with_version(path, LLAMA_STACK_API_V1ALPHA)
+        and not _path_starts_with_version(path, LLAMA_STACK_API_V1BETA)
+    )
+
+
+def _is_experimental_path(path: str) -> bool:
+    """Check if a path is an experimental path (v1alpha or v1beta)."""
+    return _path_starts_with_version(path, LLAMA_STACK_API_V1ALPHA) or _path_starts_with_version(
+        path, LLAMA_STACK_API_V1BETA
+    )
+
+
+def _is_path_deprecated(path_item: dict[str, Any]) -> bool:
+    """Check if a path item has any deprecated operations."""
+    if not isinstance(path_item, dict):
+        return False
+    for method in ["get", "post", "put", "delete", "patch", "head", "options"]:
+        if isinstance(path_item.get(method), dict) and path_item[method].get("deprecated", False):
+            return True
+    return False
+
+
+def _filter_schema_by_version(
+    openapi_schema: dict[str, Any], stable_only: bool = True, exclude_deprecated: bool = True
+) -> dict[str, Any]:
+    """
+    Filter OpenAPI schema by API version.
+
+    Args:
+        openapi_schema: The full OpenAPI schema
+        stable_only: If True, return only /v1/ paths (stable). If False, return only /v1alpha/ and /v1beta/ paths (experimental).
+        exclude_deprecated: If True, exclude deprecated endpoints from the result.
+
+    Returns:
+        Filtered OpenAPI schema
+    """
+    filtered_schema = openapi_schema.copy()
+
+    if "paths" not in filtered_schema:
+        return filtered_schema
+
+    filtered_paths = {}
+    for path, path_item in filtered_schema["paths"].items():
+        if not isinstance(path_item, dict):
+            continue
+
+        # Filter at operation level, not path level
+        # This allows paths with both deprecated and non-deprecated operations
+        filtered_path_item = {}
+        for method in ["get", "post", "put", "delete", "patch", "head", "options"]:
+            if method not in path_item:
+                continue
+            operation = path_item[method]
+            if not isinstance(operation, dict):
+                continue
+
+            # Skip deprecated operations if exclude_deprecated is True
+            if exclude_deprecated and operation.get("deprecated", False):
+                continue
+
+            filtered_path_item[method] = operation
+
+        # Only include path if it has at least one operation after filtering
+        if filtered_path_item:
+            # Check if path matches version filter
+            if (stable_only and _is_stable_path(path)) or (not stable_only and _is_experimental_path(path)):
+                filtered_paths[path] = filtered_path_item
+
+    filtered_schema["paths"] = filtered_paths
+    return _filter_schemas_by_references(filtered_schema, filtered_paths, openapi_schema)
+
+
+def _filter_deprecated_schema(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Filter OpenAPI schema to include only deprecated endpoints.
+    Includes all deprecated endpoints regardless of version (v1, v1alpha, v1beta).
+    """
+    filtered_schema = openapi_schema.copy()
+
+    if "paths" not in filtered_schema:
+        return filtered_schema
+
+    # Filter paths to only include deprecated ones
+    filtered_paths = {}
+    for path, path_item in filtered_schema["paths"].items():
+        if _is_path_deprecated(path_item):
+            filtered_paths[path] = path_item
+
+    filtered_schema["paths"] = filtered_paths
+
+    return filtered_schema
+
+
+def _filter_combined_schema(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Filter OpenAPI schema to include both stable (v1) and experimental (v1alpha, v1beta) APIs.
+    Includes deprecated endpoints. This is used for the combined "stainless" spec.
+    """
+    filtered_schema = openapi_schema.copy()
+
+    if "paths" not in filtered_schema:
+        return filtered_schema
+
+    # Filter paths to include stable (v1) and experimental (v1alpha, v1beta), excluding deprecated
+    filtered_paths = {}
+    for path, path_item in filtered_schema["paths"].items():
+        if not isinstance(path_item, dict):
+            continue
+
+        # Filter at operation level, not path level
+        # This allows paths with both deprecated and non-deprecated operations
+        filtered_path_item = {}
+        for method in ["get", "post", "put", "delete", "patch", "head", "options"]:
+            if method not in path_item:
+                continue
+            operation = path_item[method]
+            if not isinstance(operation, dict):
+                continue
+
+            filtered_path_item[method] = operation
+
+        # Only include path if it has at least one operation after filtering
+        if filtered_path_item:
+            # Check if path matches version filter (stable or experimental)
+            if _is_stable_path(path) or _is_experimental_path(path):
+                filtered_paths[path] = filtered_path_item
+
+    filtered_schema["paths"] = filtered_paths
+
+    return _filter_schemas_by_references(filtered_schema, filtered_paths, openapi_schema)

scripts/openapi_generator/schema_transforms.py

@@ -0,0 +1,963 @@
+# 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.
+
+"""
+Schema transformations and fixes for OpenAPI generation.
+"""
+
+import copy
+from collections import OrderedDict
+from pathlib import Path
+from typing import Any
+
+import yaml
+from openapi_spec_validator import validate_spec
+from openapi_spec_validator.exceptions import OpenAPISpecValidatorError
+
+from . import endpoints, schema_collection
+from ._legacy_order import (
+    LEGACY_OPERATION_KEYS,
+    LEGACY_PATH_ORDER,
+    LEGACY_RESPONSE_ORDER,
+    LEGACY_SCHEMA_ORDER,
+    LEGACY_SECURITY,
+    LEGACY_TAG_GROUPS,
+    LEGACY_TAGS,
+)
+from .state import _extra_body_fields
+
+
+def _fix_ref_references(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Fix $ref references to point to components/schemas instead of $defs.
+    This prevents the YAML dumper from creating a root-level $defs section.
+    """
+
+    def fix_refs(obj: Any) -> None:
+        if isinstance(obj, dict):
+            if "$ref" in obj and obj["$ref"].startswith("#/$defs/"):
+                # Replace #/$defs/ with #/components/schemas/
+                obj["$ref"] = obj["$ref"].replace("#/$defs/", "#/components/schemas/")
+            for value in obj.values():
+                fix_refs(value)
+        elif isinstance(obj, list):
+            for item in obj:
+                fix_refs(item)
+
+    fix_refs(openapi_schema)
+    return openapi_schema
+
+
+def _normalize_empty_responses(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """Convert empty 200 responses into 204 No Content."""
+
+    for path_item in openapi_schema.get("paths", {}).values():
+        if not isinstance(path_item, dict):
+            continue
+        for method in list(path_item.keys()):
+            operation = path_item.get(method)
+            if not isinstance(operation, dict):
+                continue
+            responses = operation.get("responses")
+            if not isinstance(responses, dict):
+                continue
+            response_200 = responses.get("200") or responses.get(200)
+            if response_200 is None:
+                continue
+            content = response_200.get("content")
+            if content and any(
+                isinstance(media, dict) and media.get("schema") not in ({}, None) for media in content.values()
+            ):
+                continue
+            responses.pop("200", None)
+            responses.pop(200, None)
+            responses["204"] = {"description": response_200.get("description", "No Content")}
+    return openapi_schema
+
+
+def _eliminate_defs_section(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Eliminate $defs section entirely by moving all definitions to components/schemas.
+    This matches the structure of the old pyopenapi generator for oasdiff compatibility.
+    """
+    schema_collection._ensure_components_schemas(openapi_schema)
+
+    # First pass: collect all $defs from anywhere in the schema
+    defs_to_move = {}
+
+    def collect_defs(obj: Any) -> None:
+        if isinstance(obj, dict):
+            if "$defs" in obj:
+                # Collect $defs for later processing
+                for def_name, def_schema in obj["$defs"].items():
+                    if def_name not in defs_to_move:
+                        defs_to_move[def_name] = def_schema
+
+            # Recursively process all values
+            for value in obj.values():
+                collect_defs(value)
+        elif isinstance(obj, list):
+            for item in obj:
+                collect_defs(item)
+
+    # Collect all $defs
+    collect_defs(openapi_schema)
+
+    # Move all $defs to components/schemas
+    for def_name, def_schema in defs_to_move.items():
+        if def_name not in openapi_schema["components"]["schemas"]:
+            openapi_schema["components"]["schemas"][def_name] = def_schema
+
+    # Also move any existing root-level $defs to components/schemas
+    if "$defs" in openapi_schema:
+        print(f"Found root-level $defs with {len(openapi_schema['$defs'])} items, moving to components/schemas")
+        for def_name, def_schema in openapi_schema["$defs"].items():
+            if def_name not in openapi_schema["components"]["schemas"]:
+                openapi_schema["components"]["schemas"][def_name] = def_schema
+        # Remove the root-level $defs
+        del openapi_schema["$defs"]
+
+    # Second pass: remove all $defs sections from anywhere in the schema
+    def remove_defs(obj: Any) -> None:
+        if isinstance(obj, dict):
+            if "$defs" in obj:
+                del obj["$defs"]
+
+            # Recursively process all values
+            for value in obj.values():
+                remove_defs(value)
+        elif isinstance(obj, list):
+            for item in obj:
+                remove_defs(item)
+
+    # Remove all $defs sections
+    remove_defs(openapi_schema)
+
+    return openapi_schema
+
+
+def _add_error_responses(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Add standard error response definitions to the OpenAPI schema.
+    Uses the actual Error model from the codebase for consistency.
+    """
+    if "components" not in openapi_schema:
+        openapi_schema["components"] = {}
+    if "responses" not in openapi_schema["components"]:
+        openapi_schema["components"]["responses"] = {}
+
+    try:
+        from llama_stack_api.datatypes import Error
+
+        schema_collection._ensure_components_schemas(openapi_schema)
+        if "Error" not in openapi_schema["components"]["schemas"]:
+            openapi_schema["components"]["schemas"]["Error"] = Error.model_json_schema()
+    except ImportError:
+        pass
+
+    schema_collection._ensure_components_schemas(openapi_schema)
+    if "Response" not in openapi_schema["components"]["schemas"]:
+        openapi_schema["components"]["schemas"]["Response"] = {"title": "Response", "type": "object"}
+
+    # Define standard HTTP error responses
+    error_responses = {
+        400: {
+            "name": "BadRequest400",
+            "description": "The request was invalid or malformed",
+            "example": {"status": 400, "title": "Bad Request", "detail": "The request was invalid or malformed"},
+        },
+        429: {
+            "name": "TooManyRequests429",
+            "description": "The client has sent too many requests in a given amount of time",
+            "example": {
+                "status": 429,
+                "title": "Too Many Requests",
+                "detail": "You have exceeded the rate limit. Please try again later.",
+            },
+        },
+        500: {
+            "name": "InternalServerError500",
+            "description": "The server encountered an unexpected error",
+            "example": {"status": 500, "title": "Internal Server Error", "detail": "An unexpected error occurred"},
+        },
+    }
+
+    # Add each error response to the schema
+    for _, error_info in error_responses.items():
+        response_name = error_info["name"]
+        openapi_schema["components"]["responses"][response_name] = {
+            "description": error_info["description"],
+            "content": {
+                "application/json": {"schema": {"$ref": "#/components/schemas/Error"}, "example": error_info["example"]}
+            },
+        }
+
+    # Add a default error response
+    openapi_schema["components"]["responses"]["DefaultError"] = {
+        "description": "An error occurred",
+        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}},
+    }
+
+    return openapi_schema
+
+
+def _fix_path_parameters(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Fix path parameter resolution issues by adding explicit parameter definitions.
+    """
+    if "paths" not in openapi_schema:
+        return openapi_schema
+
+    for path, path_item in openapi_schema["paths"].items():
+        # Extract path parameters from the URL
+        path_params = endpoints._extract_path_parameters(path)
+
+        if not path_params:
+            continue
+
+        # Add parameters to each operation in this path
+        for method in ["get", "post", "put", "delete", "patch", "head", "options"]:
+            if method in path_item and isinstance(path_item[method], dict):
+                operation = path_item[method]
+                if "parameters" not in operation:
+                    operation["parameters"] = []
+
+                # Add path parameters that aren't already defined
+                existing_param_names = {p.get("name") for p in operation["parameters"] if p.get("in") == "path"}
+                for param in path_params:
+                    if param["name"] not in existing_param_names:
+                        operation["parameters"].append(param)
+
+    return openapi_schema
+
+
+def _get_schema_title(item: dict[str, Any]) -> str | None:
+    """Extract a title for a schema item to use in union variant names."""
+    if "$ref" in item:
+        return item["$ref"].split("/")[-1]
+    elif "type" in item:
+        type_val = item["type"]
+        if type_val == "null":
+            return None
+        if type_val == "array" and "items" in item:
+            items = item["items"]
+            if isinstance(items, dict):
+                if "anyOf" in items or "oneOf" in items:
+                    nested_union = items.get("anyOf") or items.get("oneOf")
+                    if isinstance(nested_union, list) and len(nested_union) > 0:
+                        nested_types = []
+                        for nested_item in nested_union:
+                            if isinstance(nested_item, dict):
+                                if "$ref" in nested_item:
+                                    nested_types.append(nested_item["$ref"].split("/")[-1])
+                                elif "oneOf" in nested_item:
+                                    one_of_items = nested_item.get("oneOf", [])
+                                    if one_of_items and isinstance(one_of_items[0], dict) and "$ref" in one_of_items[0]:
+                                        base_name = one_of_items[0]["$ref"].split("/")[-1].split("-")[0]
+                                        nested_types.append(f"{base_name}Union")
+                                    else:
+                                        nested_types.append("Union")
+                                elif "type" in nested_item and nested_item["type"] != "null":
+                                    nested_types.append(nested_item["type"])
+                        if nested_types:
+                            unique_nested = list(dict.fromkeys(nested_types))
+                            # Use more descriptive names for better code generation
+                            if len(unique_nested) <= 3:
+                                return f"list[{' | '.join(unique_nested)}]"
+                            else:
+                                # Include first few types for better naming
+                                return f"list[{unique_nested[0]} | {unique_nested[1]} | ...]"
+                        return "list[Union]"
+                elif "$ref" in items:
+                    return f"list[{items['$ref'].split('/')[-1]}]"
+                elif "type" in items:
+                    return f"list[{items['type']}]"
+            return "array"
+        return type_val
+    elif "title" in item:
+        return item["title"]
+    return None
+
+
+def _add_titles_to_unions(obj: Any, parent_key: str | None = None) -> None:
+    """Recursively add titles to union schemas (anyOf/oneOf) to help code generators infer names."""
+    if isinstance(obj, dict):
+        # Check if this is a union schema (anyOf or oneOf)
+        if "anyOf" in obj or "oneOf" in obj:
+            union_type = "anyOf" if "anyOf" in obj else "oneOf"
+            union_items = obj[union_type]
+
+            if isinstance(union_items, list) and len(union_items) > 0:
+                # Skip simple nullable unions (type | null) - these don't need titles
+                is_simple_nullable = (
+                    len(union_items) == 2
+                    and any(isinstance(item, dict) and item.get("type") == "null" for item in union_items)
+                    and any(
+                        isinstance(item, dict) and "type" in item and item.get("type") != "null" for item in union_items
+                    )
+                    and not any(
+                        isinstance(item, dict) and ("$ref" in item or "anyOf" in item or "oneOf" in item)
+                        for item in union_items
+                    )
+                )
+
+                if is_simple_nullable:
+                    # Remove title from simple nullable unions if it exists
+                    if "title" in obj:
+                        del obj["title"]
+                else:
+                    # Add titles to individual union variants that need them
+                    for item in union_items:
+                        if isinstance(item, dict):
+                            # Skip null types
+                            if item.get("type") == "null":
+                                continue
+                            # Add title to complex variants (arrays with unions, nested unions, etc.)
+                            # Also add to simple types if they're part of a complex union
+                            needs_title = (
+                                "items" in item
+                                or "anyOf" in item
+                                or "oneOf" in item
+                                or ("$ref" in item and "title" not in item)
+                            )
+                            if needs_title and "title" not in item:
+                                variant_title = _get_schema_title(item)
+                                if variant_title:
+                                    item["title"] = variant_title
+
+                    # Try to infer a meaningful title from the union items for the parent
+                    titles = []
+                    for item in union_items:
+                        if isinstance(item, dict):
+                            title = _get_schema_title(item)
+                            if title:
+                                titles.append(title)
+
+                    if titles:
+                        # Create a title from the union items
+                        unique_titles = list(dict.fromkeys(titles))  # Preserve order, remove duplicates
+                        if len(unique_titles) <= 3:
+                            title = " | ".join(unique_titles)
+                        else:
+                            title = f"{unique_titles[0]} | ... ({len(unique_titles)} variants)"
+                        # Always set the title for unions to help code generators
+                        # This will replace generic property titles with union-specific ones
+                        obj["title"] = title
+                    elif "title" not in obj and parent_key:
+                        # Use parent key as fallback only if no title exists
+                        obj["title"] = f"{parent_key.title()}Union"
+
+        # Recursively process all values
+        for key, value in obj.items():
+            _add_titles_to_unions(value, key)
+    elif isinstance(obj, list):
+        for item in obj:
+            _add_titles_to_unions(item, parent_key)
+
+
+def _convert_anyof_const_to_enum(obj: Any) -> None:
+    """Convert anyOf with multiple const string values to a proper enum."""
+    if isinstance(obj, dict):
+        if "anyOf" in obj:
+            any_of = obj["anyOf"]
+            if isinstance(any_of, list):
+                # Check if all items are const string values
+                const_values = []
+                has_null = False
+                can_convert = True
+                for item in any_of:
+                    if isinstance(item, dict):
+                        if item.get("type") == "null":
+                            has_null = True
+                        elif item.get("type") == "string" and "const" in item:
+                            const_values.append(item["const"])
+                        else:
+                            # Not a simple const pattern, skip conversion for this anyOf
+                            can_convert = False
+                            break
+
+                # If we have const values and they're all strings, convert to enum
+                if can_convert and const_values and len(const_values) == len(any_of) - (1 if has_null else 0):
+                    # Convert to enum
+                    obj["type"] = "string"
+                    obj["enum"] = const_values
+                    # Preserve default if present, otherwise try to get from first const item
+                    if "default" not in obj:
+                        for item in any_of:
+                            if isinstance(item, dict) and "const" in item:
+                                obj["default"] = item["const"]
+                                break
+                    # Remove anyOf
+                    del obj["anyOf"]
+                    # Handle nullable
+                    if has_null:
+                        obj["nullable"] = True
+                    # Remove title if it's just "string"
+                    if obj.get("title") == "string":
+                        del obj["title"]
+
+        # Recursively process all values
+        for value in obj.values():
+            _convert_anyof_const_to_enum(value)
+    elif isinstance(obj, list):
+        for item in obj:
+            _convert_anyof_const_to_enum(item)
+
+
+def _fix_schema_recursive(obj: Any) -> None:
+    """Recursively fix schema issues: exclusiveMinimum and null defaults."""
+    if isinstance(obj, dict):
+        if "exclusiveMinimum" in obj and isinstance(obj["exclusiveMinimum"], int | float):
+            obj["minimum"] = obj.pop("exclusiveMinimum")
+        if "default" in obj and obj["default"] is None:
+            del obj["default"]
+            obj["nullable"] = True
+        for value in obj.values():
+            _fix_schema_recursive(value)
+    elif isinstance(obj, list):
+        for item in obj:
+            _fix_schema_recursive(item)
+
+
+def _clean_description(description: str) -> str:
+    """Remove :param, :type, :returns, and other docstring metadata from description."""
+    if not description:
+        return description
+
+    lines = description.split("\n")
+    cleaned_lines = []
+    skip_until_empty = False
+
+    for line in lines:
+        stripped = line.strip()
+        # Skip lines that start with docstring metadata markers
+        if stripped.startswith(
+            (":param", ":type", ":return", ":returns", ":raises", ":exception", ":yield", ":yields", ":cvar")
+        ):
+            skip_until_empty = True
+            continue
+        # If we're skipping and hit an empty line, resume normal processing
+        if skip_until_empty:
+            if not stripped:
+                skip_until_empty = False
+            continue
+        # Include the line if we're not skipping
+        cleaned_lines.append(line)
+
+    # Join and strip trailing whitespace
+    result = "\n".join(cleaned_lines).strip()
+    return result
+
+
+def _clean_schema_descriptions(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """Clean descriptions in schema definitions by removing docstring metadata."""
+    if "components" not in openapi_schema or "schemas" not in openapi_schema["components"]:
+        return openapi_schema
+
+    schemas = openapi_schema["components"]["schemas"]
+    for schema_def in schemas.values():
+        if isinstance(schema_def, dict) and "description" in schema_def and isinstance(schema_def["description"], str):
+            schema_def["description"] = _clean_description(schema_def["description"])
+
+    return openapi_schema
+
+
+def _add_extra_body_params_extension(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Add x-llama-stack-extra-body-params extension to requestBody for endpoints with ExtraBodyField parameters.
+    """
+    if "paths" not in openapi_schema:
+        return openapi_schema
+
+    from pydantic import TypeAdapter
+
+    for path, path_item in openapi_schema["paths"].items():
+        if not isinstance(path_item, dict):
+            continue
+
+        for method in ["get", "post", "put", "delete", "patch", "head", "options"]:
+            if method not in path_item:
+                continue
+
+            operation = path_item[method]
+            if not isinstance(operation, dict):
+                continue
+
+            # Check if we have extra body fields for this path/method
+            key = (path, method.upper())
+            if key not in _extra_body_fields:
+                continue
+
+            extra_body_params = _extra_body_fields[key]
+
+            # Ensure requestBody exists
+            if "requestBody" not in operation:
+                continue
+
+            request_body = operation["requestBody"]
+            if not isinstance(request_body, dict):
+                continue
+
+            # Get the schema from requestBody
+            content = request_body.get("content", {})
+            json_content = content.get("application/json", {})
+            schema_ref = json_content.get("schema", {})
+
+            # Remove extra body fields from the schema if they exist as properties
+            # Handle both $ref schemas and inline schemas
+            if isinstance(schema_ref, dict):
+                if "$ref" in schema_ref:
+                    # Schema is a reference - remove from the referenced schema
+                    ref_path = schema_ref["$ref"]
+                    if ref_path.startswith("#/components/schemas/"):
+                        schema_name = ref_path.split("/")[-1]
+                        if "components" in openapi_schema and "schemas" in openapi_schema["components"]:
+                            schema_def = openapi_schema["components"]["schemas"].get(schema_name)
+                            if isinstance(schema_def, dict) and "properties" in schema_def:
+                                for param_name, _, _ in extra_body_params:
+                                    if param_name in schema_def["properties"]:
+                                        del schema_def["properties"][param_name]
+                                        # Also remove from required if present
+                                        if "required" in schema_def and param_name in schema_def["required"]:
+                                            schema_def["required"].remove(param_name)
+                elif "properties" in schema_ref:
+                    # Schema is inline - remove directly from it
+                    for param_name, _, _ in extra_body_params:
+                        if param_name in schema_ref["properties"]:
+                            del schema_ref["properties"][param_name]
+                            # Also remove from required if present
+                            if "required" in schema_ref and param_name in schema_ref["required"]:
+                                schema_ref["required"].remove(param_name)
+
+            # Build the extra body params schema
+            extra_params_schema = {}
+            for param_name, param_type, description in extra_body_params:
+                try:
+                    # Generate JSON schema for the parameter type
+                    adapter = TypeAdapter(param_type)
+                    param_schema = adapter.json_schema(ref_template="#/components/schemas/{model}")
+
+                    # Add description if provided
+                    if description:
+                        param_schema["description"] = description
+
+                    extra_params_schema[param_name] = param_schema
+                except Exception:
+                    # If we can't generate schema, skip this parameter
+                    continue
+
+            if extra_params_schema:
+                # Add the extension to requestBody
+                if "x-llama-stack-extra-body-params" not in request_body:
+                    request_body["x-llama-stack-extra-body-params"] = extra_params_schema
+
+    return openapi_schema
+
+
+def _remove_query_params_from_body_endpoints(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Remove query parameters from POST/PUT/PATCH endpoints that have a request body.
+    FastAPI sometimes infers parameters as query params even when they should be in the request body.
+    """
+    if "paths" not in openapi_schema:
+        return openapi_schema
+
+    body_methods = {"post", "put", "patch"}
+
+    for _path, path_item in openapi_schema["paths"].items():
+        if not isinstance(path_item, dict):
+            continue
+
+        for method in body_methods:
+            if method not in path_item:
+                continue
+
+            operation = path_item[method]
+            if not isinstance(operation, dict):
+                continue
+
+            # Check if this operation has a request body
+            has_request_body = "requestBody" in operation and operation["requestBody"]
+
+            if has_request_body:
+                # Remove all query parameters (parameters with "in": "query")
+                if "parameters" in operation:
+                    # Filter out query parameters, keep path and header parameters
+                    operation["parameters"] = [
+                        param
+                        for param in operation["parameters"]
+                        if isinstance(param, dict) and param.get("in") != "query"
+                    ]
+                    # Remove the parameters key if it's now empty
+                    if not operation["parameters"]:
+                        del operation["parameters"]
+
+    return openapi_schema
+
+
+def _remove_request_bodies_from_get_endpoints(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Remove request bodies from GET endpoints and convert their parameters to query parameters.
+
+    GET requests should never have request bodies - all parameters should be query parameters.
+    This function removes any requestBody that FastAPI may have incorrectly added to GET endpoints
+    and converts any parameters in the requestBody to query parameters.
+    """
+    if "paths" not in openapi_schema:
+        return openapi_schema
+
+    for _path, path_item in openapi_schema["paths"].items():
+        if not isinstance(path_item, dict):
+            continue
+
+        # Check GET method specifically
+        if "get" in path_item:
+            operation = path_item["get"]
+            if not isinstance(operation, dict):
+                continue
+
+            if "requestBody" in operation:
+                request_body = operation["requestBody"]
+                # Extract parameters from requestBody and convert to query parameters
+                if isinstance(request_body, dict) and "content" in request_body:
+                    content = request_body.get("content", {})
+                    json_content = content.get("application/json", {})
+                    schema = json_content.get("schema", {})
+
+                    if "parameters" not in operation:
+                        operation["parameters"] = []
+                    elif not isinstance(operation["parameters"], list):
+                        operation["parameters"] = []
+
+                    # If the schema has properties, convert each to a query parameter
+                    if isinstance(schema, dict) and "properties" in schema:
+                        for param_name, param_schema in schema["properties"].items():
+                            # Check if this parameter is already in the parameters list
+                            existing_param = None
+                            for existing in operation["parameters"]:
+                                if isinstance(existing, dict) and existing.get("name") == param_name:
+                                    existing_param = existing
+                                    break
+
+                            if not existing_param:
+                                # Create a new query parameter from the requestBody property
+                                required = param_name in schema.get("required", [])
+                                query_param = {
+                                    "name": param_name,
+                                    "in": "query",
+                                    "required": required,
+                                    "schema": param_schema,
+                                }
+                                # Add description if present
+                                if "description" in param_schema:
+                                    query_param["description"] = param_schema["description"]
+                                operation["parameters"].append(query_param)
+                    elif isinstance(schema, dict):
+                        # Handle direct schema (not a model with properties)
+                        # Try to infer parameter name from schema title
+                        param_name = schema.get("title", "").lower().replace(" ", "_")
+                        if param_name:
+                            # Check if this parameter is already in the parameters list
+                            existing_param = None
+                            for existing in operation["parameters"]:
+                                if isinstance(existing, dict) and existing.get("name") == param_name:
+                                    existing_param = existing
+                                    break
+
+                            if not existing_param:
+                                # Create a new query parameter from the requestBody schema
+                                query_param = {
+                                    "name": param_name,
+                                    "in": "query",
+                                    "required": False,  # Default to optional for GET requests
+                                    "schema": schema,
+                                }
+                                # Add description if present
+                                if "description" in schema:
+                                    query_param["description"] = schema["description"]
+                                operation["parameters"].append(query_param)
+
+                # Remove request body from GET endpoint
+                del operation["requestBody"]
+
+    return openapi_schema
+
+
+def _extract_duplicate_union_types(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Extract duplicate union types to shared schema references.
+
+    Stainless generates type names from union types based on their context, which can cause
+    duplicate names when the same union appears in different places. This function extracts
+    these duplicate unions to shared schema definitions and replaces inline definitions with
+    references to them.
+
+    According to Stainless docs, when duplicate types are detected, they should be extracted
+    to the same ref and declared as a model. This ensures Stainless generates consistent
+    type names regardless of where the union is referenced.
+
+    Fixes: https://www.stainless.com/docs/reference/diagnostics#Python/DuplicateDeclaration
+    """
+    if "components" not in openapi_schema or "schemas" not in openapi_schema["components"]:
+        return openapi_schema
+
+    schemas = openapi_schema["components"]["schemas"]
+
+    # Extract the Output union type (used in OpenAIResponseObjectWithInput-Output and ListOpenAIResponseInputItem)
+    output_union_schema_name = "OpenAIResponseMessageOutputUnion"
+    output_union_title = None
+
+    # Get the union type from OpenAIResponseObjectWithInput-Output.input.items.anyOf
+    if "OpenAIResponseObjectWithInput-Output" in schemas:
+        schema = schemas["OpenAIResponseObjectWithInput-Output"]
+        if isinstance(schema, dict) and "properties" in schema:
+            input_prop = schema["properties"].get("input")
+            if isinstance(input_prop, dict) and "items" in input_prop:
+                items = input_prop["items"]
+                if isinstance(items, dict) and "anyOf" in items:
+                    # Extract the union schema with deep copy
+                    output_union_schema = copy.deepcopy(items["anyOf"])
+                    output_union_title = items.get("title", "OpenAIResponseMessageOutputUnion")
+
+                    # Collect all refs from the oneOf to detect duplicates
+                    refs_in_oneof = set()
+                    for item in output_union_schema:
+                        if isinstance(item, dict) and "oneOf" in item:
+                            oneof = item["oneOf"]
+                            if isinstance(oneof, list):
+                                for variant in oneof:
+                                    if isinstance(variant, dict) and "$ref" in variant:
+                                        refs_in_oneof.add(variant["$ref"])
+                            item["x-stainless-naming"] = "OpenAIResponseMessageOutputOneOf"
+
+                    # Remove duplicate refs from anyOf that are already in oneOf
+                    deduplicated_schema = []
+                    for item in output_union_schema:
+                        if isinstance(item, dict) and "$ref" in item:
+                            if item["$ref"] not in refs_in_oneof:
+                                deduplicated_schema.append(item)
+                        else:
+                            deduplicated_schema.append(item)
+                    output_union_schema = deduplicated_schema
+
+                    # Create the shared schema with x-stainless-naming to ensure consistent naming
+                    if output_union_schema_name not in schemas:
+                        schemas[output_union_schema_name] = {
+                            "anyOf": output_union_schema,
+                            "title": output_union_title,
+                            "x-stainless-naming": output_union_schema_name,
+                        }
+                    # Replace with reference
+                    input_prop["items"] = {"$ref": f"#/components/schemas/{output_union_schema_name}"}
+
+    # Replace the same union in ListOpenAIResponseInputItem.data.items.anyOf
+    if "ListOpenAIResponseInputItem" in schemas and output_union_schema_name in schemas:
+        schema = schemas["ListOpenAIResponseInputItem"]
+        if isinstance(schema, dict) and "properties" in schema:
+            data_prop = schema["properties"].get("data")
+            if isinstance(data_prop, dict) and "items" in data_prop:
+                items = data_prop["items"]
+                if isinstance(items, dict) and "anyOf" in items:
+                    # Replace with reference
+                    data_prop["items"] = {"$ref": f"#/components/schemas/{output_union_schema_name}"}
+
+    # Extract the Input union type (used in _responses_Request.input.anyOf[1].items.anyOf)
+    input_union_schema_name = "OpenAIResponseMessageInputUnion"
+
+    if "_responses_Request" in schemas:
+        schema = schemas["_responses_Request"]
+        if isinstance(schema, dict) and "properties" in schema:
+            input_prop = schema["properties"].get("input")
+            if isinstance(input_prop, dict) and "anyOf" in input_prop:
+                any_of = input_prop["anyOf"]
+                if isinstance(any_of, list) and len(any_of) > 1:
+                    # Check the second item (index 1) which should be the array type
+                    second_item = any_of[1]
+                    if isinstance(second_item, dict) and "items" in second_item:
+                        items = second_item["items"]
+                        if isinstance(items, dict) and "anyOf" in items:
+                            # Extract the union schema with deep copy
+                            input_union_schema = copy.deepcopy(items["anyOf"])
+                            input_union_title = items.get("title", "OpenAIResponseMessageInputUnion")
+
+                            # Collect all refs from the oneOf to detect duplicates
+                            refs_in_oneof = set()
+                            for item in input_union_schema:
+                                if isinstance(item, dict) and "oneOf" in item:
+                                    oneof = item["oneOf"]
+                                    if isinstance(oneof, list):
+                                        for variant in oneof:
+                                            if isinstance(variant, dict) and "$ref" in variant:
+                                                refs_in_oneof.add(variant["$ref"])
+                                    item["x-stainless-naming"] = "OpenAIResponseMessageInputOneOf"
+
+                            # Remove duplicate refs from anyOf that are already in oneOf
+                            deduplicated_schema = []
+                            for item in input_union_schema:
+                                if isinstance(item, dict) and "$ref" in item:
+                                    if item["$ref"] not in refs_in_oneof:
+                                        deduplicated_schema.append(item)
+                                else:
+                                    deduplicated_schema.append(item)
+                            input_union_schema = deduplicated_schema
+
+                            # Create the shared schema with x-stainless-naming to ensure consistent naming
+                            if input_union_schema_name not in schemas:
+                                schemas[input_union_schema_name] = {
+                                    "anyOf": input_union_schema,
+                                    "title": input_union_title,
+                                    "x-stainless-naming": input_union_schema_name,
+                                }
+                            # Replace with reference
+                            second_item["items"] = {"$ref": f"#/components/schemas/{input_union_schema_name}"}
+
+    return openapi_schema
+
+
+def _convert_multiline_strings_to_literal(obj: Any) -> Any:
+    """Recursively convert multi-line strings to LiteralScalarString for YAML block scalar formatting."""
+    try:
+        from ruamel.yaml.scalarstring import LiteralScalarString
+
+        if isinstance(obj, str) and "\n" in obj:
+            return LiteralScalarString(obj)
+        elif isinstance(obj, dict):
+            return {key: _convert_multiline_strings_to_literal(value) for key, value in obj.items()}
+        elif isinstance(obj, list):
+            return [_convert_multiline_strings_to_literal(item) for item in obj]
+        else:
+            return obj
+    except ImportError:
+        return obj
+
+
+def _write_yaml_file(file_path: Path, schema: dict[str, Any]) -> None:
+    """Write schema to YAML file using ruamel.yaml if available, otherwise standard yaml."""
+    try:
+        from ruamel.yaml import YAML
+
+        yaml_writer = YAML()
+        yaml_writer.default_flow_style = False
+        yaml_writer.sort_keys = False
+        yaml_writer.width = 4096
+        yaml_writer.allow_unicode = True
+        schema = _convert_multiline_strings_to_literal(schema)
+        with open(file_path, "w") as f:
+            yaml_writer.dump(schema, f)
+    except ImportError:
+        with open(file_path, "w") as f:
+            yaml.dump(schema, f, default_flow_style=False, sort_keys=False)
+
+    # Post-process to remove trailing whitespace from all lines
+    with open(file_path) as f:
+        lines = f.readlines()
+
+    # Strip trailing whitespace from each line, preserving newlines
+    cleaned_lines = [line.rstrip() + "\n" if line.endswith("\n") else line.rstrip() for line in lines]
+
+    with open(file_path, "w") as f:
+        f.writelines(cleaned_lines)
+
+
+def _apply_legacy_sorting(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """
+    Temporarily match the legacy ordering from origin/main so diffs are easier to read.
+    Remove this once the generator output stabilizes and we no longer need legacy diffs.
+    """
+
+    def order_mapping(data: dict[str, Any], priority: list[str]) -> OrderedDict[str, Any]:
+        ordered: OrderedDict[str, Any] = OrderedDict()
+        for key in priority:
+            if key in data:
+                ordered[key] = data[key]
+        for key, value in data.items():
+            if key not in ordered:
+                ordered[key] = value
+        return ordered
+
+    paths = openapi_schema.get("paths")
+    if isinstance(paths, dict):
+        openapi_schema["paths"] = order_mapping(paths, LEGACY_PATH_ORDER)
+        for path, path_item in openapi_schema["paths"].items():
+            if not isinstance(path_item, dict):
+                continue
+            ordered_path_item = OrderedDict()
+            for method in ["get", "post", "put", "delete", "patch", "head", "options"]:
+                if method in path_item:
+                    ordered_path_item[method] = order_mapping(path_item[method], LEGACY_OPERATION_KEYS)
+            for key, value in path_item.items():
+                if key not in ordered_path_item:
+                    if isinstance(value, dict) and key.lower() in {
+                        "get",
+                        "post",
+                        "put",
+                        "delete",
+                        "patch",
+                        "head",
+                        "options",
+                    }:
+                        ordered_path_item[key] = order_mapping(value, LEGACY_OPERATION_KEYS)
+                    else:
+                        ordered_path_item[key] = value
+            openapi_schema["paths"][path] = ordered_path_item
+
+    components = openapi_schema.setdefault("components", {})
+    schemas = components.get("schemas")
+    if isinstance(schemas, dict):
+        components["schemas"] = order_mapping(schemas, LEGACY_SCHEMA_ORDER)
+    responses = components.get("responses")
+    if isinstance(responses, dict):
+        components["responses"] = order_mapping(responses, LEGACY_RESPONSE_ORDER)
+
+    if LEGACY_TAGS:
+        openapi_schema["tags"] = LEGACY_TAGS
+
+    if LEGACY_TAG_GROUPS:
+        openapi_schema["x-tagGroups"] = LEGACY_TAG_GROUPS
+
+    if LEGACY_SECURITY:
+        openapi_schema["security"] = LEGACY_SECURITY
+
+    return openapi_schema
+
+
+def _fix_schema_issues(openapi_schema: dict[str, Any]) -> dict[str, Any]:
+    """Fix common schema issues: exclusiveMinimum, null defaults, and add titles to unions."""
+    # Convert anyOf with const values to enums across the entire schema
+    _convert_anyof_const_to_enum(openapi_schema)
+
+    # Fix other schema issues and add titles to unions
+    if "components" in openapi_schema and "schemas" in openapi_schema["components"]:
+        for schema_name, schema_def in openapi_schema["components"]["schemas"].items():
+            _fix_schema_recursive(schema_def)
+            _add_titles_to_unions(schema_def, schema_name)
+    return openapi_schema
+
+
+def validate_openapi_schema(schema: dict[str, Any], schema_name: str = "OpenAPI schema") -> bool:
+    """
+    Validate an OpenAPI schema using openapi-spec-validator.
+
+    Args:
+        schema: The OpenAPI schema dictionary to validate
+        schema_name: Name of the schema for error reporting
+
+    Returns:
+        True if valid, False otherwise
+
+    Raises:
+        OpenAPIValidationError: If validation fails
+    """
+    try:
+        validate_spec(schema)
+        print(f"{schema_name} is valid")
+        return True
+    except OpenAPISpecValidatorError as e:
+        print(f"{schema_name} validation failed: {e}")
+        return False
+    except Exception as e:
+        print(f"{schema_name} validation error: {e}")
+        return False

scripts/openapi_generator/state.py

@@ -0,0 +1,41 @@
+# 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.
+
+"""
+Shared state for the OpenAPI generator module.
+"""
+
+from typing import Any
+
+from llama_stack_api import Api
+from llama_stack_api.schema_utils import clear_dynamic_schema_types, register_dynamic_schema_type
+
+_dynamic_model_registry: dict[str, type] = {}
+
+# Cache for protocol methods to avoid repeated lookups
+_protocol_methods_cache: dict[Api, dict[str, Any]] | None = None
+
+# Global dict to store extra body field information by endpoint
+# Key: (path, method) tuple, Value: list of (param_name, param_type, description) tuples
+_extra_body_fields: dict[tuple[str, str], list[tuple[str, type, str | None]]] = {}
+
+
+def register_dynamic_model(name: str, model: type) -> type:
+    """Register and deduplicate dynamically generated request models."""
+    existing = _dynamic_model_registry.get(name)
+    if existing is not None:
+        register_dynamic_schema_type(existing)
+        return existing
+    _dynamic_model_registry[name] = model
+    register_dynamic_schema_type(model)
+    return model
+
+
+def reset_generator_state() -> None:
+    """Clear per-run caches so repeated generations stay deterministic."""
+    _dynamic_model_registry.clear()
+    _extra_body_fields.clear()
+    clear_dynamic_schema_types()

scripts/run_openapi_generator.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+# 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.
+
+PYTHONPATH=${PYTHONPATH:-}
+THIS_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+
+set -euo pipefail
+
+
+stack_dir=$(dirname "$THIS_DIR")
+PYTHONPATH=$PYTHONPATH:$stack_dir \
+  python3 -m scripts.openapi_generator "$stack_dir"/docs/static
+
+cp "$stack_dir"/docs/static/stainless-llama-stack-spec.yaml "$stack_dir"/client-sdks/stainless/openapi.yml

src/llama_stack/core/library_client.py

@@ -19,7 +19,7 @@ import httpx
 import yaml
 from fastapi import Response as FastAPIResponse
 
-from llama_stack_api import is_unwrapped_body_param
+from llama_stack.core.utils.type_inspection import is_unwrapped_body_param
 
 try:
     from llama_stack_client import (
@@ -42,17 +42,10 @@ from termcolor import cprint
 from llama_stack.core.build import print_pip_install_help
 from llama_stack.core.configure import parse_and_maybe_upgrade_config
 from llama_stack.core.datatypes import BuildConfig, BuildProvider, DistributionSpec
-from llama_stack.core.request_headers import (
+from llama_stack.core.request_headers import PROVIDER_DATA_VAR, request_provider_data_context
-    PROVIDER_DATA_VAR,
-    request_provider_data_context,
-)
 from llama_stack.core.resolver import ProviderRegistry
 from llama_stack.core.server.routes import RouteImpls, find_matching_route, initialize_route_impls
-from llama_stack.core.stack import (
+from llama_stack.core.stack import Stack, get_stack_run_config_from_distro, replace_env_vars
-    Stack,
-    get_stack_run_config_from_distro,
-    replace_env_vars,
-)
 from llama_stack.core.telemetry import Telemetry
 from llama_stack.core.telemetry.tracing import CURRENT_TRACE_CONTEXT, end_trace, setup_logger, start_trace
 from llama_stack.core.utils.config import redact_sensitive_fields

src/llama_stack/core/utils/type_inspection.py

@@ -0,0 +1,45 @@
+# 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.
+
+"""
+Utility functions for type inspection and parameter handling.
+"""
+
+import inspect
+import typing
+from typing import Any, get_args, get_origin
+
+from pydantic import BaseModel
+from pydantic.fields import FieldInfo
+
+
+def is_unwrapped_body_param(param_type: Any) -> bool:
+    """
+    Check if a parameter type represents an unwrapped body parameter.
+    An unwrapped body parameter is an Annotated type with Body(embed=False)
+
+    This is used to determine whether request parameters should be flattened
+    in OpenAPI specs and client libraries (matching FastAPI's embed=False behavior).
+
+    Args:
+        param_type: The parameter type annotation to check
+
+    Returns:
+        True if the parameter should be treated as an unwrapped body parameter
+    """
+    # Check if it's Annotated with Body(embed=False)
+    if get_origin(param_type) is typing.Annotated:
+        args = get_args(param_type)
+        base_type = args[0]
+        metadata = args[1:]
+
+        # Look for Body annotation with embed=False
+        # Body() returns a FieldInfo object, so we check for that type and the embed attribute
+        for item in metadata:
+            if isinstance(item, FieldInfo) and hasattr(item, "embed") and not item.embed:
+                return inspect.isclass(base_type) and issubclass(base_type, BaseModel)
+
+    return False

src/llama_stack_api/__init__.py

@@ -353,8 +353,15 @@ from .safety import (
 from .schema_utils import (
     CallableT,
     ExtraBodyField,
+    SchemaInfo,
     WebMethod,
+    clear_dynamic_schema_types,
+    get_registered_schema_info,
+    iter_dynamic_schema_types,
+    iter_json_schema_types,
+    iter_registered_schema_types,
     json_schema_type,
+    register_dynamic_schema_type,
     register_schema,
     webmethod,
 )
@@ -388,27 +395,6 @@ from .shields import (
 )
 
 # 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,
@@ -537,6 +523,7 @@ __all__ = [
     "ExtraBodyField",
     "Files",
     "Fp8QuantizationConfig",
+    "clear_dynamic_schema_types",
     "get_schema_identifier",
     "get_signature",
     "GrammarResponseFormat",
@@ -557,6 +544,10 @@ __all__ = [
     "is_type_optional",
     "is_type_union",
     "is_unwrapped_body_param",
+    "iter_dynamic_schema_types",
+    "iter_json_schema_types",
+    "iter_registered_schema_types",
+    "get_registered_schema_info",
     "Job",
     "JobStatus",
     "json_dump_string",
@@ -759,6 +750,7 @@ __all__ = [
     "RAGQueryGeneratorConfig",
     "RAGQueryResult",
     "RAGSearchMode",
+    "register_dynamic_schema_type",
     "register_schema",
     "RLHFAlgorithm",
     "RRFRanker",
@@ -796,6 +788,7 @@ __all__ = [
     "ScoringResult",
     "ScoringResultRow",
     "Schema",
+    "SchemaInfo",
     "SchemaOptions",
     "SearchRankingOptions",
     "Shield",

src/llama_stack_api/benchmarks.py

@@ -48,6 +48,7 @@ class BenchmarkInput(CommonBenchmarkFields, BaseModel):
     provider_benchmark_id: str | None = None
 
 
+@json_schema_type
 class ListBenchmarksResponse(BaseModel):
     data: list[Benchmark]
 

src/llama_stack_api/datasets.py

@@ -136,6 +136,7 @@ class DatasetInput(CommonDatasetFields, BaseModel):
     dataset_id: str
 
 
+@json_schema_type
 class ListDatasetsResponse(BaseModel):
     """Response from listing datasets.
 

src/llama_stack_api/inspect.py

@@ -54,6 +54,7 @@ class VersionInfo(BaseModel):
     version: str
 
 
+@json_schema_type
 class ListRoutesResponse(BaseModel):
     """Response containing a list of all available API routes.
 

src/llama_stack_api/models.py

@@ -100,6 +100,7 @@ class OpenAIModel(BaseModel):
     custom_metadata: dict[str, Any] | None = None
 
 
+@json_schema_type
 class OpenAIListModelsResponse(BaseModel):
     data: list[OpenAIModel]
 

src/llama_stack_api/openai_responses.py

@@ -1316,6 +1316,7 @@ OpenAIResponseInput = Annotated[
 register_schema(OpenAIResponseInput, name="OpenAIResponseInput")
 
 
+@json_schema_type
 class ListOpenAIResponseInputItem(BaseModel):
     """List container for OpenAI response input items.
 

src/llama_stack_api/post_training.py

@@ -236,6 +236,7 @@ class PostTrainingRLHFRequest(BaseModel):
     logger_config: dict[str, Any]
 
 
+@json_schema_type
 class PostTrainingJob(BaseModel):
     job_uuid: str
 
@@ -265,6 +266,7 @@ class PostTrainingJobStatusResponse(BaseModel):
     checkpoints: list[Checkpoint] = Field(default_factory=list)
 
 
+@json_schema_type
 class ListPostTrainingJobsResponse(BaseModel):
     data: list[PostTrainingJob]
 

src/llama_stack_api/prompts.py

@@ -85,6 +85,7 @@ class Prompt(BaseModel):
         return f"pmpt_{hex_string}"
 
 
+@json_schema_type
 class ListPromptsResponse(BaseModel):
     """Response model to list prompts."""
 

src/llama_stack_api/providers.py

@@ -31,6 +31,7 @@ class ProviderInfo(BaseModel):
     health: HealthResponse
 
 
+@json_schema_type
 class ListProvidersResponse(BaseModel):
     """Response containing a list of all available providers.
 

src/llama_stack_api/schema_utils.py

@@ -4,11 +4,9 @@
 # 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 collections.abc import Callable, Iterable
 from dataclasses import dataclass
-from typing import Any, TypeVar
+from typing import Any, Literal, TypeVar
-
-from .strong_typing.schema import json_schema_type, register_schema  # noqa: F401
 
 
 class ExtraBodyField[T]:
@@ -48,6 +46,98 @@ class ExtraBodyField[T]:
         self.description = description
 
 
+SchemaSource = Literal["json_schema_type", "registered_schema", "dynamic_schema"]
+
+
+@dataclass(frozen=True)
+class SchemaInfo:
+    """Metadata describing a schema entry exposed to OpenAPI generation."""
+
+    name: str
+    type: Any
+    source: SchemaSource
+
+
+_json_schema_types: dict[type, SchemaInfo] = {}
+
+
+def json_schema_type(cls):
+    """
+    Decorator to mark a Pydantic model for top-level component registration.
+
+    Models marked with this decorator will be registered as top-level components
+    in the OpenAPI schema, while unmarked models will be inlined.
+
+    This provides control over schema registration to avoid unnecessary indirection
+    for simple one-off types while keeping complex reusable types as components.
+    """
+    cls._llama_stack_schema_type = True
+    schema_name = getattr(cls, "__name__", f"Anonymous_{id(cls)}")
+    cls._llama_stack_schema_name = schema_name
+    _json_schema_types.setdefault(cls, SchemaInfo(name=schema_name, type=cls, source="json_schema_type"))
+    return cls
+
+
+# Global registries for schemas discoverable by the generator
+_registered_schemas: dict[Any, SchemaInfo] = {}
+_dynamic_schema_types: dict[type, SchemaInfo] = {}
+
+
+def register_schema(schema_type, name: str | None = None):
+    """
+    Register a schema type for top-level component registration.
+
+    This replicates the behavior of strong_typing's register_schema function.
+    It's used for union types and other complex types that should appear as
+    top-level components in the OpenAPI schema.
+
+    Args:
+        schema_type: The type to register (e.g., union types, Annotated types)
+        name: Optional name for the schema in the OpenAPI spec. If not provided,
+              uses the type's __name__ or a generated name.
+    """
+    if name is None:
+        name = getattr(schema_type, "__name__", f"Anonymous_{id(schema_type)}")
+
+    # Store the registration information in a global registry
+    # since union types don't allow setting attributes
+    _registered_schemas[schema_type] = SchemaInfo(name=name, type=schema_type, source="registered_schema")
+
+    return schema_type
+
+
+def get_registered_schema_info(schema_type: Any) -> SchemaInfo | None:
+    """Return the registration metadata for a schema type if present."""
+    return _registered_schemas.get(schema_type)
+
+
+def iter_registered_schema_types() -> Iterable[SchemaInfo]:
+    """Iterate over all explicitly registered schema entries."""
+    return tuple(_registered_schemas.values())
+
+
+def iter_json_schema_types() -> Iterable[type]:
+    """Iterate over all Pydantic models decorated with @json_schema_type."""
+    return tuple(info.type for info in _json_schema_types.values())
+
+
+def iter_dynamic_schema_types() -> Iterable[type]:
+    """Iterate over dynamic models registered at generation time."""
+    return tuple(info.type for info in _dynamic_schema_types.values())
+
+
+def register_dynamic_schema_type(schema_type: type, name: str | None = None) -> type:
+    """Register a dynamic model generated at runtime for schema inclusion."""
+    schema_name = name if name is not None else getattr(schema_type, "__name__", f"Anonymous_{id(schema_type)}")
+    _dynamic_schema_types[schema_type] = SchemaInfo(name=schema_name, type=schema_type, source="dynamic_schema")
+    return schema_type
+
+
+def clear_dynamic_schema_types() -> None:
+    """Clear dynamic schema registrations."""
+    _dynamic_schema_types.clear()
+
+
 @dataclass
 class WebMethod:
     level: str | None = None

src/llama_stack_api/scoring_functions.py

@@ -155,6 +155,7 @@ class ScoringFnInput(CommonScoringFnFields, BaseModel):
     provider_scoring_fn_id: str | None = None
 
 
+@json_schema_type
 class ListScoringFunctionsResponse(BaseModel):
     data: list[ScoringFn]
 

src/llama_stack_api/shields.py

@@ -43,6 +43,7 @@ class ShieldInput(CommonShieldFields):
     provider_shield_id: str | None = None
 
 
+@json_schema_type
 class ListShieldsResponse(BaseModel):
     data: list[Shield]
 

src/llama_stack_api/strong_typing/__init__.py

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -88,6 +88,7 @@ class ToolStore(Protocol):
     async def get_tool_group(self, toolgroup_id: str) -> ToolGroup: ...
 
 
+@json_schema_type
 class ListToolGroupsResponse(BaseModel):
     """Response containing a list of tool groups.
 
@@ -97,6 +98,7 @@ class ListToolGroupsResponse(BaseModel):
     data: list[ToolGroup]
 
 
+@json_schema_type
 class ListToolDefsResponse(BaseModel):
     """Response containing a list of tool definitions.
 

src/llama_stack_api/vector_io.py

@@ -15,8 +15,7 @@ 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.schema_utils import json_schema_type, register_schema, 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
 
@@ -738,8 +737,8 @@ class VectorIO(Protocol):
         self,
         vector_store_id: str,
         file_id: str,
-        include_embeddings: Annotated[bool | None, Query(default=False)] = False,
+        include_embeddings: Annotated[bool | None, Query()] = False,
-        include_metadata: Annotated[bool | None, Query(default=False)] = False,
+        include_metadata: Annotated[bool | None, Query()] = False,
     ) -> VectorStoreFileContentResponse:
         """Retrieves the contents of a vector store file.
 

tests/unit/server/test_schema_registry.py

@@ -0,0 +1,48 @@
+# 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 pydantic import BaseModel
+
+from llama_stack_api import Conversation, SamplingStrategy
+from llama_stack_api.schema_utils import (
+    clear_dynamic_schema_types,
+    get_registered_schema_info,
+    iter_dynamic_schema_types,
+    iter_json_schema_types,
+    iter_registered_schema_types,
+    register_dynamic_schema_type,
+)
+
+
+def test_json_schema_registry_contains_known_model() -> None:
+    assert Conversation in iter_json_schema_types()
+
+
+def test_registered_schema_registry_contains_sampling_strategy() -> None:
+    registered_names = {info.name for info in iter_registered_schema_types()}
+    assert "SamplingStrategy" in registered_names
+
+    schema_info = get_registered_schema_info(SamplingStrategy)
+    assert schema_info is not None
+    assert schema_info.name == "SamplingStrategy"
+
+
+def test_dynamic_schema_registration_round_trip() -> None:
+    existing_models = tuple(iter_dynamic_schema_types())
+    clear_dynamic_schema_types()
+    try:
+
+        class TemporaryModel(BaseModel):
+            foo: str
+
+        register_dynamic_schema_type(TemporaryModel)
+        assert TemporaryModel in iter_dynamic_schema_types()
+
+        clear_dynamic_schema_types()
+        assert TemporaryModel not in iter_dynamic_schema_types()
+    finally:
+        for model in existing_models:
+            register_dynamic_schema_type(model)

uv.lock

@@ -1834,6 +1834,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/fe/54/c86cd8e011fe98803d7e382fd67c0df5ceab8d2b7ad8c5a81524f791551c/jsonschema-4.25.0-py3-none-any.whl", hash = "sha256:24c2e8da302de79c8b9382fee3e76b355e44d2a4364bb207159ce10b517bd716", size = 89184, upload-time = "2025-07-18T15:39:42.956Z" },
 ]
 
+[[package]]
+name = "jsonschema-path"
+version = "0.3.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pathable" },
+    { name = "pyyaml" },
+    { name = "referencing" },
+    { name = "requests" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/6e/45/41ebc679c2a4fced6a722f624c18d658dee42612b83ea24c1caf7c0eb3a8/jsonschema_path-0.3.4.tar.gz", hash = "sha256:8365356039f16cc65fddffafda5f58766e34bebab7d6d105616ab52bc4297001", size = 11159, upload-time = "2025-01-24T14:33:16.547Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cb/58/3485da8cb93d2f393bce453adeef16896751f14ba3e2024bc21dc9597646/jsonschema_path-0.3.4-py3-none-any.whl", hash = "sha256:f502191fdc2b22050f9a81c9237be9d27145b9001c55842bece5e94e382e52f8", size = 14810, upload-time = "2025-01-24T14:33:14.652Z" },
+]
+
 [[package]]
 name = "jsonschema-specifications"
 version = "2025.4.1"
@@ -1913,6 +1928,38 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/89/43/d9bebfc3db7dea6ec80df5cb2aad8d274dd18ec2edd6c4f21f32c237cbbb/kubernetes-33.1.0-py2.py3-none-any.whl", hash = "sha256:544de42b24b64287f7e0aa9513c93cb503f7f40eea39b20f66810011a86eabc5", size = 1941335, upload-time = "2025-06-09T21:57:56.327Z" },
 ]
 
+[[package]]
+name = "lazy-object-proxy"
+version = "1.12.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/08/a2/69df9c6ba6d316cfd81fe2381e464db3e6de5db45f8c43c6a23504abf8cb/lazy_object_proxy-1.12.0.tar.gz", hash = "sha256:1f5a462d92fd0cfb82f1fab28b51bfb209fabbe6aabf7f0d51472c0c124c0c61", size = 43681, upload-time = "2025-08-22T13:50:06.783Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/0d/1b/b5f5bd6bda26f1e15cd3232b223892e4498e34ec70a7f4f11c401ac969f1/lazy_object_proxy-1.12.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:8ee0d6027b760a11cc18281e702c0309dd92da458a74b4c15025d7fc490deede", size = 26746, upload-time = "2025-08-22T13:42:37.572Z" },
+    { url = "https://files.pythonhosted.org/packages/55/64/314889b618075c2bfc19293ffa9153ce880ac6153aacfd0a52fcabf21a66/lazy_object_proxy-1.12.0-cp312-cp312-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:4ab2c584e3cc8be0dfca422e05ad30a9abe3555ce63e9ab7a559f62f8dbc6ff9", size = 71457, upload-time = "2025-08-22T13:42:38.743Z" },
+    { url = "https://files.pythonhosted.org/packages/11/53/857fc2827fc1e13fbdfc0ba2629a7d2579645a06192d5461809540b78913/lazy_object_proxy-1.12.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:14e348185adbd03ec17d051e169ec45686dcd840a3779c9d4c10aabe2ca6e1c0", size = 71036, upload-time = "2025-08-22T13:42:40.184Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/24/e581ffed864cd33c1b445b5763d617448ebb880f48675fc9de0471a95cbc/lazy_object_proxy-1.12.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:c4fcbe74fb85df8ba7825fa05eddca764138da752904b378f0ae5ab33a36c308", size = 69329, upload-time = "2025-08-22T13:42:41.311Z" },
+    { url = "https://files.pythonhosted.org/packages/78/be/15f8f5a0b0b2e668e756a152257d26370132c97f2f1943329b08f057eff0/lazy_object_proxy-1.12.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:563d2ec8e4d4b68ee7848c5ab4d6057a6d703cb7963b342968bb8758dda33a23", size = 70690, upload-time = "2025-08-22T13:42:42.51Z" },
+    { url = "https://files.pythonhosted.org/packages/5d/aa/f02be9bbfb270e13ee608c2b28b8771f20a5f64356c6d9317b20043c6129/lazy_object_proxy-1.12.0-cp312-cp312-win_amd64.whl", hash = "sha256:53c7fd99eb156bbb82cbc5d5188891d8fdd805ba6c1e3b92b90092da2a837073", size = 26563, upload-time = "2025-08-22T13:42:43.685Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/26/b74c791008841f8ad896c7f293415136c66cc27e7c7577de4ee68040c110/lazy_object_proxy-1.12.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:86fd61cb2ba249b9f436d789d1356deae69ad3231dc3c0f17293ac535162672e", size = 26745, upload-time = "2025-08-22T13:42:44.982Z" },
+    { url = "https://files.pythonhosted.org/packages/9b/52/641870d309e5d1fb1ea7d462a818ca727e43bfa431d8c34b173eb090348c/lazy_object_proxy-1.12.0-cp313-cp313-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:81d1852fb30fab81696f93db1b1e55a5d1ff7940838191062f5f56987d5fcc3e", size = 71537, upload-time = "2025-08-22T13:42:46.141Z" },
+    { url = "https://files.pythonhosted.org/packages/47/b6/919118e99d51c5e76e8bf5a27df406884921c0acf2c7b8a3b38d847ab3e9/lazy_object_proxy-1.12.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:be9045646d83f6c2664c1330904b245ae2371b5c57a3195e4028aedc9f999655", size = 71141, upload-time = "2025-08-22T13:42:47.375Z" },
+    { url = "https://files.pythonhosted.org/packages/e5/47/1d20e626567b41de085cf4d4fb3661a56c159feaa73c825917b3b4d4f806/lazy_object_proxy-1.12.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:67f07ab742f1adfb3966c40f630baaa7902be4222a17941f3d85fd1dae5565ff", size = 69449, upload-time = "2025-08-22T13:42:48.49Z" },
+    { url = "https://files.pythonhosted.org/packages/58/8d/25c20ff1a1a8426d9af2d0b6f29f6388005fc8cd10d6ee71f48bff86fdd0/lazy_object_proxy-1.12.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:75ba769017b944fcacbf6a80c18b2761a1795b03f8899acdad1f1c39db4409be", size = 70744, upload-time = "2025-08-22T13:42:49.608Z" },
+    { url = "https://files.pythonhosted.org/packages/c0/67/8ec9abe15c4f8a4bcc6e65160a2c667240d025cbb6591b879bea55625263/lazy_object_proxy-1.12.0-cp313-cp313-win_amd64.whl", hash = "sha256:7b22c2bbfb155706b928ac4d74c1a63ac8552a55ba7fff4445155523ea4067e1", size = 26568, upload-time = "2025-08-22T13:42:57.719Z" },
+    { url = "https://files.pythonhosted.org/packages/23/12/cd2235463f3469fd6c62d41d92b7f120e8134f76e52421413a0ad16d493e/lazy_object_proxy-1.12.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:4a79b909aa16bde8ae606f06e6bbc9d3219d2e57fb3e0076e17879072b742c65", size = 27391, upload-time = "2025-08-22T13:42:50.62Z" },
+    { url = "https://files.pythonhosted.org/packages/60/9e/f1c53e39bbebad2e8609c67d0830cc275f694d0ea23d78e8f6db526c12d3/lazy_object_proxy-1.12.0-cp313-cp313t-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:338ab2f132276203e404951205fe80c3fd59429b3a724e7b662b2eb539bb1be9", size = 80552, upload-time = "2025-08-22T13:42:51.731Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/b6/6c513693448dcb317d9d8c91d91f47addc09553613379e504435b4cc8b3e/lazy_object_proxy-1.12.0-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8c40b3c9faee2e32bfce0df4ae63f4e73529766893258eca78548bac801c8f66", size = 82857, upload-time = "2025-08-22T13:42:53.225Z" },
+    { url = "https://files.pythonhosted.org/packages/12/1c/d9c4aaa4c75da11eb7c22c43d7c90a53b4fca0e27784a5ab207768debea7/lazy_object_proxy-1.12.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:717484c309df78cedf48396e420fa57fc8a2b1f06ea889df7248fdd156e58847", size = 80833, upload-time = "2025-08-22T13:42:54.391Z" },
+    { url = "https://files.pythonhosted.org/packages/0b/ae/29117275aac7d7d78ae4f5a4787f36ff33262499d486ac0bf3e0b97889f6/lazy_object_proxy-1.12.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:a6b7ea5ea1ffe15059eb44bcbcb258f97bcb40e139b88152c40d07b1a1dfc9ac", size = 79516, upload-time = "2025-08-22T13:42:55.812Z" },
+    { url = "https://files.pythonhosted.org/packages/19/40/b4e48b2c38c69392ae702ae7afa7b6551e0ca5d38263198b7c79de8b3bdf/lazy_object_proxy-1.12.0-cp313-cp313t-win_amd64.whl", hash = "sha256:08c465fb5cd23527512f9bd7b4c7ba6cec33e28aad36fbbe46bf7b858f9f3f7f", size = 27656, upload-time = "2025-08-22T13:42:56.793Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/3a/277857b51ae419a1574557c0b12e0d06bf327b758ba94cafc664cb1e2f66/lazy_object_proxy-1.12.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c9defba70ab943f1df98a656247966d7729da2fe9c2d5d85346464bf320820a3", size = 26582, upload-time = "2025-08-22T13:49:49.366Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/b6/c5e0fa43535bb9c87880e0ba037cdb1c50e01850b0831e80eb4f4762f270/lazy_object_proxy-1.12.0-cp314-cp314-manylinux1_x86_64.manylinux_2_28_x86_64.manylinux_2_5_x86_64.whl", hash = "sha256:6763941dbf97eea6b90f5b06eb4da9418cc088fce0e3883f5816090f9afcde4a", size = 71059, upload-time = "2025-08-22T13:49:50.488Z" },
+    { url = "https://files.pythonhosted.org/packages/06/8a/7dcad19c685963c652624702f1a968ff10220b16bfcc442257038216bf55/lazy_object_proxy-1.12.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fdc70d81235fc586b9e3d1aeef7d1553259b62ecaae9db2167a5d2550dcc391a", size = 71034, upload-time = "2025-08-22T13:49:54.224Z" },
+    { url = "https://files.pythonhosted.org/packages/12/ac/34cbfb433a10e28c7fd830f91c5a348462ba748413cbb950c7f259e67aa7/lazy_object_proxy-1.12.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:0a83c6f7a6b2bfc11ef3ed67f8cbe99f8ff500b05655d8e7df9aab993a6abc95", size = 69529, upload-time = "2025-08-22T13:49:55.29Z" },
+    { url = "https://files.pythonhosted.org/packages/6f/6a/11ad7e349307c3ca4c0175db7a77d60ce42a41c60bcb11800aabd6a8acb8/lazy_object_proxy-1.12.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:256262384ebd2a77b023ad02fbcc9326282bcfd16484d5531154b02bc304f4c5", size = 70391, upload-time = "2025-08-22T13:49:56.35Z" },
+    { url = "https://files.pythonhosted.org/packages/59/97/9b410ed8fbc6e79c1ee8b13f8777a80137d4bc189caf2c6202358e66192c/lazy_object_proxy-1.12.0-cp314-cp314-win_amd64.whl", hash = "sha256:7601ec171c7e8584f8ff3f4e440aa2eebf93e854f04639263875b8c2971f819f", size = 26988, upload-time = "2025-08-22T13:49:57.302Z" },
+]
+
 [[package]]
 name = "linkify"
 version = "1.4"
@@ -1992,6 +2039,7 @@ dev = [
     { name = "black" },
     { name = "mypy" },
     { name = "nbval" },
+    { name = "openapi-spec-validator" },
     { name = "pre-commit" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
@@ -2117,6 +2165,7 @@ requires-dist = [
     { name = "python-dotenv" },
     { name = "python-multipart", specifier = ">=0.0.20" },
     { name = "pyyaml", specifier = ">=6.0" },
+    { name = "pyyaml", specifier = ">=6.0.2" },
     { name = "rich" },
     { name = "sqlalchemy", extras = ["asyncio"], specifier = ">=2.0.41" },
     { name = "starlette" },
@@ -2138,6 +2187,7 @@ dev = [
     { name = "black" },
     { name = "mypy" },
     { name = "nbval" },
+    { name = "openapi-spec-validator", specifier = ">=0.7.2" },
     { name = "pre-commit", specifier = ">=4.4.0" },
     { name = "pytest", specifier = ">=8.4" },
     { name = "pytest-asyncio", specifier = ">=1.0" },
@@ -3011,6 +3061,35 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/14/f3/ebbd700d8dc1e6380a7a382969d96bc0cbea8717b52fb38ff0ca2a7653e8/openai-2.5.0-py3-none-any.whl", hash = "sha256:21380e5f52a71666dbadbf322dd518bdf2b9d11ed0bb3f96bea17310302d6280", size = 999851, upload-time = "2025-10-17T18:14:45.528Z" },
 ]
 
+[[package]]
+name = "openapi-schema-validator"
+version = "0.6.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "jsonschema" },
+    { name = "jsonschema-specifications" },
+    { name = "rfc3339-validator" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8b/f3/5507ad3325169347cd8ced61c232ff3df70e2b250c49f0fe140edb4973c6/openapi_schema_validator-0.6.3.tar.gz", hash = "sha256:f37bace4fc2a5d96692f4f8b31dc0f8d7400fd04f3a937798eaf880d425de6ee", size = 11550, upload-time = "2025-01-10T18:08:22.268Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/21/c6/ad0fba32775ae749016829dace42ed80f4407b171da41313d1a3a5f102e4/openapi_schema_validator-0.6.3-py3-none-any.whl", hash = "sha256:f3b9870f4e556b5a62a1c39da72a6b4b16f3ad9c73dc80084b1b11e74ba148a3", size = 8755, upload-time = "2025-01-10T18:08:19.758Z" },
+]
+
+[[package]]
+name = "openapi-spec-validator"
+version = "0.7.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "jsonschema" },
+    { name = "jsonschema-path" },
+    { name = "lazy-object-proxy" },
+    { name = "openapi-schema-validator" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/82/af/fe2d7618d6eae6fb3a82766a44ed87cd8d6d82b4564ed1c7cfb0f6378e91/openapi_spec_validator-0.7.2.tar.gz", hash = "sha256:cc029309b5c5dbc7859df0372d55e9d1ff43e96d678b9ba087f7c56fc586f734", size = 36855, upload-time = "2025-06-07T14:48:56.299Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/27/dd/b3fd642260cb17532f66cc1e8250f3507d1e580483e209dc1e9d13bd980d/openapi_spec_validator-0.7.2-py3-none-any.whl", hash = "sha256:4bbdc0894ec85f1d1bea1d6d9c8b2c3c8d7ccaa13577ef40da9c006c9fd0eb60", size = 39713, upload-time = "2025-06-07T14:48:54.077Z" },
+]
+
 [[package]]
 name = "opentelemetry-api"
 version = "1.36.0"
@@ -3247,6 +3326,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c6/ac/dac4a63f978e4dcb3c6d3a78c4d8e0192a113d288502a1216950c41b1027/parso-0.8.4-py2.py3-none-any.whl", hash = "sha256:a418670a20291dacd2dddc80c377c5c3791378ee1e8d12bffc35420643d43f18", size = 103650, upload-time = "2024-04-05T09:43:53.299Z" },
 ]
 
+[[package]]
+name = "pathable"
+version = "0.4.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/67/93/8f2c2075b180c12c1e9f6a09d1a985bc2036906b13dff1d8917e395f2048/pathable-0.4.4.tar.gz", hash = "sha256:6905a3cd17804edfac7875b5f6c9142a218c7caef78693c2dbbbfbac186d88b2", size = 8124, upload-time = "2025-01-10T18:43:13.247Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7d/eb/b6260b31b1a96386c0a880edebe26f89669098acea8e0318bff6adb378fd/pathable-0.4.4-py3-none-any.whl", hash = "sha256:5ae9e94793b6ef5a4cbe0a7ce9dbbefc1eec38df253763fd0aeeacf2762dbbc2", size = 9592, upload-time = "2025-01-10T18:43:11.88Z" },
+]
+
 [[package]]
 name = "pathspec"
 version = "0.12.1"
@@ -4404,6 +4492,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/1c/4c/cc276ce57e572c102d9542d383b2cfd551276581dc60004cb94fe8774c11/responses-0.25.8-py3-none-any.whl", hash = "sha256:0c710af92def29c8352ceadff0c3fe340ace27cf5af1bbe46fb71275bcd2831c", size = 34769, upload-time = "2025-08-08T19:01:45.018Z" },
 ]
 
+[[package]]
+name = "rfc3339-validator"
+version = "0.1.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "six" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/28/ea/a9387748e2d111c3c2b275ba970b735e04e15cdb1eb30693b6b5708c4dbd/rfc3339_validator-0.1.4.tar.gz", hash = "sha256:138a2abdf93304ad60530167e51d2dfb9549521a836871b88d7f4695d0022f6b", size = 5513, upload-time = "2021-05-12T16:37:54.178Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7b/44/4e421b96b67b2daff264473f7465db72fbdf36a07e05494f50300cc7b0c6/rfc3339_validator-0.1.4-py2.py3-none-any.whl", hash = "sha256:24f6ec1eda14ef823da9e36ec7113124b39c04d50a4d3d3a3c2859577e7791fa", size = 3490, upload-time = "2021-05-12T16:37:52.536Z" },
+]
+
 [[package]]
 name = "rich"
 version = "14.1.0"
@@ -4516,40 +4616,46 @@ wheels = [
 
 [[package]]
 name = "ruamel-yaml"
-version = "0.18.14"
+version = "0.18.16"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "ruamel-yaml-clib", marker = "python_full_version < '3.14' and platform_python_implementation == 'CPython'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/39/87/6da0df742a4684263261c253f00edd5829e6aca970fff69e75028cccc547/ruamel.yaml-0.18.14.tar.gz", hash = "sha256:7227b76aaec364df15936730efbf7d72b30c0b79b1d578bbb8e3dcb2d81f52b7", size = 145511, upload-time = "2025-06-09T08:51:09.828Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/9f/c7/ee630b29e04a672ecfc9b63227c87fd7a37eb67c1bf30fe95376437f897c/ruamel.yaml-0.18.16.tar.gz", hash = "sha256:a6e587512f3c998b2225d68aa1f35111c29fad14aed561a26e73fab729ec5e5a", size = 147269, upload-time = "2025-10-22T17:54:02.346Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/af/6d/6fe4805235e193aad4aaf979160dd1f3c487c57d48b810c816e6e842171b/ruamel.yaml-0.18.14-py3-none-any.whl", hash = "sha256:710ff198bb53da66718c7db27eec4fbcc9aa6ca7204e4c1df2f282b6fe5eb6b2", size = 118570, upload-time = "2025-06-09T08:51:06.348Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/73/bb1bc2529f852e7bf64a2dec885e89ff9f5cc7bbf6c9340eed30ff2c69c5/ruamel.yaml-0.18.16-py3-none-any.whl", hash = "sha256:048f26d64245bae57a4f9ef6feb5b552a386830ef7a826f235ffb804c59efbba", size = 119858, upload-time = "2025-10-22T17:53:59.012Z" },
 ]
 
 [[package]]
 name = "ruamel-yaml-clib"
-version = "0.2.12"
+version = "0.2.14"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/20/84/80203abff8ea4993a87d823a5f632e4d92831ef75d404c9fc78d0176d2b5/ruamel.yaml.clib-0.2.12.tar.gz", hash = "sha256:6c8fbb13ec503f99a91901ab46e0b07ae7941cd527393187039aec586fdfd36f", size = 225315, upload-time = "2024-10-20T10:10:56.22Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/d8/e9/39ec4d4b3f91188fad1842748f67d4e749c77c37e353c4e545052ee8e893/ruamel.yaml.clib-0.2.14.tar.gz", hash = "sha256:803f5044b13602d58ea378576dd75aa759f52116a0232608e8fdada4da33752e", size = 225394, upload-time = "2025-09-22T19:51:23.753Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/48/41/e7a405afbdc26af961678474a55373e1b323605a4f5e2ddd4a80ea80f628/ruamel.yaml.clib-0.2.12-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:20b0f8dc160ba83b6dcc0e256846e1a02d044e13f7ea74a3d1d56ede4e48c632", size = 133433, upload-time = "2024-10-20T10:12:55.657Z" },
+    { url = "https://files.pythonhosted.org/packages/b4/42/ccfb34a25289afbbc42017e4d3d4288e61d35b2e00cfc6b92974a6a1f94b/ruamel.yaml.clib-0.2.14-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:6aeadc170090ff1889f0d2c3057557f9cd71f975f17535c26a5d37af98f19c27", size = 271775, upload-time = "2025-09-23T14:24:12.771Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/b0/b850385604334c2ce90e3ee1013bd911aedf058a934905863a6ea95e9eb4/ruamel.yaml.clib-0.2.12-cp312-cp312-manylinux2014_aarch64.whl", hash = "sha256:943f32bc9dedb3abff9879edc134901df92cfce2c3d5c9348f172f62eb2d771d", size = 647362, upload-time = "2024-10-20T10:12:57.155Z" },
+    { url = "https://files.pythonhosted.org/packages/82/73/e628a92e80197ff6a79ab81ec3fa00d4cc082d58ab78d3337b7ba7043301/ruamel.yaml.clib-0.2.14-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:5e56ac47260c0eed992789fa0b8efe43404a9adb608608631a948cee4fc2b052", size = 138842, upload-time = "2025-09-22T19:50:49.156Z" },
-    { url = "https://files.pythonhosted.org/packages/44/d0/3f68a86e006448fb6c005aee66565b9eb89014a70c491d70c08de597f8e4/ruamel.yaml.clib-0.2.12-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:95c3829bb364fdb8e0332c9931ecf57d9be3519241323c5274bd82f709cebc0c", size = 754118, upload-time = "2024-10-20T10:12:58.501Z" },
+    { url = "https://files.pythonhosted.org/packages/2b/c5/346c7094344a60419764b4b1334d9e0285031c961176ff88ffb652405b0c/ruamel.yaml.clib-0.2.14-cp312-cp312-manylinux2014_aarch64.whl", hash = "sha256:a911aa73588d9a8b08d662b9484bc0567949529824a55d3885b77e8dd62a127a", size = 647404, upload-time = "2025-09-22T19:50:52.921Z" },
-    { url = "https://files.pythonhosted.org/packages/52/a9/d39f3c5ada0a3bb2870d7db41901125dbe2434fa4f12ca8c5b83a42d7c53/ruamel.yaml.clib-0.2.12-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:749c16fcc4a2b09f28843cda5a193e0283e47454b63ec4b81eaa2242f50e4ccd", size = 706497, upload-time = "2024-10-20T10:13:00.211Z" },
+    { url = "https://files.pythonhosted.org/packages/df/99/65080c863eb06d4498de3d6c86f3e90595e02e159fd8529f1565f56cfe2c/ruamel.yaml.clib-0.2.14-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a05ba88adf3d7189a974b2de7a9d56731548d35dc0a822ec3dc669caa7019b29", size = 753141, upload-time = "2025-09-22T19:50:50.294Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/fa/097e38135dadd9ac25aecf2a54be17ddf6e4c23e43d538492a90ab3d71c6/ruamel.yaml.clib-0.2.12-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:bf165fef1f223beae7333275156ab2022cffe255dcc51c27f066b4370da81e31", size = 698042, upload-time = "2024-10-21T11:26:46.038Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/e3/0de85f3e3333f8e29e4b10244374a202a87665d1131798946ee22cf05c7c/ruamel.yaml.clib-0.2.14-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:fb04c5650de6668b853623eceadcdb1a9f2fee381f5d7b6bc842ee7c239eeec4", size = 703477, upload-time = "2025-09-22T19:50:51.508Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/d5/a659ca6f503b9379b930f13bc6b130c9f176469b73b9834296822a83a132/ruamel.yaml.clib-0.2.12-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:32621c177bbf782ca5a18ba4d7af0f1082a3f6e517ac2a18b3974d4edf349680", size = 745831, upload-time = "2024-10-21T11:26:47.487Z" },
+    { url = "https://files.pythonhosted.org/packages/d9/25/0d2f09d8833c7fd77ab8efeff213093c16856479a9d293180a0d89f6bed9/ruamel.yaml.clib-0.2.14-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:df3ec9959241d07bc261f4983d25a1205ff37703faf42b474f15d54d88b4f8c9", size = 741157, upload-time = "2025-09-23T18:42:50.408Z" },
-    { url = "https://files.pythonhosted.org/packages/db/5d/36619b61ffa2429eeaefaab4f3374666adf36ad8ac6330d855848d7d36fd/ruamel.yaml.clib-0.2.12-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:b82a7c94a498853aa0b272fd5bc67f29008da798d4f93a2f9f289feb8426a58d", size = 715692, upload-time = "2024-12-11T19:58:17.252Z" },
+    { url = "https://files.pythonhosted.org/packages/d3/8c/959f10c2e2153cbdab834c46e6954b6dd9e3b109c8f8c0a3cf1618310985/ruamel.yaml.clib-0.2.14-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:fbc08c02e9b147a11dfcaa1ac8a83168b699863493e183f7c0c8b12850b7d259", size = 745859, upload-time = "2025-09-22T19:50:54.497Z" },
-    { url = "https://files.pythonhosted.org/packages/b1/82/85cb92f15a4231c89b95dfe08b09eb6adca929ef7df7e17ab59902b6f589/ruamel.yaml.clib-0.2.12-cp312-cp312-win32.whl", hash = "sha256:e8c4ebfcfd57177b572e2040777b8abc537cdef58a2120e830124946aa9b42c5", size = 98777, upload-time = "2024-10-20T10:13:01.395Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/6b/e580a7c18b485e1a5f30a32cda96b20364b0ba649d9d2baaf72f8bd21f83/ruamel.yaml.clib-0.2.14-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:c099cafc1834d3c5dac305865d04235f7c21c167c8dd31ebc3d6bbc357e2f023", size = 770200, upload-time = "2025-09-22T19:50:55.718Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/8f/c3654f6f1ddb75daf3922c3d8fc6005b1ab56671ad56ffb874d908bfa668/ruamel.yaml.clib-0.2.12-cp312-cp312-win_amd64.whl", hash = "sha256:0467c5965282c62203273b838ae77c0d29d7638c8a4e3a1c8bdd3602c10904e4", size = 115523, upload-time = "2024-10-20T10:13:02.768Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/44/3455eebc761dc8e8fdced90f2b0a3fa61e32ba38b50de4130e2d57db0f21/ruamel.yaml.clib-0.2.14-cp312-cp312-win32.whl", hash = "sha256:b5b0f7e294700b615a3bcf6d28b26e6da94e8eba63b079f4ec92e9ba6c0d6b54", size = 98829, upload-time = "2025-09-22T19:50:58.895Z" },
-    { url = "https://files.pythonhosted.org/packages/29/00/4864119668d71a5fa45678f380b5923ff410701565821925c69780356ffa/ruamel.yaml.clib-0.2.12-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:4c8c5d82f50bb53986a5e02d1b3092b03622c02c2eb78e29bec33fd9593bae1a", size = 132011, upload-time = "2024-10-20T10:13:04.377Z" },
+    { url = "https://files.pythonhosted.org/packages/76/ab/5121f7f3b651db93de546f8c982c241397aad0a4765d793aca1dac5eadee/ruamel.yaml.clib-0.2.14-cp312-cp312-win_amd64.whl", hash = "sha256:a37f40a859b503304dd740686359fcf541d6fb3ff7fc10f539af7f7150917c68", size = 115570, upload-time = "2025-09-22T19:50:57.981Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/5e/212f473a93ae78c669ffa0cb051e3fee1139cb2d385d2ae1653d64281507/ruamel.yaml.clib-0.2.12-cp313-cp313-manylinux2014_aarch64.whl", hash = "sha256:e7e3736715fbf53e9be2a79eb4db68e4ed857017344d697e8b9749444ae57475", size = 642488, upload-time = "2024-10-20T10:13:05.906Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/ae/e3811f05415594025e96000349d3400978adaed88d8f98d494352d9761ee/ruamel.yaml.clib-0.2.14-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:7e4f9da7e7549946e02a6122dcad00b7c1168513acb1f8a726b1aaf504a99d32", size = 269205, upload-time = "2025-09-23T14:24:15.06Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/8f/ecfbe2123ade605c49ef769788f79c38ddb1c8fa81e01f4dbf5cf1a44b16/ruamel.yaml.clib-0.2.12-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0b7e75b4965e1d4690e93021adfcecccbca7d61c7bddd8e22406ef2ff20d74ef", size = 745066, upload-time = "2024-10-20T10:13:07.26Z" },
+    { url = "https://files.pythonhosted.org/packages/72/06/7d51f4688d6d72bb72fa74254e1593c4f5ebd0036be5b41fe39315b275e9/ruamel.yaml.clib-0.2.14-cp313-cp313-macosx_15_0_arm64.whl", hash = "sha256:dd7546c851e59c06197a7c651335755e74aa383a835878ca86d2c650c07a2f85", size = 137417, upload-time = "2025-09-22T19:50:59.82Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/a9/28f60726d29dfc01b8decdb385de4ced2ced9faeb37a847bd5cf26836815/ruamel.yaml.clib-0.2.12-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:96777d473c05ee3e5e3c3e999f5d23c6f4ec5b0c38c098b3a5229085f74236c6", size = 701785, upload-time = "2024-10-20T10:13:08.504Z" },
+    { url = "https://files.pythonhosted.org/packages/5a/08/b4499234a420ef42960eeb05585df5cc7eb25ccb8c980490b079e6367050/ruamel.yaml.clib-0.2.14-cp313-cp313-manylinux2014_aarch64.whl", hash = "sha256:1c1acc3a0209ea9042cc3cfc0790edd2eddd431a2ec3f8283d081e4d5018571e", size = 642558, upload-time = "2025-09-22T19:51:03.388Z" },
-    { url = "https://files.pythonhosted.org/packages/84/7e/8e7ec45920daa7f76046578e4f677a3215fe8f18ee30a9cb7627a19d9b4c/ruamel.yaml.clib-0.2.12-cp313-cp313-musllinux_1_1_i686.whl", hash = "sha256:3bc2a80e6420ca8b7d3590791e2dfc709c88ab9152c00eeb511c9875ce5778bf", size = 693017, upload-time = "2024-10-21T11:26:48.866Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/ba/1975a27dedf1c4c33306ee67c948121be8710b19387aada29e2f139c43ee/ruamel.yaml.clib-0.2.14-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2070bf0ad1540d5c77a664de07ebcc45eebd1ddcab71a7a06f26936920692beb", size = 744087, upload-time = "2025-09-22T19:51:00.897Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/b3/d650eaade4ca225f02a648321e1ab835b9d361c60d51150bac49063b83fa/ruamel.yaml.clib-0.2.12-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:e188d2699864c11c36cdfdada94d781fd5d6b0071cd9c427bceb08ad3d7c70e1", size = 741270, upload-time = "2024-10-21T11:26:50.213Z" },
+    { url = "https://files.pythonhosted.org/packages/20/15/8a19a13d27f3bd09fa18813add8380a29115a47b553845f08802959acbce/ruamel.yaml.clib-0.2.14-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:9bd8fe07f49c170e09d76773fb86ad9135e0beee44f36e1576a201b0676d3d1d", size = 699709, upload-time = "2025-09-22T19:51:02.075Z" },
-    { url = "https://files.pythonhosted.org/packages/87/b8/01c29b924dcbbed75cc45b30c30d565d763b9c4d540545a0eeecffb8f09c/ruamel.yaml.clib-0.2.12-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:4f6f3eac23941b32afccc23081e1f50612bdbe4e982012ef4f5797986828cd01", size = 709059, upload-time = "2024-12-11T19:58:18.846Z" },
+    { url = "https://files.pythonhosted.org/packages/19/ee/8d6146a079ad21e534b5083c9ee4a4c8bec42f79cf87594b60978286b39a/ruamel.yaml.clib-0.2.14-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ff86876889ea478b1381089e55cf9e345707b312beda4986f823e1d95e8c0f59", size = 708926, upload-time = "2025-09-23T18:42:51.707Z" },
-    { url = "https://files.pythonhosted.org/packages/30/8c/ed73f047a73638257aa9377ad356bea4d96125b305c34a28766f4445cc0f/ruamel.yaml.clib-0.2.12-cp313-cp313-win32.whl", hash = "sha256:6442cb36270b3afb1b4951f060eccca1ce49f3d087ca1ca4563a6eb479cb3de6", size = 98583, upload-time = "2024-10-20T10:13:09.658Z" },
+    { url = "https://files.pythonhosted.org/packages/a9/f5/426b714abdc222392e68f3b8ad323930d05a214a27c7e7a0f06c69126401/ruamel.yaml.clib-0.2.14-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:1f118b707eece8cf84ecbc3e3ec94d9db879d85ed608f95870d39b2d2efa5dca", size = 740202, upload-time = "2025-09-22T19:51:04.673Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/85/e8e751d8791564dd333d5d9a4eab0a7a115f7e349595417fd50ecae3395c/ruamel.yaml.clib-0.2.12-cp313-cp313-win_amd64.whl", hash = "sha256:e5b8daf27af0b90da7bb903a876477a9e6d7270be6146906b276605997c7e9a3", size = 115190, upload-time = "2024-10-20T10:13:10.66Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/ac/3c5c2b27a183f4fda8a57c82211721c016bcb689a4a175865f7646db9f94/ruamel.yaml.clib-0.2.14-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:b30110b29484adc597df6bd92a37b90e63a8c152ca8136aad100a02f8ba6d1b6", size = 765196, upload-time = "2025-09-22T19:51:05.916Z" },
+    { url = "https://files.pythonhosted.org/packages/92/2e/06f56a71fd55021c993ed6e848c9b2e5e9cfce180a42179f0ddd28253f7c/ruamel.yaml.clib-0.2.14-cp313-cp313-win32.whl", hash = "sha256:f4e97a1cf0b7a30af9e1d9dad10a5671157b9acee790d9e26996391f49b965a2", size = 98635, upload-time = "2025-09-22T19:51:08.183Z" },
+    { url = "https://files.pythonhosted.org/packages/51/79/76aba16a1689b50528224b182f71097ece338e7a4ab55e84c2e73443b78a/ruamel.yaml.clib-0.2.14-cp313-cp313-win_amd64.whl", hash = "sha256:090782b5fb9d98df96509eecdbcaffd037d47389a89492320280d52f91330d78", size = 115238, upload-time = "2025-09-22T19:51:07.081Z" },
+    { url = "https://files.pythonhosted.org/packages/21/e2/a59ff65c26aaf21a24eb38df777cb9af5d87ba8fc8107c163c2da9d1e85e/ruamel.yaml.clib-0.2.14-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:7df6f6e9d0e33c7b1d435defb185095386c469109de723d514142632a7b9d07f", size = 271441, upload-time = "2025-09-23T14:24:16.498Z" },
+    { url = "https://files.pythonhosted.org/packages/6b/fa/3234f913fe9a6525a7b97c6dad1f51e72b917e6872e051a5e2ffd8b16fbb/ruamel.yaml.clib-0.2.14-cp314-cp314-macosx_15_0_arm64.whl", hash = "sha256:70eda7703b8126f5e52fcf276e6c0f40b0d314674f896fc58c47b0aef2b9ae83", size = 137970, upload-time = "2025-09-22T19:51:09.472Z" },
+    { url = "https://files.pythonhosted.org/packages/ef/ec/4edbf17ac2c87fa0845dd366ef8d5852b96eb58fcd65fc1ecf5fe27b4641/ruamel.yaml.clib-0.2.14-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:a0cb71ccc6ef9ce36eecb6272c81afdc2f565950cdcec33ae8e6cd8f7fc86f27", size = 739639, upload-time = "2025-09-22T19:51:10.566Z" },
+    { url = "https://files.pythonhosted.org/packages/15/18/b0e1fafe59051de9e79cdd431863b03593ecfa8341c110affad7c8121efc/ruamel.yaml.clib-0.2.14-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:e7cb9ad1d525d40f7d87b6df7c0ff916a66bc52cb61b66ac1b2a16d0c1b07640", size = 764456, upload-time = "2025-09-22T19:51:11.736Z" },
 ]
 
 [[package]]