Inference API
=============

HTTP-сервис инференса — :mod:`inference_service` (FastAPI, порт по умолчанию 8001).
Полная OpenAPI-спецификация доступна в Swagger UI по адресу
``http://localhost:8001/docs`` при поднятом сервисе.

Эндпоинты
---------

``POST /predict``
~~~~~~~~~~~~~~~~~

Основной эндпоинт: прогноз задержки для одного (текущая точка, целевая остановка).

- **Request** — плоский JSON с фичами (то же множество полей, что и в
  ``FEATURES`` из :mod:`features.tabular`) плюс идентификаторы рейса/точки/цели.
- **Response** — ``pred_delay_s`` (секунды), а также диагностика:
  ``pred_residual_s``, ``cur_dev_s``, версия модели, временные метки.
- Латентность ~2 мс на запрос при ONNX fp32-пути.

``POST /predict/batch``
~~~~~~~~~~~~~~~~~~~~~~~

Батч-версия ``/predict``: тот же контракт, но принимает массив объектов
и возвращает массив предсказаний в том же порядке. Используется backend'ом
для массового прогона обновлений с NDTP-потока.

``GET /health``
~~~~~~~~~~~~~~~

Проверка живости сервиса. Возвращает статус, загруженные модели, версию.
Используется в docker healthcheck и оркестрации.

``GET /metrics/model``
~~~~~~~~~~~~~~~~~~~~~~

Метрики модели: MAE/медиана/p90 на последних валидационных прогонах,
таймстемпы обучения, размеры артефактов, латентность (``latency_ms_p50``,
``latency_ms_p95``). Прокси backend'а в ``GET /metrics/model`` (порт 8000)
возвращает то же тело с кешем на случай, если ML недоступен.

``POST /whatif/predict``
~~~~~~~~~~~~~~~~~~~~~~~~

Точечный пересчёт задержки для одного ТС при заданной мере
(``scenario`` из ``add_reserve``, ``adjust_interval``, ``detour``,
``signal_priority``, ``hold_at_stop``). Backend вызывает его пер-ТС
в ``POST /whatif``; при недоступности ML используется локальная эвристика
``MEASURE_EFFECT`` — форма ответа идентична.

``GET /model/info``, ``POST /reload``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Административные эндпоинты: описание артефактов и hot-reload из
``ml/artifacts``. Не используются фронтом (``frontend/js/api.js`` их
не зовёт) и не проксируются backend'ом — только оператор из Swagger.

Контракты и ошибки
------------------

- Схемы request/response определены через ``pydantic``-модели в
  :mod:`inference_service` — Swagger UI генерирует их автоматически.
- Валидация полей — 422 при отсутствующих/некорректных фичах.
- Внутренние ошибки — 500 с ``request_id`` для трассировки в логах.

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

- `Архитектура §7.1 (контракт API) <../../ARCHITECTURE_AND_ROLES.md>`_ —
  канонический контракт полей запроса/ответа и SLA.
- :mod:`inference_service` — исходники FastAPI-приложения.