BTC Short Horizon ML

Отдельный ML-механизм для прогноза BTC от фиксированного времени на горизонтах +5, +10 и +15 минут.

Проект сделан отдельно от торгового бота и отдельно от Polymarket-модуля. Он не отправляет ордера и не строит автоторговлю. Его задача только одна: обучить модель на исторических 5m-данных BTC и выдавать вероятностный прогноз UP / DOWN на ближайшие 1, 2 и 3 пятиминутные свечи.

Почему базовый таймфрейм здесь именно 5m:

1. Это совпадает с логикой 5-minute BTC Up/Down рынков.
2. Для горизонтов +5, +10, +15 минут не нужен лишний шум 1m.
3. Исторических 5m-данных локально у тебя заметно больше, чем 1m.

Что умеет модуль

1. Загружать локальные BTC OHLCV-данные из feather.
2. Строить признаки по 5m, а также добавлять informative-фичи из 15m и 1h.
3. При наличии файлов автоматически добавлять:
   1. basis futures против Binance spot
   2. spread futures против mark price
   3. funding rate и его дельты
   4. cross-venue spread против Binance futures
   5. spread между mark price разных venues
4. Калибровать вероятности после обучения, чтобы thresholds были ближе к реальной частоте успеха.
5. Применять recency bias через weight_factor, чтобы более свежие бары весили больше старых.
6. Работать с ternary target DOWN / NO_EDGE / UP, а не только с бинарным UP / DOWN.
7. Сравнивать preprocessing режимы:
   1. baseline
   2. pca
   3. pca_di_svm
8. Обучать regime-specific submodels поверх глобальной модели.
9. Обучать три отдельные модели:
   1. +5m
   2. +10m
   3. +15m
10. Делать walk-forward оценку по времени, а не случайный shuffle.
11. По умолчанию учиться на fixed rolling window 30d, а не на unlimited history.
12. Сравнивать окна 20d, 30d, 45d против expanding window.
13. Поддерживать optional microstructure-фичи:
14. open interest
15. taker buy/sell imbalance
16. liquidations
17. Сохранять модели и метрики в artifacts/.
18. Сохранять out-of-sample fold predictions для анализа signal gate.
19. Давать прогноз на конкретное время или на последний доступный закрытый 5m бар.
20. Показывать свежесть модели и блокировать live-trading, если артефакт старше expiration_hours.
21. Применять второй слой signal gate: UP / DOWN / SKIP.
22. Применять regime filter поверх gate.
23. Давать отдельную команду polymarket-signal под 5-minute BTC Up/Down market.
24. Перед web-прогнозом подтягивать свежие BTC данные с биржи и дописывать их в feather.
25. Запускать отдельный локальный data-updater-daemon.
26. При наличии existing pipeline опционально дергать его как внешний sync hook.
27. Строить в web UI график вероятностей UP по времени.
28. Показывать Опорная цена из Polymarket Price to beat.

Структура

btc_short_horizon_ml/
├── README.md
├── requirements.txt
└── app/
    ├── __init__.py
    ├── config.py
    ├── data_loader.py
    ├── exceptions.py
    ├── features.py
    ├── main.py
    ├── modeling.py
    ├── models.py
    ├── polymarket_reference.py
    ├── predictor.py
    ├── regime.py
    ├── live_data.py
    ├── web.py
    ├── web_index.html
    ├── training.py
    └── utils.py

Зависимости

Минимально нужны:

1. pandas
2. numpy
3. scikit-learn
4. lightgbm
5. pyarrow
6. joblib
7. fastapi
8. uvicorn
9. ccxt

У тебя они уже стоят в /Users/mac/trade/.venv.

Если хочешь отдельное окружение:

cd "/Users/mac/Documents/New project/btc_short_horizon_ml"
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Если хочешь использовать уже существующее рабочее окружение:

source /Users/mac/trade/.venv/bin/activate

Данные по умолчанию

По умолчанию модуль использует:

