Why Financial Dynamics?

Most regime detection tools are either black-box neural networks or simplistic threshold rules. Financial Dynamics sits in the sweet spot: fully transparent Bayesian inference with production-grade engineering.

Every probability is traceable. Every transition is explainable. Every signal has a clear mathematical origin.

                         ┌─────────────────────────────────┐
                         │     Financial Dynamics Model     │
                         └────────────────┬────────────────┘
                                          │
              ┌───────────────────────────┼───────────────────────────┐
              │                           │                           │
     ┌────────▼────────┐        ┌────────▼────────┐        ┌────────▼────────┐
     │   Python API    │        │   Streamlit App  │        │    CLI Tools    │
     │                 │        │                  │        │                 │
     │ pipeline.run()  │        │  Interactive 3D  │        │  run_pipeline   │
     │ pipeline.step() │        │  Live Charts     │        │  run_backtest   │
     │ pipeline.fore-  │        │  Signal Feed     │        │  run_calibrate  │
     │   cast()        │        │  Forecasts       │        │  run_benchmark  │
     └─────────────────┘        └──────────────────┘        └─────────────────┘

Installation

# Core library
pip install financial-dynamics

# With live data (yfinance)
pip install financial-dynamics[data]

# Full dashboard (Streamlit + Plotly + yfinance)
pip install financial-dynamics[dashboard]

# Everything including dev tools
pip install financial-dynamics[all]

Or from source:

git clone https://github.com/jmiaie/financial-dynamics-model.git
cd financial-dynamics-model
pip install -e ".[all]"

Quick Start

Interactive Dashboard

streamlit run app.py

Load any ticker (SPY, QQQ, AAPL, BTC-USD) and watch regime classification in real-time. Charts update instantly, forecasts auto-compute, signals fire as regimes shift.

Try it now: financial-dynamics-model.streamlit.app

Python API

from financial_dynamics import FinancialDynamicsPipeline
from financial_dynamics.data_loader import fetch_ohlcv

# Fetch data & run pipeline
df = fetch_ohlcv("SPY", period="1y", interval="1d")
pipeline = FinancialDynamicsPipeline()
results = pipeline.run(df)

# Current regime + confidence
current = results["risk_adjusted_regime"].iloc[-1]
confidence = results["post_prob_CALM_TREND"].iloc[-1]
print(f"Regime: {current} ({confidence:.1%} confidence)")

# Forecast next 10 bars
forecast = pipeline.forecast(horizon=10)
print(f"Expected duration: {forecast.expected_duration:.1f} bars")
print(f"Path: {' → '.join(r.name for r in forecast.most_likely_path[:5])}")

CLI

python scripts/run_pipeline.py --symbol SPY --period 1y --interval 1d
python scripts/run_backtest.py --data historical.csv --labels regimes.csv --rolling
python scripts/run_calibration.py --output calibrated.yaml
python scripts/run_benchmark.py --config config/default.yaml

Pipeline Architecture

 ╔══════════════════════════════════════════════════════════════╗
 ║                     RAW OHLCV DATA                          ║
 ╚══════════════════════════╦═══════════════════════════════════╝
                            ▼
 ┌──────────────────────────────────────────────────────────────┐
 │  PHASE 0 │ Feature Engineering                              │
 │          │ 5D normalized: vol · trend · drawdown · corr · shock │
 └──────────────────────────┬───────────────────────────────────┘
                            ▼
 ┌──────────────────────────────────────────────────────────────┐
 │  PHASE 1 │ Centroid Classification                          │
 │          │ P(Sᵢ|Xₜ) = exp(−‖Xₜ − Cᵢ‖ / τ) / Z             │
 └──────────────────────────┬───────────────────────────────────┘
                            ▼
 ┌──────────────────────────────────────────────────────────────┐
 │  PHASE 2 │ Bayesian Markov Transitions                      │
 │          │ P_post = P_centroid × T[prev, :] / Z              │
 │          │ Dirichlet prior · online learning                 │
 └──────────────────────────┬───────────────────────────────────┘
                            ▼
 ┌──────────────────────────────────────────────────────────────┐
 │  PHASE 3 │ Temporal Stabilization                           │
 │          │ Hysteresis · persistence · majority vote          │
 └──────────────────────────┬───────────────────────────────────┘
                            ▼
 ┌──────────────────────────────────────────────────────────────┐
 │  PHASE 4 │ Risk Conditioning                                │
 │          │ Risk-Off confirmation · overextension · chop loop │
 └──────────────────────────┬───────────────────────────────────┘
                            ▼
 ╔══════════════════════════════════════════════════════════════╗
 ║              REGIME + CONFIDENCE + FORECAST                  ║
 ╚══════════════════════════════════════════════════════════════╝

Market Regimes

3D Phase-Space Attractor Field

The interactive 3D visualization projects the 5D feature space onto 3 principal components, revealing the geometric structure of market regimes:

10 interactive toggles — enable/disable each layer independently. Drag to rotate, scroll to zoom, hover for details.

Configuration

All parameters in config/default.yaml:

features:
  volatility_span: 20          # EWMA lookback
  trend_window: 14             # Linear regression window
  drawdown_window: 60          # Rolling peak window
  normalization_method: zscore # zscore | minmax

regimes:
  temperature: 1.0             # Softmax temperature (lower = sharper)

transitions:
  prior_strength: 10.0         # Dirichlet prior concentration
  learning_rate: 0.05          # Bayesian update speed

stabilization:
  hysteresis_threshold: 0.15   # Min probability gap to flip
  min_persistence_bars: 5      # Bars before confirming change
  majority_vote_window: 10     # Rolling vote window

risk:
  riskoff_confirmation_count: 3  # Stressors needed for Risk-Off
  overextension_decay: 0.02      # Regime fatigue rate

Testing

pytest tests/ -v                          # All 229 tests
pytest tests/test_phase0_features.py -v   # Feature engineering
pytest tests/test_pipeline_integration.py # End-to-end
pytest tests/test_stress.py               # Numerical stability
pytest tests/test_visualization.py        # 3D rendering

Project Structure

src/financial_dynamics/
├── pipeline.py                  # Orchestrator (batch + streaming)
├── types.py                     # Regime, FeatureVector, BarState
├── config.py                    # Typed config + YAML loader
├── phase0_features/             # EWMA vol, trend, drawdown, corr, shock
├── phase1_regimes/              # Softmax centroid classification
├── phase2_transitions/          # Dirichlet-Bayesian Markov learning
├── phase3_stabilization/        # Hysteresis, persistence, majority vote
├── phase4_risk/                 # Risk-Off confirmation, overextension
├── visualization/               # 2D/3D phase-space, dashboard, trajectory
├── calibration/                 # Centroid fitting, hyperparameter tuning
├── backtesting/                 # Rolling-window evaluation
├── benchmarks/                  # Baseline classifiers
├── forecasting/                 # k-step regime forecasts
├── signals/                     # Regime change / risk detection
├── data_loader.py               # yfinance integration
└── persistence/                 # State serialization

app.py                           # Streamlit interactive dashboard
config/default.yaml              # All tunable parameters

Use Cases

Deployment

git push origin main

docker build -t financial-dynamics .
docker run -d -p 8501:8501 --restart unless-stopped financial-dynamics

Documentation

Contributing

Contributions welcome. Please open an issue first to discuss major changes.

git clone https://github.com/jmiaie/financial-dynamics-model.git
cd financial-dynamics-model
pip install -e ".[all]"
pytest tests/ -v

License

MIT — Jeff Milam & Micap.AI