Configuration Management

Overview

Lexigram uses hierarchical YAML configuration with LEX_ environment variable overrides and profile-based overlays. Config is discovered automatically from application.yaml in the project root.

Config Precedence

Lowest:   Code defaults in config dataclasses
          Base YAML (application.yaml)
          Profile YAML (application.{profile}.yaml)
          LEX_ env-var overrides
Highest:  LEX_ env-var overrides with __ nesting

YAML Structure

# application.yaml
app_name: my-app        # root fields on LexigramConfig
env: production         # development | staging | production | test
debug: false

db:                     # lexigram-sql section (config_key "db")
  backend:
    url: postgresql+asyncpg://user:pass@localhost:5432/mydb
  pool:
    max_size: 10

cache:
  service:
    default_backend: null
    default_serializer: json
  backends:
    - name: memory
      type: memory      # memory | redis | memcached
      default: true

Secrets use "${ENV_VAR}" interpolation, e.g. url: "${DATABASE_URL}". See application.example.yaml in the repo root for the full annotated reference.

Environment Variable Overrides

# LEX_<PACKAGE>__<FIELD> syntax — each extension declares its own prefix
LEX_SQL__BACKEND__URL=postgresql+asyncpg://prod:pass@host:5432/db
LEX_CACHE__ENABLED=true
LEX_DEBUG=true

Nested sections use double underscore:

LEX_SQL__POOL__MAX_SIZE=20
LEX_AI_LLM__PROVIDER=anthropic

Profile Overlays

export LEX_PROFILE=development
# Loads application.yaml + application.development.yaml

# application.development.yaml — overrides base values
debug: true
db:
  backend:
    url: sqlite+aiosqlite:///dev.db

Config in Providers

Providers don't resolve their own config — the boot pipeline injects it before register() runs:

class MyProvider(Provider):
    name = "my_service"
    config_key = "my_service"        # section in application.yaml
    config_model = MyServiceConfig   # both required together

    async def register(self, container: ContainerRegistrarProtocol) -> None:
        # self.config already populated via LexigramConfig.get_section()
        container.singleton(MyServiceProtocol, MyService(self.config))

Injection resolves LexigramConfig from the container and calls get_section(config_key, config_model) into provider.config. Raises ConfigurationError if config_model is missing or LexigramConfig isn't registered. Setting provider.config directly before boot skips injection.

Quick Reference

lexigram config show                       # Resolved config (secrets masked)
lexigram config show --reveal-secrets      # Unmasked
lexigram config validate                   # Validate against schemas
lexigram config doctor --env production    # Diagnose config issues
lexigram config env                        # Show env vars used
lexigram config diff --baseline a.yaml --compare b.yaml
lexigram config env-example                # Generate .env.example

Common Mistakes

• Assuming env vars override YAML — they do, but the LEX_ prefix is required
• Using wrong separator — double underscore __ for nesting, not .
• Confusing env: (deployment environment in YAML) with LEX_ENV/APP_ENV (the env var read by Environment.from_env())
• Embedding secrets in application.yaml — use ${VAR} interpolation or a secrets backend