# vahini-1/hsmm-state-detection architecture

> Architecture diagram of the GitHub repository vahini-1/hsmm-state-detection, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vahini-1/hsmm-state-detection
- Repository: https://github.com/vahini-1/hsmm-state-detection

## Overview

This is a quantitative regime-research framework: market data is turned into return/volatility features, modeled with offline HSMM inference or online particle filtering, then used for regime diagnostics, MS-VAR impulse responses, and strategy backtests. Its C++ engine provides explicit-duration HSMM primitives through a Python binding; Python also provides a Gibbs-sampling alternative and the broader research workflow. The README documents phase relationships, while several implementation details—especially unsampled CLI wiring and offline changepoint algorithms—are not independently verified here.

Main entry points: [`python/hsmm_regime/__init__.py`](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/__init__.py) (Python HSMM API), [`python/scripts/backtest_strategy.py`](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/backtest_strategy.py) (Backtest CLI), [`cpp/src/particle_filter.cpp`](https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/particle_filter.cpp) (Particle filter), [`python/hsmm_regime/data.py`](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/data.py) (Data features)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Market data"]
  node_data_tools["Data features<br/>[data.py]"]
  node_feature_cli["Feature CLI<br/>[build_features.py]"]
  node_fetch_cli["Fetch CLI<br/>[fetch_data.py]"]
end

subgraph group_inference["Regime inference"]
  node_offline_cli["Offline fit CLI"]
  node_online_cli["Online filter CLI"]
  node_gibbs_cli["Gibbs fit CLI<br/>[fit_gibbs_hsmm.py]"]
  node_python_api["Python HSMM API<br/>[__init__.py]"]
  node_cpp_binding["Python binding<br/>[bindings.cpp]"]
  node_em_engine["EM and decoding<br/>[em_engine.cpp]"]
  node_fb_engine["Forward-backward"]
  node_particle_filter["Particle filter"]
  node_duration_model["Duration model"]
  node_emission_model["Emission model<br/>[emissions.cpp]"]
  node_gibbs_sampler["Bayesian sampler<br/>[gibbs.py]"]
end

subgraph group_analysis["Research analysis"]
  node_plotting["Regime diagnostics<br/>[plotting.py]"]
  node_msvar["MS-VAR and IRFs<br/>[ms_var.py]"]
  node_msvar_cli["MS-VAR CLI<br/>[fit_ms_var.py]"]
end

subgraph group_allocation["Allocation"]
  node_strategy["Strategy backtest<br/>[strategy.py]"]
  node_backtest_cli["Backtest CLI"]
end

node_researcher(("Researcher"))
node_market_data(("Market data service"))

node_researcher -->|"requests data"| node_fetch_cli
node_market_data -->|"supplies OHLCV"| node_data_tools
node_fetch_cli -->|"fetches"| node_data_tools
node_data_tools -->|"builds features"| node_feature_cli
node_feature_cli -->|"feeds fitting"| node_offline_cli
node_offline_cli -->|"fits and decodes"| node_python_api
node_python_api -->|"calls extension"| node_cpp_binding
node_cpp_binding -->|"exposes fitting"| node_em_engine
node_cpp_binding -->|"exposes filtering"| node_particle_filter
node_online_cli -->|"streams observations"| node_python_api
node_python_api -->|"steps filter"| node_particle_filter
node_em_engine -->|"uses durations"| node_duration_model
node_em_engine -->|"fits emissions"| node_emission_model
node_gibbs_cli -->|"runs sampler"| node_gibbs_sampler
node_offline_cli -->|"creates diagnostics"| node_plotting
node_online_cli -->|"plots posteriors"| node_plotting
node_msvar_cli -->|"fits MS-VAR"| node_msvar
node_msvar_cli -->|"plots IRFs"| node_plotting
node_backtest_cli -->|"runs backtest"| node_strategy
node_backtest_cli -->|"loads features"| node_data_tools
node_backtest_cli -->|"uses regime API"| node_python_api
node_backtest_cli -->|"plots performance"| node_plotting
node_fb_engine -->|"uses durations"| node_duration_model
node_fb_engine -->|"uses emissions"| node_emission_model
node_particle_filter -->|"uses durations"| node_duration_model
node_particle_filter -->|"uses emissions"| node_emission_model

