YAXKAX — Ancestral Precision

Docs

Guía de Instalación

Cómo levantar el stack completo de YAXKAX: backend de datos, CLI de machine learning, frontend y despliegue en producción con systemd y Cloudflare.

Monorepo

Un solo repositorio, dos mitades. La raíz es el frontend SvelteKit, compilado con adapter node y servido en el puerto 3042. El directorio server/ es el backend Python: una API FastAPI de solo lectura en el puerto 8000 y una CLI Typer que es el único punto de entrada que escribe en la base.

Estructura

yaxkax-ui/          raíz del repo · frontend SvelteKit (adapter-node, puerto 3042)
├── src/            rutas, componentes y estilos del terminal
├── build/          salida de producción → node build/index.js
└── server/         backend Python · API FastAPI :8000 + CLI Typer
    ├── configs/    experimentos ML (un YAML = un experimento)
    ├── migrations/ esquema SQLite (append only)
    └── deploy/     units de systemd (API, ingesta, ML)

Backend

Requiere Python 3.11 o superior. La ingestión usa el FAPI público de Binance, así que no necesita claves de exchange.

Instalación

cd server

# 1. Entorno virtual
python3 -m venv .venv
# Si tu python viene sin ensurepip:
#   python3 -m venv --without-pip .venv
#   curl -sSO https://bootstrap.pypa.io/get-pip.py && .venv/bin/python get-pip.py

# 2. Paquete en modo editable + dependencias de desarrollo
make install                        # = pip install -e ".[dev]"
.venv/bin/pip install -e ".[ml]"    # opcional: CLI de machine learning (LightGBM)

# 3. Configuración local (el .env real nunca se commitea)
cp .env.example .env

Variable	Qué controla
YAXKAX_DB_PATH	Ruta del archivo SQLite (modo WAL)
YAXKAX_API_KEYS	Claves de la API de solo lectura (header X-API-Key)
INGEST_SYMBOLS	Símbolos a ingerir, en CSV (BTCUSDT,ETHUSDT,…)
INGEST_INTERVAL	Intervalo de las barras (1d por defecto)
MODELS_DIR	Directorio de artefactos ML versionados

Migrar · ingerir · servir

make migrate    # aplica las migraciones pendientes (idempotente)
make ingest     # ingesta klines de los símbolos de .env
make serve      # API de solo lectura en 127.0.0.1:8000 (uvicorn)

Verificación

curl localhost:8000/healthz                          # {"status":"ok"}
curl -H "X-API-Key: $KEY" localhost:8000/inventory   # cobertura por ticker
# $KEY = una de las claves de YAXKAX_API_KEYS; sin header → 401 (esperado)

CLI de Machine Learning

Cada experimento vive en un YAML bajo server/configs/ y se pasa con la bandera -c. La API nunca entrena ni infiere: GET /predictions sirve los resultados precomputados de la tabla prediction.

Comandos

.venv/bin/yaxkax train -c configs/alt_btc_1d.yaml      # entrena + backtest + artefacto
.venv/bin/yaxkax backtest -c configs/alt_btc_1d.yaml   # solo métricas, sin artefacto
.venv/bin/yaxkax predict -c configs/alt_btc_1d.yaml    # escribe la tabla prediction
.venv/bin/yaxkax models list                           # registro de modelos
.venv/bin/yaxkax models show alt_btc_1d
.venv/bin/yaxkax models prune alt_btc_1d               # conserva keep_versions

yaxkax train

Backtest walk-forward con purge sobre toda la historia y guarda un artefacto versionado (config congelada incluida) en MODELS_DIR.

yaxkax backtest

Solo métricas out of sample; no escribe ningún artefacto.

yaxkax predict

Última barra por símbolo → tabla prediction. Se niega si el modelo supera max_model_age_hours: nunca sirve predicciones con un modelo vencido.

yaxkax models list · show · prune

Inspecciona y depura el registro de modelos en filesystem.

Frontend

La clave YAXKAX_API_KEY se usa únicamente en cargas del lado del servidor de SvelteKit y jamás llega al navegador: las páginas en vivo inyectan el header X-API-Key desde el servidor.

Instalación y build

npm ci
cp .env.example .env    # YAXKAX_API_KEY = una clave de YAXKAX_API_KEYS del backend

npm run dev             # desarrollo · Vite carga .env automáticamente
npm run build           # producción → build/
node build/index.js     # sirve el terminal en el puerto 3042

Producción · systemd + Cloudflare Tunnel

Los units viven en server/deploy/. Solo los timers escriben en la base; la API y el frontend solo leen.

Activar units y timers

sudo cp server/deploy/*.service server/deploy/*.timer /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now yaxkax-api.service
sudo systemctl enable --now yaxkax-ingest.timer yaxkax-ml.timer

Timer	Horario	Qué dispara
yaxkax-ingest.timer	00:10 UTC	Ingesta diaria poco después del cierre de la barra 1d.
yaxkax-ml.timer	00:25 UTC	Reentrena y predice después de la ingesta.

El gotcha de EnvironmentFile

Un servidor adapter node ya compilado no carga .env automáticamente como lo hace Vite en desarrollo. El unit del frontend necesita una línea EnvironmentFile= para que la clave de la API llegue al proceso:

# /etc/systemd/system/yaxkax.service → bajo [Service]
EnvironmentFile=/home/developer/cancun-codes/yaxkax-ui/.env

# después:
sudo systemctl daemon-reload && sudo systemctl restart yaxkax.service

Por último, cloudflared expone el puerto 3042 por HTTPS mediante un tunnel de Cloudflare: sin abrir puertos y sin IP pública.