FinazTradingEngine — Manual pedagógico¶

Bienvenido. Este manual explica qué es FinazTradingEngine, cómo está construido y por qué está construido así, desde los conceptos de mercado más básicos hasta la operación del servidor donde corre la plataforma.

En una frase

FinazTradingEngine es una plataforma de investigación cuantitativa causal y reproducible: datos point-in-time, un banco de backtesting con dos motores de paridad verificable (NautilusTrader y VectorTA) que actúa como oráculo, y una familia de motores de modelado y optimización (Ridge, CatBoost, ARIMA/ETS/GARCH, NHITS en PyTorch, Chronos-2, TimesFM 2.5, ERC y CP-SAT) sobre PostgreSQL, ClickHouse, Redpanda y MinIO, todo certificado por gates.

Lo que hay dentro¶

Una sola plataforma, siete familias de motores. Cada motor tiene un contrato de entrada y salida, corre en una imagen con solo sus dependencias y está certificado por un gate. El detalle, motor a motor, está en el Catálogo de motores.

Familia	Motores y librerías	Imagen / gate
Banco de backtesting y features (oráculo de paridad)	NautilusTrader 1.231.0, VectorTA 0.2.8, ledger SIM-S propio (NumPy v1 / Numba v2), 386 indicadores descubiertos (39 ejecutables por API), 31 templates (30 en el catálogo + Q08B)	`finaz/bench:0.2.0-x86-64-v3` (H0–H4)
Runtime causal	ClockEngine, FlowSpec + registry + compiler, runtime batch/replay/stream, checkpoints CAS, fencing por lease PG (numpy, numba, scipy, polars, pyarrow, kafka-python, psycopg)	`core`, `io` (G1–G3)
Tabular y estadística	Ridge exacto propio (Cholesky), CatBoost (challenger con puerta), statsmodels (ARIMA/ETS), arch (GARCH), statsforecast (AutoARIMA)	`quant` (G4)
Riesgo, cartera y discreto	Ledoit-Wolf propio + VaR/ES históricos; allocation ERC / mínima varianza / máxima diversificación con cvxpy + Clarabel; skfolio; scikit-learn (paridad); CP-SAT de OR-Tools (lotes enteros en subproceso); ConstraintValidator (productor exclusivo de targets aprobados)	`opt` (G5, G6)
Redes neuronales	PyTorch 2.9.1 CPU + neuralforecast 3.2.2 (NHITS real: puerta causal de exógenas, deadline, artefacto sin pickle, baseline naive estacional)	`neural:s4` (G7)
Modelos fundacionales	Chronos-2 (chronos-forecasting + transformers) y TimesFM 2.5 (timesfm), checkpoints con SHA y provenance, CPU	`chronos`, `timesfm25` (G8)
Datos y control	PostgreSQL (control, admisión, leases, outbox, publicaciones), ClickHouse (revision log PIT `market_bars_v1`, 141 551 barras reales desde 2026-09-22), Redpanda (stream y replay), MinIO/CAS (snapshots sellados), calendarios versionados, instrument master PIT	`api`, `core`, `io`
Entrenamiento y registro	Labels con madurez y embargo, splits walk-forward, TrainingSpec/Run, artefactos CAS, ModelRef, promoción	`quant` (G4)
API	API de backtesting `bench-api` (FastAPI, `:8000`, rutas `/v1/...`, Swagger); API de plataforma `/platform/v1` (loopback `:18300`, Bearer, OpenAPI 3.1)	`bench-api`, `api` (G1)

Totales: 26 paquetes (packages/finaz_*), 53 contratos congelados, 8 imágenes, 30 fichas de agente AG-001…AG-030. Estado tras el hito 4 (2026-09-22): todos los gates en PASS salvo S5 (el daemon de stream corre en :s3 sin fencing; su promoción a :s4 está pendiente).

flowchart LR
    subgraph DATOS["Datos y control"]
        PG[("PostgreSQL<br/>control y publicación")]
        CH[("ClickHouse<br/>revision log PIT")]
        RD[("Redpanda<br/>stream y replay")]
        MN[("MinIO / CAS<br/>snapshots sellados")]
    end
    subgraph BANCO["Banco de backtesting (oráculo)"]
        NT["NautilusTrader"]
        VT["VectorTA"]
        SL["Ledger SIM-S"]
    end
    subgraph RT["Runtime causal"]
        CK["ClockEngine + FlowSpec"]
        RN["batch · replay · stream<br/>(fencing PG)"]
    end
    subgraph MOD["Motores de modelos"]
        Q["quant: Ridge, CatBoost,<br/>ARIMA/ETS, GARCH, AutoARIMA"]
        O["opt: Ledoit-Wolf, ERC,<br/>CP-SAT, ConstraintValidator"]
        N["neural: NHITS"]
        F["chronos / timesfm25"]
    end
    subgraph API["APIs"]
        A1["API de backtesting<br/>:8000 /v1"]
        A2["API de plataforma<br/>:18300 /platform/v1"]
    end
    CH --> CK --> RN
    RD --> RN
    RN --> PG
    MN --> Q & O & N & F
    Q & N & F --> O
    BANCO -. "paridad y shadow<br/>(oráculo)" .-> RN
    BANCO --> A1
    PG --> A2
    G{{"Gates G0–G9 · S0–S6"}} -.-> BANCO & RT & MOD