1. base futures 5m: /Users/mac/trade/user_data/data/bitget/futures/BTC_USDT_USDT-5m-futures.feather
2. optional mark 5m: /Users/mac/trade/user_data/data/bitget/futures/BTC_USDT_USDT-5m-mark.feather
3. optional funding 1h: /Users/mac/trade/user_data/data/bitget/futures/BTC_USDT_USDT-1h-funding_rate.feather
4. optional Binance spot 5m: /Users/mac/trade/user_data/data/binance/BTC_USDT-5m.feather
5. optional Binance futures 5m: /Users/mac/trade/user_data/data/binance/futures/BTC_USDT_USDT-5m-futures.feather
6. optional Binance mark 1h: /Users/mac/trade/user_data/data/binance/futures/BTC_USDT_USDT-1h-mark.feather
7. optional Binance funding 1h: /Users/mac/trade/user_data/data/binance/futures/BTC_USDT_USDT-1h-funding_rate.feather
8. optional open interest: путь задается через --open-interest-data-path
9. optional taker buy/sell: путь задается через --taker-data-path
10. optional liquidations: путь задается через --liquidation-data-path

Можно передать свои пути через CLI.

Важно: funding loader автоматически определяет, в какой колонке реально лежит funding rate. Это нужно, потому что у некоторых бирж в feather-файлах funding записан в open, а close может быть нулевым.

Как обучить

Базовый запуск:

cd "/Users/mac/Documents/New project/btc_short_horizon_ml"
source /Users/mac/trade/.venv/bin/activate
python -m app.main train

Теперь этот запуск по умолчанию использует:

1. fixed rolling window 30d
2. weight_factor=0.9998
3. live_retrain_hours=0.5
4. expiration_hours=0.5
5. test_days=5, step_days=5
6. ternary target DOWN / NO_EDGE / UP
7. preprocessing_mode=baseline

Полезный запуск с ограничением истории и своими окнами walk-forward:

python -m app.main train \
  --max-rows 25000 \
  --min-train-days 30 \
  --max-train-days 30 \
  --test-days 5 \
  --step-days 5 \
  --weight-factor 0.9998

Пример fixed rolling window:

python -m app.main train \
  --min-train-days 30 \
  --max-train-days 30 \
  --test-days 5 \
  --step-days 5

Если нужен expanding window:

python -m app.main train \
  --min-train-days 30 \
  --expanding-window

Если хочешь жестче давить свежие данные:

python -m app.main train \
  --weight-factor 0.9997

Если хочешь мягче:

python -m app.main train \
  --weight-factor 0.9999

Если хочешь включить ternary target явно и задать ширину зоны NO_EDGE:

python -m app.main train \
  --no-edge-threshold 0.0005

Если нужно вернуться к старому бинарному target:

python -m app.main train \
  --binary-target

Параметры свежести модели:

python -m app.main train \
  --live-retrain-hours 0.25 \
  --expiration-hours 0.5

Preprocessing-режимы:

python -m app.main train --preprocessing-mode baseline
python -m app.main train --preprocessing-mode pca
python -m app.main train --preprocessing-mode pca_di_svm

Если нужно сравнить чисто базовый контур без calibration или без regime models:

python -m app.main train --disable-calibration --disable-regime-models

После обучения появятся:

1. artifacts/model_bundle.joblib
2. artifacts/metrics_summary.json
3. artifacts/fold_predictions.feather

Как получить прогноз

Последний доступный закрытый 5m бар:

python -m app.main predict

Конкретное время:

python -m app.main predict --at "2026-03-08T08:35:00Z"

Если время не совпадает с границей свечи, будет взят последний закрытый 5m бар не позже указанного времени.

Прогноз с gate:

python -m app.main predict --with-gate

Своими порогами:

python -m app.main predict \
  --with-gate \
  --primary-threshold 0.60 \
  --support-threshold 0.60 \
  --min-alignment-count 1

Что показывает прогноз

Для каждого горизонта:

