# AGENTS.md

## Overview

Multi-instrument trading analysis system: real-time monitoring, technical analysis, ML prediction, and virtual trading. Not a single app — loosely coupled collection of tools sharing a MySQL DB.

## Entrypoints

| Script | Purpose |
|--------|---------|
| `execute.py` | Production orchestrator: polls DB for new H1 candles, spawns `analyzer/analyzer.py` subprocesses, manages aggregator + virtual trader |
| `aggregator.py --server` | TCP (9050) + WebSocket (8765) data distribution hub |
| `aggregator.py` (no args) | Reads JSON from stdin, forwards to TCP server |
| `analyzer/analyzer.py --inst <INSTR> --json` | Multi-timeframe technical analysis as subprocess |
| `AI/ai_binary/main.py` | ML prediction CLI (see `AI/ai_binary/AGENTS.md`) |

## Startup order

1. Start MySQL (remote: `nlbotinterface.ru:3306`, DB `bitcoin_tickers`)
2. `python aggregate.py --server` (or let `execute.py` auto-start it)
3. `python execute.py`

## Key commands

```bash
python execute.py                         # full monitoring + trading loop
python aggregator.py --server             # standalone aggregator
python analyzer/analyzer.py --inst BTC --json          # single-instrument analysis
python analyzer/analyzer.py --inst BTC --json --force  # force re-analyze
```

## Architecture

- **`execute.py`** — main loop: polls `{INSTRUMENT}_H1` tables for new max timestamps every hour, spawns analyzer subprocesses (max 5 parallel via ThreadPoolExecutor), forwards JSON results to aggregator TCP 9050, runs VirtualTrader (position sizing, TP/SL, trailing stop). Persists state in `portfolio.json`.
- **`aggregator.py`** — TCP server receives JSON from analyzers, stores per-instrument data with history (limit 3 entries), broadcasts to WebSocket clients on 8765.
- **`analyzer/analyser.py`** — multi-timeframe (H1/D1/W1) technical analysis: trend, volatility, candle patterns, levels, wave analysis, price action/volume, pullback, ATR, trading signals. Outputs JSON on stdout.
- **`AI/ai_binary/`** — separate ML subsystem with its own `AGENTS.md`. TensorFlow/Keras LSTM+Attention models. Not called by `execute.py`.
- **`moex/`** — MOEX exchange data integration (`moex.py`).

## Config

- **Root**: `config.json` — central config for `execute.py` and `analyzer/analyzer.py` (virtual trader, pattern thresholds, timeframes, signal weights, atr/volatility/wave parameters).
- **analyzer**: `analyzer/config.json` — separate copy, loaded by analyzer subprocess.
- **AI**: `AI/ai_binary/config.py` — hardcoded `Config` class with DB creds, window sizes, risk params.
- `exclude.json` (optional) — JSON array of instrument names to skip during monitoring.

## Database

MySQL at `nlbotinterface.ru:3306`, DB `bitcoin_tickers`, user `bitcoin`. Tables: `instruments` (instrument list), `{INSTRUMENT}_H1` / `_D1` / `_W1` per instrument. Credentials hardcoded in `execute.py:DB_CONFIG` and `config.json`. Do not commit secrets.

## Virtual trader

Managed by `execute.py:VirtualTrader`. State in `portfolio.json`. Long-only by default. 10% position size, 1.5% TP, 0.8% SL, optional trailing stop (activates at 0.5% gain, trails at 0.3% distance). Initial capital: 10000.

## Conventions

- `.ipynb_checkpoints/` directories are Jupyter artifacts — never edit them
- `AI/ai_binary_backup_full/` is a stale backup — never edit it
- Hardcoded credentials; no `requirements.txt` or `pyproject.toml`
- `MAX_ANALYZER_WORKERS = 5` caps concurrent analyzer subprocesses
- `aggregator.log` is generated at runtime (from `execute.py`'s aggregator subprocess)
- `portfolio.json` is the live virtual trader state — do not delete
- Weekly schedule (`_W1`): Monday at UTC midnight (weekday 0)