aignostics-foundry-core 0.8.2

🏭 Foundational infrastructure for Foundry components.

🏭 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

Initialise the context at application startup

Call set_context() once, before any library code runs, then call boot() to initialise logging, the SSL trust chain, and optional Sentry integration:

# 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() derives everything from package metadata and environment variables:

• name, version, version_full — from importlib.metadata
• environment — from MYPROJECT_ENVIRONMENT → ENV → VERCEL_ENV → RAILWAY_ENVIRONMENT → "local"
• is_container, is_cli, is_test, is_library — detected automatically
• env_prefix ("MYPROJECT_") — used by every settings class in the library

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---run.12345 in staging

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

Pass context explicitly in tests

Never call set_context() in tests. Pass a FoundryContext directly to each function via its optional context parameter instead:

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.

Database

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(): ...

FoundryContext.from_package() activates database configuration automatically when the following environment variables are present:

Variable	Required	Description
{PREFIX}DB_URL	yes (to activate)	Full database connection URL
{PREFIX}DB_POOL_SIZE	no	Connection pool size (default 10)
{PREFIX}DB_MAX_OVERFLOW	no	Max pool overflow (default 10)
{PREFIX}DB_POOL_TIMEOUT	no	Pool wait timeout in seconds (default 30.0)
{PREFIX}DB_NAME	no	Override database name in the URL path

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"))

Health API

from aignostics_foundry_core.health import Health, HealthStatus

health = Health(status=HealthStatus.UP)

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