Jel Boljam (Жел Болжам) — агент прогноза выработки ВЭС

«Жел болжам» по-казахски — «прогноз ветра». Агент сам получает прогноз погоды, известный на момент выпуска, рассчитывает почасовую выработку ветроэлектростанции на 24–48 часов, проверяет результат, пишет резюме и пересчитывает прогноз при обновлении данных.

Данные и погода

Источники, правило «без утечки будущего», часовой пояс и очистка SCADA описаны в data/README_data.md. Сборка датасета: python -m data.build_dataset.

Дашборд

python -m streamlit run app/dashboard.py

Откроется в браузере. Вкладки:

• Прогноз — почасовая мощность на 48 ч для выбранного выпуска и прогноз ветра ECMWF и GFS;
• Проверки агента — диапазон, скачки, расхождение погодных моделей, согласие с прошлым выпуском; журнал бэктеста агента (решение по каждому выпуску) и итоговый прогноз на февраль;
• Качество модели — nMAE на январе 2026 и график «факт против прогноза»;
• Запуск агента — полный цикл вживую: погода Open-Meteo на момент выпуска → признаки → модель → проверки. Выпуск в 12:00 UTC показывает пересчёт при обновлении прогноза погоды.

Модель и метрики

Запуск модели: python -m model.train. Обучение идёт на train.parquet до 01.01.2026, январь 2026 используется для валидации, а февраль — для итогового прогноза. Используются ветер и его ансамбль, направление в sin/cos, температура, час, месяц и календарные циклы. Предсказание обрезается в [0, 1].

nMAE = 100 * mean(abs(y - pred)); результаты LightGBM записываются в model/metrics_lgbm.csv, прогноз февраля — в model/forecast_lgbm_feb.csv. После появления фактической SCADA скрипт также записывает сравнение LightGBM, persistence, climatology и power curve за февраль в model/metrics_february.csv с разбиением на горизонты 1–24 и 25–48 часов.

Метрики на январе 2026 (валидация, nMAE в % от установленной мощности, меньше — лучше):

Модель	1–24 ч	25–48 ч	Все горизонты
Persistence	30.58%	37.30%	33.88%
Climatology	29.26%	29.14%	29.20%
Power curve	21.10%	21.80%	21.44%
LightGBM	15.91%	16.97%	16.43%

Метрики считаются по фактической мощности power, время SCADA — UTC+6. В валидацию входят только выпуски после конца обучающих данных (с 01.01.2026 00:00 UTC), а кривая для поиска простоев строится без января. LightGBM обучается в несколько потоков, поэтому на другом компьютере его метрика может отличаться в сотых долях процента; значения в таблице — из model/metrics_lgbm.csv в репозитории. Подробнее — в разделе о данных. Пересчёт: python -m model.baseline_nwp и python -m model.train.

LightGBM снижает ошибку на 5 п.п. относительно кривой мощности по прогнозу ветра и почти вдвое относительно persistence.

Агент: полный цикл за февраль

python agent_backtest.py --mode lightgbm --trained-through 2025-12-31T18:00:00+00:00 --out artifacts/agent_run

Агент «проигрывает» тестовый период: каждый день с 31.01 по 28.02.2026 в 00:00 UTC он сам выполняет цикл.

1. Погода. Берёт прогноз, известный на момент выпуска: data.weather_client, проверка check_no_leakage.
2. Прогноз. Готовит признаки и считает мощность LightGBM на 48 ч.
3. Анализ. Проверяет диапазон, пропуски, дубли часов, скачки и пересмотр относительно прошлого выпуска.
4. Решение. Принимает выпуск или отклоняет его. Принятый выпуск заменяет пересекающиеся 24 ч прошлого прогноза: так работает пересчёт при обновлении входных данных. Отклонённый пишется в журнал, а в силе остаётся прошлый прогноз.

Параметр --trained-through — момент, когда стало известно последнее наблюдение из обучения: 31.12.2025 23:00 по UTC+6, час закончился в 18:00 UTC. Если модель видела данные позже первого выпуска, агент откажется запускаться. Каждый запуск требует новую папку --out.

Готовый прогон уже лежит в репозитории, в artifacts/agent_lgbm/. Агент не перезаписывает прошлые эксперименты, поэтому для повторного запуска нужна новая папка, как artifacts/agent_run в команде выше. Состав результата:

• february_latest.csv — итоговый почасовой прогноз на 1–28 февраля: 672 ч, время SCADA UTC+6;
• forecast_history.csv — все версии прогноза по выпускам;
• runs.jsonl — решение агента, ошибки, предупреждения и резюме по каждому выпуску;
• summary.json — сводка прогона.

Проверка: 29 из 29 выпусков приняты, 672 из 672 часов февраля. Прогноз агента совпадает с model/forecast_lgbm_feb.csv до последнего знака.

LLM-резюме (необязательно). Нужно выполнить pip install openai, задать переменную окружения OPENAI_API_KEY и добавить --llm-model <модель>. Без ключа или при ошибке API резюме строится по правилам.

Другие режимы и тесты. Бейзлайн запускается с --mode baseline. Тесты агента: python -m unittest discover -s tests -v. Подробности — в docs/agent_integration.md.

Воспроизведение с нуля

Нужен Python 3.10+. Исходные CSV организаторов уже лежат в data/raw/.

На Windows, если команда python открывает Microsoft Store или не находится, используйте лаунчер py вместо python (например, py -m pip install -r requirements.txt). На Linux и macOS может понадобиться python3.

python -m pip install -r requirements.txt
python -m data.build_dataset       # архив прогнозов Open-Meteo + SCADA -> data/processed/
python -m model.baseline_nwp       # бейзлайны и метрики на январе
python -m model.train              # LightGBM: метрики на январе, прогноз на февраль
python agent_backtest.py --mode lightgbm --trained-through 2025-12-31T18:00:00+00:00 --out artifacts/agent_run
python -m streamlit run app/dashboard.py

Февральские метрики считаются по целевым часам 01.02–28.02 (target_time_local). Фактической мощности за февраль в выданных данных нет, поэтому model/metrics_february.csv заполнится, когда эти данные появятся в data/raw/.

Проверка по критериям кейса

Критерий	Чем закрыт
Соответствие задаче	почасовой прогноз на 48 ч по каждому выпуску; архивные прогнозы погоды, а не факт; февраль целиком, 672 ч
Техническая реализация	модули data / model / агент; проверка утечки по реальному расписанию выхода NWP; ансамбль ECMWF + GFS; LightGBM; агент с проверками, журналом и LLM-резюме
README и воспроизводимость	команды выше; кэш погоды; тесты агента; фиксированные сиды
Ценность	nMAE на январе: 16,4% у LightGBM против 21,4% у кривой мощности и 33,9% у persistence; дашборд для диспетчера
Потенциал	Single Runs API для пересчёта на каждом прогоне 00/06/12/18 UTC; дополнительные модели NWP; квантильный прогноз