Easy Trading App (NebulaQuant)

Backend + web GUI pro výzkum, backtest, paper trading a nasazení jednoduchého „agent“ režimu.

Co to umí (stav teď)

• Data pipeline: fetch_store přes CCXT → ukládání do TimescaleDB → načítání pro grafy, indikátory, ML.
• Grafy: OHLC + volitelně Heikin Ashi / Renko (jako base chart i overlay).
• Indikátory: pandas-ta + custom indikátory, včetně:
  • flat_market (detekce „flat/range“),
  • candle_patterns (≈30 nejběžnějších svíčkových formací, binární sloupce),
  • harmonic_patterns (ABCD/Gartley/Bat/Butterfly/Crab + pattern_score, bez future-leakage).
• DSL strategie: pravidla podmínka -> ACTION [TAG] + validace a vizualizace signálů v grafu.
• ML: trénink klasifikátorů (XGB/RF/LR/LGBM/SVM) a predikce do sloupců:
  • ML_SIGNAL (0/1),
  • ML_PROB (0..1 = confidence pro LONG),
  • ML_ALLOW / ML_ABSTAIN (abstain zóna pro potlačení obchodů v nejistotě).
• ML „label mode“ (co se učí):
  • direction (default): close[t+h] > close[t],
  • triple_barrier: TP/SL/timeout event (blíž exekuci).
• Kalibrace pravděpodobností (pro ML_PROB): sigmoid / isotonic.
• Filtrace ML signálů:
  • přes DSL (gating pomocí indikátorů; v režimu Combined je DSL vyhodnocené na frame s ML_SIGNAL/ML_PROB),
  • nebo přes volby „Confidence + threshold“, „Confirm N candles“ a „Abstain low/high“ (backtest/paper/agent).
• MTF (multi-timeframe) featury: volba mtf_timeframes (např. 1h,4h) → sloupce se suffixem ..._1h, ..._4h.
• Backtest: DSL/ML/Combined, equity + trades + metriky; podporuje jednoduchý fill model spread_bps + impact_bps.
• Paper sessions (Schedule tab):
  • více paralelních sessions, každá má vlastní equity a tabulku obchodů,
  • equity křivka + trades table pod každou běžící session,
  • risk guardrails (max daily loss, max DD, cooldown po sérii ztrát, max leverage/notional),
  • audit trail rozhodnutí (best-effort do DB).
• Pattern scanner:
  • endpoint /api/pattern_scan,
  • UI: „Pattern scanner“ v Indicators tabu + volitelný overlay markerů do grafu.

Quick start (Docker)

1. Nastav .env (DB + burza/klíče) podle docker-compose.yml.
2. Spusť:

./scripts/docker_compose_up_logged.sh

Pro no-cache build:

./scripts/docker_compose_build_logged.sh --no-cache

• Build logy: logs/docker-compose-build-*.log

• Up logy: logs/docker-compose-up-*.log

• GUI: http://localhost:3000

• Backend: http://localhost:8000

Database migrations

Před prvním spuštěním backendu aplikuj schéma:

python -m db.migrate

Spusť to ve stejném prostředí/kontejneru, kde běží backend (má přístup k PG).

API auth (optional)

Pokud nastavíš NQ_API_TOKEN, backend vyžaduje header X-API-Key nebo Authorization: Bearer ... pro všechny endpointy kromě /health, /api/version, /docs, /openapi.json.

