# ml_crypto_lab

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

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

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

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

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

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

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

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

```text
artifacts/runs/<run_id>/
```

В ней будут:

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

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

### Feature Builder

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

Пример:

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

### Target Builder

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

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

### Model Factory

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

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

### Experiment

Комбинация:

```text
feature_set + target + model
```

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

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

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

```text
src/ml_crypto_lab/features/my_features.py
```

Добавь:

```python
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`:

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

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

Аналогично:

```python
from ml_crypto_lab.core.registry import TARGET_REGISTRY

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

И в конфиг:

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

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

```python
from ml_crypto_lab.core.registry import MODEL_REGISTRY

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

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

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

```text
features
    отдельно

targets
    отдельно

models
    отдельно

experiments
    отдельно

ensembles
    отдельно
```

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

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