Main Classification Engine & Timeline
Relevant source files
The following files were used as context for generating this wiki page:
The Main Classification Engine & Timeline constitute the core execution layer of the regime detection system. This module is responsible for orchestrating the transition from raw market and macro data into structured economic regime classifications. It manages the temporal sequencing of data, applying deterministic rules and statistical models across a sliding window of time to produce a historical "timeline" of market environments.
The engine serves as the unified interface for both V1 and V2 detection logic, coordinating diverse input streams—such as price action (OHLCV), central bank sentiment, and network fragility—to output high-fidelity regime labels. By utilizing a structured RegimeTimeline, the system provides a continuous record of regime shifts, supporting both live classification and historical walk-forward analysis.
Sources: src/regime_detection/engine.py, src/regime_detection/models.py, TECH_DEBT_AUDIT.md
Engine Architecture
The architecture revolves around the RegimeEngine class, which acts as the primary orchestrator. It consumes a RegimeConfig to initialize detection parameters and provides two main entry points: classify for single-day labels and classify_window for multi-day timeline generation.
Execution Flow
The engine follows a strict sequence to transform data into regime outputs:
- Context Building: Aggregates raw data into a
MarketContext, which handles normalization and temporal alignment. - Feature Generation: Processes the context into a
FeatureStore, computing technical indicators and macro features. - Timeline Construction: Iterates through the requested sessions, applying axis-level rules and transition risk logic.
The flow represents the transformation of raw inputs into the final timeline artifact.
Sources: src/regime_detection/engine.py:46-104, scripts/profile_engine.py:1040-1070
Core Components
| Component | Description |
|---|---|
RegimeEngine | Public interface for executing classification logic. |
MarketContext | A unified container for all inputs (market data, macro series, event calendars). |
RegimeTimeline | A temporal collection of RegimeOutput objects representing a sequence of days. |
RegimeOutput | The final structured data model containing labels, evidence, and strategy responses. |
Sources: src/regime_detection/engine.py:38-44, src/regime_detection/models.py:539-586
Classification Logic & Timeline Generation
The engine generates a RegimeTimeline by processing data over a specified lookback_days window. This process ensures that regime shifts are detected with historical context, allowing for "stable" label logic where transitions require confirmation over multiple sessions.
Timeline Windowing
When classify_window is invoked, the engine calculates the necessary history required by various sub-models (e.g., HMM requires longer training windows than simple trend detection). It then slices the context to provide the minimum history needed for a valid classification at each step in the window.
The sequence shows how the engine orchestrates the timeline builder to iterate over multiple sessions.
Sources: src/regime_detection/engine.py:98-124, scripts/profile_engine.py:114-131
Data Requirements
The engine mandates certain inputs to ensure valid classification. Specifically, an event_calendar is required to compute structural causal states, such as option expiry or earnings dates.
def _require_event_calendar(event_calendar: pd.DataFrame | None) -> pd.DataFrame:
if event_calendar is None:
raise ValueError(
"event_calendar is required for RegimeEngine classification."
)
return event_calendar
Sources: src/regime_detection/engine.py:28-36
Data Models & Output Structure
The output of the engine is strictly typed using Pydantic models to ensure wire-compatibility and facilitate debugging.
RegimeOutput Model
The RegimeOutput is the primary artifact for a single session. It includes:
- Axis Outputs: Detailed objects for
trend_direction,volatility_state, andbreadth_state. - V2 Enrichments: Optional fields for
network_fragility,inflation_growth_state, andcredit_funding_statethat activate when V2 inputs are provided. - Transition Risk: A consolidated risk state (e.g.,
crisis,bear_stress) derived from axis combinations. - Strategy Response: Actionable trading constraints (e.g.,
leverage_allowed,position_size_multiplier).
Sources: src/regime_detection/models.py:539-573
Classification Status Reporting
The engine disambiguates between "Unknown" labels caused by no rules firing versus those caused by missing data or cold-starts. This is handled by the derive_classification_status function.
| Status | Meaning |
|---|---|
classified | A valid regime label was determined by the rules. |
no_rule_fired | Data was present, but no specific regime criteria were met. |
data_unavailable | Critical input data was missing for the classification date. |
insufficient_history | The session is in a cold-start period (e.g., first few days of a 50d MA). |
Sources: src/regime_detection/models.py:101-125
V2 Walk-forward & Gating
The engine supports walk-forward analysis through specialized scripts like run_v2_walkforward_gate.py. This allows developers to compare the performance and activation rates of V2 features against the V1 baseline over a multi-year out-of-sample window.
Gate Metrics
During walk-forward runs, the engine tallies "activations"—the frequency with which specific V2 axes (like Network Fragility or Monetary Pressure) produce a non-null classification.
Diagram showing the comparative logic used to validate V2 engine enhancements.
Sources: scripts/run_v2_walkforward_gate.py:126-170, scripts/run_v2_walkforward_gate.py:199-231
Conclusion
The Main Classification Engine & Timeline provide the foundational infrastructure for transforming heterogeneous financial data into a structured temporal record of market regimes. By isolating the orchestration logic within the RegimeEngine and enforcing strict Pydantic data models for the RegimeTimeline, the system ensures that regime detection remains deterministic, auditable, and extensible as new V2 feature slices are integrated.