WebSockety (/ws/*) očekávají buď header Authorization: Bearer ..., X-API-Key, nebo query param token / api_key.

Frontend může posílat token automaticky přes:

VITE_API_TOKEN=your-token

DSL external sync (VS Codium bridge)

Backend přijímá DSL přes:

POST /api/dsl_push
{ "dsl": "ENTRY_LONG ..." }

Front‑end může poslouchat /api/dsl_stream (SSE). V Strategy editoru zapni External DSL sync.

Volitelné rate limiting:

NQ_RATE_LIMIT_RPS=20

NQ_CORS_ORIGINS lze nastavit jako seznam originů (oddělených čárkou), např.:

NQ_CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

Rust core indicators (optional)

If you run the Rust sidecar (rust_core) and set:

RUST_CORE_URL=http://localhost:8787
NQ_RUST_INDICATORS=true

then common OHLCV indicators (EMA/SMA/RSI/MACD/ATR/BBands/Stoch/ADX/VWAP/WMA/ROC/MOM/CCI/MFI/OBV/CMF) will be computed via Rust (fallback to Python if unavailable).

Production note: if NQ_ENV=prod (or production), the app will fail fast on startup if RUST_CORE_URL is missing or the Rust health check fails. In dev, the fallback is allowed, but a warning is logged when Rust is missing.

Rust core runtime flags (normalize/orderflow/market fetch)

Core runtime paths default to Rust and do not silently fall back in production. For development-only fallback you must explicitly allow it:

RUST_CORE_URL=http://localhost:8787
NQ_RUST_NORMALIZE=true
NQ_RUST_ORDERFLOW=true
NQ_RUST_MARKET_FETCH=true

# Dev-only fallbacks (default false)
NQ_ALLOW_PYTHON_NORMALIZE=false
NQ_ALLOW_PYTHON_ORDERFLOW=false

If NQ_ENV=prod, missing Rust or non-200 Rust responses will raise immediately. Set the NQ_ALLOW_PYTHON_* flags only in dev when you intentionally want Python fallback.

Polars-first execution (optional)

Set NQ_POLARS=true to keep the majority of the data pipeline in polars and only fall back to pandas for legacy helpers (DSL validation, indicator metadata, ML labels and exports). Combine it with NQ_POLARS_ONLY=true to log a clear error whenever polars is absent (the service still stays functional), and with NQ_POLARS_QUIET=true to suppress the retry warnings once the dependency is stable.

Runbook: docs/RUNBOOK.md (prod/dev env flags + troubleshooting).

Log rotation (optional):

LOG_MAX_BYTES=10485760
LOG_BACKUP_COUNT=5

Logging guard (CI)

Project enforces strict logging rules (no str(exc) and no logger.warning(...exc...) without exc_info=True).

Run:

./scripts/ci.sh

Základní workflow

1. Data → Load data
   • načti svíčky do DB (fetch_store).
2. Indicators
   • vyber indikátory + parametry (včetně price_source a MTF override).
3. Strategy (DSL)
   • napiš pravidla, validuj, zobraz signály do grafu.
4. ML
   • natrénuj modely, zvol filtr signálu (majority/prob + threshold/confirm).
5. Backtest / Results
   • ověř výkon a realistickou exekuci (fee/spread/impact).
6. Schedule / Paper
   • spusť paper session, sleduj equity a obchodní log v reálném čase.

Poznámky k ML (prakticky)

• ML se učí na featurách z indikátorů (včetně pattern sloupců) a cílovém labelu.
• ML_PROB můžeš použít i přímo v DSL jako „abstain zone“, např.:
  • ML_PROB > 0.6 AND ML_SIGNAL == 1 -> ENTRY_LONG [ML]
  • ML_PROB < 0.4 AND ML_SIGNAL == 0 -> ENTRY_SHORT [ML]
• Pokud používáš backendový „abstain“ (low/high), můžeš v DSL navíc kontrolovat ML_ALLOW == 1.
• Pokud nechceš, aby systém „překlikával“ každý bar, používej „edge“ pravidla (změna signálu), např.:
  • ML_SIGNAL == 1 AND shift(ML_SIGNAL, 1) == 0 -> ENTRY_LONG [EDGE]

Kompletní reference: DSL_REFERENCE.md.

IOS-like CLI Shell (Arista/Cisco styl)

Interaktivní konzole pro „show/enable/conf t/commit“ práci s agent configem a uloženými strategiemi/indicator sety. Shell běží v separátním kontejneru a volá backend přes HTTP.

Spuštění:

docker compose run --rm ai_trading_cli_shell

Základní workflow:

• show running-config
• enable
• conf t
• set symbol BTC/USDT
• set timeframe 1h
• set mode combined
• set ml min-prob 0.6
• set ml invert
• commit
• end

Nápověda:

• ? (např. show ?)
• help

Více: CLI_REFERENCE.md.

MTF (multi-timeframe) v kostce

• mtf_timeframes: extra timeframe(s), které se periodicky dopočítají a mergnou do base timeframe.

Developer workflow & fast feedback

1. Lokální statická analýza (bez spuštění aplikace)

   • Rust: spusť cargo check z kořenového adresáře a používej rust-analyzer v editoru (VS Code, RustRover, etc.) — chyby vidíš ihned, ještě než spustíš build nebo Docker.
   • Python: definuj pyrightconfig.json/mypy.ini (resp. přidej pyright config do pyproject.toml) a spouštěj pyright resp. mypy před odesláním změn. Obvykle stačí pyright (pokryje i typy pro FastAPI + pandas) a ruff check src/ tests/.
   • Ruff: ruff check . odhalí syntaktické chyby, nepoužité importy a další drobnosti v milisekundách. Přidej prefiks do VS Code tasků nebo hook automaticky před git commit.

2. Docker Compose s bind mounty pro okamžité změny

   • Použij docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build pro vývoj. docker-compose.dev.yml přidává bind mounty (.:/app:z), reload příkaz pro backend (uvicorn app:app --reload) a cargo watch pro Rust core.
   • Díky bind mountu měníš kód lokálně a změny se okamžitě promítnou do běžících kontejnerů. Pro backend i worker mapujeme celý repozitář a logy zůstávají v ./logs.
   • Ve vývojovém režimu se backend spouští přes uvicorn s --reload, takže FastAPI server se restartuje po každé úpravě.

3. Cargo watch uvnitř Rust kontejneru

   • Docker image s Rust core nyní obsahuje cargo-watch. Vývojový docker-compose.dev.yml nastavuje command: cargo watch -x run.
   • Jakmile uložíš Rust soubor, cargo watch v kontejneru automaticky překompiluje a znovu spustí službu (target cache zůstává uvnitř kontejneru).
   • Pokud chceš spustit přímo místně mimo Docker, nainstaluj cargo-watch (cargo install cargo-watch) a spusť cargo watch -x run ve složce rust_core.

Automatická kontrola před spuštěním

• Před zapnutím Docker dev stacku spusť ./scripts/preflight.sh. Využívá cargo check, pyright a ruff (pokud jsou nainstalované) a brzo chytí chybné typy nebo lint problémy.
• Pokud některý nástroj chybí (např. pyright není nainstalován) skript o tom jen vypíše upozornění místo chyby.
• Tento krok můžeš přidat do svého workflow nebo pre-commit hooku tak, aby se kontrola spouštěla ještě před změnou kontejneru.

4. Multi-stage builds + caching Rust závislostí
   • Rust Dockerfile respektuje typický pattern: nejprve se kopírují pouze Cargo.toml/Cargo.lock + prázdný src/main.rs, spustí se cargo build --release pro cache závislostí, a až poté se přidají skutečné zdrojáky.
   • Výsledkem je, že změna v src/ nezruší cache cargo build a build trvá mnohem méně času. cargo-watch využívá stejnou cache, takže kompilace je rychlá i při vývoji.

Tipy

• Použij ruff, pyright, mypy + cargo check v pre-commit nebo make lint.
• U Pythonu mohou pomoci nástroje jako watchmedo shell-command --patterns "*.py" --recursive --command "pytest" nebo nodemon pro restart datových skriptů.
• U Rustu můžeš spouštět cargo check automaticky po uložení pomocí cargo watch -x check.
• Sloupce mají suffix _{tf}, např. ema_20_1h, harmonic_patterns_gartley_bull_4h.
• Pro harmonics můžeš mít jiný pivot lookback / confirm per TF (MTF overrides v Indicators panelu).

Troubleshooting

• Graf je prázdný: nejdřív spusť Load data (a ověř, že burza/DB běží).
• Pokud ML nevidí žádné featury: zkontroluj indikátory (a že DataFrame nemá jen NaN).
• Pattern scanner nic nenajde: přidej candle_patterns / harmonic_patterns do indikátorů, nebo spusť scan s vyšším limitem.