aignostics-foundry-core

🏭 Foundry Python Core

Foundational infrastructure for Foundry components.

Prerequisites

Install mise (task runner and dev tool manager):

brew install mise

Or follow the installation guide for other methods. Then activate mise in your shell profile.

Usage

Quickstart

FoundryContext is the single source of truth for all project-specific values. One call at application startup makes everything available library-wide — logging, Sentry, database settings, and more all derive from it automatically.

Initialise and boot

# main.py
from aignostics_foundry_core.foundry import FoundryContext, set_context
from aignostics_foundry_core.boot import boot

set_context(FoundryContext.from_package("myproject"))
boot()

FoundryContext.from_package("myproject") reads package metadata and environment variables to populate every field:

• name, version, version_full — from importlib.metadata
• environment — resolved from env vars in priority order (see Configuration reference below)
• env_prefix ("MYPROJECT_") — used by every settings class; all env vars for this project share this prefix
• is_container, is_cli, is_test, is_library — detected automatically

boot() initialises logging (loguru), amends the SSL trust chain (truststore + certifi), and optionally starts Sentry — all in one call.

Env file search order

Settings are loaded from the environment and from env files. Highest priority first:

1. .env.{environment}
2. .env
3. {MYPROJECT_ENV_FILE} (optional extra file; when the variable is set)
4. ~/.myproject/.env.{environment}
5. ~/.myproject/.env

Access the context from any module

from aignostics_foundry_core.foundry import get_context

ctx = get_context()
print(f"Running {ctx.name} v{ctx.version_full} in {ctx.environment}")
# → Running myproject v1.2.3+main-abc1234---run.12345---build.42 in staging

get_context() raises RuntimeError with a clear message if set_context() was never called.

Testing pattern

Never call set_context() in tests. Pass a FoundryContext directly to functions via their optional context parameter:

from aignostics_foundry_core.foundry import FoundryContext
from aignostics_foundry_core.log import logging_initialize

ctx = FoundryContext(name="myproject", version="0.0.0", version_full="0.0.0", environment="test")
logging_initialize(context=ctx)

All public library functions (logging_initialize, sentry_initialize, boot, load_modules, etc.) accept an optional context keyword argument and fall back to get_context() when it is None.

---

Configuration reference

All settings classes read from environment variables prefixed with {PREFIX} where {PREFIX} = MYPROJECT_ for a package named myproject.

Context & deployment environment

Read directly by FoundryContext.from_package() — no settings class.

Build metadata

Read by FoundryContext.from_package() to build version_full and version_with_vcs_ref. All optional; most useful in CI.

When any of these variables is set, version_full gains a +… suffix, e.g. 1.2.3+main-abc1234---run.12345---build.42.

Logging ({PREFIX}LOG_)

Settings class: LogSettings

logging_initialize() sets the stdlib loggers httpx, httpx2 and urllib3 to WARNING. These HTTP clients log each request URL at INFO, and the URL can contain credentials in its query string (for example, the signature of a signed URL). At WARNING, these request lines do not get to the log sinks or to Sentry. The psycopg and psycopg.pool loggers are also at WARNING.

Sentry ({PREFIX}SENTRY_)

Settings class: SentrySettings. Sentry is only initialised when ENABLED=true and DSN is set.

Log records do not go to Sentry Logs, because they can contain credentials and personal data. To send them, pass LoggingIntegration(capture_sentry_logs=True) or LoguruIntegration(capture_sentry_logs=True) to boot(sentry_integrations=...). foundry-core requires sentry-sdk 2.68.0 or later, and it has no {PREFIX}SENTRY_ENABLE_LOGS setting.

OpenTelemetry ({PREFIX}OTEL_)

Settings class: OTelSettings. OpenTelemetry is only initialised when ENABLED=true and the standard OTEL_EXPORTER_OTLP_ENDPOINT is set. Each signal is then independently toggleable — traces and metrics default on, logs off (their volume/cost profile differs). Telemetry is exported via OTLP/gRPC, e.g. to the internal OTel gateway backing the Grafana stack (Tempo/Loki/Prometheus).

The OTLP log sink uses the same {PREFIX}LOG_LEVEL as the stderr and file sinks. It also uses the log_filter that the service passes to boot(). Records below the log level, and records that the filter rejects, do not go to the OTLP endpoint.

Endpoint, service name, and all other exporter behaviour come from the standard, unprefixed OpenTelemetry environment variables the SDK reads itself — not project-prefixed settings:

Process-level tracing/metrics/logs are set up by boot(). boot() also applies default auto-instrumentors (HTTPX, SQLAlchemy) when traces are enabled — override via boot(otel_instrumentors=[...]), or pass [] to opt out. Request-level FastAPI spans are instrumented automatically too: init_api() applies instrument_fastapi() to the app it builds (and to every versioned sub-app) — no explicit call needed. A project that constructs its FastAPI instance some other way can call instrument_fastapi(app) directly, once, after construction.

Database ({PREFIX}DB_)

Settings class: DatabaseSettings. Database configuration is only activated when {PREFIX}DB_URL is present (in the environment or in an env file).

Once a context is configured via set_context(), all database functions work with no arguments — the URL and pool settings are read from the context:

from aignostics_foundry_core.database import init_engine, cli_run_with_db, with_engine

# Zero-arg engine init — reads MYPROJECT_DB_URL, _DB_POOL_SIZE, etc. from env
init_engine()

# CLI helper — initialises engine, runs coroutine, disposes engine
cli_run_with_db(my_async_func)


# Background job decorator — engine initialised before each invocation
@with_engine
async def my_job(): ...


# Override for a secondary database
@with_engine(db_url="postgresql+asyncpg://user:pass@host/secondary")
async def my_other_job(): ...

In tests, construct DatabaseSettings directly instead of setting env vars:

from aignostics_foundry_core.database import DatabaseSettings
from tests.conftest import make_context

ctx = make_context(database=DatabaseSettings(_env_prefix="TEST_DB_", url="sqlite+aiosqlite:///test.db"))

Authentication ({PREFIX}AUTH_)

Settings class: AuthSettings. All fields are optional with defaults unless enabled=True, which activates several cross-field requirements. Only needed when using aignostics_foundry_core.api.auth dependencies.

Console

Read directly from the environment — no settings class.

Further Reading

• Foundry Project Guide - Complete toolchain, testing, CI/CD, and project setup guide
• Security policy - Documentation of security checks, tools, and principles
• Release notes - Complete log of improvements and changes
• Attributions - Open source projects this project builds upon