1. вероятность UP
2. вероятность DOWN
3. вероятность NO_EDGE, если модель считает движение слишком слабым
4. итоговое направление
5. уровень уверенности
6. опорную цену на момент прогноза
7. целевое время горизонта
8. model_freshness, чтобы было видно, пора ли уже retrain или артефакт протух

Если включен --with-gate, дополнительно будет:

1. итоговое решение UP, DOWN или SKIP
2. причина решения
3. какие supportive horizon подтвердили сигнал
4. consensus score

Polymarket signal

Готовый сигнал специально под 5-minute BTC Up/Down:

python -m app.main polymarket-signal

Для конкретного времени:

python -m app.main polymarket-signal --at "2026-03-08T05:30:00Z"

Команда возвращает:

1. текущий regime snapshot
2. raw horizon predictions
3. итоговый UP, DOWN или SKIP
4. причину, почему сигнал пропущен или принят

Логика такая:

1. сначала идет consensus gate по 5m с подтверждением от 10m/15m
2. потом regime filter может дополнительно вырезать:
   1. весь range, потому что там качество сигнала оказалось слабым
   2. volatile_trend_up, потому что в этом режиме short-horizon сигнал сейчас шумный
   3. слишком слабый сигнал в high_volatility
   4. сигнал, который идет против выраженного trend regime без достаточного edge

Signal gate report

Чтобы понять, какие пороги реально улучшают точность, а какие только режут покрытие:

python -m app.main gate-report

Можно ограничить отчет минимальным покрытием:

python -m app.main gate-report --min-coverage 0.12 --top 10

Отчет показывает:

1. baseline без gate
2. лучшие одиночные threshold'ы по каждому горизонту
3. лучшие consensus-комбинации для primary=5m с поддержкой 10m/15m
4. результат default regime-aware gate
5. breakdown по режимам рынка

Window report

Чтобы сравнить свежие fixed windows против expanding:

python -m app.main window-report

Своими окнами:

python -m app.main window-report --windows 20,30,45,expanding

Окна 20d, 30d, 45d здесь основная рабочая сетка для short-horizon BTC. expanding оставлен для сравнения, а не как дефолт.

Сравнение preprocessing режимов поверх тех же окон:

python -m app.main window-report \
  --windows 20,30,45 \
  --preprocessing-modes baseline,pca,pca_di_svm

Отчет показывает:

1. какое окно дало лучший accuracy
2. как меняются 5m, 10m, 15m метрики
3. где фиксированное окно лучше expanding

Web интерфейс

Можно поднять локальную страницу, где прогноз будет пересчитываться циклически, пока включен свитчер Прогноз:

cd "/Users/mac/Documents/New project/btc_short_horizon_ml"
source /Users/mac/trade/.venv/bin/activate
python -m app.main web --host 127.0.0.1 --port 8010 \
  --polymarket-event auto-current

После запуска открой:

http://127.0.0.1:8010

Что делает web-режим:

1. показывает итоговый UP, DOWN или SKIP
2. показывает raw-прогнозы на 5m, 10m, 15m
3. показывает regime snapshot и confidence primary сигнала
4. показывает Опорная цена из Polymarket Price to beat
5. перед прогнозом пытается подтянуть свежие BTC данные с биржи
6. пишет историю вероятностей в локальный график на странице
7. пока свитчер включен, обновляет прогноз через выбранный интервал
8. когда свитчер выключен, останавливает циклические запросы

Важно: web-интерфейс сам по себе не обновляет исходные feather-данные. Он только перечитывает локальные данные и пересчитывает прогноз. Поэтому live-режим будет действительно живым только если внешний data pipeline параллельно обновляет BTC-файлы.

Дополнительно в web-режиме включена защита от ложного live-прогноза: если последний доступный 5m бар отстает от текущего UTC-времени больше чем на 15 минут, /api/forecast вернет ошибку о том, что данные устарели. Это сделано специально, чтобы не рисовать прогноз «в будущее» от давно устаревшей рыночной точки.

Под капотом web-режим теперь умеет:

