# SKILLS.md | MOEX Neural Network Backtester

> **Архитектурная спецификация для разработки нейросетевой алгоритмической стратегии на Московской бирже.**

## 🎯 Назначение

Multi-task нейросеть (LSTM / Transformer / MLP) обучается на **15 тикерах H1** через Triple Barrier labeling (Marcos Lopez de Prado) и предсказывает:
- вероятность входа (`entry_proba`)
- расстояние до SL в ATR (`sl_distance`)
- расстояние до TP в ATR (`tp_distance`)
- уверенность модели (`confidence`)

## 🗄️ Конфигурация БД

- **Движок:** MySQL/MariaDB
- **Хост:** `nlbotinterface.ru:3306` / `bitcoin_tickers`
- **Подключение:** SQLAlchemy + PyMySQL, `pool_size=5`
- **Имена таблиц:** `{TICKER}_{TF}` (пример: `SBER_H1`, `GAZP_H1`)
- **Структура:**
  - `timestamp` (bigint, PK) — Unix epoch
  - `Date` (varchar) — `YYYY-MM-DD`
  - `Time` (varchar) — `HH:MM`
  - `Open, High, Low, Close` (decimal)
  - `Volume` (bigint)
- **Тикеры:** SBER, GAZP, PLZL, VTBR, LKOH, ROSN, NVTK, MTSS, PHOR, SNGSP, ASTR, X5, MOEX, BITCOIN, EURUSD

## 🧩 Модули и Ответственности

| Модуль | Файл | Назначение |
|--------|------|-----------|
| `config/` | `__init__.py` | Singleton Config из `.env` |
| `db/` | `__init__.py` | SQLAlchemy engine, `fetch_ohlcv(ticker, tf, start, end)` |
| `core/data_loader.py` | `DataPreparator` | Загрузка H1, очистка NaN, сортировка по timestamp |
| `ai/features.py` | `add_technicals` | Feature engineering: ATR, RSI, MACD, BB, OBV, MFI... |
| `ai/labeling.py` | `compute_triple_barrier_labels` | Triple Barrier Method → outcome, pnl_pct, MFE/MAE |
| `ai/dataset_v2.py` | `MultiTickerDataset` | Сборка датасета из всех тикеров, train/val split |
| `ai/model_v2.py` | `LSTMMultiTaskModel` / `TransformerMultiTaskModel` / `MLPMultiTaskModel` | Multi-task архитектуры |
| `ai/trainer_v2.py` | `MultiTaskTrainer` | Combined loss (BCE + MSE), early stopping, scaler |
| `ai/inference_v2.py` | `NeuralPredictor` | Генерация сигналов, фильтрация по порогам |
| `backtest/engine.py` | `NeuralBacktester` | Симуляция сделок, журнал, exit checks |
| `backtest/metrics.py` | `calculate_metrics` | WinRate, PF, MaxDD, Sharpe, Equity Curve |
| `scanner/scanner.py` | `NeuralScanner` | Live-мониторинг всех тикеров |
| `scanner/virtual_trading.py` | `VirtualTrader` | Виртуальная торговля с риск-менеджментом |

## 📐 Triple Barrier Method

Стандартные параметры:
- `tp_atr_mult = 1.5` — TP = entry + ATR × 1.5
- `sl_atr_mult = 1.0` — SL = entry - ATR × 1.0
- `max_holding_bars = 48` — максимум 2 дня H1
- `min_atr_pct = 0.3` — минимальная волатильность

**Breakeven WR** = SL / (SL + TP) = 1.0 / 2.5 = **40%** (при TP=1.5, SL=1.0)

Логика labeling:
- `outcome = 1` (TP hit) → `entry_signal = 1`
- `outcome = -1` (SL hit) → `entry_signal = 0`
- `outcome = 0` (timeout) → `entry_signal = 0` (НЕ 1!)

**КРИТИЧНО:** Никогда не использовать `entry_signal = (outcome != 0)` — это даёт 99% positive rate.

## 🧠 Multi-Task Архитектура

### Выходы модели

```python
output = model(x)
# output.entry_proba  → P(входить) [0-1]
# output.sl_distance  → SL в ATR [0.3-3.0]
# output.tp_distance  → TP в ATR [0.5-5.0]
# output.confidence   → Уверенность [0-1]
```

### Loss

```
Total = entry_weight × BCE(entry) + sl_weight × MSE(SL) + tp_weight × MSE(TP)
```

Defaults: `entry_weight=1.0, sl_weight=0.5, tp_weight=0.5`

### Модели

| Модель | Архитектура | Когда использовать |
|--------|-------------|---------------------|
| `LSTMMultiTaskModel` | 2-layer LSTM + attention | **Рекомендуется** для последовательных паттернов |
| `TransformerMultiTaskModel` | 4-head Transformer encoder | Для сложных нелинейных зависимостей |
| `MLPMultiTaskModel` | 3-layer MLP | Baseline / быстрый прототип |

## 📊 Risk-Reward & Управление

- **Риск:** 1% от текущего капитала (`RISK_PER_TRADE=0.01`)
- **SL/TP:** предсказаны нейросетью в ATR; модель выдаёт `sl_distance_atr`, `tp_distance_atr`
- **Позиция:** `size = (capital × risk) / (sl_distance × price)`
- **Max positions:** 5
- **Commission:** 0.04% (хардкод в constants)
- **Slippage:** 0.05% (DEFAULT_SLIPPAGE)
- **Session filter:** все бары H1 (10:00-18:25 MSK)

## ✅ Критерии приемки (Acceptance Criteria)

- [ ] Датасет генерируется для всех 15 тикеров H1 без NaN
- [ ] `entry_signal` positive rate = 30-50% (НЕ 99%!)
- [ ] Triple Barrier outcomes: TP=33-45%, SL=15-25%, timeout=30-50%
- [ ] Модель обучается, val_loss падает, accuracy > 0.55
- [ ] `NeuralPredictor.predict_signals()` генерирует SL/TP для последних баров
- [ ] `NeuralBacktester` исполняет сигналы с правильным PnL
- [ ] Sharpe ratio > 1.0 на out-of-sample
- [ ] Profit Factor > 1.2 на out-of-sample
- [ ] 114+ тестов проходят (`pytest -v`)
- [ ] Код соответствует PEP8, типизирован, логирование через `loguru`

## 🚀 Типичный Workflow

```bash
# 1. Загрузить данные
python scripts/load_moex_data.py

# 2. Обучить модель
python scripts/train_neural_model.py --start 2023-01-01 --end 2024-01-01

# 3. Бэктест
python main.py --backtest --ticker SBER --start 2023-01-01 --end 2024-01-01

# 4. Пакетный бэктест
python scripts/batch_backtest.py --start 2023-01-01 --end 2024-01-01

# 5. Live-мониторинг
python main.py --scan --interval 60
```