click node_data_tools "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/data.py"
click node_feature_cli "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/build_features.py"
click node_fetch_cli "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/fetch_data.py"
click node_offline_cli "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/fit_offline_hsmm.py"
click node_online_cli "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/run_online_filter.py"
click node_gibbs_cli "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/fit_gibbs_hsmm.py"
click node_python_api "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/__init__.py"
click node_cpp_binding "https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/bindings.cpp"
click node_em_engine "https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/em_engine.cpp"
click node_fb_engine "https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/forward_backward.cpp"
click node_particle_filter "https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/particle_filter.cpp"
click node_duration_model "https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/duration_distributions.cpp"
click node_emission_model "https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/emissions.cpp"
click node_gibbs_sampler "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/gibbs.py"
click node_plotting "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/plotting.py"
click node_msvar "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/ms_var.py"
click node_msvar_cli "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/fit_ms_var.py"
click node_strategy "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/strategy.py"
click node_backtest_cli "https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/backtest_strategy.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_data_tools,node_feature_cli,node_fetch_cli toneBlue
class node_offline_cli,node_online_cli,node_gibbs_cli,node_python_api,node_cpp_binding,node_em_engine,node_fb_engine,node_particle_filter,node_duration_model,node_emission_model,node_gibbs_sampler toneAmber
class node_plotting,node_msvar,node_msvar_cli toneMint
class node_strategy,node_backtest_cli toneRose
class node_researcher,node_market_data toneIndigo
```

## Components

### Market data

- [Data features](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/data.py): `python/hsmm_regime/data.py`
- [Feature CLI](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/build_features.py): `python/scripts/build_features.py`
- [Fetch CLI](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/fetch_data.py): `python/scripts/fetch_data.py`

### Regime inference

- [Offline fit CLI](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/fit_offline_hsmm.py): `python/scripts/fit_offline_hsmm.py`
- [Online filter CLI](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/run_online_filter.py): `python/scripts/run_online_filter.py`
- [Gibbs fit CLI](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/fit_gibbs_hsmm.py): `python/scripts/fit_gibbs_hsmm.py`
- [Python HSMM API](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/__init__.py): `python/hsmm_regime/__init__.py`
- [Python binding](https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/bindings.cpp): `cpp/src/bindings.cpp`
- [EM and decoding](https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/em_engine.cpp): `cpp/src/em_engine.cpp`
- [Forward-backward](https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/forward_backward.cpp): `cpp/src/forward_backward.cpp`
- [Particle filter](https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/particle_filter.cpp): `cpp/src/particle_filter.cpp`
- [Duration model](https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/duration_distributions.cpp): `cpp/src/duration_distributions.cpp`
- [Emission model](https://github.com/vahini-1/hsmm-state-detection/blob/main/cpp/src/emissions.cpp): `cpp/src/emissions.cpp`
- [Bayesian sampler](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/gibbs.py): `python/hsmm_regime/gibbs.py`

### Research analysis

- [Regime diagnostics](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/plotting.py): `python/hsmm_regime/plotting.py`
- [MS-VAR and IRFs](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/ms_var.py): `python/hsmm_regime/ms_var.py`
- [MS-VAR CLI](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/fit_ms_var.py): `python/scripts/fit_ms_var.py`

### Allocation

- [Strategy backtest](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/hsmm_regime/strategy.py): `python/hsmm_regime/strategy.py`
- [Backtest CLI](https://github.com/vahini-1/hsmm-state-detection/blob/main/python/scripts/backtest_strategy.py): `python/scripts/backtest_strategy.py`

### Other components

- **Researcher**
- **Market data service**

## Connections

- Researcher → Fetch CLI: requests data (evidence: `README.md`)
- Market data service → Data features: supplies OHLCV (evidence: `python/hsmm_regime/data.py`)
- Fetch CLI → Data features: fetches (evidence: `python/scripts/fetch_data.py`)
- Data features → Feature CLI: builds features (evidence: `python/scripts/build_features.py`)
- Feature CLI → Offline fit CLI: feeds fitting (evidence: `README.md`)
- Offline fit CLI → Python HSMM API: fits and decodes (evidence: `python/scripts/fit_offline_hsmm.py`)
- Python HSMM API → Python binding: calls extension (evidence: `README.md`)
- Python binding → EM and decoding: exposes fitting (evidence: `cpp/src/bindings.cpp`)
- Python binding → Particle filter: exposes filtering (evidence: `cpp/src/bindings.cpp`)
- Online filter CLI → Python HSMM API: streams observations (evidence: `python/scripts/run_online_filter.py`)
- Python HSMM API → Particle filter: steps filter (evidence: `python/hsmm_regime/__init__.py`)
- EM and decoding → Duration model: uses durations (evidence: `cpp/src/em_engine.cpp`)
- EM and decoding → Emission model: fits emissions (evidence: `cpp/src/em_engine.cpp`)
- Gibbs fit CLI → Bayesian sampler: runs sampler (evidence: `python/scripts/fit_gibbs_hsmm.py`)
- Offline fit CLI → Regime diagnostics: creates diagnostics (evidence: `README.md`)
- Online filter CLI → Regime diagnostics: plots posteriors (evidence: `README.md`)
- MS-VAR CLI → MS-VAR and IRFs: fits MS-VAR (evidence: `python/scripts/fit_ms_var.py`)
- MS-VAR CLI → Regime diagnostics: plots IRFs (evidence: `python/scripts/fit_ms_var.py`)
- Backtest CLI → Strategy backtest: runs backtest (evidence: `python/scripts/backtest_strategy.py`)
- Backtest CLI → Data features: loads features (evidence: `python/scripts/backtest_strategy.py`)
- Backtest CLI → Python HSMM API: uses regime API (evidence: `python/scripts/backtest_strategy.py`)
- Backtest CLI → Regime diagnostics: plots performance (evidence: `python/scripts/backtest_strategy.py`)
- Forward-backward → Duration model: uses durations (evidence: `cpp/src/forward_backward.cpp`)
- Forward-backward → Emission model: uses emissions (evidence: `cpp/src/forward_backward.cpp`)
- Particle filter → Duration model: uses durations (evidence: `cpp/src/particle_filter.cpp`)
- Particle filter → Emission model: uses emissions (evidence: `cpp/src/particle_filter.cpp`)
