aoa-fastapi-adapter 1.0.0__tar.gz

aoa_fastapi_adapter-1.0.0/.gitignore

@@ -0,0 +1,92 @@
+# ============================================================================
+# Python
+# ============================================================================
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# ============================================================================
+# Virtual environments
+# ============================================================================
+.venv/
+venv/
+ENV/
+env/
+
+# ============================================================================
+# Distribution / packaging
+# ============================================================================
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+
+# ============================================================================
+# Testing
+# ============================================================================
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+*.cover
+.hypothesis/
+.tox/
+.nox/
+
+# ============================================================================
+# Type checking
+# ============================================================================
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+
+# ============================================================================
+# Node (Maxitor web client — source lives in git; node_modules stays local only)
+# ============================================================================
+packages/aoa-maxitor/client/node_modules/
+packages/aoa-maxitor/client/.vite/
+
+# ============================================================================
+# IDE
+# ============================================================================
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# ============================================================================
+# Logs and temporary files
+# ============================================================================
+*.log
+code_quality.log
+*.tmp
+*.temp
+
+# ============================================================================
+# Project specific - ARCHIVE (ваши локальные снимки)
+# ============================================================================
+archive/
+*.ver
+code.txt
+project_structure.txt
+
+# ============================================================================
+# Локальные черновики (русские версии документации и примеров)
+# ============================================================================
+*_draft.md
+*_draft.py
+.ipynb_checkpoints/
+docs/ru/
+
+# ============================================================================
+# НЕ ИГНОРИРУЕМ - эти файлы должны быть в git!
+# ============================================================================
+!.python-version
+!uv.lock

