feat(di): drop project_name, use context only

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

Author: olivermeyer

src/aignostics_foundry_core/api/core.py

@@ -6,9 +6,15 @@
 - API initialization and metadata building
 """
 
+from __future__ import annotations
+
 from typing import TYPE_CHECKING, Any, ClassVar, Self, cast
 
 from aignostics_foundry_core.di import load_modules
+from aignostics_foundry_core.foundry import get_context
+
+if TYPE_CHECKING:
+    from aignostics_foundry_core.foundry import FoundryContext
 
 from .exceptions import (
     AccessDeniedException,
@@ -50,10 +56,10 @@ class VersionedAPIRouter:
     """
 
     # Class variable to track all created instances
-    _instances: ClassVar[list["VersionedAPIRouter"]] = []
+    _instances: ClassVar[list[VersionedAPIRouter]] = []
 
     @classmethod
-    def get_instances(cls) -> list["VersionedAPIRouter"]:
+    def get_instances(cls) -> list[VersionedAPIRouter]:
         """Get all created router instances.
 
         Returns:
@@ -117,7 +123,7 @@ def create_public_router(
     prefix: str | None = None,
     extra_tags: list[str] | None = None,
     extra_dependencies: list[Any] | None = None,
-) -> "APIRouter":
+) -> APIRouter:
     """Create a public API router (no authentication required).
 
     Args:
@@ -143,7 +149,7 @@ def create_authenticated_router(
     prefix: str | None = None,
     extra_tags: list[str] | None = None,
     extra_dependencies: list[Any] | None = None,
-) -> "APIRouter":
+) -> APIRouter:
     """Create an authenticated API router (requires valid Auth0 session).
 
     Args:
@@ -173,7 +179,7 @@ def create_admin_router(
     prefix: str | None = None,
     extra_tags: list[str] | None = None,
     extra_dependencies: list[Any] | None = None,
-) -> "APIRouter":
+) -> APIRouter:
     """Create an admin API router (requires admin role).
 
     Args:
@@ -203,7 +209,7 @@ def create_internal_router(
     prefix: str | None = None,
     extra_tags: list[str] | None = None,
     extra_dependencies: list[Any] | None = None,
-) -> "APIRouter":
+) -> APIRouter:
     """Create an internal API router (requires internal org membership).
 
     Args:
@@ -233,7 +239,7 @@ def create_internal_admin_router(
     prefix: str | None = None,
     extra_tags: list[str] | None = None,
     extra_dependencies: list[Any] | None = None,
-) -> "APIRouter":
+) -> APIRouter:
     """Create an internal admin API router (requires internal org + admin role).
 
     Args:
@@ -344,28 +350,31 @@ def build_root_api_tags(base_url: str, versions: list[str]) -> list[dict[str, An
 
 
 def get_versioned_api_instances(
-    project_name: str,
     versions: list[str],
     build_metadata: dict[str, Any] | None = None,
-) -> "dict[str, FastAPI]":
+    *,
+    context: FoundryContext | None = None,
+) -> dict[str, FastAPI]:
     """Build per-version FastAPI instances and route registered routers to them.
 
-    Loads all modules in *project_name* so that ``VersionedAPIRouter`` instances
-    created at module import time are registered.  Each router whose ``version``
-    attribute matches a name in *versions* is included in the corresponding
+    Loads all modules in the configured project package so that ``VersionedAPIRouter``
+    instances created at module import time are registered.  Each router whose
+    ``version`` attribute matches a name in *versions* is included in the corresponding
     FastAPI sub-application.
 
     Args:
-        project_name: Package name whose modules should be loaded (to trigger router registration).
         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.
 
     Returns:
         Mapping from version name to its configured ``FastAPI`` instance.
     """
     from fastapi import FastAPI  # noqa: PLC0415
 
-    load_modules(project_name)
+    load_modules(context=context or get_context())
     api_instances: dict[str, FastAPI] = {version: FastAPI(**(build_metadata or {})) for version in versions}
 
     for router in VersionedAPIRouter.get_instances():
@@ -386,7 +395,7 @@ def init_api(
     lifespan: Any | None = None,  # noqa: ANN401
     exception_handler_registrations: list[tuple[type[Exception], Any]] | None = None,
     **fastapi_kwargs: Any,  # noqa: ANN401
-) -> "FastAPI":
+) -> FastAPI:
     """Initialise a FastAPI application with standard exception handlers.
 
     This is a generic factory that creates a ``FastAPI`` instance and registers

src/aignostics_foundry_core/cli.py

@@ -1,22 +1,31 @@
 """Command-line interface (CLI) utilities."""
 
+from __future__ import annotations
+
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import typer
 
 from aignostics_foundry_core.di import locate_implementations
+from aignostics_foundry_core.foundry import get_context
+
+if TYPE_CHECKING:
+    from aignostics_foundry_core.foundry import FoundryContext
 
 
-def prepare_cli(cli: typer.Typer, epilog: str, project_name: str) -> None:
+def prepare_cli(cli: typer.Typer, epilog: str, *, context: FoundryContext | None = None) -> None:
     """Dynamically locate, register and prepare subcommands.
 
     Args:
         cli (typer.Typer): Typer instance
         epilog (str): Epilog to add
