# Configuration Subpackage

**Parent**: [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md)

Centralized configuration via pydantic-settings BaseSettings. Automatic priority:
**CLI > env vars > opendeviationbar.toml > defaults**.

---

## File Map

| File            | Purpose                                               | Env Prefix                    |
| --------------- | ----------------------------------------------------- | ----------------------------- |
| `settings.py`   | `Settings` singleton (`get()`, `reload()`)            | —                             |
| `population.py` | Cache population knobs + feature toggles (Issue #128) | `OPENDEVIATIONBAR_`           |
| `monitoring.py` | Telegram, gap-backfill thresholds, environment        | `OPENDEVIATIONBAR_`           |
| `clickhouse.py` | ClickHouse host, port, mode, tunnel                   | `OPENDEVIATIONBAR_CH_`        |
| `sidecar.py`    | Streaming sidecar watchdog, backpressure              | `OPENDEVIATIONBAR_STREAMING_` |
| `algorithm.py`  | Rust AlgorithmConfig subset (batch size, memory opt)  | `OPENDEVIATIONBAR_ALGORITHM_` |
| `streaming.py`  | Rust StreamingConfig (channels, circuit breaker)      | `OPENDEVIATIONBAR_STREAMING_` |
| `redis.py`      | Redis write lock config (Issue #158 Phase 7)          | `OPENDEVIATIONBAR_REDIS_`     |
| `cli_models.py` | Pydantic CliApp models (Populate subcommands)         | `OPENDEVIATIONBAR_`           |
| `__init__.py`   | Re-exports: Settings, PopulationConfig, ...           | —                             |

---

## Configuration Priority (Automatic)

    1. CLI flags           opendeviationbar populate range --hurst --threshold 500
    2. Environment vars    OPENDEVIATIONBAR_COMPUTE_HURST=true  (from .mise.toml)
    3. TOML config file    opendeviationbar.toml [population] compute_hurst = true
    4. Model defaults      compute_hurst: bool = False

No manual wiring — pydantic-settings handles the cascade.

---

## Settings Singleton

    from opendeviationbar.config import Settings

    s = Settings.get()              # Thread-safe, cached
    s.population.compute_tier2      # True
    s.clickhouse.host               # "localhost"
    s.sidecar.watchdog_timeout_s    # 600
    s.algorithm.processing_batch_size  # 100000
    s.streaming.circuit_breaker_threshold  # 0.5

    Settings.reload()               # Re-read from env
    Settings.reload_and_clear()     # + clear threshold cache (Issue #126)

---

## Related

- [/CLAUDE.md](/CLAUDE.md) - Project hub
- [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) - Python API layer
- [/python/opendeviationbar/clickhouse/CLAUDE.md](/python/opendeviationbar/clickhouse/CLAUDE.md) - ClickHouse cache
- [/scripts/CLAUDE.md](/scripts/CLAUDE.md) - Pueue ops, per-year parallelization