1. напрямую подтягивать BTC 5m и 1h данные из Bitget и Binance через ccxt
2. обновлять base, mark, funding, spot, binance futures, binance mark, binance funding
3. использовать cooldown между sync, чтобы не спамить биржу на каждом опросе
4. опционально дергать existing script: /Users/mac/Documents/New project/trade_control/tools/freqai_dataset_incremental_sync.sh

Data updater daemon

Если нужен отдельный локальный процесс, который держит BTC feather-данные свежими независимо от web UI:

cd "/Users/mac/Documents/New project/btc_short_horizon_ml"
source /Users/mac/trade/.venv/bin/activate
python -m app.main data-updater-daemon --daemon-interval-seconds 60

Что делает daemon:

1. циклически обновляет BTC источники и пишет их в feather
2. использует межпроцессный lock, чтобы web и daemon не писали файлы одновременно
3. по таймеру может запускать existing pipeline hook, если он есть

Launchd сервис на macOS

Для daemon добавлен LaunchAgent:

1. plist: /Users/mac/Documents/New project/btc_short_horizon_ml/launchd/ai.trade.btc-short-horizon-ml-data-updater.plist
2. run script: /Users/mac/Documents/New project/btc_short_horizon_ml/scripts/run_data_updater_daemon.sh
3. install script: /Users/mac/Documents/New project/btc_short_horizon_ml/tools/install_data_updater_launchagent.sh
4. при установке launcher копируется в: ~/Library/Application Support/btc_short_horizon_ml/run_data_updater_daemon.sh

Установка и перезапуск:

bash "/Users/mac/Documents/New project/btc_short_horizon_ml/tools/install_data_updater_launchagent.sh"

После установки LaunchAgent будет:

1. стартовать при логине
2. автоматически перезапускаться при падении
3. писать логи в: /Users/mac/Documents/New project/btc_short_horizon_ml/runtime/launchd/
4. запускаться через копию launcher-скрипта из Application Support, чтобы обойти macOS-ограничение на прямой запуск background-скриптов из Documents

Если нужно передать кастомные аргументы daemon, можно задать env:

export BTC_SHORT_HORIZON_ML_DAEMON_ARGS="--daemon-interval-seconds 30 --sync-cooldown-seconds 20"

и потом перезагрузить LaunchAgent через install script.

Практический смысл новых усилений

1. Probability calibration помогает сделать 0.58, 0.60, 0.65 более честными порогами вероятности.
2. Extra market features добавляют не только OHLCV, но и funding/basis/cross-venue spread.
3. Regime-specific submodels позволяют не заставлять один и тот же классификатор одинаково работать в range, trend и high_volatility.
4. Window report помогает не переоценивать старую историю, если свежий rolling window реально работает лучше.

Как читать результат

Если модель показывает:

1. UP probability = 0.74
2. DOWN probability = 0.26
3. confidence = 0.48

Это значит, что на данном историческом паттерне модель считает более вероятным сценарий close_future >= close_now на выбранном горизонте.

Это не гарантирует результат и не является торговой рекомендацией.

Какой горизонт обычно самый предсказуемый

Точного ответа без walk-forward нет. На практике:

1. +5m обычно самый шумный
2. +10m часто дает лучший баланс между скоростью и стабильностью
3. +15m иногда выигрывает по качеству сигнала, но медленнее реагирует

Этот модуль специально считает out-of-sample метрики отдельно для +5m, +10m, +15m, чтобы не гадать.

Ограничения

1. Модель обучается только на том диапазоне истории, который есть локально.
2. Если история короткая, качество walk-forward будет ограниченным.
3. При смене биржи, режима рынка или микроструктуры модель нужно переобучать.
4. Это infrastructure/research tool, а не стратегия автоторговли.

Не является финансовой рекомендацией

Модуль не обещает прибыль, не гарантирует точность и не заменяет риск-менеджмент. Используй его как исследовательский инструмент для проверки гипотез и вероятностной оценки направления BTC на ближайшие 5-15 минут.