-        project_name (str): Project name used for subcommand discovery
+        context: Project context used for subcommand discovery.  When ``None``,
+            the global context installed via
+            :func:`aignostics_foundry_core.foundry.set_context` is used.
     """
-    for sub_cli in locate_implementations(typer.Typer, project_name):
+    for sub_cli in locate_implementations(typer.Typer, context=context or get_context()):
         if sub_cli != cli:
             cli.add_typer(sub_cli)
 

src/aignostics_foundry_core/di.py

@@ -1,12 +1,20 @@
 """Dependency injection using dynamic import and discovery of implementations and subclasses."""
 
+from __future__ import annotations
+
 import importlib
 import pkgutil
-from collections.abc import Callable
 from functools import lru_cache
 from importlib.metadata import entry_points
 from inspect import isclass
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+from aignostics_foundry_core.foundry import get_context
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from aignostics_foundry_core.foundry import FoundryContext
 
 _implementation_cache: dict[tuple[Any, str], list[Any]] = {}
 _subclass_cache: dict[tuple[Any, str], list[Any]] = {}
@@ -32,15 +40,19 @@ def discover_plugin_packages() -> tuple[str, ...]:
     return tuple(ep.value for ep in eps)
 
 
-def load_modules(project_name: str) -> None:
-    """Import all top-level submodules of the given project package.
+def load_modules(*, context: FoundryContext | None = None) -> None:
+    """Import all top-level submodules of the configured project package.
 
     Args:
-        project_name: The importable package name to scan (e.g. ``"bridge"``).
+        context: Project context supplying the package name.  When ``None``,
+            the global context installed via :func:`aignostics_foundry_core.foundry.set_context`
+            is used; :func:`~aignostics_foundry_core.foundry.get_context` raises
+            ``RuntimeError`` if no context has been configured.
     """
-    package = importlib.import_module(project_name)
+    ctx = context or get_context()
+    package = importlib.import_module(ctx.name)
     for _, name, _ in pkgutil.iter_modules(package.__path__):
