feat(foundry): add FoundryContext and set_context()

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

Author: olivermeyer

ATTRIBUTIONS.md

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

docs/decisions/0003-project-context-injection.md

@@ -58,11 +58,11 @@ project_name = os.getenv("FOUNDRY_CORE_PROJECT_NAME")
 A one-time call at startup sets global library state; all functions then read from it. This is similar to configuration/init pattern used by logging libraries and the Sentry SDK.
 
 ```python
-foundry.set_context(project_name="bridge", version=__version__, ...)
+set_context(project_name="bridge", version=__version__, ...)
 locate_subclasses(BaseService)  # reads from global state
 
 def locate_subclasses(_class):
-    project_name = foundry.context.name
+    project_name = get_context().name
     ...
 ```
 
@@ -83,23 +83,23 @@ locate_subclasses(BaseService, context=ctx)
 * Pros: requirements #1 and #2 satisfied; typed; derivation logic lives once in the library
 * Cons: requirement #3 only partially satisfied — projects must hold and thread their own `context` reference to read derived values, which doesn't fully eliminate `_constants.py`
 
-**#5 `FoundryContext.from_package()` + `set_context()` + `foundry.context` accessor (combination of #3 and #4)**
+**#5 `FoundryContext.from_package()` + `set_context()` + `get_context()` (combination of #3 and #4)**
 
-Extends #4 with a `set_context()` call that stores the context as library-level state, exposed back to callers via `foundry.context`. Library functions fall back to the configured default but accept an explicit `context` override for testing.
+Extends #4 with a `set_context()` call that stores the context as library-level state, retrieved via `get_context()`. Library functions fall back to the configured default but accept an explicit `context` override for testing.
 
 ```python
 # at startup — replaces _constants.py entirely
-foundry.set_context(FoundryContext.from_package("bridge"))
+set_context(FoundryContext.from_package("bridge"))
 
 # library functions use the configured default
 locate_subclasses(BaseService)
 
 def locate_subclasses(_class: type, context: FoundryContext | None = None) -> list:
-    context = context or foundry.context
+    context = context or get_context()
     ...
 
 # projects read derived values back from the library
-print(foundry.context.version_full)
+print(get_context().version_full)
 
 # in tests — explicit override, no global state touched
 locate_subclasses(BaseService, context=FoundryContext(name="test-project", ...))
@@ -150,23 +150,30 @@ class FoundryContext(BaseModel):
 Each project calls `set_context()` once at startup. This single line replaces `_constants.py` entirely:
 
 ```python
-foundry.set_context(FoundryContext.from_package("bridge"))
+from aignostics_foundry_core.foundry import FoundryContext, set_context
+
+set_context(FoundryContext.from_package("bridge"))
 ```
 
-The configured `FoundryContext` is accessible anywhere via `foundry.context`:
+The configured `FoundryContext` is accessible anywhere via `get_context()`:
 
 ```python
+from aignostics_foundry_core.foundry import get_context
+
 # before: from bridge.utils._constants import __version_full__, __project_name__
 # after:
-foundry.context.version_full
-foundry.context.name
+get_context().version_full
+get_context().name
 ```
 
-All public library functions fall back to `foundry.context` but accept an explicit override:
+All public library functions fall back to `get_context()` but accept an explicit override:
 
 ```python
+from aignostics_foundry_core.foundry import get_context
+
+
 def locate_subclasses(_class: type, context: FoundryContext | None = None) -> list:
-    context = context or foundry.context
+    context = context or get_context()
     ...
 ```
 
@@ -197,13 +204,15 @@ At startup the subclass instance is passed to `set_context()` as usual:
 foundry.set_context(BridgeContext.from_package("bridge"))
 ```
 
