circuitforge-core/docs/modules/config.md

config

Env-driven settings with .env file loading. Provides a base Settings class that products subclass to add their own fields.

from circuitforge_core.config import Settings

Design

Configuration follows a strict priority order: environment variables > .env file > defaults. This means Docker compose environment: overrides always win, which is essential for cloud vs local deployment switching without image rebuilds.

Base Settings

class Settings(BaseSettings):
    # Database
    db_path: str = "data/app.db"

    # LLM
    llm_config_path: str = "config/llm.yaml"

    # Tier system
    license_key: str | None = None
    cloud_mode: bool = False

    # Cloud
    cloud_data_root: str = "/devl/app-cloud-data"
    cloud_auth_bypass_ips: list[str] = []
    coordinator_url: str = "http://10.1.10.71:7700"

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

Extending in a product

# myproduct/app/core/config.py
from circuitforge_core.config import Settings as _BaseSettings

class Settings(_BaseSettings):
    # Product-specific settings
    max_pantry_items: int = 500
    barcode_timeout_ms: int = 5000
    recipe_corpus_path: str = "data/recipes.db"

    class Config(_BaseSettings.Config):
        env_prefix = "MYPRODUCT_"

.env file

Each product ships a .env.example (committed) and a .env (gitignored). The .env file is loaded automatically by the Settings class.

# .env.example
DB_PATH=data/app.db
CLOUD_MODE=false
LICENSE_KEY=

!!! tip "Never commit .env" .env files contain secrets and environment-specific paths. Always commit .env.example instead.

Singleton pattern

Products typically expose a cached get_settings() function:

from functools import lru_cache
from .config import Settings

@lru_cache(maxsize=1)
def get_settings() -> Settings:
    return Settings()

This ensures the .env file is only read once at startup, and all modules share the same settings instance.