aoa_fastapi_adapter-1.0.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `aoa-fastapi-adapter` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] – 2026-06-24
+
+### Added
+
+- **Initial standalone release, extracted from `aoa-action-machine`.** `FastApiAdapter`, `FastApiRouteRecord`, and `query_field_before` helpers are now distributed under the `aoa.fastapi` namespace as a separate package (`pip install aoa-fastapi-adapter`). The package depends on `aoa-action-machine`, `fastapi`, and `uvicorn[standard]`. ([#63](https://github.com/bystrovmaxim/aoa/issues/63))
+
+For the pre-extraction history of `FastApiAdapter` (originally introduced in the monorepo at `[0.5.5]`), see the [aoa-action-machine CHANGELOG](../aoa-action-machine/CHANGELOG.md).

aoa_fastapi_adapter-1.0.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: aoa-fastapi-adapter
+Version: 1.0.0
+Summary: FastAPI adapter for AOA — expose Actions as HTTP endpoints.
+Project-URL: Homepage, https://github.com/bystrovmaxim/aoa
+Project-URL: Repository, https://github.com/bystrovmaxim/aoa
+Author: @Bystrov.Maxim
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: aoa-action-machine>=1.0.0a5
+Requires-Dist: fastapi<1.0,>=0.100
+Requires-Dist: uvicorn[standard]<1.0,>=0.20

aoa_fastapi_adapter-1.0.0/pyproject.toml

@@ -0,0 +1,24 @@
+# packages/aoa-fastapi-adapter/pyproject.toml — publishable distribution for ``aoa.fastapi``.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aoa-fastapi-adapter"
+version = "1.0.0"
+description = "FastAPI adapter for AOA — expose Actions as HTTP endpoints."
+license = { text = "MIT" }
+requires-python = ">=3.12"
+authors = [{ name = "@Bystrov.Maxim" }]
+dependencies = [
+    "aoa-action-machine>=1.0.0a5",
+    "fastapi>=0.100,<1.0",
+    "uvicorn[standard]>=0.20,<1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/bystrovmaxim/aoa"
+Repository = "https://github.com/bystrovmaxim/aoa"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aoa"]

aoa_fastapi_adapter-1.0.0/src/aoa/fastapi/__init__.py

@@ -0,0 +1,28 @@
+# packages/aoa-fastapi-adapter/src/aoa/fastapi/__init__.py
+"""
+FastAPI adapter for AOA ActionMachine.
+
+Install: pip install aoa-fastapi-adapter
+
+Usage:
+    from aoa.fastapi import FastApiAdapter, FastApiRouteRecord
+    from aoa.fastapi.query_field_before import QUERY_STR_LIST_BEFORE, coerce_query_str_list
+"""
+
+try:
+    import fastapi  # noqa: F401
+except ImportError:
+    raise ImportError(
+        "To use aoa-fastapi-adapter, install: pip install aoa-fastapi-adapter"
+    ) from None
+
+from aoa.fastapi.adapter import FastApiAdapter
+from aoa.fastapi.query_field_before import QUERY_STR_LIST_BEFORE, coerce_query_str_list
+from aoa.fastapi.route_record import FastApiRouteRecord
+
+__all__ = [
+    "QUERY_STR_LIST_BEFORE",
+    "FastApiAdapter",
+    "FastApiRouteRecord",
+    "coerce_query_str_list",
+]

aoa_fastapi_adapter-1.0.0/src/aoa/fastapi/adapter.py

@@ -0,0 +1,889 @@
+# packages/aoa-fastapi-adapter/src/aoa/fastapi/adapter.py
+"""
+FastApiAdapter — HTTP adapter for ActionMachine using FastAPI.
+
+═══════════════════════════════════════════════════════════════════════════════
+PURPOSE
+═══════════════════════════════════════════════════════════════════════════════
+
+FastApiAdapter converts Actions into FastAPI HTTP endpoints. One call to a
+protocol method (post/get/put/delete/patch) registers one endpoint.
+All protocol methods return ``self`` for fluent chaining:
+
+    app = adapter \\
+        .get("/api/v1/ping", PingAction, tags=["system"]) \\
+        .post("/api/v1/orders", CreateOrderAction, tags=["orders"]) \\
+        .build()
+
+OpenAPI documentation is generated automatically from metadata already declared
+in code: field descriptions from ``Field(description=...)``, constraints from
+``Field(gt=0, min_length=3, pattern=...)``, summary from ``@meta``, and tags
+from route registration arguments.
+
+═══════════════════════════════════════════════════════════════════════════════
+REQUIRED AUTHENTICATION
+═══════════════════════════════════════════════════════════════════════════════
+
+The ``auth_coordinator`` argument is required (inherited from ``BaseAdapter``).
+This prevents accidental auth omission: ``auth_coordinator=None`` fails fast
+with ``TypeError`` instead of becoming a silent production bug. For open APIs,
+use ``NoAuthCoordinator`` explicitly:
+
+    from aoa.action_machine.intents.check_roles import NoAuthCoordinator
+
+    adapter = FastApiAdapter(
+        machine=machine,
+        auth_coordinator=NoAuthCoordinator(context=Context()),
+    )
+
+═══════════════════════════════════════════════════════════════════════════════
+MAPPER NAMING CONVENTION
+═══════════════════════════════════════════════════════════════════════════════
+
+Each mapper is named by what it RETURNS:
+
+    params_mapper   -> returns params   (transforms request -> params)
+    response_mapper -> returns response (transforms result  -> response)
+
+═══════════════════════════════════════════════════════════════════════════════
+ENDPOINT GENERATION STRATEGIES
+═══════════════════════════════════════════════════════════════════════════════
+
+The adapter uses three endpoint generation strategies depending on HTTP method
+and whether the params model has fields:
+
+1. POST/PUT/PATCH with non-empty Params -> parameters are passed in JSON body.
+   FastAPI validates the body using the Pydantic model.
+
+2. GET/DELETE with non-empty Params -> parameters are passed via query/path.
+   If URL has path params (e.g. ``{order_id}``), FastAPI extracts those from
+   path and the rest from query string.
+
+3. Any method with empty Params (no fields) -> endpoint takes no body/query.
+   Empty Params instance is created inside the handler.
+
+═══════════════════════════════════════════════════════════════════════════════
+ERROR HANDLING
+═══════════════════════════════════════════════════════════════════════════════
+
+Exception handlers are registered at application level:
+
+    AuthorizationError   -> HTTP 403 {"detail": "..."}
+    ValidationFieldError -> HTTP 422 {"detail": "..."}
+
+Unhandled exceptions are caught by middleware wrapping each request in
+try/except and returning HTTP 500 for any error not handled above.
+
+═══════════════════════════════════════════════════════════════════════════════
+TESTING NOTE (HTTP routes)
+═══════════════════════════════════════════════════════════════════════════════
+
+Route and handler tests should use a real ``ActionProductMachine`` so
+OpenAPI-related wiring and graph metadata match production.
+
+To control results or speed, stub ``machine.run`` only — not the whole stack.
+
+::
+
+    Request body / query / path
+              |
+              v
+    FastAPI validation / mappers  --->  auth_coordinator  --->  machine.run  ~~~~ stub
+         ^___________________________ production ___________________________^
+                                                                           ~~~~
+                                                                optional AsyncMock
+
+    response mapping / JSON response  <---  (after run)
+         ^
+         production
+
+See ``BaseAdapter`` module docstring (ADAPTER TESTING CONTRACT) for the full
+adapter-level picture.
+
+═══════════════════════════════════════════════════════════════════════════════
+HEALTH CHECK
+═══════════════════════════════════════════════════════════════════════════════
+
+Endpoint ``GET /health`` is added automatically during ``build()``.
+Returns ``{"status": "ok"}``.
+
+"""
+
+# Ruff/isort lists first-party ``action_machine`` before FastAPI (known-first-party).
+# pylint: disable=wrong-import-order
+from __future__ import annotations
+
+import inspect
+import re
+from collections.abc import Callable, Mapping
+from typing import Annotated, Any, Self, get_origin
+
+from pydantic import BaseModel
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request as StarletteRequest
+from starlette.responses import Response as StarletteResponse
+
+from aoa.action_machine.adapters.base_adapter import BaseAdapter
+from aoa.action_machine.adapters.base_route_record import ensure_machine_params, ensure_protocol_response
+from aoa.action_machine.exceptions.authorization_error import AuthorizationError
+from aoa.action_machine.exceptions.validation_field_error import ValidationFieldError
+from aoa.action_machine.graph.core.node_graph_coordinator import NodeGraphCoordinator
+from aoa.action_machine.graph.nodes.action_graph_node import ActionGraphNode
+from aoa.action_machine.model.base_action import BaseAction
+from aoa.action_machine.resources.per_call_connection import ConnectionValue, resolve_connections
+from aoa.action_machine.runtime.action_product_machine import ActionProductMachine
+from aoa.action_machine.system_core.type_introspection import TypeIntrospection
+from aoa.fastapi.route_record import FastApiRouteRecord
+from fastapi import FastAPI, Query, Request
+from fastapi.responses import JSONResponse
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Module-level helper functions
+# ═════════════════════════════════════════════════════════════════════════════
+
+_PATH_PARAM_PATTERN: re.Pattern[str] = re.compile(r"\{(\w+)\}")
+
+
+def _fastapi_query_param_annotation(field_name: str, field_info: Any, path_params: set[str]) -> Any:
+    """
+    Build the FastAPI endpoint parameter annotation for one query field.
+
+    FastAPI treats bare ``list[...]`` on GET handlers as a JSON body field; wrap with
+    :class:`fastapi.Query` so list values bind from repeated query keys (or a single
+    value, depending on client) instead.
+    """
+    if field_name in path_params:
+        return field_info.annotation if field_info.annotation is not None else str
+    ann = field_info.annotation
+    if ann is None:
+        return str
+    if get_origin(ann) is list:
+        if field_info.is_required():
+            return Annotated[ann, Query()]
+        return Annotated[ann, Query(default_factory=list)]
+    return ann
+
+
+def _fastapi_route_label(record: FastApiRouteRecord) -> str:
+    return f"{record.method} {record.path}"
+
+
+def _get_action_class_description(
+    action_class: type,
+    *,
+    coordinator: NodeGraphCoordinator | None = None,
+) -> str:
+    """
+    Extract description from action ``@meta`` declaration.
+
+    Used to auto-fill endpoint summary when summary is not provided explicitly
+    during route registration.
+
+    Args:
+        action_class: action class.
+
+    Returns:
+        Description string from the node graph, ``@meta`` scratch, or empty string.
+    """
+    if coordinator is not None:
+        try:
+            node = coordinator.get_node_by_id(
+                TypeIntrospection.full_qualname(action_class),
+                ActionGraphNode.NODE_TYPE,
+            )
+        except (LookupError, RuntimeError):
+            node = None
+        if node is not None:
+            return str(node.properties.get("description", "") or "")
+
+    meta_info = getattr(action_class, "_meta_info", None)
+    if meta_info and isinstance(meta_info, dict):
+        return str(meta_info.get("description", ""))
+    return ""
+
+
+def _get_model_fields(model: type) -> dict[str, Any]:
+    """
+    Return Pydantic model fields as a dictionary.
+
+    For Pydantic ``BaseModel`` uses ``model_fields``.
+    For other types returns an empty dict.
+
+    Args:
+        model: model class (Pydantic ``BaseModel`` or another type).
+
+    Returns:
+        Dict of ``{field_name: FieldInfo}`` or empty dict.
+    """
+    if isinstance(model, type) and issubclass(model, BaseModel):
+        return model.model_fields
+    return {}
+
+
+def _extract_path_params(path: str) -> set[str]:
+    """
+    Extract path-parameter names from URL template.
+
+    Args:
+        path: URL path with placeholders like ``{param_name}``.
+
+    Returns:
+        Set of path-parameter names.
+    """
+    return set(_PATH_PARAM_PATTERN.findall(path))
+
+
+def _has_body_method(method: str) -> bool:
+    """
+    Return whether HTTP method supports request body.
+
+    POST/PUT/PATCH support body.
+    GET/DELETE do not use body in this adapter.
+
+    Args:
+        method: uppercase HTTP method.
+
+    Returns:
+        True if method supports body.
+    """
+    return method in ("POST", "PUT", "PATCH")
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Endpoint function factories
+# ═════════════════════════════════════════════════════════════════════════════
+
+
+def _make_endpoint_with_body(
+    record: FastApiRouteRecord,
+    machine: ActionProductMachine,
+    auth_coordinator: Any,
+) -> Callable[..., Any]:
+    """
+    Create endpoint for methods with JSON body (POST, PUT, PATCH).
+
+    ``body`` parameter is annotated with concrete Pydantic model.
+    FastAPI validates request body and generates OpenAPI schema automatically.
+
+    Args:
+        record: route configuration.
+        machine: action execution machine.
+        auth_coordinator: authentication coordinator (required).
+
+    Returns:
+        Async endpoint function for ``app.add_api_route()``.
+    """
+    req_model = record.effective_request_model
+    has_params_mapper = record.params_mapper is not None
+    has_response_mapper = record.response_mapper is not None
+
+    async def endpoint(request: Request, body: Any) -> Any:
+        if has_params_mapper:
+            params = record.params_mapper(body)  # type: ignore[misc]
+        else:
+            params = body
+
+        ensure_machine_params(
+            params,
+            record.params_type,
+            adapter="FastAPI",
+            route_label=_fastapi_route_label(record),
+        )
+
+        context = await auth_coordinator.process(request)
+        if context is None:
+            raise AuthorizationError("Authentication required")
+
+        connections = resolve_connections(record.connections)
+
+        action = record.action_class()
+        result = await machine.run(context, action, params, connections)
+
+        if has_response_mapper:
+            mapped = record.response_mapper(result)  # type: ignore[misc]
+            ensure_protocol_response(
+                mapped,
+                record.effective_response_model,
+                adapter="FastAPI",
+                route_label=_fastapi_route_label(record),
+            )
+            return mapped
+        return result
+
+    sig_params = [
+        inspect.Parameter("request", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=Request),
+        inspect.Parameter("body", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=req_model),
+    ]
+    endpoint.__signature__ = inspect.Signature(sig_params)  # type: ignore[attr-defined]
+
+    return endpoint
+
+
+def _make_endpoint_with_query(
+    record: FastApiRouteRecord,
+    machine: ActionProductMachine,
+    auth_coordinator: Any,
+) -> Callable[..., Any]:
+    """
+    Create endpoint for GET/DELETE with query/path parameters.
+
+    Each Params model field becomes a function argument. FastAPI resolves which
+    parameters come from path and which from query string using annotations and
+    route path placeholders.
+
+    Args:
+        record: route configuration.
+        machine: action execution machine.
+        auth_coordinator: authentication coordinator (required).
+
+    Returns:
+        Async endpoint function for ``app.add_api_route()``.
+    """
+    req_model = record.effective_request_model
+    has_params_mapper = record.params_mapper is not None
+    has_response_mapper = record.response_mapper is not None
+    model_fields = _get_model_fields(req_model)
+    path_params = _extract_path_params(record.path)
+
+    async def endpoint(request: Request, **kwargs: Any) -> Any:
+        body = req_model(**kwargs)
+
+        if has_params_mapper:
+            params = record.params_mapper(body)  # type: ignore[misc]
+        else:
+            params = body
+
+        ensure_machine_params(
+            params,
+            record.params_type,
+            adapter="FastAPI",
+            route_label=_fastapi_route_label(record),
+        )
+
+        context = await auth_coordinator.process(request)
+        if context is None:
+            raise AuthorizationError("Authentication required")
+
+        connections = resolve_connections(record.connections)
+
+        action = record.action_class()
+        result = await machine.run(context, action, params, connections)
+
+        if has_response_mapper:
+            mapped = record.response_mapper(result)  # type: ignore[misc]
+            ensure_protocol_response(
+                mapped,
+                record.effective_response_model,
+                adapter="FastAPI",
+                route_label=_fastapi_route_label(record),
+            )
+            return mapped
+        return result
+
+    sig_params = [
+        inspect.Parameter("request", inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=Request),
+    ]
+
+    for field_name, field_info in model_fields.items():
+        annotation = _fastapi_query_param_annotation(field_name, field_info, path_params)
+
+        if field_name in path_params:
+            if field_info.default is not None and not field_info.is_required():
+                sig_params.append(
+                    inspect.Parameter(
+                        field_name,
+                        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                        annotation=annotation,
+                        default=field_info.default,
+                    )
+                )
+            else:
+                sig_params.append(
+                    inspect.Parameter(
+                        field_name,
+                        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                        annotation=annotation,
+                    )
+                )
+        else:
+            default = field_info.default if not field_info.is_required() else inspect.Parameter.empty
+            sig_params.append(
+                inspect.Parameter(
+                    field_name,
+                    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                    annotation=annotation,
+                    default=default,
+                )
+            )
+
+    endpoint.__signature__ = inspect.Signature(sig_params)  # type: ignore[attr-defined]
+
+    return endpoint
+
+
+def _make_endpoint_no_params(
+    record: FastApiRouteRecord,
+    machine: ActionProductMachine,
+    auth_coordinator: Any,
+) -> Callable[..., Any]:
+    """
+    Create endpoint for actions with empty Params (no fields).
+
+    Endpoint accepts no body/query parameters. Empty Params instance is created
+    inside handler.
+
+    Args:
+        record: route configuration.
+        machine: action execution machine.
+        auth_coordinator: authentication coordinator (required).
+
+    Returns:
+        Async endpoint function for ``app.add_api_route()``.
+    """
+    req_model = record.effective_request_model
+    has_params_mapper = record.params_mapper is not None
+    has_response_mapper = record.response_mapper is not None
+
+    async def endpoint(request: Request) -> Any:
+        body = req_model()
+
+        if has_params_mapper:
+            params = record.params_mapper(body)  # type: ignore[misc]
+        else:
+            params = body
+
+        ensure_machine_params(
+            params,
+            record.params_type,
+            adapter="FastAPI",
+            route_label=_fastapi_route_label(record),
+        )
+
+        context = await auth_coordinator.process(request)
+        if context is None:
+            raise AuthorizationError("Authentication required")
+
+        connections = resolve_connections(record.connections)
+
+        action = record.action_class()
+        result = await machine.run(context, action, params, connections)
+
+        if has_response_mapper:
+            mapped = record.response_mapper(result)  # type: ignore[misc]
+            ensure_protocol_response(
+                mapped,
+                record.effective_response_model,
+                adapter="FastAPI",
+                route_label=_fastapi_route_label(record),
+            )
+            return mapped
+        return result
+
+    return endpoint
+
+
+def _make_endpoint(
+    record: FastApiRouteRecord,
+    machine: ActionProductMachine,
+    auth_coordinator: Any,
+) -> Callable[..., Any]:
+    """
+    Endpoint factory for FastAPI.
+
+    Chooses generation strategy by HTTP method and Params model shape:
+
+    1. Empty model (no fields) -> endpoint without parameters.
+    2. POST/PUT/PATCH with fields -> endpoint with JSON body.
+    3. GET/DELETE with fields -> endpoint with query/path parameters.
+
+    Args:
+        record: route configuration.
+        machine: action execution machine.
+        auth_coordinator: authentication coordinator (required).
+
+    Returns:
+        Async function suitable for ``app.add_api_route()``.
+    """
+    model_fields = _get_model_fields(record.effective_request_model)
+
+    if not model_fields:
+        return _make_endpoint_no_params(record, machine, auth_coordinator)
+
+    if _has_body_method(record.method):
+        return _make_endpoint_with_body(record, machine, auth_coordinator)
+
+    return _make_endpoint_with_query(record, machine, auth_coordinator)
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Middleware
+# ═════════════════════════════════════════════════════════════════════════════
+
+
+class _CatchAllErrorsMiddleware(BaseHTTPMiddleware):
+    """
+    Middleware that catches unhandled exceptions.
+
+    Wraps each request in try/except and guarantees HTTP 500 for uncaught errors.
+    """
+
+    async def dispatch(
+        self,
+        request: StarletteRequest,
+        call_next: Callable[..., Any],
+    ) -> StarletteResponse:
+        try:
+            response: StarletteResponse = await call_next(request)
+            return response
+        except Exception:
+            return JSONResponse(
+                status_code=500,
+                content={"detail": "Internal server error"},
+            )
+
+
+# ═════════════════════════════════════════════════════════════════════════════
+# Adapter class
+# ═════════════════════════════════════════════════════════════════════════════
+
+
+class FastApiAdapter(BaseAdapter[FastApiRouteRecord]):
+    """
+    FastAPI-based HTTP adapter for ActionMachine.
+
+    Inherits ``BaseAdapter[FastApiRouteRecord]`` and exposes protocol methods
+    ``post/get/put/delete/patch`` for endpoint registration. All protocol
+    methods return ``self`` for fluent chaining. ``build()`` finalizes the
+    chain and creates FastAPI application.
+
+    ``auth_coordinator`` is required (inherited from ``BaseAdapter``). For open
+    APIs, use ``NoAuthCoordinator(context=Context())`` explicitly.
+
+    Attributes:
+        _title : str
+            API title for OpenAPI/Swagger UI.
+
+        _version : str
+            API version for OpenAPI.
+
+        _description : str
+            API description for OpenAPI (Markdown supported).
+    """
+
+    def __init__(
+        self,
+        machine: ActionProductMachine,
+        auth_coordinator: Any,
+        *,
+        title: str = "ActionMachine API",
+        version: str = "0.1.0",
+        description: str = "",
+    ) -> None:
+        """
+        Initialize FastAPI adapter.
+
+        Args:
+            machine: action execution machine (required).
+            auth_coordinator: authentication coordinator (required).
+                For open APIs use ``NoAuthCoordinator(context=Context())``. ``None`` is invalid.
+            title: API title for OpenAPI/Swagger UI.
+            version: API version for OpenAPI.
+            description: API description for OpenAPI (Markdown supported).
+        """
+        super().__init__(
+            machine=machine,
+            auth_coordinator=auth_coordinator,
+        )
+        self._title: str = title
+        self._version: str = version
+        self._description: str = description
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Properties
+    # ─────────────────────────────────────────────────────────────────────
+
+    @property
+    def title(self) -> str:
+        """API title for OpenAPI."""
+        return self._title
+
+    @property
+    def version(self) -> str:
+        """API version for OpenAPI."""
+        return self._version
+
+    @property
+    def api_description(self) -> str:
+        """API description for OpenAPI."""
+        return self._description
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Internal registration method (fluent)
+    # ─────────────────────────────────────────────────────────────────────
+
+    def _register(
+        self,
+        method: str,
+        path: str,
+        action_class: type[BaseAction[Any, Any]],
+        request_model: type | None = None,
+        response_model: type | None = None,
+        params_mapper: Callable[..., Any] | None = None,
+        response_mapper: Callable[..., Any] | None = None,
+        tags: list[str] | None = None,
+        summary: str = "",
+        description: str = "",
+        operation_id: str | None = None,
+        deprecated: bool = False,
+        *,
+        connections: Mapping[str, ConnectionValue] | None = None,
+    ) -> Self:
+        """
+        Create ``FastApiRouteRecord``, append to ``_routes``, and return ``self``.
+
+        If ``summary`` is empty, fill it from action ``@meta`` description.
+        """
+        effective_summary = summary or _get_action_class_description(
+            action_class,
+            coordinator=self.graph_coordinator,
+        )
+
+        record = FastApiRouteRecord(
+            action_class=action_class,
+            request_model=request_model,
+            response_model=response_model,
+            params_mapper=params_mapper,
+            response_mapper=response_mapper,
+            connections=connections,
+            method=method,
+            path=path,
+            tags=tuple(tags or ()),
+            summary=effective_summary,
+            description=description,
+            operation_id=operation_id,
+            deprecated=deprecated,
+        )
+        return self._add_route(record)
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Protocol methods (fluent — return Self)
+    # ─────────────────────────────────────────────────────────────────────
+
+    def post(
+        self,
+        path: str,
+        action_class: type[BaseAction[Any, Any]],
+        request_model: type | None = None,
+        response_model: type | None = None,
+        params_mapper: Callable[..., Any] | None = None,
+        response_mapper: Callable[..., Any] | None = None,
+        tags: list[str] | None = None,
+        summary: str = "",
+        description: str = "",
+        operation_id: str | None = None,
+        deprecated: bool = False,
+        *,
+        connections: Mapping[str, ConnectionValue] | None = None,
+    ) -> Self:
+        """Register POST endpoint. Returns self for fluent chain."""
+        return self._register(
+            "POST", path, action_class, request_model, response_model,
+            params_mapper, response_mapper, tags, summary, description,
+            operation_id, deprecated, connections=connections,
+        )
+
+    def get(
+        self,
+        path: str,
+        action_class: type[BaseAction[Any, Any]],
+        request_model: type | None = None,
+        response_model: type | None = None,
+        params_mapper: Callable[..., Any] | None = None,
+        response_mapper: Callable[..., Any] | None = None,
+        tags: list[str] | None = None,
+        summary: str = "",
+        description: str = "",
+        operation_id: str | None = None,
+        deprecated: bool = False,
+        *,
+        connections: Mapping[str, ConnectionValue] | None = None,
+    ) -> Self:
+        """Register GET endpoint. Returns self for fluent chain."""
+        return self._register(
+            "GET", path, action_class, request_model, response_model,
+            params_mapper, response_mapper, tags, summary, description,
+            operation_id, deprecated, connections=connections,
+        )
+
+    def put(
+        self,
+        path: str,
+        action_class: type[BaseAction[Any, Any]],
+        request_model: type | None = None,
+        response_model: type | None = None,
+        params_mapper: Callable[..., Any] | None = None,
+        response_mapper: Callable[..., Any] | None = None,
+        tags: list[str] | None = None,
+        summary: str = "",
+        description: str = "",
+        operation_id: str | None = None,
+        deprecated: bool = False,
+        *,
+        connections: Mapping[str, ConnectionValue] | None = None,
+    ) -> Self:
+        """Register PUT endpoint. Returns self for fluent chain."""
+        return self._register(
+            "PUT", path, action_class, request_model, response_model,
+            params_mapper, response_mapper, tags, summary, description,
+            operation_id, deprecated, connections=connections,
+        )
+
+    def delete(
+        self,
+        path: str,
+        action_class: type[BaseAction[Any, Any]],
+        request_model: type | None = None,
+        response_model: type | None = None,
+        params_mapper: Callable[..., Any] | None = None,
+        response_mapper: Callable[..., Any] | None = None,
+        tags: list[str] | None = None,
+        summary: str = "",
+        description: str = "",
+        operation_id: str | None = None,
+        deprecated: bool = False,
+        *,
+        connections: Mapping[str, ConnectionValue] | None = None,
+    ) -> Self:
+        """Register DELETE endpoint. Returns self for fluent chain."""
+        return self._register(
+            "DELETE", path, action_class, request_model, response_model,
+            params_mapper, response_mapper, tags, summary, description,
+            operation_id, deprecated, connections=connections,
+        )
+
+    def patch(
+        self,
+        path: str,
+        action_class: type[BaseAction[Any, Any]],
+        request_model: type | None = None,
+        response_model: type | None = None,
+        params_mapper: Callable[..., Any] | None = None,
+        response_mapper: Callable[..., Any] | None = None,
+        tags: list[str] | None = None,
+        summary: str = "",
+        description: str = "",
+        operation_id: str | None = None,
+        deprecated: bool = False,
+        *,
+        connections: Mapping[str, ConnectionValue] | None = None,
+    ) -> Self:
+        """Register PATCH endpoint. Returns self for fluent chain."""
+        return self._register(
+            "PATCH", path, action_class, request_model, response_model,
+            params_mapper, response_mapper, tags, summary, description,
+            operation_id, deprecated, connections=connections,
+        )
+
+    # ─────────────────────────────────────────────────────────────────────
+    # FastAPI application build
+    # ─────────────────────────────────────────────────────────────────────
+
+    def build(self) -> FastAPI:
+        """
+        Create FastAPI application from registered routes.
+
+        Initialization order:
+        1. Create FastAPI app with OpenAPI metadata.
+        2. Add middleware for uncaught exception handling.
+        3. Register exception handlers.
+        4. Register health check endpoint ``GET /health``.
+        5. Generate/register endpoint for each route.
+
+        Returns:
+            Ready-to-run FastAPI application.
+        """
+        app = FastAPI(
+            title=self._title,
+            version=self._version,
+            description=self._description,
+        )
+
+        app.add_middleware(_CatchAllErrorsMiddleware)
+        self._register_exception_handlers(app)
+        self._register_health_check(app)
+
+        for record in self._routes:
+            self._register_endpoint(app, record)
+
+        return app
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Endpoint generation
+    # ─────────────────────────────────────────────────────────────────────
+
+    def _register_endpoint(self, app: FastAPI, record: FastApiRouteRecord) -> None:
+        """
+        Generate and register one async endpoint from ``FastApiRouteRecord``.
+        """
+        endpoint = _make_endpoint(
+            record=record,
+            machine=self._machine,
+            auth_coordinator=self._auth_coordinator,
+        )
+
+        app.add_api_route(
+            path=record.path,
+            endpoint=endpoint,
+            methods=[record.method],
+            response_model=record.effective_response_model,
+            tags=list(record.tags) if record.tags else None,
+            summary=record.summary or None,
+            description=record.description or None,
+            operation_id=record.operation_id,
+            deprecated=record.deprecated or None,
+        )
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Exception handlers
+    # ─────────────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _register_exception_handlers(app: FastAPI) -> None:
+        """
+        Register ActionMachine exception handlers at app level.
+
+            AuthorizationError   -> HTTP 403 Forbidden
+            ValidationFieldError -> HTTP 422 Unprocessable Entity
+        """
+
+        @app.exception_handler(AuthorizationError)
+        async def handle_authorization_error(
+            request: Request,
+            exc: AuthorizationError,
+        ) -> JSONResponse:
+            return JSONResponse(
+                status_code=403,
+                content={"detail": str(exc)},
+            )
+
+        @app.exception_handler(ValidationFieldError)
+        async def handle_validation_error(
+            request: Request,
+            exc: ValidationFieldError,
+        ) -> JSONResponse:
+            return JSONResponse(
+                status_code=422,
+                content={"detail": str(exc)},
+            )
+
+    # ─────────────────────────────────────────────────────────────────────
+    # Health check
+    # ─────────────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _register_health_check(app: FastAPI) -> None:
+        """Add ``GET /health -> {"status": "ok"}`` endpoint."""
+
+        @app.get("/health", tags=["system"])
+        async def health_check() -> dict[str, str]:
+            return {"status": "ok"}

aoa_fastapi_adapter-1.0.0/src/aoa/fastapi/query_field_before/__init__.py

@@ -0,0 +1,17 @@
+# packages/aoa-fastapi-adapter/src/aoa/fastapi/query_field_before/__init__.py
+"""
+Reusable Pydantic ``BeforeValidator`` helpers for FastAPI query-shaped inputs.
+
+Use with action ``Params`` fields typed as ``list[str]``. Prefer :data:`QUERY_STR_LIST_BEFORE`
+for OpenAPI query arrays (repeated keys, no delimiter splitting inside values).
+"""
+
+from aoa.fastapi.query_field_before.query_str_list import (
+    QUERY_STR_LIST_BEFORE,
+    coerce_query_str_list,
+)
+
+__all__ = [
+    "QUERY_STR_LIST_BEFORE",
+    "coerce_query_str_list",
+]

aoa_fastapi_adapter-1.0.0/src/aoa/fastapi/query_field_before/query_str_list.py

@@ -0,0 +1,49 @@
+# packages/aoa-fastapi-adapter/src/aoa/fastapi/query_field_before/query_str_list.py
+"""
+Query array → ``list[str]`` coercion (OpenAPI ``explode``, no delimiter splitting).
+
+AI-CORE-BEGIN
+ROLE: Normalize FastAPI query inputs into a clean ``list[str]`` before Pydantic validates ``list[str]``.
+CONTRACT: ``None`` / ``""`` → ``[]``; ``str`` → at most one token (strip only); ``list`` / ``tuple`` → strip each item, drop empties.
+INVARIANTS: Does not split on commas or other delimiters inside values.
+AI-CORE-END
+"""
+
+from __future__ import annotations
+
+from functools import partial
+
+from pydantic import BeforeValidator
+
+
+def coerce_query_str_list(value: object) -> list[str]:
+    """
+    Normalize a query-style value to ``list[str]`` without delimiter splitting.
+
+    Args:
+        value: ``None``, empty string, one non-empty string, or a sequence of values coercible to ``str``.
+
+    Returns:
+        List of stripped non-empty strings, order preserved.
+
+    Raises:
+        TypeError: If ``value`` is not ``None``, ``str``, ``list``, or ``tuple``.
+    """
+    if value is None or value == "":
+        return []
+    if isinstance(value, str):
+        s = value.strip()
+        return [s] if s else []
+    if isinstance(value, (list, tuple)):
+        out: list[str] = []
+        for item in value:
+            s = str(item).strip()
+            if s:
+                out.append(s)
+        return out
+    msg = f"expected None, str, list, or tuple, got {type(value).__name__}"
+    raise TypeError(msg)
+
+
+#: Repeated query keys / one string token per value (see :func:`coerce_query_str_list`).
+QUERY_STR_LIST_BEFORE = BeforeValidator(partial(coerce_query_str_list))

aoa_fastapi_adapter-1.0.0/src/aoa/fastapi/route_record.py

@@ -0,0 +1,124 @@
+# packages/aoa-fastapi-adapter/src/aoa/fastapi/route_record.py
+"""
+FastApiRouteRecord — frozen route record for FastAPI adapter.
+
+═══════════════════════════════════════════════════════════════════════════════
+PURPOSE
+═══════════════════════════════════════════════════════════════════════════════
+
+Concrete ``BaseRouteRecord`` subtype for HTTP transport metadata.
+It stores one endpoint contract consumed by ``FastApiAdapter.build()``.
+
+═══════════════════════════════════════════════════════════════════════════════
+ARCHITECTURE / DATA FLOW
+═══════════════════════════════════════════════════════════════════════════════
+
+    Protocol registration
+            |
+            v
+    FastApiAdapter.post/get/...(...)
+            |
+            v
+    FastApiRouteRecord(
+        action_class + mappers + HTTP metadata
+    )
+            |
+            v
+    FastApiAdapter.build()
+            |
+            v
+    FastAPI route + OpenAPI operation
+
+═══════════════════════════════════════════════════════════════════════════════
+HTTP-SPECIFIC FIELDS
+═══════════════════════════════════════════════════════════════════════════════
+
+- ``method``: HTTP method, default ``"POST"``.
+- ``path``: endpoint URL path, default ``"/"``.
+- ``tags``: OpenAPI tags, default ``()``.
+- ``summary``: short OpenAPI summary, default ``""``.
+- ``description``: detailed OpenAPI description, default ``""``.
+- ``operation_id``: optional operation identifier, default ``None``.
+- ``deprecated``: deprecation flag, default ``False``.
+
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from aoa.action_machine.adapters.base_route_record import BaseRouteRecord
+
+# Allowed HTTP methods.
+_ALLOWED_METHODS: frozenset[str] = frozenset(
+    {
+        "GET",
+        "POST",
+        "PUT",
+        "DELETE",
+        "PATCH",
+    }
+)
+
+
+@dataclass(frozen=True)
+class FastApiRouteRecord(BaseRouteRecord):
+    """
+    AI-CORE-BEGIN
+        ROLE: Binds one action contract to one HTTP/OpenAPI endpoint declaration.
+        CONTRACT: Extends BaseRouteRecord with method/path/tags/docs metadata.
+        INVARIANTS: Frozen instance, validated method, validated path.
+        AI-CORE-END
+    """
+
+    # ── HTTP-specific fields ───────────────────────────────────────────
+
+    method: str = "POST"
+    path: str = "/"
+    tags: tuple[str, ...] = ()
+    summary: str = ""
+    description: str = ""
+    operation_id: str | None = None
+    deprecated: bool = False
+
+    # ── Validation ──────────────────────────────────────────────────────
+
+    def __post_init__(self) -> None:
+        """
+        Validate HTTP-specific invariants after instance construction.
+
+        Order:
+
+        1. Call ``super().__post_init__()`` to validate BaseRouteRecord
+           invariants (action class, mapper contracts, generic extraction).
+
+        2. Normalize method to uppercase.
+           Because this is a frozen dataclass, ``object.__setattr__`` is used.
+
+        3. Validate method against allowed set.
+
+        4. Validate non-empty path starting with ``/``.
+
+        Raises:
+            TypeError: from BaseRouteRecord when base invariants fail.
+            ValueError: from BaseRouteRecord mapper invariants, unsupported
+                method, empty path, or missing leading slash.
+        """
+        # ── 1. BaseRouteRecord invariants ──
+        super().__post_init__()
+
+        # ── 2. Method normalization ──
+        normalized_method = self.method.upper()
+        object.__setattr__(self, "method", normalized_method)
+
+        # ── 3. Method validation ──
+        if normalized_method not in _ALLOWED_METHODS:
+            allowed = ", ".join(sorted(_ALLOWED_METHODS))
+            raise ValueError(f"method must be one of: {allowed}. " f"Got: '{self.method}'.")
+
+        # ── 4. Path validation ──
+        if not self.path or not self.path.strip():
+            raise ValueError("path cannot be empty. " "Provide an endpoint path, for example '/api/v1/orders'.")
+
+        if not self.path.startswith("/"):
+            raise ValueError(f"path must start with '/'. " f"Got: '{self.path}'. " f"Use a path like '/{self.path}'.")