# mayongupta/quantmltoolkit architecture

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

- Interactive diagram: https://gitdiagram.com/mayongupta/quantmltoolkit
- Repository: https://github.com/mayongupta/quantmltoolkit

## Overview

quant-ml-toolkit is a Python toolkit for building and honestly evaluating price-data ML models, with leakage-safe walk-forward validation as its central capability. Its documented workflow generates or receives OHLCV data, derives past-only features and forward-looking targets, creates chronological folds (optionally purged with an embargo), trains fresh models per fold, and reports classification or regression metrics. The README also describes feature-importance reporting. The example’s source was not sampled, so workflow links rely on README statements; implementation links use the excerpts shown.

Main entry points: [`quant_ml/evaluation.py`](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/evaluation.py) (Classification runner), [`quant_ml/synthetic_data.py`](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/synthetic_data.py) (Synthetic OHLCV), [`quant_ml/features.py`](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/features.py) (Feature engineering), [`quant_ml/labels.py`](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/labels.py) (Target labels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_prep["Data Preparation"]
  node_synthetic_data["Synthetic OHLCV<br/>[synthetic_data.py]"]
  node_features["Feature engineering<br/>[features.py]"]
  node_labels["Target labels<br/>[labels.py]"]
end

subgraph group_validation["Leak-Free Validation"]
  node_validation_splits["Walk-forward splits<br/>[validation.py]"]
end

subgraph group_modeling["Modeling"]
  node_model_factories["Model factories<br/>[models.py]"]
  node_importance["Feature importance<br/>[models.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_classification_eval["Classification runner<br/>[evaluation.py]"]
  node_regression_eval["Regression runner<br/>[evaluation.py]"]
  node_metrics["Fold metrics<br/>[evaluation.py]"]
end

node_user(("Pipeline user"))

node_user -->|"generates data"| node_synthetic_data
node_synthetic_data -->|"provides OHLCV"| node_features
node_synthetic_data -->|"provides OHLCV"| node_labels
node_features -->|"supplies features"| node_classification_eval
node_labels -->|"supplies targets"| node_classification_eval
node_features -->|"supplies features"| node_regression_eval
node_labels -->|"supplies targets"| node_regression_eval
node_validation_splits -->|"supplies folds"| node_classification_eval
node_validation_splits -->|"supplies folds"| node_regression_eval
node_model_factories -->|"creates models"| node_classification_eval
node_model_factories -->|"creates models"| node_regression_eval
node_classification_eval -->|"reports metrics"| node_metrics
node_regression_eval -->|"reports metrics"| node_metrics
node_user -->|"requests importance"| node_importance

click node_synthetic_data "https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/synthetic_data.py"
click node_features "https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/features.py"
click node_labels "https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/labels.py"
click node_validation_splits "https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/validation.py"
click node_model_factories "https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/models.py"
click node_classification_eval "https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/evaluation.py"
click node_regression_eval "https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/evaluation.py"
click node_metrics "https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/evaluation.py"
click node_importance "https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/models.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_synthetic_data,node_features,node_labels,node_user toneBlue
class node_validation_splits toneAmber
class node_model_factories,node_importance toneMint
class node_classification_eval,node_regression_eval,node_metrics toneRose
```

## Components

### Data Preparation

- [Synthetic OHLCV](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/synthetic_data.py): `quant_ml/synthetic_data.py`
- [Feature engineering](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/features.py): `quant_ml/features.py`
- [Target labels](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/labels.py): `quant_ml/labels.py`

### Leak-Free Validation

- [Walk-forward splits](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/validation.py): `quant_ml/validation.py`

### Modeling

- [Model factories](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/models.py): `quant_ml/models.py`
- [Feature importance](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/models.py): `quant_ml/models.py`

### Evaluation

- [Classification runner](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/evaluation.py): `quant_ml/evaluation.py`
- [Regression runner](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/evaluation.py): `quant_ml/evaluation.py`
- [Fold metrics](https://github.com/mayongupta/quantmltoolkit/blob/main/quant_ml/evaluation.py): `quant_ml/evaluation.py`

### Other components

- **Pipeline user**

## Connections

- Pipeline user → Synthetic OHLCV: generates data (evidence: `README.md`)
- Synthetic OHLCV → Feature engineering: provides OHLCV (evidence: `README.md`)
- Synthetic OHLCV → Target labels: provides OHLCV (evidence: `README.md`)
- Feature engineering → Classification runner: supplies features (evidence: `README.md`)
- Target labels → Classification runner: supplies targets (evidence: `README.md`)
- Feature engineering → Regression runner: supplies features (evidence: `README.md`)
- Target labels → Regression runner: supplies targets (evidence: `README.md`)
- Walk-forward splits → Classification runner: supplies folds (evidence: `README.md`)
- Walk-forward splits → Regression runner: supplies folds (evidence: `README.md`)
- Model factories → Classification runner: creates models (evidence: `quant_ml/evaluation.py`)
- Model factories → Regression runner: creates models (evidence: `quant_ml/evaluation.py`)
- Classification runner → Fold metrics: reports metrics (evidence: `quant_ml/evaluation.py`)
- Regression runner → Fold metrics: reports metrics (evidence: `quant_ml/evaluation.py`)
- Pipeline user → Feature importance: requests importance (evidence: `README.md`)