Para quién es este manual¶

Si eres…	Te interesa sobre todo	Empieza por
Trader cuantitativo / analista	Cómo se define una estrategia, qué significa que un backtest sea causal, qué modelo elegir	Parte I · Fundamentos, Catálogo de motores y Parte V · Estrategias
Desarrollador	Contratos, adaptadores, APIs, FlowSpec, runtime	Mapa del sistema, Catálogo de motores, Parte III, Parte VI, Parte VII
Operador / SRE	Docker, servidor, secretos, backups, rollback, gates	Parte VIII · Operación y Gates

Si no sabes por dónde empezar, lee Cómo leer este manual: propone itinerarios de lectura por perfil y explica las convenciones.

La idea central: una tubería causal¶

Todos los motores comparten una tubería causal: los datos entran con su instante de disponibilidad, se convierten en features, un modelo o una política decide, un motor de ejecución o de cartera aplica reglas exactas y, al final, se publican resultados reproducibles que cualquiera puede consultar por API.

flowchart LR
    A["Datos PIT<br/>(Parquet canónico, ClickHouse, calendarios)"] --> B["Features<br/>(EMA, RSI, … con warmup)"]
    B --> C["Decisión<br/>(política, previsión o pesos)"]
    C --> D["Ejecución / cartera<br/>(ledger SIM-S, ConstraintValidator)"]
    D --> E["Resultados<br/>(fills, equity, paridad, ResultRef)"]
    E --> F["API de backtesting :8000<br/>API de plataforma :18300"]

La plataforma reutiliza la infraestructura compartida del servidor (PostgreSQL, ClickHouse, Redpanda y MinIO) sin duplicarla:

flowchart TB
    subgraph TE["Proyecto Compose finaz-trading-engine"]
        APIP["api<br/>127.0.0.1:18300"]
        WB["worker-batch"]
        WS["worker-stream"]
        RP["replay (job one-shot)"]
        JOBS["jobs de modelos<br/>quant · opt · neural · chronos · timesfm25"]
    end
    subgraph FZ["Proyecto Compose finaz (compartido, no se toca)"]
        PGS[("PostgreSQL")]
        CHS[("ClickHouse")]
        RDS[("Redpanda")]
        MNS[("MinIO")]
    end
    APIP --> PGS
    WB --> PGS
    WB --> CHS
    WS --> RDS
    RP --> RDS
    JOBS --> MNS
    WB --> MNS

Cómo está organizado¶

Parte	Contenido
0 · Cómo leer	Itinerarios, convenciones y símbolos
I · Fundamentos	Barras OHLCV, calendarios, indicadores, backtesting causal y el mapa del sistema
Catálogo de motores	Una ficha por motor: qué hace, cuándo usarlo, contrato, imagen, gate y límites
II · Datos	Fuentes, Parquet canónico, calendarios XNYS/XMAD/FX, datos del runtime
III · Motores de backtesting	NautilusTrader vs VectorTA, carriles, ledger SIM-S, paridad y benchmarks
IV · Indicadores	Catálogo de 386, niveles de capacidad, ejemplos numéricos, primitivas
V · Estrategias	Definición, populares P01–P20, cartera y quant, walk-forward, ejemplo completo
VI · API de backtesting y análisis	`bench-api`: backtest, paridad, sweeps, indicadores, jobs
VII · Runtime causal, streaming y modelos	Arquitectura, FlowSpec y Clock, runtime, API de plataforma, modelos, gates
VIII · Operación	Docker, servidor `finaz-new`, backup y rollback, seguridad
IX · Anexos	Glosario, preguntas frecuentes, ejercicios y referencias

Principio rector: nada sin condiciones

En este proyecto ninguna cifra se publica sin sus condiciones (huella del dato, contrato de ejecución, máquina, paridad). Y ningún gate se declara PASS si depende de algo simulado u omitido: entonces es INCOMPLETO. El manual sigue la misma regla: cuando algo no está verificado, lo decimos.