andres31416/pen-usd-trading-model

PEN/USD Trading Model

Modelo Transformer (arquitectura tipo PatchTST) para forecasting del tipo de cambio Sol Peruano (PEN) / Dolar Americano (USD), con una capa de reglas que convierte la prediccion en señales de trading: COMPRAR / VENDER / MANTENER.

Entrenado sobre andres31416/pen-usd-trading-dataset.

Arquitectura

El modelo esta inspirado en PatchTST ("A Time Series is Worth 64 Words: Long-term Forecasting with Transformers", Nie et al. 2023): en vez de procesar la serie de precios punto por punto, la divide en parches (segmentos superpuestos) y aplica atencion (self-attention) sobre esos parches. Esto le permite capturar tanto patrones de corto plazo como tendencias de largo plazo de forma mas eficiente que un Transformer tradicional o una LSTM.

Precio (serie temporal)
        |
        v
  Division en parches
        |
        v
  Embedding + Positional Encoding
        |
        v
  Transformer Encoder (N capas, atencion multi-cabeza)
        |
        v
  Cabeza de prediccion -> precio(s) futuro(s)

Dos tipos de señal, combinadas en una alarma

El proyecto no se queda solo en "predecir el precio futuro". Combina dos enfoques complementarios:

1. Señal de forecasting (signal_logic.generar_senal): que predice el Transformer sobre el precio FUTURO (proximo paso).

2. Señal tecnica (technical_indicators.generar_senal_tecnica): evalua si el precio ACTUAL esta en una zona anormal (sobrecompra/sobreventa) respecto a su comportamiento reciente, usando 3 indicadores clasicos de estrategias de "mean reversion":

   • RSI (Relative Strength Index): >70 sobrecompra, <30 sobreventa.
   • Bandas de Bollinger (%B): precio fuera del canal normal de desviacion estandar.
   • Z-score: cuantas desviaciones estandar esta el precio actual respecto a su media movil reciente.

   Los 3 indicadores "votan" COMPRAR/VENDER/NEUTRAL, y la señal tecnica final es la que tenga mayoria de votos.

3. Alarma combinada (signal_logic.combinar_senales): junta ambas señales en una sola alerta, con 3 niveles:

   Forecasting	Tecnico	Resultado
   COMPRAR	COMPRAR	🔴 ALARMA ALTA — Comprar
   VENDER	VENDER	🔴 ALARMA ALTA — Vender
   COMPRAR	MANTENER (o viceversa)	🟡 ALARMA MODERADA — con precaucion
   COMPRAR	VENDER (opuestas)	⚪ SIN ALARMA — señales contradictorias
   MANTENER	MANTENER	⚪ SIN ALARMA — nada que hacer

   La logica completa esta en src/inference.py, que corre ambas evaluaciones y muestra los 3 bloques de resultado (prediccion, señal tecnica, alarma combinada).

Por que esta arquitectura

• Maneja bien series largas (el dataset tiene historico diario desde 2001).
• Es el estado del arte actual en forecasting de series de tiempo con Transformers, superando en varios benchmarks a LSTMs e incluso a otros Transformers mas complejos (Informer, Autoformer).
• Se adapta naturalmente a fine-tuning incremental (ver siguiente seccion), que era un requisito clave de este proyecto.

Aprendizaje incremental (sin re-entrenar desde cero)

Un requisito importante de este proyecto es que el modelo pueda incorporar datos nuevos en tiempo real sin re-entrenar desde cero.

Es importante ser claro sobre como se logra esto de forma segura: un modelo que actualiza sus pesos con CADA dato nuevo, sin ningun control, sufre "catastrophic forgetting" (olvida patrones de largo plazo al sobre-ajustarse a lo mas reciente) — esto es especialmente riesgoso en un modelo de trading.

Por eso este proyecto implementa fine-tuning incremental controlado (src/incremental_update.py):

1. El modelo parte de sus pesos ACTUALES (no se reinicia).
2. Se ajusta con los datos nuevos usando un learning rate mucho mas bajo que el entrenamiento original (incremental_learning_rate en config/config.py), y pocas epochs.
3. Antes de sobreescribir el checkpoint, se guarda automaticamente un respaldo con timestamp en checkpoints/backup_*.pt, para poder revertir si el modelo actualizado empeora.
4. Se lleva un contador (incremental_updates) de cuantas veces se ha actualizado el modelo desde su entrenamiento inicial.