-        importlib.import_module(f"{project_name}.{name}")
+        importlib.import_module(f"{ctx.name}.{name}")
 
 
 def _scan_packages_deep(
@@ -117,27 +129,29 @@ def _scan_packages_shallow(
     return results
 
 
-def locate_implementations(_class: type[Any], project_name: str) -> list[Any]:
+def locate_implementations(_class: type[Any], *, context: FoundryContext | None = None) -> list[Any]:
     """Dynamically discover all instances of some class.
 
     Searches plugin top-level exports first (shallow scan), then deep-scans all
     submodules of the main project package. Plugins are registered via entry
     points; only their top-level ``__init__.py`` exports are examined (submodules
     are not walked). The main package retains full deep-scan behaviour.
 
-    Cache keys include *project_name* to avoid cross-project cache pollution when
-    multiple projects share this library.
+    Cache keys include the context name to avoid cross-project cache pollution
+    when multiple projects share this library.
 
     Args:
         _class: Class to search for.
-        project_name: Importable package name of the calling project
-            (e.g. ``"bridge"``). Used as the deep-scan root and as part of the
-            cache key.
+        context: Project context supplying the package name.  When ``None``,
+            the global context installed via :func:`aignostics_foundry_core.foundry.set_context`
+            is used; :func:`~aignostics_foundry_core.foundry.get_context` raises
+            ``RuntimeError`` if no context has been configured.
 
     Returns:
         List of discovered instances of the given class.
     """
-    cache_key = (_class, project_name)
+    ctx = context or get_context()
+    cache_key = (_class, ctx.name)
     if cache_key in _implementation_cache:
         return _implementation_cache[cache_key]
 
@@ -146,33 +160,35 @@ def predicate(member: object) -> bool:
 
     results = [
         *_scan_packages_shallow(discover_plugin_packages(), predicate),
-        *_scan_packages_deep(project_name, predicate),
+        *_scan_packages_deep(ctx.name, predicate),
     ]
     _implementation_cache[cache_key] = results
     return results
 
 
-def locate_subclasses(_class: type[Any], project_name: str) -> list[Any]:
+def locate_subclasses(_class: type[Any], *, context: FoundryContext | None = None) -> list[Any]:
     """Dynamically discover all classes that are subclasses of some type.
 
     Searches plugin top-level exports first (shallow scan), then deep-scans all
     submodules of the main project package. Plugins are registered via entry
     points; only their top-level ``__init__.py`` exports are examined (submodules
     are not walked). The main package retains full deep-scan behaviour.
 
-    Cache keys include *project_name* to avoid cross-project cache pollution when
-    multiple projects share this library.
+    Cache keys include the context name to avoid cross-project cache pollution
+    when multiple projects share this library.
 
     Args:
         _class: Parent class of subclasses to search for.
-        project_name: Importable package name of the calling project
-            (e.g. ``"bridge"``). Used as the deep-scan root and as part of the
-            cache key.
+        context: Project context supplying the package name.  When ``None``,
+            the global context installed via :func:`aignostics_foundry_core.foundry.set_context`
+            is used; :func:`~aignostics_foundry_core.foundry.get_context` raises
+            ``RuntimeError`` if no context has been configured.
 
     Returns:
         List of discovered subclasses of the given class.
     """
-    cache_key = (_class, project_name)
+    ctx = context or get_context()
+    cache_key = (_class, ctx.name)
     if cache_key in _subclass_cache:
         return _subclass_cache[cache_key]
 
@@ -181,7 +197,7 @@ def predicate(member: object) -> bool:
 
     results = [
         *_scan_packages_shallow(discover_plugin_packages(), predicate),
-        *_scan_packages_deep(project_name, predicate),
+        *_scan_packages_deep(ctx.name, predicate),
     ]
     _subclass_cache[cache_key] = results
     return results

src/aignostics_foundry_core/gui/core.py

@@ -7,14 +7,21 @@
 - Constants: WINDOW_SIZE, BROWSER_RECONNECT_TIMEOUT, RESPONSE_TIMEOUT
 """
 
-from abc import ABC, abstractmethod
-from collections.abc import Callable
-from typing import Any
+from __future__ import annotations
 
-from fastapi import FastAPI
-from fastapi.routing import APIRouter
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
 
 from aignostics_foundry_core.di import locate_subclasses
+from aignostics_foundry_core.foundry import get_context
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from fastapi import FastAPI
+    from fastapi.routing import APIRouter
+
+    from aignostics_foundry_core.foundry import FoundryContext
 
 WINDOW_SIZE = (1280, 768)
 BROWSER_RECONNECT_TIMEOUT = 60 * 60 * 24 * 7  # 7 days
@@ -42,16 +49,18 @@ def register_pages() -> None:
         """Register NiceGUI pages."""
 
 
-def gui_register_pages(project_name: str) -> None:
+def gui_register_pages(*, context: FoundryContext | None = None) -> None:
     """Register pages from all discovered PageBuilders.
 
-    Discovers all ``BasePageBuilder`` subclasses for the given project and calls
-    ``register_pages()`` on each one.
+    Discovers all ``BasePageBuilder`` subclasses for the configured project and
+    calls ``register_pages()`` on each one.
 
     Args:
-        project_name: Project name passed to locate_subclasses for discovery.
+        context: Project context used for PageBuilder discovery.  When ``None``,
+            the global context installed via
+            :func:`aignostics_foundry_core.foundry.set_context` is used.
     """
-    page_builders = locate_subclasses(BasePageBuilder, project_name)
+    page_builders = locate_subclasses(BasePageBuilder, context=context or get_context())
     for page_builder in page_builders:
         page_builder: BasePageBuilder  # type: ignore[no-redef]
         page_builder.register_pages()
@@ -103,7 +112,6 @@ def redirect_to_api_docs() -> RedirectResponse:  # pyright: ignore[reportUnusedF
 
 
 def gui_run(  # noqa: PLR0913, PLR0917
-    project_name: str,
     show: bool = False,
     host: str | None = None,
     port: int | None = None,
@@ -113,15 +121,17 @@ def gui_run(  # noqa: PLR0913, PLR0917
     auth_router: APIRouter | None = None,
     startup_callbacks: list[Callable[[], Any]] | None = None,
     shutdown_callbacks: list[Callable[[], Any]] | None = None,
+    *,
+    context: FoundryContext | None = None,
 ) -> None:
     """Start the NiceGUI application.
 
     Args:
-        project_name: Project name for page builder discovery.
         show: Whether to open a browser window on startup.
         host: Host to bind to. Defaults to NiceGUI's default.
         port: Port to listen on. Defaults to an open port found automatically.
-        title: Title shown in the browser tab. Defaults to ``project_name``.
+        title: Title shown in the browser tab. Defaults to the project name
+            from *context*.
         watch: Whether to reload on source file changes.
         fastapi_app: Optional FastAPI application to mount at ``/api``. When
             provided, ``/docs`` is redirected to ``/api/docs``, and the
@@ -133,18 +143,23 @@ def gui_run(  # noqa: PLR0913, PLR0917
             ``app.on_startup``. Use this to initialise a database engine etc.
         shutdown_callbacks: Optional list of callables registered via
             ``app.on_shutdown``. Use this to dispose resources on shutdown.
+        context: Project context used for page builder discovery and window
+            title.  When ``None``, the global context installed via
+            :func:`aignostics_foundry_core.foundry.set_context` is used.
     """
     from nicegui import app, ui  # noqa: PLC0415
     from nicegui import native as native_app  # noqa: PLC0415
 
+    ctx = context or get_context()
+
     _register_callbacks(app, startup_callbacks, shutdown_callbacks)
-    gui_register_pages(project_name)
+    gui_register_pages(context=ctx)
 
     if fastapi_app is not None:
         _mount_fastapi_app(app, fastapi_app, auth_router)
 
     ui.run(  # pyright: ignore[reportUnknownMemberType]
-        title=title or project_name,
+        title=title or ctx.name,
         native=False,
         reload=watch,
         host=host,