# AGENTS.md — MOEX Neural Network Backtester

> **Центральный хаб для всех AI-агентов. Читается ПЕРВЫМ при каждой сессии или запросе.**

---

## ⚠️ ПРОТОКОЛ ЧТЕНИЯ СОСТОЯНИЯ (ОБЯЗАТЕЛЕН)

**Перед выполнением ЛЮБОЙ задачи агент ОБЯЗАН прочитать актуальное состояние проекта:**

```
1. docs/reports/00-STATE.md      — мастер-файл: статус стратегии, текущая фаза, что сломано
2. docs/reports/02-BUGS.md       — известные баги (читать перед code review/исправлениями)
3. docs/reports/03-PARAMETERS.md — текущие параметры (читать перед бэктестами/тюнингом)
4. docs/reports/04-CHANGELOG.md  — история изменений (читать для контекста)
```

**После внесения изменений агент ОБЯЗАН обновить соответствующие файлы в `docs/reports/`:**

| Действие агента | Обновить файл |
|-----------------|---------------|
| Проведён бэктест | `01-BACKTEST-RESULTS.md`, `00-STATE.md` (метрики) |
| Найден/исправлен баг | `02-BUGS.md` |
| Изменены параметры | `03-PARAMETERS.md` |
| Любое изменение | `04-CHANGELOG.md` (append, сверху) |
| Изменился статус стратегии | `00-STATE.md` |

---

## 🎯 О ПРОЕКТЕ

**MOEX Neural Network Backtester** — алгоритмический движок для генерации торговых сигналов на Московской бирже с использованием **нейронной сети** (LSTM/Transformer/MLP).

### Стратегия

- **Только нейросеть**: старый VSA-алгоритм полностью удалён
- **Multi-Task Learning**: модель предсказывает entry/SL/TP/confidence одновременно
- **Triple Barrier Method** для labeling (Marcos Lopez de Prado)
- **15 тикеров** MOEX + крипта + форекс обучаются вместе

---

## 📂 Карта файлов состояния

```
docs/reports/
  00-STATE.md              ← Мастер-файл: метрики, фаза, статус
  01-BACKTEST-RESULTS.md   ← Полный отчёт последнего бэктеста
  02-BUGS.md               ← Все известные баги
  03-PARAMETERS.md         ← Глобальные + per-ticker параметры
  04-CHANGELOG.md          ← Хронология всех изменений

moex_vsa_backtester/reports/
  BACKTEST_REPORT_*.md       ← Детальные отчёты бэктестов
  batch_backtest_*.json      ← Raw JSON с метриками
  *_metrics_*.json           ← Потикерные метрики
```

---

## 🤖 Агенты и их зоны ответственности

| Агент | Файл конфигурации | Роль | Что читает | Что пишет |
|-------|-------------------|------|-----------|-----------|
| **backtest-runner** | `.opencode/agents/backtest-runner.md` | Запуск бэктестов, анализ | 00, 01, 03 | 00, 01, 03, 04 |
| **model-trainer** | `.opencode/agents/model-trainer.md` | Обучение и тюнинг нейросети | 00, 01, 03 | 00, 03, 04 |
| **market-analyst** | `.opencode/agents/market-analyst.md` | Анализ сигналов и рыночных данных | 00, 01 | 04 |
| **bug-hunter** | `.opencode/agents/bug-hunter.md` | Поиск багов и проблем | 00, 02 | 02, 04 |
| **code-reviewer** | `.opencode/agents/code-reviewer.md` | Code review | 00, 02 | 04 |
| **neural-dev** | `.opencode/agents/neural-dev.md` | Разработка нейросетевого кода | 00, 02, 03 | 00, 02, 04 |

---

## ⚡ Быстрый старт (новая сессия)

> **Все команды выполняются из окружения `tf_env`:** `conda run -n tf_env <команда>`, либо через `conda activate tf_env` перед запуском.

```bash
# 1. Прочитать состояние
cat docs/reports/00-STATE.md

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

# 3. Бэктест одного тикера
conda run -n tf_env python main.py --backtest --ticker SBER --start 2023-01-01 --end 2024-01-01

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

# 5. Проверить тесты
conda run -n tf_env pytest -v
```

---

## 🏗️ Архитектура проекта

```
moex_vsa_backtester/
  config/       Singleton Config (dotenv → dict). config["KEY"] / config.get("KEY", default)
  db/           SQLAlchemy+PyMySQL, pool_size=5. Tables: {TICKER}_{TF} (e.g. SBER_H1)
  core/         data_loader, risk_manager, virtual_trader, trade_journal
  backtest/     NeuralBacktester + metrics
  ai/           Neural pipeline:
                  - labeling.py         (Triple Barrier)
                  - dataset_v2.py       (Multi-ticker dataset)
                  - features.py         (Feature engineering)
                  - model_v2.py         (LSTM/Transformer/MLP)
                  - trainer_v2.py       (Multi-task training)
                  - inference_v2.py     (Prediction)
  scanner/      NeuralScanner (live monitoring), scheduler, virtual_trading
  domain/       Dataclasses + Enums — re-exported flat from domain/__init__.py
  tests/        test_labeling, test_dataset_v2, test_model_v2, test_trainer_v2, test_inference_v2, test_backtester
  utils/        Market hours + holidays
  scripts/      train_neural_model.py, batch_backtest.py, deep_analysis.py, load_moex_data.py
  models/       .pt (PyTorch) trained models
  reports/      Backtest reports and metrics JSON
```

