# patrickresearch/forecastlens architecture

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

- Interactive diagram: https://gitdiagram.com/patrickresearch/forecastlens
- Repository: https://github.com/patrickresearch/forecastlens

## Overview

ForecastLens is a framework-agnostic diagnostic layer for existing time-series forecasts; it does not train models. The main workflow normalizes model output into a shared forecast representation, then evaluates accuracy overall or by detected regime, or translates forecasts into decision outcomes. Separate capabilities include leak-safe walk-forward splitting and synthetic price/demand data with ground truth. The web demo illustrates regime-aware evaluation and procurement timing. Edges follow README statements or source-index references; unsampled implementations are represented by their exact paths, but their internal calls are not inferred.

Main entry points: [`src/forecastlens/core/result.py`](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/core/result.py) (ForecastResult), [`src/forecastlens/evaluators/regime_aware.py`](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/evaluators/regime_aware.py) (Regime evaluator), [`src/forecastlens/decision/bucket_accuracy.py`](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/bucket_accuracy.py) (Bucket accuracy), [`web_demo/app.py`](https://github.com/patrickresearch/forecastlens/blob/main/web_demo/app.py) (Interactive demo)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_forecast["Forecast Inputs"]
  node_darts["Darts adapter<br/>[darts.py]"]
  node_neural["NeuralForecast adapter<br/>[neuralforecast.py]"]
  node_raw["Tabular adapter<br/>[raw.py]"]
  node_forecast_result["ForecastResult<br/>[result.py]"]
  node_splitter["Walk-forward splitter<br/>[splitter.py]"]
end

subgraph group_analysis["Evaluation"]
  node_metrics["Forecast metrics<br/>[pinball.py]"]
  node_demand_eval["Demand evaluator<br/>[demand.py]"]
  node_regime_eval["Regime evaluator<br/>[regime_aware.py]"]
  node_detector["Regime detectors<br/>[cusum.py]"]
  node_cluster["Regime clustering<br/>[clustering.py]"]
  node_volatility["Volatility detector<br/>[volatility.py]"]
end

subgraph group_decisions["Decision Analysis"]
  node_bucket_definition["Decision buckets<br/>[buckets.py]"]
  node_cost_matrix["Decision costs<br/>[cost_matrix.py]"]
  node_bucket_accuracy["Bucket accuracy<br/>[bucket_accuracy.py]"]
  node_value_score["Value score<br/>[value_score.py]"]
  node_procurement["Procurement timing"]
end

subgraph group_data["Data and Demo"]
  node_price_data["Synthetic price data<br/>[price.py]"]
  node_demand_data["Synthetic demand data<br/>[demand.py]"]
  node_series["Generated series<br/>[series.py]"]
  node_demo["Interactive demo<br/>[app.py]"]
end

node_user(("Forecast user"))

node_user -->|"provides forecast"| node_darts
node_user -->|"provides forecast"| node_neural
node_user -->|"provides tabular output"| node_raw
node_darts -->|"normalizes to"| node_forecast_result
node_neural -->|"normalizes to"| node_forecast_result
node_raw -->|"normalizes to"| node_forecast_result
node_forecast_result -->|"evaluated by"| node_regime_eval
node_forecast_result -->|"evaluated by"| node_demand_eval
node_forecast_result -->|"informs timing"| node_procurement
node_user -->|"requests splits"| node_splitter
node_user -->|"scores forecast"| node_metrics
node_regime_eval -->|"detects regimes"| node_detector
node_regime_eval -->|"computes scores"| node_metrics
node_cluster -->|"clusters detections"| node_detector
node_volatility -->|"implements detector"| node_detector
node_bucket_accuracy -->|"assigns buckets"| node_bucket_definition
node_bucket_accuracy -->|"prices outcomes"| node_cost_matrix
node_bucket_accuracy -->|"computes value"| node_value_score
node_price_data -->|"returns series"| node_series
node_demand_data -->|"returns series"| node_series
node_demo -->|"loads presets"| node_price_data
node_demo -->|"runs evaluation"| node_regime_eval
node_demo -->|"runs timing"| node_procurement

click node_darts "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/adapters/darts.py"
click node_neural "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/adapters/neuralforecast.py"
click node_raw "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/adapters/raw.py"
click node_forecast_result "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/core/result.py"
click node_splitter "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/backtesting/splitter.py"
click node_metrics "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/metrics/pinball.py"
click node_demand_eval "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/evaluators/demand.py"
click node_regime_eval "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/evaluators/regime_aware.py"
click node_detector "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/regime/cusum.py"
click node_cluster "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/regime/clustering.py"
click node_volatility "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/regime/volatility.py"
click node_bucket_definition "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/buckets.py"
click node_cost_matrix "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/cost_matrix.py"
click node_bucket_accuracy "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/bucket_accuracy.py"
click node_value_score "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/value_score.py"
click node_procurement "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/procurement_timing.py"
click node_price_data "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/synthetic/price.py"
click node_demand_data "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/synthetic/demand.py"
click node_series "https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/synthetic/series.py"
click node_demo "https://github.com/patrickresearch/forecastlens/blob/main/web_demo/app.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_darts,node_neural,node_raw,node_forecast_result,node_splitter,node_user toneBlue
class node_metrics,node_demand_eval,node_regime_eval,node_detector,node_cluster,node_volatility toneAmber
class node_bucket_definition,node_cost_matrix,node_bucket_accuracy,node_value_score,node_procurement toneMint
class node_price_data,node_demand_data,node_series,node_demo toneRose
```

## Components

### Forecast Inputs

- [Darts adapter](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/adapters/darts.py): `src/forecastlens/adapters/darts.py`
- [NeuralForecast adapter](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/adapters/neuralforecast.py): `src/forecastlens/adapters/neuralforecast.py`
- [Tabular adapter](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/adapters/raw.py): `src/forecastlens/adapters/raw.py`
- [ForecastResult](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/core/result.py): `src/forecastlens/core/result.py`
- [Walk-forward splitter](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/backtesting/splitter.py): `src/forecastlens/backtesting/splitter.py`

### Evaluation

- [Forecast metrics](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/metrics/pinball.py): `src/forecastlens/metrics/pinball.py`
- [Demand evaluator](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/evaluators/demand.py): `src/forecastlens/evaluators/demand.py`
- [Regime evaluator](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/evaluators/regime_aware.py): `src/forecastlens/evaluators/regime_aware.py`
- [Regime detectors](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/regime/cusum.py): `src/forecastlens/regime/cusum.py`
- [Regime clustering](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/regime/clustering.py): `src/forecastlens/regime/clustering.py`
- [Volatility detector](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/regime/volatility.py): `src/forecastlens/regime/volatility.py`

### Decision Analysis

- [Decision buckets](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/buckets.py): `src/forecastlens/decision/buckets.py`
- [Decision costs](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/cost_matrix.py): `src/forecastlens/decision/cost_matrix.py`
- [Bucket accuracy](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/bucket_accuracy.py): `src/forecastlens/decision/bucket_accuracy.py`
- [Value score](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/value_score.py): `src/forecastlens/decision/value_score.py`
- [Procurement timing](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/decision/procurement_timing.py): `src/forecastlens/decision/procurement_timing.py`

### Data and Demo

- [Synthetic price data](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/synthetic/price.py): `src/forecastlens/synthetic/price.py`
- [Synthetic demand data](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/synthetic/demand.py): `src/forecastlens/synthetic/demand.py`
- [Generated series](https://github.com/patrickresearch/forecastlens/blob/main/src/forecastlens/synthetic/series.py): `src/forecastlens/synthetic/series.py`
- [Interactive demo](https://github.com/patrickresearch/forecastlens/blob/main/web_demo/app.py): `web_demo/app.py`

### Other components

- **Forecast user**

## Connections

- Forecast user → Darts adapter: provides forecast
- Forecast user → NeuralForecast adapter: provides forecast
- Forecast user → Tabular adapter: provides tabular output
- Darts adapter → ForecastResult: normalizes to (evidence: `src/forecastlens/adapters/darts.py`)
- NeuralForecast adapter → ForecastResult: normalizes to (evidence: `src/forecastlens/adapters/neuralforecast.py`)
- Tabular adapter → ForecastResult: normalizes to (evidence: `src/forecastlens/adapters/raw.py`)
- ForecastResult → Regime evaluator: evaluated by (evidence: `src/forecastlens/evaluators/regime_aware.py`)
- ForecastResult → Demand evaluator: evaluated by (evidence: `src/forecastlens/evaluators/demand.py`)
- ForecastResult → Procurement timing: informs timing (evidence: `src/forecastlens/decision/procurement_timing.py`)
- Forecast user → Walk-forward splitter: requests splits
- Forecast user → Forecast metrics: scores forecast
- Regime evaluator → Regime detectors: detects regimes (evidence: `src/forecastlens/evaluators/regime_aware.py`)
- Regime evaluator → Forecast metrics: computes scores (evidence: `src/forecastlens/evaluators/regime_aware.py`)
- Regime clustering → Regime detectors: clusters detections (evidence: `src/forecastlens/regime/clustering.py`)
- Volatility detector → Regime detectors: implements detector (evidence: `src/forecastlens/regime/volatility.py`)
- Bucket accuracy → Decision buckets: assigns buckets (evidence: `src/forecastlens/decision/bucket_accuracy.py`)
- Bucket accuracy → Decision costs: prices outcomes (evidence: `src/forecastlens/decision/bucket_accuracy.py`)
- Bucket accuracy → Value score: computes value (evidence: `src/forecastlens/decision/bucket_accuracy.py`)
- Synthetic price data → Generated series: returns series (evidence: `src/forecastlens/synthetic/price.py`)
- Synthetic demand data → Generated series: returns series (evidence: `src/forecastlens/synthetic/demand.py`)
- Interactive demo → Synthetic price data: loads presets (evidence: `web_demo/app.py`)
- Interactive demo → Regime evaluator: runs evaluation (evidence: `web_demo/app.py`)
- Interactive demo → Procurement timing: runs timing (evidence: `web_demo/app.py`)
