refactor(api): derive metadata from context in api.core helpers

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

Author: olivermeyer

src/aignostics_foundry_core/AGENTS.md

@@ -135,10 +135,10 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
   - `API_TAG_PUBLIC`, `API_TAG_AUTHENTICATED`, `API_TAG_ADMIN`, `API_TAG_INTERNAL`, `API_TAG_INTERNAL_ADMIN` — string constants for OpenAPI tagging
   - `create_public_router(module_tag, *, version, prefix, …)` — public (unauthenticated) router
   - `create_authenticated_router`, `create_admin_router`, `create_internal_router`, `create_internal_admin_router` — router factories that inject the appropriate `require_*` dependency from `api.auth`
-  - `build_api_metadata(title, description, author_name, author_email, repository_url, documentation_url, version)` — returns a `dict` suitable for `FastAPI(**metadata)`
-  - `build_versioned_api_tags(version_name, repository_url)` — OpenAPI tags for a single versioned sub-app
+  - `build_api_metadata(version=None, *, context=None)` — returns a `dict` suitable for `FastAPI(**metadata)`; derives title, description, author, and URLs from *context* (falls back to global context)
+  - `build_versioned_api_tags(version_name, *, context=None)` — OpenAPI tags for a single versioned sub-app; reads `repository_url` from *context*
   - `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
+  - `get_versioned_api_instances(versions, *, context=None)` — loads project modules (resolved via context), calls `build_api_metadata(context=ctx)` to configure each `FastAPI` instance, routes registered `VersionedAPIRouter` instances to the matching version
   - `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`)

src/aignostics_foundry_core/api/core.py

@@ -262,58 +262,53 @@ def create_internal_admin_router(
     return cast("APIRouter", VersionedAPIRouter(version, prefix=actual_prefix, tags=tags, dependencies=dependencies))
 
 
-def build_api_metadata(  # noqa: PLR0913, PLR0917
-    title: str,
-    description: str = "",
-    author_name: str = "",
-    author_email: str = "",
-    repository_url: str = "",
-    documentation_url: str = "",
-    version: str | None = None,
-) -> dict[str, Any]:
+def build_api_metadata(version: str | None = None, *, context: FoundryContext | None = None) -> dict[str, Any]:
     """Build a metadata dictionary suitable for passing to a FastAPI instance.
 
+    All fields (title, description, author, URLs) are derived from *context*.
+
     Args:
-        title: The API title (project name).
-        description: Human-readable description of the API.
-        author_name: Contact person or team name.
-        author_email: Contact email address.
-        repository_url: URL to the source repository.
-        documentation_url: URL to the documentation or terms of service.
         version: Optional API version string.
+        context: Project context supplying the title, description, author, and URLs.
+            When ``None``, the global context installed via
+            :func:`aignostics_foundry_core.foundry.set_context` is used.
 
     Returns:
         Dictionary containing FastAPI metadata keys.
     """
+    ctx = context or get_context()
     metadata: dict[str, Any] = {
-        "title": title,
-        "description": description,
+        "title": ctx.name,
+        "description": ctx.metadata.description,
         "contact": {
-            "name": author_name or "Unknown",
-            "email": author_email,
-            "url": repository_url,
+            "name": ctx.metadata.author_name or "Unknown",
+            "email": ctx.metadata.author_email or "",
+            "url": ctx.metadata.repository_url,
         },
-        "terms_of_service": documentation_url,
+        "terms_of_service": ctx.metadata.documentation_url,
         "license_info": {
             "name": "Aignostics Commercial License",
-            "url": f"{repository_url}/blob/main/LICENSE",
+            "url": f"{ctx.metadata.repository_url}/blob/main/LICENSE",
         },
     }
     if version is not None:
         metadata["version"] = version
     return metadata
 
 
-def build_versioned_api_tags(version_name: str, repository_url: str = "") -> list[dict[str, Any]]:
+def build_versioned_api_tags(version_name: str, *, context: FoundryContext | None = None) -> list[dict[str, Any]]:
     """Build ``openapi_tags`` for a versioned API instance.
 
     Args:
         version_name: The version name (e.g., "v1").
-        repository_url: URL to the source repository (used for external docs link).
+        context: Project context supplying the repository URL for the external docs link.
+            When ``None``, the global context installed via
+            :func:`aignostics_foundry_core.foundry.set_context` is used.
 
     Returns:
         List of OpenAPI tag dictionaries for the versioned API.
     """
+    repository_url = (context or get_context()).metadata.repository_url
     return [
         {
             "name": version_name,
@@ -351,7 +346,6 @@ def build_root_api_tags(base_url: str, versions: list[str]) -> list[dict[str, An
 
 def get_versioned_api_instances(
     versions: list[str],
-    build_metadata: dict[str, Any] | None = None,
     *,
     context: FoundryContext | None = None,
 ) -> dict[str, FastAPI]:
@@ -364,18 +358,19 @@ def get_versioned_api_instances(
 
     Args:
         versions: Ordered list of API version names (e.g., ``["v1", "v2"]``).
-        build_metadata: Optional extra kwargs forwarded to each ``FastAPI()`` constructor.
-        context: Project context supplying the package name.  When ``None``,
-            the global context installed via
-            :func:`aignostics_foundry_core.foundry.set_context` is used.
+        context: Project context supplying the package name, title, description, author,
+            and URLs for each ``FastAPI`` instance.  When ``None``, the global context
+            installed via :func:`aignostics_foundry_core.foundry.set_context` is used.
 
     Returns:
         Mapping from version name to its configured ``FastAPI`` instance.
     """
     from fastapi import FastAPI  # noqa: PLC0415
 
-    load_modules(context=context or get_context())
-    api_instances: dict[str, FastAPI] = {version: FastAPI(**(build_metadata or {})) for version in versions}
+    ctx = context or get_context()
+    load_modules(context=ctx)
+    api_metadata = build_api_metadata(context=ctx)
+    api_instances: dict[str, FastAPI] = {version: FastAPI(**api_metadata) for version in versions}
 
     for router in VersionedAPIRouter.get_instances():
         router_version: str = cast("Any", router).version

tests/aignostics_foundry_core/api/core_test.py

@@ -56,10 +56,10 @@ def test_api_tag_constants() -> None:
 
 @pytest.mark.unit
 def test_build_api_metadata_returns_dict_with_title() -> None:
-    """build_api_metadata returns a dict containing the title key."""
+    """build_api_metadata returns a dict containing the title derived from context."""
     from aignostics_foundry_core.api.core import build_api_metadata
 
-    result = build_api_metadata(title=TEST_TITLE, description="Test API", repository_url="https://example.com")
+    result = build_api_metadata(context=make_context(name=TEST_TITLE))
 
     assert isinstance(result, dict)
     assert result[TITLE_KEY] == TEST_TITLE
@@ -184,7 +184,7 @@ def test_build_api_metadata_includes_version_when_provided() -> None:
     """build_api_metadata adds a 'version' key when version is supplied."""
     from aignostics_foundry_core.api.core import build_api_metadata
 
-    result = build_api_metadata(title=TEST_TITLE, version=TEST_VERSION_STR)
+    result = build_api_metadata(version=TEST_VERSION_STR, context=make_context())
 
     assert result["version"] == TEST_VERSION_STR
 
@@ -194,13 +194,26 @@ def test_build_versioned_api_tags_returns_tag_for_version() -> None:
     """build_versioned_api_tags returns a single-element list with the correct name."""
     from aignostics_foundry_core.api.core import build_versioned_api_tags
 
-    tags = build_versioned_api_tags("v2", repository_url=BASE_URL)
+    tags = build_versioned_api_tags("v2", context=make_context(repository_url=BASE_URL))
 
     assert len(tags) == 1
     assert tags[0]["name"] == "v2"
     assert BASE_URL in tags[0]["externalDocs"]["url"]
 
 
+@pytest.mark.unit
+def test_build_api_metadata_contact_uses_context_author() -> None:
+    """build_api_metadata populates contact from context's PackageMetadata author fields."""
+    from aignostics_foundry_core.api.core import build_api_metadata
+    from aignostics_foundry_core.foundry import PackageMetadata
+
+    ctx = make_context(metadata=PackageMetadata(author_name="Ada", author_email="ada@example.com"))
+    result = build_api_metadata(context=ctx)
+
+    assert result["contact"]["name"] == "Ada"
+    assert result["contact"]["email"] == "ada@example.com"
+
+
 @pytest.mark.unit
 def test_build_root_api_tags_one_entry_per_version() -> None:
     """build_root_api_tags returns one tag dict per version with correct name and URL."""
@@ -217,7 +230,7 @@ def test_build_root_api_tags_one_entry_per_version() -> None:
 
 @pytest.mark.unit
 def test_get_versioned_api_instances_returns_fastapi_per_version() -> None:
-    """get_versioned_api_instances returns a FastAPI instance for each requested version."""
+    """get_versioned_api_instances returns a FastAPI instance with the context name as title."""
     from fastapi import FastAPI
 
     from aignostics_foundry_core.api.core import VersionedAPIRouter, get_versioned_api_instances
@@ -227,6 +240,7 @@ def test_get_versioned_api_instances_returns_fastapi_per_version() -> None:
 
     assert VERSION_GVI in result
     assert isinstance(result[VERSION_GVI], FastAPI)
+    assert result[VERSION_GVI].title == "aignostics_foundry_core"
 
 
 @pytest.mark.unit