Este enfoque es el mismo que se usa en sistemas de trading algoritmico reales en produccion (a veces llamado online fine-tuning o continual learning con warm-start), y es mucho mas estable que el verdadero "online learning" punto-a-punto, que no es apto para modelos Transformer robustos como este.

Estructura del repositorio

pen-usd-trading-model/
├── README.md                    # Esta model card
├── requirements.txt
├── config/
│   └── config.py                 # Hiperparametros y rutas
├── src/
│   ├── dataset.py                 # Carga y ventaneo de datos
│   ├── model.py                   # Arquitectura PatchTST
│   ├── train.py                   # Entrenamiento inicial (desde cero)
│   ├── incremental_update.py      # Fine-tuning incremental (warm-start)
│   ├── signal_logic.py            # Señal forecasting + combinacion de alarma
│   ├── technical_indicators.py    # RSI, Bollinger %B, Z-score (señal tecnica)
│   └── inference.py               # Prediccion + señal tecnica + alarma combinada
└── checkpoints/
    ├── best_model.pt               # Checkpoint activo (se sube via Git LFS)
    ├── backup_*.pt                 # Respaldos automaticos antes de cada update
    └── training_history.json       # Historial de perdida por epoch

Como entrenar el modelo desde cero

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Asegurate que el dataset este clonado como carpeta hermana, o define:
export PEN_USD_DATASET_DIR=/ruta/a/pen-usd-trading-dataset/data

python3 src/train.py

Esto genera checkpoints/best_model.pt y checkpoints/training_history.json.

Como actualizar el modelo con datos nuevos (incremental)

python3 src/incremental_update.py --nuevos_datos ruta/a/datos_nuevos.csv

El CSV de datos nuevos debe tener el mismo formato que los del dataset (date,time,datetime_utc,open,high,low,close,volume).

Como generar una prediccion y señal de trading

python3 src/inference.py --datos ruta/a/daily.csv

Salida de ejemplo (3 bloques: forecasting, tecnico, alarma combinada): ```

RESULTADO DE LA PREDICCION (FORECASTING)

Precio actual: 3.40000 Prediccion (siguiente paso): 3.36667 Prediccion ajustada al banco: 3.36667 (multiplicador=1.0) Cambio esperado: -0.980% Señal de forecasting: VENDER (confianza: alta)

Prediccion completa (5 pasos futuros): paso +1: 3.36667 paso +2: 3.35323 ...

SEÑAL TECNICA (basada en el precio ACTUAL)

RSI: 55.42 Bollinger %B: 0.70 Z-score: 0.79 Votos compra/venta: 0/0 Señal tecnica: MANTENER Detalle: RSI=55.4 (zona neutral) | Bollinger %B=0.70 (dentro del canal normal) | Z-score=0.79 (zona neutral)

ALARMA COMBINADA (forecasting + tecnico)

Nivel de alarma: MODERADA Accion final: VENDER ¿Coinciden?: NO Mensaje: Solo una de las dos señales sugiere accion (VENDER). Alarma moderada: considerar con precaucion.

## Configuracion del spread bancario

En `config/config.py`, `SignalConfig.bank_spread_multiplier` permite
ajustar la prediccion de mercado a una aproximacion de lo que cobraria
un banco comercial especifico (ej. BCP), sin contaminar el entrenamiento
del modelo con ese margen comercial. Ajusta este valor comparando
periodicamente contra la tasa real publicada por el banco.

## Limitaciones y consideraciones importantes

- Este modelo predice **precio**, no garantiza rentabilidad. Los mercados
  de forex son influenciados por eventos politicos, decisiones del BCRP,
  y factores globales que un modelo entrenado solo con precio historico
  no puede anticipar.
- El fine-tuning incremental reduce el riesgo de "olvido catastrofico"
  pero no lo elimina por completo. Se recomienda monitorear
  `training_history.json` y comparar el desempeño antes/despues de cada
  actualizacion incremental.
- Este modelo es una herramienta de apoyo a la decision, no un sistema
  de ejecucion automatica de ordenes por si solo. La conexion a un broker
  real para ejecutar ordenes es un componente separado (a definir en el
  repositorio de despliegue en GitHub).

## Licencia

MIT.