feat(api): add versions param to init_api()

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: olivermeyer

src/aignostics_foundry_core/AGENTS.md

@@ -125,7 +125,7 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
   - `build_versioned_api_tags(version_name, repository_url)` — OpenAPI tags for a single versioned sub-app
   - `build_root_api_tags(base_url, versions)` — OpenAPI tags for the root app linking to each version's docs
   - `get_versioned_api_instances(versions, build_metadata=None, *, context=None)` — loads project modules (resolved via context), creates one `FastAPI` per version, routes registered `VersionedAPIRouter` instances to the matching version
-  - `init_api(root_path, lifespan, exception_handler_registrations, **fastapi_kwargs)` — creates a `FastAPI` with the standard Foundry exception handlers (`ApiException`, `RequestValidationError`, `ValidationError`, `Exception`) pre-registered
+  - `init_api(root_path, lifespan, exception_handler_registrations, versions=None, version_exception_handler_registrations=None, **fastapi_kwargs)` — creates a `FastAPI` with the standard Foundry exception handlers (`ApiException`, `RequestValidationError`, `ValidationError`, `Exception`) pre-registered; when *versions* is supplied, calls `get_versioned_api_instances` internally, optionally applies *version_exception_handler_registrations* to each sub-app, and mounts them at `/{version}` on the root app
 - **Location**: `aignostics_foundry_core/api/core.py`
 - **Dependencies**: `fastapi>=0.110,<1` (mandatory); `aignostics_foundry_core.di` (`load_modules`)
 - **Import**: `from aignostics_foundry_core.api.core import VersionedAPIRouter, init_api, build_api_metadata, …` or `from aignostics_foundry_core.api import …`

src/aignostics_foundry_core/api/core.py

@@ -394,20 +394,30 @@ def init_api(
     root_path: str = "",
     lifespan: Any | None = None,  # noqa: ANN401
     exception_handler_registrations: list[tuple[type[Exception], Any]] | None = None,
+    versions: list[str] | None = None,
+    version_exception_handler_registrations: list[tuple[type[Exception], Any]] | None = None,
     **fastapi_kwargs: Any,  # noqa: ANN401
 ) -> FastAPI:
     """Initialise a FastAPI application with standard exception handlers.
 
     This is a generic factory that creates a ``FastAPI`` instance and registers
-    the standard Foundry exception handlers.  Versioned sub-application mounting
-    (Bridge-specific) is left to the caller; use ``get_versioned_api_instances``
-    and ``FastAPI.mount`` for that pattern.
+    the standard Foundry exception handlers.  When *versions* is supplied the
+    function also creates versioned sub-applications via
+    ``get_versioned_api_instances``, optionally applies per-version exception
+    handlers, and mounts each sub-app at ``/{version}`` on the root app.
 
     Args:
         root_path: ASGI root path (useful for reverse-proxy setups).
         lifespan: Optional async context manager for application lifespan.
         exception_handler_registrations: Additional ``(exc_class, handler)`` pairs
             to register before the standard handlers.
+        versions: Optional list of API version names (e.g. ``["v1", "v2"]``).
+            When provided, ``get_versioned_api_instances`` is called internally
+            and each resulting sub-app is mounted at ``/{version}`` on the root
+            app.
+        version_exception_handler_registrations: ``(exc_class, handler)`` pairs
+            to register on *every* versioned sub-app before mounting.  Only used
+            when *versions* is also provided.
         **fastapi_kwargs: Extra keyword arguments forwarded to ``FastAPI()``.
 
     Returns:
@@ -429,4 +439,11 @@ def init_api(
     api.add_exception_handler(exc_class_or_status_code=ValidationError, handler=validation_exception_handler)
     api.add_exception_handler(exc_class_or_status_code=Exception, handler=unhandled_exception_handler)
 
+    if versions:
+        versioned_apps = get_versioned_api_instances(versions)
+        for version_name, version_app in versioned_apps.items():
+            for exc_class, handler in version_exception_handler_registrations or []:
+                version_app.add_exception_handler(exc_class_or_status_code=exc_class, handler=handler)
+            api.mount(f"/{version_name}", version_app)
+
     return api

tests/aignostics_foundry_core/api/core_test.py

@@ -244,3 +244,73 @@ def handler(request: object, exc: Exception) -> None:
 
     assert isinstance(app, FastAPI)
     assert ValueError in app.exception_handlers
+
+
+VERSION_V1 = "v1"
+VERSION_V2 = "v2"
+MOUNT_PATH_V1 = "/v1"
+MOUNT_PATH_V2 = "/v2"
+
+
+@pytest.mark.unit
+def test_init_api_mounts_versioned_apps(monkeypatch: pytest.MonkeyPatch) -> None:
+    """init_api mounts each versioned sub-app at /{version} on the root app."""
+    from typing import Any
+
+    from fastapi import FastAPI
+    from starlette.routing import Mount
+
+    import aignostics_foundry_core.api.core as core_module
+    from aignostics_foundry_core.api.core import init_api
+
+    stub_v1 = FastAPI()
+    stub_v2 = FastAPI()
+
+    def fake_get_versioned(versions: list[str], **_: Any) -> dict[str, FastAPI]:  # noqa: ANN401
+        return {VERSION_V1: stub_v1, VERSION_V2: stub_v2}
+
+    monkeypatch.setattr(core_module, "get_versioned_api_instances", fake_get_versioned)
+
+    app = init_api(versions=[VERSION_V1, VERSION_V2])
+
+    mount_paths = [r.path for r in app.routes if isinstance(r, Mount)]
+    assert MOUNT_PATH_V1 in mount_paths
+    assert MOUNT_PATH_V2 in mount_paths
+
+
+@pytest.mark.unit
+def test_init_api_applies_version_exception_handlers(monkeypatch: pytest.MonkeyPatch) -> None:
+    """init_api applies version_exception_handler_registrations to each versioned sub-app."""
+    from typing import Any
+    from unittest.mock import MagicMock
+
+    import aignostics_foundry_core.api.core as core_module
+    from aignostics_foundry_core.api.core import init_api
+
+    stub_v1 = MagicMock()
+    stub_v2 = MagicMock()
+
+    def fake_get_versioned(versions: list[str], **_: Any) -> dict[str, MagicMock]:  # noqa: ANN401
+        return {VERSION_V1: stub_v1, VERSION_V2: stub_v2}
+
+    monkeypatch.setattr(core_module, "get_versioned_api_instances", fake_get_versioned)
+
+    def my_handler(request: object, exc: Exception) -> None: ...
+
+    init_api(versions=[VERSION_V1, VERSION_V2], version_exception_handler_registrations=[(ValueError, my_handler)])
+
+    stub_v1.add_exception_handler.assert_called_once_with(exc_class_or_status_code=ValueError, handler=my_handler)
+    stub_v2.add_exception_handler.assert_called_once_with(exc_class_or_status_code=ValueError, handler=my_handler)
+
+
+@pytest.mark.unit
+def test_init_api_without_versions_unchanged() -> None:
+    """init_api without versions adds no Mount routes (backward compatibility)."""
+    from starlette.routing import Mount
+
+    from aignostics_foundry_core.api.core import init_api
+
+    app = init_api()
+
+    mount_routes = [r for r in app.routes if isinstance(r, Mount)]
+    assert mount_routes == []