6fe2158511
- Introduced a new plan to modify the Optuna objective function to prioritize precision under a recall constraint of 0.35, improving model performance in scenarios where false positives are costly. - Updated training scripts to implement precision-based metrics and adjusted the walk-forward cross-validation process to incorporate precision and recall calculations. - Enhanced the active LGBM parameters and training log to reflect the new metrics and model configurations. - Added a new design document outlining the implementation steps for the precision-focused optimization. This update aims to refine the model's decision-making process by emphasizing precision, thereby reducing potential losses from false positives.
117 lines
5.4 KiB
Markdown
117 lines
5.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
CoinTrader is a Python asyncio-based automated cryptocurrency trading bot for Binance Futures. It trades XRPUSDT on 15-minute candles, using BTC/ETH as correlation features. The system has 5 layers: Data (WebSocket streams) → Signal (technical indicators) → ML Filter (ONNX/LightGBM) → Execution & Risk → Event/Alert (Discord).
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# venv
|
|
source .venv/bin/activate
|
|
|
|
# Run the bot
|
|
python main.py
|
|
|
|
# Run full test suite
|
|
bash scripts/run_tests.sh
|
|
|
|
# Run filtered tests
|
|
bash scripts/run_tests.sh -k "bot"
|
|
|
|
# Run pytest directly
|
|
pytest tests/ -v --tb=short
|
|
|
|
# ML training pipeline (LightGBM default)
|
|
bash scripts/train_and_deploy.sh
|
|
|
|
# MLX GPU training (macOS Apple Silicon)
|
|
bash scripts/train_and_deploy.sh mlx
|
|
|
|
# Hyperparameter tuning (50 trials, 5-fold walk-forward)
|
|
python scripts/tune_hyperparams.py
|
|
|
|
# Fetch historical data
|
|
python scripts/fetch_history.py --symbols XRPUSDT BTCUSDT ETHUSDT --interval 15m --days 365
|
|
|
|
# Deploy models to production
|
|
bash scripts/deploy_model.sh
|
|
```
|
|
|
|
## Architecture
|
|
|
|
**Entry point**: `main.py` → creates `Config` (dataclass from env vars) → runs `TradingBot`
|
|
|
|
**5-layer data flow on each 15m candle close:**
|
|
1. `src/data_stream.py` — Combined WebSocket for XRP/BTC/ETH, deque buffers (200 candles each)
|
|
2. `src/indicators.py` — RSI, MACD, BB, EMA, StochRSI, ATR; weighted signal aggregation → LONG/SHORT/HOLD
|
|
3. `src/ml_filter.py` + `src/ml_features.py` — 23-feature extraction, ONNX priority > LightGBM fallback, threshold ≥ 0.60
|
|
4. `src/exchange.py` + `src/risk_manager.py` — Dynamic margin, MARKET orders with SL/TP, daily loss limit (5%)
|
|
5. `src/user_data_stream.py` + `src/notifier.py` — Real-time TP/SL detection via WebSocket, Discord webhooks
|
|
|
|
**Parallel execution**: `user_data_stream` runs independently via `asyncio.gather()` alongside candle processing.
|
|
|
|
## Key Patterns
|
|
|
|
- **Async-first**: All I/O operations use `async/await`; parallel tasks via `asyncio.gather()`
|
|
- **Reverse signal re-entry**: While holding LONG, if SHORT signal appears → close position, cancel SL/TP, open SHORT. `_is_reentering` flag prevents race conditions with User Data Stream
|
|
- **ML hot reload**: `ml_filter.check_and_reload()` compares file mtime on every candle, reloads model without restart
|
|
- **Active Config pattern**: Best hyperparams stored in `models/active_lgbm_params.json`, must be manually approved before retraining
|
|
- **Graceful degradation**: Missing model → all signals pass; API failure → use fallback values (0.0 for OI/funding)
|
|
- **Walk-forward validation**: Time-series CV with undersampling (1:1 class balance, preserving time order)
|
|
- **Label generation**: Binary labels based on 24-candle (6h) lookahead — check SL hit first (conservative), then TP
|
|
|
|
## Testing
|
|
|
|
- All external APIs (Binance, Discord) are mocked with `unittest.mock.AsyncMock`
|
|
- Async tests use `@pytest.mark.asyncio`
|
|
- 14 test files, 80+ test cases covering all layers
|
|
- Testing is done in actual terminal, not IDE sandbox
|
|
|
|
## Configuration
|
|
|
|
Environment variables via `.env` file (see `.env.example`). Key vars: `BINANCE_API_KEY`, `BINANCE_API_SECRET`, `SYMBOL` (default XRPUSDT), `LEVERAGE`, `DISCORD_WEBHOOK_URL`, `MARGIN_MAX_RATIO`, `MARGIN_MIN_RATIO`, `NO_ML_FILTER`.
|
|
|
|
`src/config.py` uses `@dataclass` with `__post_init__` to load and validate all env vars.
|
|
|
|
## Deployment
|
|
|
|
- **Docker**: `Dockerfile` (Python 3.12-slim) + `docker-compose.yml`
|
|
- **CI/CD**: Jenkins pipeline (Gitea → Docker registry → LXC production server)
|
|
- Models stored in `models/`, data cache in `data/`, logs in `logs/`
|
|
|
|
## Design & Implementation Plans
|
|
|
|
All design documents and implementation plans are stored in `docs/plans/` with the naming convention `YYYY-MM-DD-feature-name.md`. Design docs (`-design.md`) describe architecture decisions; implementation plans (`-plan.md`) contain step-by-step tasks for Claude to execute.
|
|
|
|
**Chronological plan history:**
|
|
|
|
| Date | Plan | Status |
|
|
|------|------|--------|
|
|
| 2026-03-01 | `xrp-futures-autotrader` | Completed |
|
|
| 2026-03-01 | `discord-notifier-and-position-recovery` | Completed |
|
|
| 2026-03-01 | `upload-to-gitea` | Completed |
|
|
| 2026-03-01 | `dockerfile-and-docker-compose` | Completed |
|
|
| 2026-03-01 | `fix-pandas-ta-python312` | Completed |
|
|
| 2026-03-01 | `jenkins-gitea-registry-cicd` | Completed |
|
|
| 2026-03-01 | `ml-filter-design` / `ml-filter-implementation` | Completed |
|
|
| 2026-03-01 | `train-on-mac-deploy-to-lxc` | Completed |
|
|
| 2026-03-01 | `m4-accelerated-training` | Completed |
|
|
| 2026-03-01 | `vectorized-dataset-builder` | Completed |
|
|
| 2026-03-01 | `btc-eth-correlation-features` (design + plan) | Completed |
|
|
| 2026-03-01 | `dynamic-margin-ratio` (design + plan) | Completed |
|
|
| 2026-03-01 | `lgbm-improvement` | Completed |
|
|
| 2026-03-01 | `15m-timeframe-upgrade` | Completed |
|
|
| 2026-03-01 | `oi-nan-epsilon-precision-threshold` | Completed |
|
|
| 2026-03-02 | `rs-divide-mlx-nan-fix` | Completed |
|
|
| 2026-03-02 | `reverse-signal-reenter` (design + plan) | Completed |
|
|
| 2026-03-02 | `realtime-oi-funding-features` | Completed |
|
|
| 2026-03-02 | `oi-funding-accumulation` | Completed |
|
|
| 2026-03-02 | `optuna-hyperparam-tuning` (design + plan) | Completed |
|
|
| 2026-03-02 | `user-data-stream-tp-sl-detection` (design + plan) | Completed |
|
|
| 2026-03-02 | `adx-filter-design` | Completed |
|
|
| 2026-03-02 | `hold-negative-sampling` (design + plan) | Completed |
|
|
| 2026-03-03 | `optuna-precision-objective-plan` | Pending |
|