ml_crypto_lab/README.md

ml_crypto_lab

Удобный проектный каркас для ML-исследований торговых режимов:

• проектирование признаков;
• проектирование целевых параметров;
• обучение моделей;
• сохранение полного описания эксперимента;
• создание ансамблей;
• повторное использование сохранённых моделей на новых данных.

Главная идея: каждый артефакт знает, из чего он был создан.

Модель сохраняется не просто как model.pkl, а вместе с:

• списком входных признаков;
• именем target;
• параметрами признаков;
• параметрами target-а;
• параметрами модели;
• результатами train/test/valid;
• backtest-метриками;
• версией кода/конфига.

Быстрый запуск

pip install -r requirements.txt
python scripts/run_full_experiment.py --config configs/experiment.yaml

После запуска появится папка:

artifacts/runs/<run_id>/

В ней будут:

models/                 сохранённые модели
predictions/            предсказания моделей
reports/                таблицы результатов
ensembles/              ансамбли
run_config.yaml         фактический конфиг запуска
registry_snapshot.json  что было доступно в registry

Основные сущности

Feature Builder

Любая функция, которая принимает OHLCV-данные и возвращает DataFrame признаков.

Пример:

@FEATURE_REGISTRY.register("market_basic")
def build_market_basic(df, cfg):
    ...
    return features_df

Target Builder

Любая функция, которая принимает OHLCV-данные и возвращает Series/DataFrame target-ов.

@TARGET_REGISTRY.register("zigzag")
def build_zigzag_targets(df, cfg):
    ...
    return target_df

Model Factory

Фабрика модели. Возвращает объект с .fit() и .predict().

@MODEL_REGISTRY.register("logreg")
def make_logreg(cfg):
    return SklearnBinaryModel(...)

Experiment

Комбинация:

feature_set + target + model

Каждая такая комбинация сохраняется отдельно.

Как добавить новый признак

Создай файл, например:

src/ml_crypto_lab/features/my_features.py

Добавь:

from ml_crypto_lab.core.registry import FEATURE_REGISTRY

@FEATURE_REGISTRY.register("my_feature_block")
def build_my_features(df, cfg):
    out = ...
    return out

Потом добавь имя в configs/experiment.yaml:

feature_sets:
  my_set:
    builders:
      - name: my_feature_block
        params: {}

Как добавить новый target

Аналогично:

from ml_crypto_lab.core.registry import TARGET_REGISTRY

@TARGET_REGISTRY.register("my_target")
def build_my_target(df, cfg):
    return target_df

И в конфиг:

target_sets:
  my_targets:
    builders:
      - name: my_target
        params: {}

Как добавить новую модель

from ml_crypto_lab.core.registry import MODEL_REGISTRY

@MODEL_REGISTRY.register("my_model")
def make_my_model(cfg):
    return MyModelWrapper(...)

Важная логика

Проект специально разделяет:

features
    отдельно

targets
    отдельно

models
    отдельно

experiments
    отдельно

ensembles
    отдельно

Так не возникает ситуации, когда непонятно:

какая модель
на каких признаках
по какому target-у
с какими параметрами
была обучена