ML-модуль
=========

Модуль ``ml/src/`` содержит фичеинжиниринг, обучение CatBoost-ансамбля
и инференс-сервис на FastAPI.

Задача
------

- **Residual regression**: цель — ``target_delay_s - cur_dev_s``.
- Такой сдвиг убирает лёгкий базовый прогноз «оставить текущее отклонение как есть»
  и заставляет модель учить именно поправку.
- Итоговое предсказание собирается обратно: ``pred_delay = cur_dev_s + pred_residual``.
- Модель обучается на исторических рейсах с проставленными фактами прибытия.

Схема данных
------------

- **train** — исторический датасет рейсов с полной телеметрией и таргетами.
- **test** — публичный тест соревнования (структура совпадает с train,
  ``target_delay_s`` отсутствует).
- **validate** — внутренние сплиты (K-fold и holdout) поверх train.
- **labels** — ``target_delay_s`` (секунды, знаковая величина).

CatBoost-ансамбль
-----------------

- 5 моделей CatBoost, обученных с разными seed-ами (0..4).
- Итоговое предсказание — среднее по ансамблю.
- Есть отдельный «no-route» набор моделей (``catboost_noroute_seed*``),
  используется когда категориальные признаки маршрута считаются нестабильными
  (LOVO / новые маршруты).
- Полный список из 56 фичей — константа ``FEATURES`` в
  :mod:`features.tabular` (см. также ``ml/artifacts/bench_latency.json``).
- Основные группы фичей:

  * плановые: ``plan_gap_prev_s``, ``plan_route_dist_m``, ``plan_speed_kmh``, ...
  * GPS-агрегаты: ``gps_med3``, ``gps_med5``, ``gps_max5``, ``gps_slope``, ...
  * динамика: ``spd1``, ``spd5``, ``spd15``, ``stop5``, ``spd_trend``, ...
  * геометрия: ``dist_tgt_m``, ``dist_next_stop_m``, ``route_left_m``, ...
  * ETA-подсказки: ``eta_dev_s``, ``eta_dev_moving_s``, ``req_speed_kmh``.
  * временные: ``hour``, ``hour_sin``, ``hour_cos``.

Валидация
---------

- **Proxy K-fold** — разбиение по прокси-ключу (рейс/машина), быстрый цикл.
- **Holdout** — фиксированный отложенный кусок для честной оценки.
- **LOVO** (leave-one-vehicle-out) — устойчивость к новым транспортным средствам.
- Разрезы качества (маршрут, час суток, хвост распределения) —
  ``ml/src/metrics_slices.py``.

Латентность
-----------

Из ``ml/artifacts/bench_latency.json`` (200 запусков, ансамбль из 5 моделей):

- CatBoost (нативный формат): ~9.4 мс на сэмпл.
- ONNX fp32: ~1.6 мс на сэмпл (продовый путь).
- ONNX int8: пока не мерили.

Ссылки
------

- `README ML-модуля <../../ml/README.md>`_ — команды запуска обучения и инференса.
- :mod:`inference_service` — REST-сервис на FastAPI.
- :mod:`train_catboost` — обучение CatBoost-ансамбля.
- :mod:`features.tabular` — фичеинжиниринг табличных признаков.