---

## 🗄️ База данных

- **Хост:** `nlbotinterface.ru:3306` / `bitcoin_tickers`
- **Таблицы:** `{TICKER}_{TF}` (верхний регистр) — 15+ тикеров × H1
- **Тикеры с данными:** SBER, GAZP, PLZL, VTBR, LKOH, ROSN, NVTK, MTSS, PHOR, SNGSP, ASTR, X5, MOEX, BITCOIN, EURUSD

### 🔄 MOEX: данные не обновляются?

Если сканер не видит новых свечей по MOEX тикерам (в логе нет `[TICKER] new candle HH:MM at HH:MM`):

1. **Проверить загрузчик MOEX данных:**
   ```bash
   ps aux | grep moex.py
   ```
   Скрипт `~/labdata/bitcoin/moex/moex.py` должен быть запущен. Он выгружает котировки MOEX с биржи в БД с периодичностью ~1-5 мин.

2. **Если moex.py не запущен:**
   ```bash
   cd ~/labdata/bitcoin/moex && python moex.py
   ```
   Или перезапустить через `systemctl` / `screen` / `tmux`, если используется.

3. **Проверить последнюю свечу в БД напрямую:**
   ```bash
   python -c "
   from db import fetch_ohlcv_last_bars
   df = fetch_ohlcv_last_bars('SBER', 'H1', 5)
   print(df[['timestamp', 'Date', 'Time', 'Close']].to_string())
   "
   ```

---

## ⚙️ Ключевые команды

> **Все команды выполняются из окружения `tf_env`:** `conda run -n tf_env <команда>`, либо через `conda activate tf_env` перед запуском.

```bash
# Обучение нейросети
python scripts/train_neural_model.py --start 2023-01-01 --end 2024-01-01

# Бэктест одного тикера
python main.py --backtest --ticker SBER --start 2023-01-01 --end 2024-01-01

# С AI-фильтром (порог входа)
python main.py --backtest --ticker SBER --ai-threshold 0.7

# Только LONG
python main.py --backtest --ticker SBER --sides LONG

# Пакетный бэктест
python scripts/batch_backtest.py [--ticker SBER,GAZP] [--start ...] [--end ...]

# Мониторинг (сканер)
python main.py --scan --interval 60

# Виртуальная торговля (нейросеть)
python main.py --scan --virtual --capital 1000000 --risk 0.01

# MACD+RSI Strategy (основной режим!) — standalone, без нейросети
python main.py --scan --strategy --interval 60

# MACD+RSI виртуальная торговля
python main.py --scan --virtual --strategy --capital 1000000 --risk 0.01

# HYBRID: MACD+RSI + NN quality evaluation (рекомендуется для торговли!)
python main.py --scan --virtual --strategy --ai-model models/neural_trader_strategy.pt --capital 1000000 --risk 0.01

# HYBRID с кастомным NN порогом качества
python main.py --scan --virtual --strategy --ai-model models/neural_trader_strategy.pt --ai-threshold 0.4 --capital 1000000 --risk 0.01

# Загрузка данных MOEX
python scripts/load_moex_data.py

# Тесты (из окружения conda)
conda run -n tf_env pytest -v
```

---

## 🧠 Архитектура нейросети

### Модели

| Архитектура | Файл | Применение |
|-------------|------|-----------|
| `LSTMMultiTaskModel` | `ai/model_v2.py` | Рекомендуется — учитывает последовательность |
| `TransformerMultiTaskModel` | `ai/model_v2.py` | Для сложных паттернов |
| `MLPMultiTaskModel` | `ai/model_v2.py` | Baseline (быстрый) |

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

```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]
```

### Multi-Task Loss

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

---

## 🐛 Ключевые gotchas (см. также `.opencode/skills/project-gotchas/SKILL.md`)

1. **Config — singleton:** `from config import config`. Мутации `config._config` персистентны.
2. **Triple Barrier** — TP/SL в ATR. Breakeven WR = SL/(SL+TP).
3. **SL-буфер**: `atr_val * 0.3-1.0` — слишком узкий = частые SL хиты.
4. **Positive rate**: должен быть 30-50% (не 99%!).
5. **Morning session** (10-11h MSK): токсична, WR=24%.
6. **xgboost не установлен**: используем только PyTorch.
7. **build_dataset()** кэширует technicals — на Pi 5 ~3-5 мин вместо 30-60 мин.
8. **Feature engineering** дублируется НЕ (теперь единый `ai/features.py`).
9. **pyproject.toml** — НЕ хватает `ai, scanner, domain, utils` пакетов.
10. **`--ai-model` default**: `models/neural_trader.pt`.