# pred-javeriana/pred-engine architecture

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

- Interactive diagram: https://gitdiagram.com/pred-javeriana/pred-engine
- Repository: https://github.com/pred-javeriana/pred-engine

## Overview

pred-engine is a Python forecasting and model-evaluation library with no UI. Its main workflow ingests and classifies demand data, routes each SKU to model families for selection and fitting, evaluates candidates with causal walk-forward evidence, then evaluates forecasts on a reserved period and publishes results through the platform database. The README documents these stages and optional semantic ingestion, synthetic-data augmentation, model families, statistical verdicts, and artifacts. The supplied excerpts show orchestration and several internal boundaries; unsampled subsystem links are included only where the README explicitly describes them.

Main entry points: [`src/pred_engine/pipeline.py`](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/pipeline.py) (Pipeline), [`src/pred_engine/ingesta/pipeline.py`](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/ingesta/pipeline.py) (Ingestion pipeline), [`src/pred_engine/optimizacion/router/enrutador.py`](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/optimizacion/router/enrutador.py) (Selection router), [`src/pred_engine/forecasting/generador_pronosticos/generacion.py`](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/generador_pronosticos/generacion.py) (Reserved forecasts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Ingestion and data"]
  node_ingest["Ingestion pipeline<br/>[pipeline.py]"]
  node_probe["Semantic header probe<br/>[sonda.py]"]
  node_classify["Series categorization<br/>[enrutador.py]"]
  node_rawdata[("Raw data root<br/>[deposito.py]")]
  node_augmentation["Synthetic augmentation<br/>[fase0.py]"]
end

subgraph group_selection["Model selection"]
  node_router["Selection router<br/>[enrutador.py]"]
  node_hpo["Hyperparameter search<br/>[estudio.py]"]
  node_classical["Classical models<br/>[sarima.py]"]
  node_ml["Machine learning models<br/>[lgbm.py]"]
  node_deep["Deep learning models<br/>[mlp.py]"]
  node_foundation["Foundation model<br/>[pipeline.py]"]
  node_manifest["Candidate manifest"]
end

subgraph group_forecasting["Forecast evaluation"]
  node_walkforward["Walk-forward evaluation<br/>[walk_forward.py]"]
  node_forecastgen["Reserved forecasts<br/>[generacion.py]"]
  node_adapter["Candidate validation<br/>[validacion.py]"]
  node_errors["Forecast error metrics<br/>[metricas.py]"]
  node_verdicts["Selection verdicts<br/>[veredictos.py]"]
  node_dm["HLN-DM testing<br/>[prueba.py]"]
  node_confirm["Evaluation confirmation<br/>[confirmacion.py]"]
end

subgraph group_delivery["Evidence and delivery"]
  node_evidence[("Evidence repository<br/>[repositorio.py]")]
  node_published[("Platform SQLite and Parquet")]
  node_artifacts["Run artifacts<br/>[run_artifacts.py]"]
end

subgraph group_shared["Shared runtime"]
  node_pipeline["Pipeline<br/>[pipeline.py]"]
  node_parallel["Parallel units"]
end

node_operator(("Data operator"))

node_operator -->|"provides CSV"| node_ingest
node_operator -->|"starts run"| node_pipeline
node_ingest -->|"deposits raw"| node_rawdata
node_ingest -->|"probes headers"| node_probe
node_probe -.->|"uses provider"| node_operator
node_ingest -->|"classifies panel"| node_classify
node_augmentation -.->|"supplies seed CSV"| node_ingest
node_pipeline -->|"runs L1"| node_ingest
node_pipeline -->|"routes candidates"| node_router
node_pipeline -->|"dispatches units"| node_parallel
node_hpo -->|"scores trials"| node_walkforward
node_router -.->|"selects family"| node_classical
node_router -.->|"selects family"| node_ml
node_router -.->|"selects family"| node_deep
node_router -.->|"selects family"| node_foundation
node_pipeline -->|"evaluates fits"| node_walkforward
node_pipeline -->|"emits candidates"| node_manifest
node_pipeline -->|"runs reserved forecasts"| node_forecastgen
node_forecastgen -->|"validates candidates"| node_adapter
node_forecastgen -->|"evaluates forecasts"| node_errors
node_pipeline -->|"selects verdicts"| node_verdicts
node_pipeline -->|"runs complementary test"| node_dm
node_pipeline -.->|"confirms evaluation"| node_confirm
node_pipeline -->|"persists evidence"| node_evidence
node_evidence -->|"writes platform DB"| node_published
node_pipeline -->|"records run"| node_artifacts
node_walkforward -->|"produces evidence"| node_artifacts
node_pipeline -->|"publishes outputs"| node_published

click node_pipeline "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/pipeline.py"
click node_ingest "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/ingesta/pipeline.py"
click node_probe "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/ingesta/sonda/sonda.py"
click node_classify "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/ingesta/categorizacion/enrutador.py"
click node_rawdata "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/ingesta/data/deposito.py"
click node_augmentation "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/aumentacion/fase0.py"
click node_router "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/optimizacion/router/enrutador.py"
click node_hpo "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/optimizacion/optimizadores/HPO/estudio.py"
click node_parallel "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/ejecucion_paralela.py"
click node_classical "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/modelos/modelos_clasicos/sarima.py"
click node_ml "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/modelos/modelos_machine_learning/lgbm.py"
click node_deep "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/modelos/modelos_deep_learning/mlp.py"
click node_foundation "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/modelos/modelos_fundacionales/pipeline.py"
click node_manifest "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/modelos/manifiesto_candidatos.py"
click node_walkforward "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/walkforward/walk_forward.py"
click node_forecastgen "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/generador_pronosticos/generacion.py"
click node_adapter "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/adaptador_candidatos/validacion.py"
click node_errors "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/evaluaciones/calculo_errores/metricas.py"
click node_verdicts "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/evaluaciones/veredictos/veredictos.py"
click node_dm "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/evaluaciones/diebold_mariano/prueba.py"
click node_confirm "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/evaluaciones/confirmacion/confirmacion.py"
click node_evidence "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/persistencia_evidencia/repositorio.py"
click node_artifacts "https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/run_artifacts.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_ingest,node_probe,node_classify,node_rawdata,node_augmentation toneBlue
class node_router,node_hpo,node_classical,node_ml,node_deep,node_foundation,node_manifest toneAmber
class node_walkforward,node_forecastgen,node_adapter,node_errors,node_verdicts,node_dm,node_confirm toneMint
class node_evidence,node_published,node_artifacts toneRose
class node_pipeline,node_parallel,node_operator toneIndigo
```

## Components

### Ingestion and data

- [Ingestion pipeline](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/ingesta/pipeline.py): `src/pred_engine/ingesta/pipeline.py`
- [Semantic header probe](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/ingesta/sonda/sonda.py): `src/pred_engine/ingesta/sonda/sonda.py`
- [Series categorization](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/ingesta/categorizacion/enrutador.py): `src/pred_engine/ingesta/categorizacion/enrutador.py`
- [Raw data root](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/ingesta/data/deposito.py): `src/pred_engine/ingesta/data/deposito.py`
- [Synthetic augmentation](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/aumentacion/fase0.py): `src/pred_engine/aumentacion/fase0.py`

### Model selection

- [Selection router](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/optimizacion/router/enrutador.py): `src/pred_engine/optimizacion/router/enrutador.py`
- [Hyperparameter search](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/optimizacion/optimizadores/HPO/estudio.py): `src/pred_engine/optimizacion/optimizadores/HPO/estudio.py`
- [Classical models](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/modelos/modelos_clasicos/sarima.py): `src/pred_engine/comun/modelos/modelos_clasicos/sarima.py`
- [Machine learning models](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/modelos/modelos_machine_learning/lgbm.py): `src/pred_engine/comun/modelos/modelos_machine_learning/lgbm.py`
- [Deep learning models](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/modelos/modelos_deep_learning/mlp.py): `src/pred_engine/comun/modelos/modelos_deep_learning/mlp.py`
- [Foundation model](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/modelos/modelos_fundacionales/pipeline.py): `src/pred_engine/comun/modelos/modelos_fundacionales/pipeline.py`
- [Candidate manifest](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/modelos/manifiesto_candidatos.py): `src/pred_engine/comun/modelos/manifiesto_candidatos.py`

### Forecast evaluation

- [Walk-forward evaluation](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/walkforward/walk_forward.py): `src/pred_engine/comun/walkforward/walk_forward.py`
- [Reserved forecasts](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/generador_pronosticos/generacion.py): `src/pred_engine/forecasting/generador_pronosticos/generacion.py`
- [Candidate validation](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/adaptador_candidatos/validacion.py): `src/pred_engine/forecasting/adaptador_candidatos/validacion.py`
- [Forecast error metrics](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/evaluaciones/calculo_errores/metricas.py): `src/pred_engine/forecasting/evaluaciones/calculo_errores/metricas.py`
- [Selection verdicts](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/evaluaciones/veredictos/veredictos.py): `src/pred_engine/forecasting/evaluaciones/veredictos/veredictos.py`
- [HLN-DM testing](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/evaluaciones/diebold_mariano/prueba.py): `src/pred_engine/forecasting/evaluaciones/diebold_mariano/prueba.py`
- [Evaluation confirmation](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/evaluaciones/confirmacion/confirmacion.py): `src/pred_engine/forecasting/evaluaciones/confirmacion/confirmacion.py`

### Evidence and delivery

- [Evidence repository](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/forecasting/persistencia_evidencia/repositorio.py): `src/pred_engine/forecasting/persistencia_evidencia/repositorio.py`
- **Platform SQLite and Parquet**
- [Run artifacts](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/run_artifacts.py): `src/pred_engine/run_artifacts.py`

### Shared runtime

- [Pipeline](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/pipeline.py): `src/pred_engine/pipeline.py`
- [Parallel units](https://github.com/pred-javeriana/pred-engine/blob/main/src/pred_engine/comun/ejecucion_paralela.py): `src/pred_engine/comun/ejecucion_paralela.py`

### Other components

- **Data operator**

## Connections

- Data operator → Ingestion pipeline: provides CSV (evidence: `src/pred_engine/ingesta/pipeline.py`)
- Data operator → Pipeline: starts run (evidence: `README.md`)
- Ingestion pipeline → Raw data root: deposits raw (evidence: `src/pred_engine/ingesta/pipeline.py`)
- Ingestion pipeline → Semantic header probe: probes headers (evidence: `src/pred_engine/ingesta/pipeline.py`)
- Semantic header probe → Data operator: uses provider (evidence: `README.md`)
- Ingestion pipeline → Series categorization: classifies panel (evidence: `src/pred_engine/ingesta/pipeline.py`)
- Synthetic augmentation → Ingestion pipeline: supplies seed CSV (evidence: `README.md`)
- Pipeline → Ingestion pipeline: runs L1 (evidence: `README.md`)
- Pipeline → Selection router: routes candidates (evidence: `src/pred_engine/pipeline.py`)
- Pipeline → Parallel units: dispatches units (evidence: `src/pred_engine/pipeline.py`)
- Hyperparameter search → Walk-forward evaluation: scores trials (evidence: `src/pred_engine/optimizacion/optimizadores/HPO/estudio.py`)
- Selection router → Classical models: selects family (evidence: `README.md`)
- Selection router → Machine learning models: selects family (evidence: `README.md`)
- Selection router → Deep learning models: selects family (evidence: `README.md`)
- Selection router → Foundation model: selects family (evidence: `README.md`)
- Pipeline → Walk-forward evaluation: evaluates fits (evidence: `README.md`)
- Pipeline → Candidate manifest: emits candidates (evidence: `README.md`)
- Pipeline → Reserved forecasts: runs reserved forecasts (evidence: `README.md`)
- Reserved forecasts → Candidate validation: validates candidates (evidence: `src/pred_engine/forecasting/generador_pronosticos/generacion.py`)
- Reserved forecasts → Forecast error metrics: evaluates forecasts (evidence: `src/pred_engine/forecasting/generador_pronosticos/generacion.py`)
- Pipeline → Selection verdicts: selects verdicts (evidence: `README.md`)
- Pipeline → HLN-DM testing: runs complementary test (evidence: `README.md`)
- Pipeline → Evaluation confirmation: confirms evaluation
- Pipeline → Evidence repository: persists evidence (evidence: `README.md`)
- Evidence repository → Platform SQLite and Parquet: writes platform DB (evidence: `README.md`)
- Pipeline → Run artifacts: records run (evidence: `README.md`)
- Walk-forward evaluation → Run artifacts: produces evidence (evidence: `README.md`)
- Pipeline → Platform SQLite and Parquet: publishes outputs (evidence: `README.md`)