-`foundry.context` is typed as `FoundryContext` — sufficient for all library functions. Project code that needs access to the extended fields keeps its own reference to the concrete instance:
+`get_context()` returns `FoundryContext` — sufficient for all library functions. Project code that needs access to the extended fields keeps its own reference to the concrete instance:
 
 ```python
+from aignostics_foundry_core.foundry import set_context
+
 bridge_context = BridgeContext.from_package("bridge")
-foundry.set_context(bridge_context)
+set_context(bridge_context)
 
-# library uses foundry.context (FoundryContext) — no project-specific fields needed
+# library uses get_context() → FoundryContext — no project-specific fields needed
 # project code uses bridge_context directly for its own extended fields
 bridge_context.tenant_id
 ```
@@ -212,9 +221,9 @@ This avoids module-level generics (which are awkward in Python) while keeping bo
 
 ## Consequences
 
-- `_constants.py` is eliminated entirely across all projects; derivation logic lives once in the library and derived values are read back via `foundry.context`.
+- `_constants.py` is eliminated entirely across all projects; derivation logic lives once in the library and derived values are read back via `get_context()`.
 - New projects (API servers and CLI tools alike) require a single `set_context()` call and no boilerplate.
 - Production call sites are clean — no context threading.
 - Tests can pass a `FoundryContext` directly without touching or resetting global state.
 - `SentryContext` nesting makes it clear that the mode flags are Sentry-specific and not general-purpose project metadata.
-- Projects that need additional fields subclass `FoundryContext` and pass their subclass to `configure()`; they hold their own typed reference for project-specific access.
+- Projects that need additional fields subclass `FoundryContext` and pass their subclass to `set_context()`; they hold their own typed reference for project-specific access.

src/aignostics_foundry_core/AGENTS.md

@@ -23,6 +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`, `BasePageBuilder`, `gui_register_pages`, `gui_run`; 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`, `SentryContext`, `FoundryContext.from_package()`, `set_context()`, `get_context()` — centralised project-specific values (name, version, environment, env files, URLs, Sentry flags) derived from package metadata and environment variables |
 | **di** | Dependency injection | `locate_subclasses`, `locate_implementations`, `load_modules`, `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 |
@@ -31,6 +32,49 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
 
 <!-- For each module, document its purpose, features, dependencies, and usage. -->
 
+### foundry
+
+**Project context injection — single startup call replaces all per-project `_constants.py` files**
+
+- **Purpose**: Provides `FoundryContext` — a frozen Pydantic model that owns all derivation logic for
+  project-specific values. One `set_context(FoundryContext.from_package("myproject"))` call at
+  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**:
+  - `SentryContext(BaseModel)` — frozen; four bool flags (`is_container`, `is_cli`, `is_test`,
+    `is_library`) all defaulting to `False`.
+  - `FoundryContext(BaseModel)` — frozen; fields: `name`, `version`, `version_full`, `environment`,
+    `env_file: list[Path]`, `repository_url`, `documentation_url`, `sentry: SentryContext`.
+  - `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"`.
+  - `set_context(ctx)` — installs *ctx* as the process-level singleton.
+  - `get_context()` — returns the installed context or raises `RuntimeError` with a helpful message
+    if `set_context()` has not been called.
+- **Location**: `aignostics_foundry_core/foundry.py`
+- **Dependencies**: `pydantic>=2`, Python stdlib (`importlib.metadata`, `os`, `sys`, `pathlib`)
+- **Import**:
+  ```python
+  from aignostics_foundry_core.foundry import FoundryContext, SentryContext, set_context, get_context
+  ```
+- **Usage example**:
+  ```python
+  # Application startup (e.g. main.py or boot.py):
+  from aignostics_foundry_core.foundry import FoundryContext, set_context, get_context
+
+  set_context(FoundryContext.from_package("myproject"))
+
+  # Library code — no threading of values through parameters:
+  ctx = get_context()  # raises RuntimeError if startup omitted set_context()
+  logger.info(f"Starting {ctx.name} {ctx.version} in {ctx.environment}")
+
+  # Tests — pass context explicitly, do not call set_context():
+  ctx = FoundryContext(name="test", version="0.0.0", version_full="0.0.0", environment="test")
+  result = my_library_function(context=ctx)
+  ```
+
 ### api.exceptions
 
 **API exception hierarchy and FastAPI exception handlers**