Configuration Management & Profiles
Relevant source files
The following files were used as context for generating this wiki page:
Configuration management in the regime-detection project is a centralized system designed to govern the behavior of the RegimeEngine, its feature extraction layers, and the various operational scripts. The system uses Pydantic-based models for strict validation of parameters and YAML-based profiles to define specific execution environments (V1, V2, or specialized calibration profiles).
This system ensures that all tunable numbers, such as thresholds, weights, and window sizes, are externalized from the code to prevent "config smell" and ensure deterministic replay across different environments. Sources: AGENTS.md, src/regime_detection/config.py:1013-1055
Core Configuration Architecture
The architecture relies on a hierarchical structure of Pydantic models. The root configuration, RegimeConfig, aggregates sub-configurations for specific modules like HMM, GMM clustering, and various market state builders.
Configuration Hierarchy
The following diagram illustrates the relationship between the central configuration and its specialized modules:
The project uses load_default_regime_config() to initialize the engine with a standard set of parameters, while load_regime_config(path) allows for custom YAML profiles. Sources: src/regime_detection/config.py:1013-1055, scripts/run_v2_shadow_ab_gate.py:348-355
Operational Profiles and Runners
The system distinguishes between runtime classification and operational workflows like calibration and profiling. These workflows use specialized "manifests" and arguments to override or complement core configurations.
1. Calibration Profiles
Calibration scripts fit statistical models (HMM and GMM) on historical data to generate "candidate" artifacts. These artifacts include hmm_state_label_map.candidate.yaml and cluster_label_map.candidate.yaml, which require manual operator review to map mathematical states to economic labels (e.g., "calm_bull"). Sources: scripts/run_v2_calibration.py:1-25
2. Profiling & Performance Metrics
The profile_engine.py script measures the wall-clock performance of the RegimeEngine across different stages. It utilizes a StageTimer to track durations for market context building, feature store assembly, and timeline emission. Sources: scripts/profile_engine.py:100-140
| Stage Component | Measurement Logic | Purpose |
|---|---|---|
build_market_context | Wall-clock time | Measures data alignment and context initialization |
build_feature_store_total | Wall-clock time | Measures extraction of V2 features and model fitting |
build_regime_timeline_total | Wall-clock time | Measures the final emission of regime labels |
| Sources: scripts/profile_engine.py:465-485 |
Environment-Driven Tunables
To support flexibility in different deployment stages, the project uses lazy accessor functions for environment-variable-backed tunables. This ensures that overrides (e.g., via pytest monkeypatching) are respected regardless of import order.
# Pattern for lazy env accessors
def max_x() -> int:
return int(os.environ.get("PROJECT_MAX_X", "10"))
This approach avoids the use of module-level constants for hardcoded numbers, which is considered a "config smell" in the repository's operating discipline. Sources: AGENTS.md
Configuration Options Summary
The following table summarizes key configuration parameters defined in the core logic:
| Config Module | Parameter | Type | Default/Requirement |
|---|---|---|---|
| HMM | training_window_days | int | Defines historical span for state fitting |
| HMM | n_states | int | Number of hidden states to detect |
| Clustering | n_clusters | int | Number of clusters for GMM |
| CentralBankText | smoothing_window_sessions | int | 30 sessions (six weeks) |
| Global | as_of_date | dt.date | The reference date for deterministic classification |
| Sources: scripts/run_v2_calibration.py:53-70, scripts/profile_engine.py:155-165 |
Manifest-Based Data Loading
For operational scripts, the project employs a "manifest" system to resolve input paths for macro data, event calendars, and OHLCV trees. This decouples the scripts from local file systems and allows for reproducible runs across different environments.
The resolution process includes overrides for specific files like macro_parquet, pit_parquet, and event_calendar. Sources: scripts/profile_engine.py:315-345, scripts/run_v2_calibration.py:220-245
Conclusion
The configuration management system provides a robust framework for managing the complexity of V1 and V2 regime detection. By combining strict Pydantic validation, externalized YAML profiles, and lazy environment accessors, the project maintains high standards for deterministic replay and operational flexibility. Sources: AGENTS.md, src/regime_detection/config.py