feat(foundry): add PackageMetadata to FoundryContext

Introduces PackageMetadata (frozen Pydantic model) with description,
author_name, author_email, repository_url, and documentation_url fields.
PackageMetadata.from_name() populates all five from importlib.metadata.

FoundryContext.from_package() now delegates to PackageMetadata.from_name()
and exposes the result as ctx.metadata; the top-level repository_url /
documentation_url fields are removed from FoundryContext.

All callers (user_agent, sentry) updated to read from ctx.metadata.

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

Author: olivermeyer

ATTRIBUTIONS.md

@@ -360,7 +360,7 @@ SOFTWARE.
 
 ```
 
-## aignostics-foundry-core (0.7.0) - MIT License
+## aignostics-foundry-core (0.7.1) - MIT License
 
 🏭 Foundational infrastructure for Foundry components.
 

src/aignostics_foundry_core/AGENTS.md

@@ -23,7 +23,7 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
 | **user_agent** | Parameterised HTTP user-agent string builder | `user_agent(project_name, version, repository_url)` — builds `{project_name}-python-sdk/{version} (…)` string including platform info, current test, and GitHub Actions run URL                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | **gui** | NiceGUI page helpers, auth decorators, and nav builder | `GUINamespace` (configurable page decorator namespace), `gui` (default singleton), `page_public/authenticated/admin/internal/internal_admin` decorators, `get_gui_user`, `require_gui_user`, `BaseNavBuilder`, `NavItem`, `NavGroup`, `gui_get_nav_groups(*, context=None)`, `BasePageBuilder`, `gui_register_pages(*, context=None)`, `gui_run(*, context=None, …)`; constants `WINDOW_SIZE`, `BROWSER_RECONNECT_TIMEOUT`, `RESPONSE_TIMEOUT`                                                                                                                                                                                             |
 | **console** | Themed terminal output | Module-level `console` object (Rich `Console`) with colour theme and `_get_console()` factory                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| **foundry** | Project context injection | `FoundryContext`, `FoundryContext.from_package()`, `set_context()`, `get_context()` — centralised project-specific values (name, version, `version_full`, `version_with_vcs_ref`, environment, env files, URLs, `python_version`, runtime mode flags `is_container`, `is_cli`, `is_test`, `is_library`, `database: DatabaseSettings \| None`) derived from package metadata and environment variables; `from_package()` populates `database` from `{env_prefix}DB_*` env vars when `{env_prefix}DB_URL` is present                                                                                                                         |
+| **foundry** | Project context injection | `PackageMetadata`, `FoundryContext`, `FoundryContext.from_package()`, `set_context()`, `get_context()` — centralised project-specific values (name, version, `version_full`, `version_with_vcs_ref`, environment, env files, URLs, `python_version`, `metadata: PackageMetadata` (description, author_name, author_email), runtime mode flags `is_container`, `is_cli`, `is_test`, `is_library`, `database: DatabaseSettings \| None`) derived from package metadata and environment variables; `from_package()` populates `metadata` from `importlib.metadata` and `database` from `{env_prefix}DB_*` env vars when `{env_prefix}DB_URL` is present                                                                                                                         |
 | **di** | Dependency injection | `locate_subclasses(cls, *, context=None)`, `locate_implementations(cls, *, context=None)`, `load_modules(*, context=None)`, `discover_plugin_packages`, `clear_caches`, `PLUGIN_ENTRY_POINT_GROUP` for plugin and subclass discovery                                                                                                                                                                                                                                                                                                                                                                                                       |
 | **health** | Service health checks | `Health` model and `HealthStatus` enum for tree-structured health status                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | **settings** | Pydantic settings loading | `OpaqueSettings`, `load_settings`, `strip_to_none_before_validator`, `UNHIDE_SENSITIVE_INFO` for env-based settings with secret masking and user-friendly validation errors; `console`, `Panel`, and `Text` are imported lazily inside `load_settings` (error path only)                                                                                                                                                                                                                                                                                                                                                                   |
@@ -41,16 +41,25 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
   application startup makes the context available everywhere in the library without threading values
   through call sites. Tests pass an explicit context override and never touch global state.
 - **Key Features**:
+  - `PackageMetadata(BaseModel)` — frozen; fields: `description: str = ""`,
+    `author_name: str | None = None`, `author_email: str | None = None`,
+    `repository_url: str = ""`, `documentation_url: str = ""`.
+    Constructor: `PackageMetadata.from_name(package_name)` — reads all five fields from
+    `importlib.metadata` (``Summary``, ``Author-email``, ``Project-URL``).
+    Defaults to empty values for direct construction (e.g. in tests).
   - `FoundryContext(BaseModel)` — frozen; fields: `name`, `version`, `version_full`, `version_with_vcs_ref`, `environment`,
-    `env_file: list[Path]`, `repository_url`, `documentation_url`, `python_version` (Python runtime
-    version string, e.g. `"3.11.9"`), plus four runtime mode bool flags: `is_container`, `is_cli`,
+    `env_file: list[Path]`, `env_prefix`, `python_version` (Python runtime version string,
+    e.g. `"3.11.9"`), `metadata: PackageMetadata` (all package-derived fields: description,
+    author, URLs; populated by `from_package()` via `PackageMetadata.from_name()`; defaults to
+    empty `PackageMetadata()`), plus four runtime mode bool flags: `is_container`, `is_cli`,
     `is_test`, `is_library` (all default `False`), and `database: DatabaseSettings | None`
     (populated by `from_package()` when `{env_prefix}DB_URL` is set; `None` otherwise).
   - `FoundryContext.from_package(package_name)` — classmethod that derives all values from
     `importlib.metadata` and environment variables (`{NAME}_ENVIRONMENT`, `VCS_REF`, `COMMIT_SHA`,
     `BUILDER`, `BUILD_DATE`, `CI_RUN_ID`, `CI_RUN_NUMBER`, `{NAME}_ENV_FILE`,
     `{NAME}_RUNNING_IN_CONTAINER`, `PYTEST_RUNNING_{NAME}`). Environment fallback chain:
     `{NAME}_ENVIRONMENT` → `ENV` → `VERCEL_ENV` → `RAILWAY_ENVIRONMENT` → `"local"`.
+    Calls `PackageMetadata.from_name(package_name)` to populate `ctx.metadata`.
     Also checks `{NAME}_DB_URL`: when present, constructs `DatabaseSettings(_env_prefix="{NAME}_DB_")`
     and stores it in `ctx.database`; otherwise `ctx.database` is `None`.
   - `set_context(ctx)` — installs *ctx* as the process-level singleton.

src/aignostics_foundry_core/foundry.py

@@ -37,6 +37,57 @@ def _empty_path_list() -> list[Path]:
     return []
 
 
+class PackageMetadata(BaseModel):
+    """All package-derived metadata: description, author, and project URLs.
+
+    Populated via :meth:`from_name` from ``importlib.metadata``.
+    Defaults to empty/``None`` values so contexts constructed directly (e.g. in tests)
+    work without any extra setup.
+    """
+
+    model_config = {"frozen": True}
+
+    description: str = ""
+    author_name: str | None = None
+    author_email: str | None = None
+    repository_url: str = ""
+    documentation_url: str = ""
+
+    @classmethod
+    def from_name(cls, package_name: str) -> PackageMetadata:
+        """Return a :class:`PackageMetadata` populated from installed package metadata.
+
+        Reads ``Summary``, ``Author-email``, and ``Project-URL`` entries from
+        ``importlib.metadata`` for *package_name*.
+
+        Args:
+            package_name: The importable package name (e.g. ``"aignostics_foundry_core"``).
+
+        Returns:
+            A fully populated, frozen :class:`PackageMetadata` instance.
+        """
+        pkg_meta = metadata.metadata(package_name)
+        authors = pkg_meta.get_all("Author-email") or []
+        author = authors[0] if authors else None
+        author_name = author.split("<")[0].strip() if author else None
+        author_email = author.split("<")[1].strip(" >") if author else None
+        description = pkg_meta.get("Summary") or ""
+        repository_url = ""
+        documentation_url = ""
+        for url_entry in pkg_meta.get_all("Project-URL") or []:
+            if url_entry.startswith("Source"):
+                repository_url = url_entry.split(", ", 1)[1]
+            elif url_entry.startswith("Documentation"):
+                documentation_url = url_entry.split(", ", 1)[1]
+        return cls(
+            description=description,
+            author_name=author_name,
+            author_email=author_email,
+            repository_url=repository_url,
+            documentation_url=documentation_url,
+        )
+
+
 class FoundryContext(BaseModel):
     """Immutable project context carrying all project-specific values.
 
@@ -71,14 +122,18 @@ class FoundryContext(BaseModel):
     environment: str
     env_file: list[Path] = Field(default_factory=_empty_path_list)
     env_prefix: str = ""
-    repository_url: str = ""
-    documentation_url: str = ""
     is_container: bool = False
     is_cli: bool = False
     is_test: bool = False
     is_library: bool = False
     python_version: str = ""
     project_path: Path | None = None
+    metadata: PackageMetadata = Field(default_factory=PackageMetadata)
+    """Package-derived author and description metadata.
+
+    Populated by :meth:`from_package` from ``importlib.metadata``.
+    Defaults to empty values when the context is constructed directly (e.g. in tests).
+    """
     database: DatabaseSettings | None = None
     """Database settings resolved from ``{env_prefix}DB_*`` environment variables.
 
@@ -119,7 +174,6 @@ def from_package(cls, package_name: str) -> FoundryContext:
         name_upper = name.upper()
         version = metadata.version(package_name)
         environment = _detect_environment(name_upper)
-        repository_url, documentation_url = _extract_urls(package_name)
         project_path = _find_project_path(package_name)
         vcs_ref = os.environ.get("VCS_REF") or (project_path and _get_vcs_ref_from_git(project_path)) or "unknown"
         env_prefix = f"{name_upper}_"
@@ -138,8 +192,7 @@ def from_package(cls, package_name: str) -> FoundryContext:
             environment=environment,
             env_file=env_files,
             env_prefix=env_prefix,
-            repository_url=repository_url,
-            documentation_url=documentation_url,
+            metadata=PackageMetadata.from_name(package_name),
             python_version=platform.python_version(),
             project_path=project_path,
             database=database,
@@ -284,19 +337,6 @@ def _any_env_file_has(key: str, env_files: list[Path]) -> bool:
     return any(key in dotenv_values(f) for f in env_files if f.is_file())
 
 
-def _extract_urls(package_name: str) -> tuple[str, str]:
-    """Return ``(repository_url, documentation_url)`` from package metadata."""
-    pkg_metadata = metadata.metadata(package_name)
-    repository_url = ""
-    documentation_url = ""
-    for url_entry in pkg_metadata.get_all("Project-URL") or []:
-        if url_entry.startswith("Source"):
-            repository_url = url_entry.split(", ", 1)[1]
-        elif url_entry.startswith("Documentation"):
-            documentation_url = url_entry.split(", ", 1)[1]
-    return repository_url, documentation_url
-
-
 def _build_runtime_flags(name: str, name_upper: str) -> dict[str, bool]:
     """Compute runtime mode flags from environment and process state.
 

src/aignostics_foundry_core/sentry.py

@@ -275,8 +275,8 @@ def sentry_initialize(
         "aignx/base",
         {
             "project_name": ctx.name,
-            "repository_url": ctx.repository_url,
-            "documentation_url": ctx.documentation_url,
+            "repository_url": ctx.metadata.repository_url,
+            "documentation_url": ctx.metadata.documentation_url,
             "version_full": ctx.version_full,
             "in_container": ctx.is_container,
             "test_mode": ctx.is_test,

src/aignostics_foundry_core/user_agent.py

@@ -42,6 +42,6 @@ def user_agent(*, context: "FoundryContext | None" = None) -> str:
     # Format: {project}-python-sdk/{version_full} ({platform}; +{repository_url}; {optional_parts})
     # TODO(oliverm): Find a way to not hard code python-sdk here. This was taken as such from Bridge.
     base_info = f"{ctx.name}-python-sdk/{ctx.version_full}"
-    system_info = f"{platform.platform()}; +{ctx.repository_url}{optional_suffix}"
+    system_info = f"{platform.platform()}; +{ctx.metadata.repository_url}{optional_suffix}"
 
     return f"{base_info} ({system_info})"

tests/aignostics_foundry_core/foundry_test.py

@@ -14,7 +14,7 @@
 import pytest
 from pydantic import ValidationError
 
-from aignostics_foundry_core.foundry import FoundryContext, get_context, reset_context, set_context
+from aignostics_foundry_core.foundry import FoundryContext, PackageMetadata, get_context, reset_context, set_context
 from tests.conftest import make_context
 
 # Constants (SonarQube S1192)
@@ -38,6 +38,77 @@
 INIT_PY = "__init__.py"
 
 
+# ---------------------------------------------------------------------------
+# PackageMetadata — field defaults
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+def test_foundry_context_metadata_field_defaults() -> None:
+    """A directly-constructed FoundryContext has empty PackageMetadata defaults."""
+    ctx = make_context()
+    assert not ctx.metadata.description
+    assert ctx.metadata.author_name is None
+    assert ctx.metadata.author_email is None
+    assert not ctx.metadata.repository_url
+    assert not ctx.metadata.documentation_url
+
+
+# ---------------------------------------------------------------------------
+# PackageMetadata.from_name() — detail assertions
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+def test_package_metadata_from_name_description() -> None:
+    """PackageMetadata.from_name() returns a non-empty description (Summary field)."""
+    pkg_meta = PackageMetadata.from_name(PACKAGE_NAME)
+    assert isinstance(pkg_meta.description, str)
+    assert pkg_meta.description
+
+
+@pytest.mark.unit
+def test_package_metadata_from_name_author_name() -> None:
+    """PackageMetadata.from_name() returns a non-None, non-empty author_name."""
+    pkg_meta = PackageMetadata.from_name(PACKAGE_NAME)
+    assert pkg_meta.author_name is not None
+    assert pkg_meta.author_name
+
+
+@pytest.mark.unit
+def test_package_metadata_from_name_author_email() -> None:
+    """PackageMetadata.from_name() returns a non-None author_email containing '@'."""
+    pkg_meta = PackageMetadata.from_name(PACKAGE_NAME)
+    assert pkg_meta.author_email is not None
+    assert "@" in pkg_meta.author_email
+
+
+@pytest.mark.unit
+def test_package_metadata_from_name_repository_url() -> None:
+    """PackageMetadata.from_name() returns a non-empty repository_url (Source URL)."""
+    pkg_meta = PackageMetadata.from_name(PACKAGE_NAME)
+    assert pkg_meta.repository_url
+
+
+@pytest.mark.unit
+def test_package_metadata_from_name_documentation_url() -> None:
+    """PackageMetadata.from_name() returns a non-empty documentation_url (Documentation URL)."""
+    pkg_meta = PackageMetadata.from_name(PACKAGE_NAME)
+    assert pkg_meta.documentation_url
+
+
+# ---------------------------------------------------------------------------
+# from_package() — wires metadata via PackageMetadata.from_name()
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.unit
+def test_from_package_metadata_is_package_metadata_instance() -> None:
+    """from_package() sets .metadata to a PackageMetadata populated via from_name()."""
+    ctx = FoundryContext.from_package(PACKAGE_NAME)
+    assert ctx.metadata == PackageMetadata.from_name(PACKAGE_NAME)
+
+
 @pytest.fixture(autouse=True)
 def _reset_context() -> Generator[None, None, None]:  # pyright: ignore[reportUnusedFunction]
     """Reset global _context to None before and after every test.

tests/aignostics_foundry_core/user_agent_test.py

@@ -55,7 +55,6 @@ def test_user_agent_uses_version_full(self, monkeypatch: pytest.MonkeyPatch) ->
             version_full=CTX_VERSION_FULL,
             version_with_vcs_ref=CTX_VERSION,
             environment="test",
-            repository_url=CTX_REPOSITORY_URL,
         )
         result = user_agent(context=ctx)
 

tests/conftest.py

@@ -8,7 +8,7 @@
 import pytest
 
 from aignostics_foundry_core.database import DatabaseSettings
-from aignostics_foundry_core.foundry import FoundryContext
+from aignostics_foundry_core.foundry import FoundryContext, PackageMetadata
 
 __all__ = ["make_context"]
 
@@ -71,6 +71,7 @@ def make_context(  # noqa: PLR0913
     repository_url: str = "",
     database: DatabaseSettings | None = None,
     env_file: list[Path] | None = None,
+    metadata: PackageMetadata | None = None,
     **kwargs: bool,
 ) -> FoundryContext:
     """Create a minimal FoundryContext for testing.
@@ -81,13 +82,18 @@ def make_context(  # noqa: PLR0913
         version: The version string (defaults to ``"0.0.0"``).
         environment: The deployment environment (defaults to ``"test"``).
         project_path: Optional path to the project root.
-        repository_url: The project repository URL (defaults to ``""``).
+        repository_url: Shorthand to set ``metadata.repository_url`` when *metadata* is
+            not provided.  Ignored when *metadata* is supplied explicitly.
         database: Optional :class:`~aignostics_foundry_core.database.DatabaseSettings`
             instance to attach to the context.
         env_file: Optional list of ``.env`` file paths to attach to the context.
+        metadata: Optional :class:`~aignostics_foundry_core.foundry.PackageMetadata`
+            to attach to the context.  When ``None``, a ``PackageMetadata`` with
+            ``repository_url`` set from the *repository_url* argument is used.
         **kwargs: Optional boolean flags forwarded to :class:`FoundryContext`
             (``is_test``, ``is_cli``, ``is_container``, ``is_library``).
     """
+    resolved_metadata = metadata if metadata is not None else PackageMetadata(repository_url=repository_url)
     return FoundryContext(
         name=name,
         version=version,
@@ -96,8 +102,8 @@ def make_context(  # noqa: PLR0913
         environment=environment,
         env_prefix=env_prefix,
         project_path=project_path,
-        repository_url=repository_url,
         database=database,
         env_file=env_file or [],
+        metadata=resolved_metadata,
         **kwargs,  # type: ignore[arg-type]
     )