Config Module¶

forge.config — Typed, validated, layered configuration from environment variables, .env files, and TOML configuration files.

Overview¶

The Config module eliminates boilerplate config loading. It uses Pydantic v2 and pydantic-settings to provide a typed, validated configuration system with clear priority ordering.

Installation¶

The config module is part of the core forge-kaif package with no extra dependencies:

pip install forge-kaif

Quick Start¶

from forge.config import ForgeConfig

# Load config from environment + .env + defaults
config = ForgeConfig()

Config Priority¶

Values are resolved in the following order (highest priority first):

Environment variables (prefixed with FORGE_)
.env.{environment} (e.g., .env.production)
.env.local
.env
forge.config.toml
Module defaults

Key Features¶

Typed Access¶

config.environment       # str
config.debug             # bool
config.log.level         # str
config.ai.default_model  # str

Required Key Validation¶

from forge.config import require

require("DATABASE_URL", "OPENAI_API_KEY")
# Raises ConfigurationError with actionable message if missing

Secret Masking¶

Secret values are automatically masked in logs and error messages:

config.ai.openai_api_key
# Output: 'sk-...abc123'

Test Overrides¶

from forge.config import override

with override({"database.url": "sqlite:///:memory:"}):
    # Config is overridden within this context
    ...

TOML Loading¶

from forge.config import load_toml

settings = load_toml("forge.config.toml")

Configuration Schema¶

The full ForgeConfig model includes nested configurations for each module:

from forge.config import (
    ForgeConfig,
    LogConfig,
    AIConfig,
    RetryConfig,
    CacheConfig,
    HealthConfig,
)

API Reference¶

Config module — layered configuration with pydantic-settings and TOML support.

Provides the ForgeConfig model with automatic environment-variable binding via pydantic-settings, the ConfigModule lifecycle wrapper, and utilities for loading TOML files, dotenv files, and deep merging.

Functions:¶

deep_merge ¶

deep_merge(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]

Alias for :func:merge_config.

field_is_sensitive ¶

field_is_sensitive(name: str) -> bool

Return True if name suggests it holds a secret value.

is_secret ¶

is_secret(value: object) -> bool

Return True if value is or contains a secret.

Checks for SecretStr, SecretBytes, or any field name containing api_key, password, secret, token.

load_dotenv ¶

load_dotenv(path: str | Path) -> dict[str, str]

Load a .env file and return key-value pairs.

Supports: - KEY=value - KEY="quoted value" - KEY='single quoted value' - # comments - Values containing = signs (e.g. connection strings)

load_toml ¶

load_toml(path: str | Path) -> dict[str, Any]

Parse a TOML file and return its contents as a dict.

Raises¶

ConfigurationError If the file cannot be parsed or contains circular references.

mask_value ¶

mask_value(value: str | SecretStr | None) -> str

Return a masked representation of value suitable for logging.

Actual secret values are never exposed in log output.

merge_config ¶

merge_config(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]

Deep-merge overlay into base, returning a new dict.

Later values win. Nested dicts are merged recursively; all other values are replaced.

str_from_secret ¶

str_from_secret(value: SecretStr | None) -> str | None

Extract the plain-text string from a SecretStr, or return None.