docs(ml): document retraining behavior in main

README.md

@@ -1,5 +1,8 @@
 # Moscow Hack 2026 — Prediction Service V2
 
+Повторное обучение модели описано в [retraining/README.md](retraining/README.md).
+Этот процесс запускается отдельно от сервиса прогноза и не заменяет его модель автоматически.
+
 Production-сервис для online-прогноза критического события по логам датчиков на произвольном положительном горизонте в часах.
 
 Модель: `CatBoostRegressor` с `SurvivalAft`.
@@ -906,4 +909,3 @@ weather = get_weather(
 ```
 
 Именно такой словарь с названиями полей выше ожидает сервис модели для каждого необходимого часа (`current`, `+1h`, `+4h`, `+8h`, `+12h`, `+16h`, `+20h`, `+24h`).
-

retraining/README.md

@@ -1,8 +1,8 @@
 # Общий пайплайн обучения
 
-Эта папка — самостоятельная точка повторного обучения модели на исходных и новых данных. Добавьте новые журналы событий в `data/incoming_events/` и запустите один скрипт: он объединит все записи, сформирует признаки, заново разобьёт устройства на train/val/test, выполнит feature selection, Optuna-тюнинг, обучит итоговую модель и посчитает метрики.
+Этот каталог содержит пять ноутбуков и `run_pipeline.py` для последовательной подготовки данных, разделения на train/val/test, отбора признаков, подбора параметров и обучения CatBoost. Скрипт не запускает облачную VM и не заменяет модель сервиса инференса. Описание относится к коду ветки `main`; экспериментальная автоматизация облачного запуска в неё не входит.
 
-Шаблоны в `notebooks/` — копии исходных тетрадок. Они **не перезаписываются**. Для каждого прогона скрипт создаёт рабочие копии в `artifacts/runs/<run_id>/notebooks/` и только там подставляет найденные годы и реально доступные чанки. Поэтому старый запуск не ломается, а новые данные (в том числе за новые годы) участвуют в обучении автоматически.
+Шаблоны в `notebooks/` не перезаписываются. Для каждого запуска создаются рабочие копии в `artifacts/runs/<run_id>/notebooks/`. В них подставляются годы входных событий и числа доступных чанков. Результат зависит от фактически переданных файлов, настроек и версии кода; пример из репозитория не заменяет полный набор событий.
 
 ## Состав
 
@@ -20,7 +20,7 @@
 Перейдите в папку пайплайна и установите зависимости в нужное Python-окружение:
 
 ```bash
-cd general_training_pipeline
+cd retraining
 python -m pip install -r requirements.txt
 python run_pipeline.py
 ```
@@ -33,11 +33,11 @@ python run_pipeline.py
 - `notebooks/` — фактически выполненные тетрадки с выводами;
 - `data/` — точный снимок данных, использованных в этом запуске.
 
-Для фиксированного имени прогона используйте `python run_pipeline.py --run-id retrain_2026_09_25`.
+Для фиксированного имени прогона используйте `python run_pipeline.py --run-id <уникальный-id>`. Если каталог с таким именем уже существует, скрипт завершится с ошибкой и не перезапишет артефакты.
 
 ## Как добавить новые данные
 
-1. Скопируйте один или несколько parquet-файлов в `data/incoming_events/`. Файлы с любым именем принимаются; записи за одинаковый год автоматически объединяются. Не удаляйте старые файлы, если они тоже должны остаться в обучающей выборке.
+1. Скопируйте один или несколько parquet-файлов в `data/incoming_events/`. Скрипт читает только файлы по `input.events_glob` из `config.yaml`; по умолчанию это `*.parquet`. Записи одного года объединяются. Если файл не должен участвовать в запуске, уберите его из входного каталога или настройте glob до запуска.
 2. Убедитесь, что у каждого файла есть колонки: `ид_события`, `ид_канала_данных`, `дата`, `время`, `значение_датчика`, `тревожное`.
 3. При изменении справочников или погоды замените соответствующий файл в `data/reference/` либо поменяйте путь в `config.yaml`.
 4. Запустите `python run_pipeline.py`.
@@ -46,6 +46,22 @@ python run_pipeline.py
 
 ## Конфигурация
 
-В `config.yaml` можно изменить каталоги данных, Jupyter kernel, таймаут и максимальное число чанков для этапов feature selection и tuning. Лимиты не могут привести к ошибке на маленьком наборе: запускатор автоматически берёт не больше существующих чанков.
+В `config.yaml` можно изменить каталоги данных, Jupyter kernel, таймаут и максимальное число чанков для этапов feature selection и tuning. Скрипт уменьшает лимит до числа существующих чанков; при нуле чанков этап завершится ошибкой.
 
 Новые данные должны быть в том же формате, что и пример. Дата должна приводиться к календарной дате; погодный CSV должен содержать колонку `time` и погодные поля из исходной тетрадки.
+
+## Фактическое использование чанков в `main`
+
+| Этап | Train | Validation | Test |
+| --- | --- | --- | --- |
+| Отбор признаков | До 4 чанков | До 20 чанков | До 20 чанков |
+| Подбор параметров | До 8 чанков | До 80 чанков | До 20 чанков в шаблоне |
+| Итоговое обучение | До 8 чанков | До 80 чанков | Все `chunk_*.parquet` для итоговой оценки |
+
+Числа заданы в `notebook_limits` и ограничиваются фактическим количеством файлов. Итоговый ноутбук получает лимиты train/val из секции `tuning`; поэтому текущий код `main` **не гарантирует обучение на всех train-чанках**. Все test-файлы читаются в итоговой оценке пакетами. Test не используется для обучения итоговой модели, но ноутбук отбора признаков считает `test_pr_auc` по кандидатам. Поэтому итоговую test-метрику нельзя считать оценкой на полностью закрытой выборке.
+
+## Проверка результата
+
+Прогон считается завершённым после успешного выхода `run_pipeline.py` и проверки `best_model.cbm`, `scores_final.csv`, `best_params.json` и выполненных ноутбуков в одном каталоге запуска. В выводе последнего ноутбука сверяйте число найденных test-файлов с входным набором. Для сравнения с прежней моделью и правилами «тревога вчера» и «не менее десяти тревог вчера» нужны отдельные расчёты на тех же строках и горизонте прогноза; текущий скрипт `main` их не выполняет. Автоматической выкладки модели нет.
+
+Для воспроизводимости фиксируйте commit, `config.yaml`, перечень Parquet и их SHA-256, число train/val/test-чанков и итоговые артефакты. Данные и секреты размещайте вне Git, если они не предназначены для публикации.