WindAgent — Agentic AI для прогнозирования выработки ВЭС

Агент, который каждые сутки сам берёт прогноз погоды, известный к концу этих суток, и выпускает почасовой прогноз выработки двух турбин ВЭС на следующие 24–48 часов — с контролем качества входа, анализом результата и пересчётом при обновлении входных данных.

Команда Technokod, HackAlem AI 2026. Трек «Энергетика», кейс Самрук-Казына «Agentic AI для прогнозирования выработки ВЭС».

Краткое описание

Агент прогнозирует почасовую выработку двух турбин ветроэлектростанции (Шелекский ветровой коридор, Алматинская область) на 24–48 часов вперёд. Для каждых суток выпуска он сам получает архивный прогноз погоды, известный к концу этих суток, проверяет полученные данные на пригодность, готовит признаки, запускает модель, анализирует результат, сравнивает с предыдущим выпуском и пересчитывает прогноз, если входные данные изменились. Пользователь: диспетчер ВЭС или энергосбытовая служба, которой нужен суточный и двухсуточный график выработки для заявок на рынок и планирования резервов.

Ключевое требование кейса — использовать прогноз погоды, доступный на момент прогнозирования, а не факт. Оно выполнено на уровне источника данных: факт погоды не используется ни в тесте, ни в обучении (docs/validation.md).

Как это выглядит

Главный экран: выбор даты выпуска, горизонт 24/48 часов, ожидаемая энергия за период и по суткам, покрытие интервала, изменение к прошлому выпуску. Роторы турбин вращаются со скоростью, пропорциональной прогнозной мощности.

Панель агента: сверху вывод по выпуску, ниже отметка о пересчёте с причиной (расхождение 0,164 при пороге 0,15), часы риска и развёрнутая трасса из шести шагов с техническими именами инструментов — видно соответствие коду.

Внизу — сводка для заявки с калиброванным коридором и блок надёжности: факт января против прогноза, выпущенного накануне, с метриками nMAE на обоих горизонтах.

Живой дашборд: https://hack.technokod.kz

Что реализовано

• Инструмент погоды на Open-Meteo Previous Runs API: для каждого часа берётся значение из прогноза, выпущенного за 1 день (сутки D+1) и за 2 дня (сутки D+2) до этого часа. Момент выпуска — конец суток D (операционный дедлайн 23:59, когда диспетчер готовит заявку на следующие сутки), и это определение существенно: слой previous_day1 для часа 23:00 дня D+1 содержит прогноз, выпущенный около 23:00 дня D. Все использованные прогнозы принадлежат суткам D и известны к их концу, но не к их началу — поэтому выпуск датируется концом дня, а не полуночью. Фактическая погода не используется нигде.
• Модель выработки по каждой турбине — смесь трёх компонентов: эмпирическая кривая мощности по прогнозной скорости ветра на 100 м, градиентный бустинг на признаках прогноза и двухэтапная схема (бустинг «признаки прогноза → скорость ветра на гондоле», затем измеренная кривая турбины «ветер гондолы → мощность»). Веса подобраны на честной валидации января 2026. Дополнительно считается интервал P10–P90 по квантилям остатков валидации, разбитым по лиду и уровню прогноза.
• Агент с шестью инструментами (get_weather, check_input_quality, prepare_and_predict, analyze, recalculate, save_forecast), класс ForecastAgent в app/agent.py. Оркестрация через function calling OpenAI (gpt-5.4-mini на выбор инструментов, gpt-5.4 на заключение). Без ключа, в режиме DEMO_MODE и при любой ошибке провайдера тот же цикл выполняет детерминированный планировщик, что фиксируется в трассе как llm_fallback. Ошибка инструмента возвращается модели как результат вызова, поэтому модель исправляется сама, а не роняет выпуск.
• Детектор обновления входных данных: прогноз на пересекающиеся часы сравнивается с выпуском предыдущего дня; при среднем изменении больше 0.15 или при штормовых часах агент выполняет повторный расчёт. Штормовые часы (≥ 22 м/с) обнуляются — буревая защита турбины.
• Контроль качества входа и отказ от выпуска: прогноз по испорченным данным внешне неотличим от исправного, поэтому вход проверяется отдельным шагом — полнота горизонта, разрывы часовой сетки, пропуски, физически невозможные значения, застрявший датчик, подозрительно ровный ряд. Вердикт fail останавливает выпуск, warn публикует его с пониженной достоверностью. Это и отличает агента от конвейера: воспроизводимый эксперимент scripts/degradation_experiment.py прогоняет оба контура по шести сценариям и показывает, что жёсткий конвейер молча публикует все шесть — в том числе выпуск с 26 строками NaN при 13 часах пропусков и ровный прогноз с КИУМ 0.84 на застрявшем датчике. Агент на тех же данных четырежды отказывает в публикации (missing_values, stuck_sensor, negative_wind, incomplete_horizon) и один раз ловит аномалию пересчётом. Равномерный сдвиг всего поля ветра контролем входа не ловится принципиально — он физически правдоподобен, и его перехватывает второй слой, сравнение с прошлым выпуском. Разбор — в docs/root-analysis/03-agency.md.
• Бэктест «как в прошлом»: 30 последовательных выпусков с 29.01 по 27.02.2026, итоговый почасовой ряд февраля в outputs/forecast_feb2026.csv, журнал действий агента по каждому дню в outputs/agent_logs/. Задание требует выпуск «на 31 января — прогноз на следующие 24–48 часов»; чтобы сами часы 31 января были закрыты при любой трактовке отсчёта, выпуски начинаются с 29 января. Побочный результат: 1 февраля получает прогноз и на сутки, и на двое суток, поэтому в итоговом файле нет ни одного пропуска.
• CLI, HTTP-сервис, тесты, контрольный скрипт для жюри и кэш всех внешних запросов, позволяющий запускать решение без сети.

Как работает решение

Цикл одного выпуска (app/agent.py):

1. get_weather(issue_date) → 48 часов прогноза по координатам ВЭС из выпусков, сделанных в течение суток issue_date и известных к их концу; возвращает диапазон дат, разбивку по лидам, минимум, среднее и максимум ветра и температуры.
2. check_input_quality() → проверка полученного кадра: полнота горизонта и непрерывность часовой сетки, пропуски, отрицательная скорость и значения выше физического предела 40 м/с, застрявшее значение (6 часов подряд одинаковой скорости), разброс ниже 0.3 м/с, температура вне −60…60 °C. Вердикт ok / warn / fail; при fail расчёт не запускается и выпуск не публикуется.
3. prepare_and_predict() → признаки и прогноз по турбинам 1 и 2, значения 0..1 (нормализованная мощность), интервал P10–P90.
4. analyze() → часы штиля (< 3 м/с), часы номинала (≥ 11.5 м/с), штормовые часы (≥ 22 м/с), разброс между турбинами, среднее и максимальное изменение относительно вчерашнего выпуска на пересекающихся часах, флаг needs_recalculation.
5. recalculate(reason) → повторный опрос источника, пересчёт модели и обнуление штормовых часов. В результате фиксируется числовой триггер (trigger, trigger_detail, trigger_values) — что именно сработало и с какими значениями, — формулировка модели reason_passed и input_changed. В ретроспективе input_changed всегда false: повторный опрос архива на прошедшую дату возвращает тот же срез, о чём в журнале стоит прямое пояснение note; в промышленном режиме здесь был бы новый выпуск прогноза погоды.
6. save_forecast() → outputs/forecasts/<дата>.csv; журнал outputs/agent_logs/<дата>.json с трассой инструментов, анализом, вердиктом качества и заключением пишется в конце выпуска.

Порядок вызовов выбирает модель. Пример реальной трассы из outputs/agent_logs_llm/2026-02-15.json: get_weather → check_input_quality → prepare_and_predict → analyze → prepare_and_predict → recalculate → save_forecast — агент увидел обновление входных данных и сам инициировал пересчёт.

Режим оркестрации не влияет на числовой результат, и это измерено, а не заявлено. Скрипт scripts/run_llm_issues.py прогнал живую LLM-оркестрацию на всех 30 выпусках тестового периода: журналы в outputs/agent_logs_llm/, откатов на детерминированный план не было ни разу. Решения модели совпали с решениями планировщика во всех 30 выпусках — пересчёт в тех же четырёх днях (06.02, 15.02, 21.02, 24.02), выпуски побитово те же. Расход на весь прогон: 184 обращения к API, 187 тыс. входных и 6 тыс. выходных токенов, то есть 5–6 вызовов и около 4.5 тыс. prompt-токенов на выпуск. Канонические журналы в outputs/agent_logs/ — детерминированные: сдача воспроизводится без ключей.

Бэктест повторяет цикл для каждого дня тестового периода, передавая выпуску дня N результат дня N−1, затем собирает итоговый ряд: на каждый час февраля берётся самый свежий выпуск (lead 1) и отдельно выпуск за двое суток (lead 2).

Результаты

Честная валидация: обучение до 31.12.2025, проверка на январе 2026 по протоколу «прогноз как в прошлом» (30 выпусков, 720 часов на каждый горизонт). Мощность нормирована на 1, поэтому nMAE — это MAE в процентах от установленной мощности. Числа из docs/metrics.json.

Турбина	Горизонт	MAE	RMSE	nMAE
1	24 ч	0.1431	0.2015	14.31 %
1	48 ч	0.1633	0.2296	16.33 %
2	24 ч	0.1455	0.2041	14.55 %
2	48 ч	0.1666	0.2316	16.66 %

Вклад компонентов на горизонте 24 ч (MAE, турбина 1 / турбина 2): кривая мощности 0.1471 / 0.1480, двухэтапная схема 0.1493 / 0.1526, градиентный бустинг «в лоб» 0.1580 / 0.1608, смесь 0.1431 / 0.1455. Подбор весов на валидации дал бустингу нулевой вес на обеих турбинах (турбина 1 — two_stage 0.5 и curve 0.5, турбина 2 — two_stage 0.4 и curve 0.6): прямое предсказание мощности проигрывает обоим физически осмысленным компонентам, а выигрыш даёт именно их усреднение. Объём обучения итоговых моделей — 31 078 и 33 710 часов.

Сравнение с эталонами (январь 2026, горизонт 24 ч, MAE, расчёт в docs/validation.md):

Метод	Турбина 1	Турбина 2
Модель	0.1431	0.1455
Климатология по часу суток	0.3003	0.3007
Константа (среднее по истории)	0.3010	0.3017
Персистентность (последние полные сутки)	0.3568	0.3463

Модель точнее персистентности на 58–60 % и климатологии на 52 %. Персистентность здесь хуже константы — это объясняет, почему лаги фактической выработки в признаки не вошли.

Два интервала неопределённости, калиброванные по-разному. Почасовой коридор P10–P90 строится по квантилям часовых остатков, разбитым по лиду и уровню прогноза: измеренное покрытие 79.4 % на горизонте 24 ч и 79.7 % на 48 ч при номинале 80 % (docs/validation.md, раздел 7).

Суточный коридор для заявки — отдельная величина, и складывать для него почасовые границы нельзя. Сумма квантилей неявно предполагает, что все 24 часа одновременно лежат на одной границе, то есть полную корреляцию ошибок: такой интервал покрывал 93.3 % при ширине 10.13 норм·ч против средней суточной выработки 7.37. Поэтому квантили суточной энергии калиброваны напрямую, на остатках суточной энергии за январь (scripts/calibrate_daily.py, данные в docs/demo/daily-interval.js):

Горизонт	q10	q90	Ширина	Покрытие (исключение суток)	Было: сумма почасовых границ
сутки вперёд	−2.554	+4.397	6.81 норм·ч	73.3 %	93.3 % при ширине 10.13
двое суток	−2.617	+4.251	6.71 норм·ч	76.7 %	93.3 % при ширине 12.20

Интервал уже прежнего в 1.5–1.8 раза и асимметричен: факт чаще превышает прогноз в хвосте — модель недооценивает выработку в самые ветреные сутки. Оговорки: выборка 30 суток на лид даёт стандартную ошибку покрытия около 7 пунктов, внутривыборочная оценка 80.0 % завышена по построению, и к истине ближе указанные 73–77 %. Разбор — docs/root-analysis/05-interval-calibration.md.

Проверка на утечку факта: прогнозная скорость ветра на 100 м против факта с гондолы за январь 2026 — корреляция 0.741, MAE 1.91 м/с, смещение −0.93 м/с. Это обычный суточный прогноз, а не переодетый факт. Подстановка фактического ветра в измеренную кривую турбины даёт MAE 0.032, то есть 78 % нынешней ошибки создаёт сам прогноз погоды и только 22 % — модель турбины.

Что показал разбор корня задачи

Прежде чем улучшать решение, мы разобрали, где в этой задаче вообще лежит ошибка и что её ограничивает. Пять разборов с численными проверками — в docs/root-analysis/; ниже выводы, включая отрицательные: они показывают, что очевидные улучшения проверены, а не пропущены.

• 78 % ошибки создаёт прогноз погоды, а не модель турбины. Подстановка фактической скорости ветра в измеренную кривую даёт MAE 0.032 против 0.143 у полного контура. Связь почти линейна: 1 м/с ошибки прогноза ветра стоит 6.3 пункта nMAE, и чтобы дойти до nMAE 10 %, нужен прогноз с ошибкой 1.2 м/с вместо нынешних 1.9. Это потолок для любой схемы «прогноз ветра → кривая мощности» (01-weather-input.md).
• Мультимодельный ансамбль проверен и проиграл. Сравнили пять источников Open-Meteo: наш best_match не побеждён ничем — ИИ-модель ECMWF AIFS хуже на 2.7 %, среднее ветров на 7.7 %, ICON на 19.9 %, GFS на 48.1 %. Причина в том, что best_match уже отобранный продукт: в этой точке он совпадает с ICON в 75.3 % часов, разнообразие мнимое. Линейная калибровка ветра тоже отвергнута — она улучшает ветер (MAE 1.913 → 1.791), но ухудшает мощность (0.1517 → 0.1586), потому что сжимает разброс, а кривая нелинейна.
• MAE оказалась правильной метрикой именно для рынка РК. Цена положительного дисбаланса — контрактная с повышающим коэффициентом, отрицательного — с понижающим; при зеркальных коэффициентах потери симметричны, а при симметрии оптимум даёт медиана, то есть минимизация MAE эквивалентна минимизации денег. Проверено и обратное: при асимметрии цен 2:1 оптимальная заявка снижает стоимость на 15 %, но увеличивает физический объём небаланса на 3.1 % (02-objective-function.md).
• Фильтровать простои вредно. Исключение часов с недобором мощности поднимает nMAE с 14.31 до 15.26 %: оценивают нас по фактической выработке с учётом недоступности, а отфильтрованная модель предсказывает доступную мощность — другую величину. Знание плановых остановов дало бы 1.6–2.3 пункта, но требует журнала SCADA (04-data-and-operations.md).
• Агентность в ретроспективе вырождается, и мы это исправили. На архиве прошлого повторный опрос источника возвращает тот же срез, поэтому пересчёт не может изменить числа: расхождение с конвейером ровно 0.0000000000 во всех выпусках. Единственное место, где агент объективно сильнее жёсткого конвейера, — право заблокировать ненадёжный выпуск. Отсюда шестой инструмент и эксперимент с деградацией входа (03-agency.md).

Технологии

Python 3.14 (эталонное окружение, на нём выполнены все замеры; в Dockerfile указан python:3.11-slim, но Docker на машине сборки не устанавливался, поэтому контейнерный путь не проверялся), pandas, scikit-learn (HistGradientBoosting), httpx, OpenAI SDK, FastAPI, matplotlib, pytest, Docker. Внешние сервисы: Open-Meteo Previous Runs API и Historical Forecast API (открытые, без ключа), OpenAI API. Резервный провайдер LLM — NVIDIA NIM через совместимый с OpenAI эндпоинт, переключается переменной LLM_PROVIDER=nvidia; вживую этот путь не проверялся, ключа NVIDIA у команды не было.

Архитектура

data/raw/*.csv ──► app/data.py (часовая агрегация)
                                        │
Open-Meteo ──► app/weather.py (архив прогнозов, кэш) ──► app/features.py ──► app/model.py
                                        │                    (кривая + GBM + двухэтапная схема, P10–P90)
                                        │                                          │
                              app/agent.py: get_weather → check_input_quality → prepare_and_predict → analyze → [recalculate] → save_forecast
                                        │           оркестратор: LLM function calling или детерминированный план
                              app/backtest.py (30 выпусков) ──► outputs/forecast_feb2026.csv, outputs/agent_logs/
                                        │
                              app/cli.py (train | forecast | backtest | report), app/serve.py (HTTP)

Подробнее: docs/architecture.md, устройство агентного контура — docs/agent-design.md, решения с обоснованием — docs/adr/.

Установка

Системные требования: Python 3.12 или новее (эталон — 3.14.2), около 400 МБ под зависимости и 250 МБ под репозиторий с данными и кэшем. Сеть нужна только для pip install и для выпусков на даты вне кэша. ОС любая: замеры выполнены на Windows 11, контрольный сценарий проверен и в bash, и в PowerShell.

git clone https://github.com/BAITC-Hacks/hack-c63c1350-technokod.git
cd hack-c63c1350-technokod
python -m venv .venv
# Windows: .venv\Scripts\activate      Linux/macOS: source .venv/bin/activate
pip install -r requirements.lock.txt   # эталонные версии; гибкая установка — requirements.txt
cp .env.example .env        # Windows: copy .env.example .env
python scripts/check_env.py

Зависимости

Два файла на выбор:

Файл	Когда использовать
requirements.lock.txt	Для сверки чисел. 52 пакета с точными версиями эталонного прогона: именно на них получены метрики в docs/metrics.json и артефакты в outputs/. Версия scikit-learn критична — формат pickle обученных моделей привязан к ней
requirements.txt	Для обычной работы: прямые зависимости с гибкими нижними границами

Прямые зависимости: pandas, scikit-learn, httpx, python-dotenv, pydantic, openai, fastapi, uvicorn, matplotlib, joblib, duckdb, pypdf, rich, pytest.

Параметры окружения

Задаются в .env (файл в .gitignore, в репозиторий не попадает), образец — .env.example:

Переменная	Назначение	По умолчанию
LLM_PROVIDER	Провайдер оркестрации: openai, nvidia или demo	openai
OPENAI_API_KEY	Ключ OpenAI; без него работает детерминированный планировщик	пусто
OPENAI_MODEL	Модель выбора инструментов	gpt-5.4-mini
OPENAI_REASONING_MODEL	Модель для заключения	gpt-5.4
NVIDIA_API_KEY, NVIDIA_BASE_URL, NVIDIA_MODEL	Резервный провайдер через OpenAI-совместимый эндпоинт	пусто
DEMO_MODE	Принудительно детерминированный режим без обращений к провайдеру	false
APP_HOST, APP_PORT	Адрес и порт HTTP-сервиса	0.0.0.0, 8000

Для полного контрольного сценария ключи не нужны: числовой прогноз считает обученная модель, а LLM отвечает только за порядок вызова инструментов и текст заключения.

Docker (.env должен существовать, его требует docker-compose.yml; этот путь не проверялся — Docker на машине сборки не устанавливался):

docker compose run --rm app bash scripts/demo.sh   # контрольный сценарий целиком, включая обучение
docker compose up                                  # HTTP-сервис на порту 8000

В docker-compose.yml смонтирована только ./data, поэтому обученные модели и результаты остаются внутри контейнера и между отдельными запусками не сохраняются. Готовый блок volumes для models/ и outputs/ приведён в docs/runbook.md.

Запуск

python -m app.cli check                        # проверка окружения, данных, моделей, кэша
python -m app.cli train                        # обучение моделей, около 15 секунд, создаёт models/
python -m app.cli forecast --date 2026-01-31   # выпуск агентом (с LLM, если задан ключ)
python -m app.cli forecast --live              # ОПЕРАТИВНЫЙ выпуск на завтра по текущему прогнозу
python -m app.cli forecast --date 2026-01-31 --no-llm
python -m app.cli backtest --no-llm            # все выпуски 29.01–27.02.2026
python -m app.cli report                       # сводка по метрикам и артефактам
python -m app.cli fetch-weather --start 2026-01-29 --end 2026-02-27   # прогрев кэша

Вспомогательные скрипты:

python scripts/degradation_experiment.py   # агент против конвейера на шести деградациях входа
python scripts/run_llm_issues.py           # живая LLM-оркестрация на всех выпусках (нужен ключ)
python scripts/calibrate_daily.py          # калибровка интервала суточной энергии
python scripts/make_dashboard_data.py      # пересборка данных дашборда из артефактов
python scripts/make_charts.py              # графики в assets/ из артефактов

HTTP-сервис (python -m app.serve, порт из APP_PORT): GET /health, GET /forecast/{issue_date}?horizon=48&llm=false, GET /submission. Если контроль качества входа даёт вердикт fail, /forecast возвращает 422 с причиной отказа и находками, а не пустой прогноз.

Оперативный режим: прогноз на завтра, а не только воспроизведение прошлого

Тестовый протокол кейса требует воспроизвести выпуски февраля 2026 по архивным прогнозам. Но то же решение работает и на сегодняшнюю дату: python -m app.cli forecast --live берёт текущий прогон Open-Meteo Forecast API по тем же координатам и выпускает прогноз на следующие двое суток.

Разница только в источнике входа, всё остальное общее — те же признаки, та же модель, тот же агентный цикл с контролем качества:

Режим	Источник погоды	Когда применим
Ретроспектива (--date)	Previous Runs API, архивные слои «что предсказывали сутки и двое назад»	воспроизведение прошлого, оценка качества на известном факте
Оперативный (--live)	Forecast API, текущий прогон модели погоды	рабочий выпуск на завтра

Архивные слои для будущего не существуют — они появляются только когда прогноз становится прошлым, поэтому для работы на сегодня нужен именно текущий прогон. Проверено 23.09.2026: выпуск покрыл 24–25 сентября, 96 строк, полная трасса get_weather → check_input_quality → prepare_and_predict → analyze → save_forecast, 8 часов штиля, ожидаемая выработка 8.5 и 9.0 норм·ч по турбинам.

Оперативные выпуски в репозиторий не коммитятся: сдаваемые артефакты — только февральские, чтобы их не смешивать.

Как проверить решение

Полный контрольный сценарий одной командой: bash scripts/demo.sh (Linux/macOS/Git Bash) или powershell -File scripts/demo.ps1 (Windows). Скрипт сам выбирает интерпретатор (PYTHON, затем .venv, затем python из PATH), останавливается на первой ошибке и выполняет семь шагов: проверка окружения → обучение (пропускается, если модели уже есть) → выпуск прогноза → бэктест февраля → сводка → автотесты → живая LLM-оркестрация (пропускается, если ключ не задан). Замерено на обученных моделях: 27 секунд в bash и 24 в PowerShell, оба прогона с кодом возврата 0; на чистом клоне с GitHub — 38 секунд вместе с обучением. Сеть не требуется: архивные прогнозы лежат в data/cache/weather/ (223 файла, 6.9 МБ; часть файлов обеспечивает воспроизводимость проверок комиссии из docs/root-analysis/ — валидацию на ноябре и декабре 2025, калибровку суточного интервала и сравнение пяти погодных моделей).

Две детали, которые важны на чужой машине. Тесты запускаются с --basetemp=.pytest_cache/tmp: системный временный каталог pytest на Windows может быть недоступен по правам, и шаг падал бы не по вине решения. Седьмой шаг после прогона с LLM восстанавливает канонический журнал детерминированным выпуском — иначе проверка с ключом переписала бы артефакт outputs/agent_logs/2026-02-15.json.

На свежем клоне первый прогон сценария занимает 38 секунд, из них 14 секунд — обучение (отдельно от этого установка зависимостей pip install идёт 1–2 минуты): файлы models/*.joblib не коммитятся, потому что pickle привязан к версии scikit-learn и на другой машине не загрузится. Если модели уже обучены, шаг 2 пропускается и сценарий проходит за 20–30 секунд.

Ожидаемый результат:

• python -m app.cli train печатает по каждой турбине веса смеси и ошибку на январе 2026: nMAE 14.31 % и 14.55 % на горизонте 24 ч, 16.33 % и 16.66 % на 48 ч (docs/metrics.json).
• python -m app.cli forecast --date 2026-01-31 --no-llm печатает трассу get_weather → check_input_quality → prepare_and_predict → analyze → save_forecast, анализ и заключение; появляется outputs/forecasts/2026-01-31.csv на 96 строк (48 часов × 2 турбины, 13 колонок).
• python -m app.cli backtest --no-llm создаёт 30 файлов выпусков, outputs/forecast_all_issues.csv на 2 880 строк, outputs/forecast_feb2026.csv на 672 часа без единого пропуска и outputs/backtest_summary.csv на 30 строк. Агент выполнил повторный расчёт в четыре дня: 06.02, 15.02, 21.02, 24.02.
• python -m pytest -q tests → 22 теста проходят примерно за 4 секунды: агрегация часов, честность выборки прогноза, признаки, выпуск агента, сборка итогового ряда февраля, буревое обнуление, откат при отказе LLM, границы и ширина интервала, вердикты контроля качества на пяти деградациях входа, блокировка публикации при fail, отказ сохранять прогноз с NaN, явный признак отсутствия вчерашнего выпуска и числовой триггер пересчёта.

Проверка LLM-оркестрации: задать OPENAI_API_KEY в .env и выполнить python -m app.cli forecast --date 2026-02-15. Порядок вызова инструментов выбирает модель, заключение пишет она же. Журналы всех 30 таких выпусков уже лежат в репозитории (outputs/agent_logs_llm/, по одному на каждую дату с 29.01 по 27.02) — их можно читать без ключа и сравнивать с детерминированными журналами в outputs/agent_logs/: решения совпадают во всех 30 выпусках. Повторить прогон целиком — python scripts/run_llm_issues.py (нужен ключ). При ошибке сети или ключа агент откатывается на детерминированный план, это фиксируется в трассе как llm_fallback и покрыто тестом.

Проверка отказа от выпуска на плохих данных: python scripts/degradation_experiment.py — печатает таблицу «сценарий → конвейер → агент» по шести деградациям входа, ключи и сеть не нужны, артефакты в outputs/ не затрагиваются.

Проверка честности прогноза (ключевое требование кейса) описана отдельным разделом в docs/test-plan.md, численное доказательство — в docs/validation.md.

Выходные файлы

Файл	Содержание
outputs/forecast_feb2026.csv	Итоговый почасовой ряд февраля 2026, 672 строки, 13 колонок: ts, turbine_1_lead1, turbine_2_lead1, turbine_1_lead2, turbine_2_lead2, turbine_1_p10, turbine_2_p10, turbine_1_p90, turbine_2_p90, farm_mean_lead1, farm_mean_lead2, farm_p10_lead1, farm_p90_lead1. Станция — среднее долей номинала двух турбин, то есть в тех же единицах
outputs/forecast_all_issues.csv	Все 30 выпусков по часам, 2 880 строк: issue_date, ts, horizon_hour (1–48), lead_day, turbine, power_norm_pred, power_gbm_pred, power_curve_pred, power_p10, power_p90, power_two_stage_pred, wind_speed_100m, wind_nacelle_pred
outputs/backtest_summary.csv	Сводка по выпускам, 30 строк: часы, отметки пересчёта и режима LLM, часы штиля, номинала и шторма, средний КИУМ по турбинам, изменение относительно прошлого выпуска
outputs/forecasts/<дата>.csv	Отдельный выпуск, 96 строк
outputs/agent_logs/<дата>.json	Журнал выпуска: issue_date, llm_used, published, confidence, quality (вердикт контроля входа и перечень находок), recalculated, analysis, conclusion, trace
outputs/agent_logs_llm/<дата>.json	Журналы всех 30 выпусков с живой LLM-оркестрацией, по одному на дату

Значения — нормализованная мощность 0..1, как в исходных данных; время местное (Алматы). Пропусков в итоговом файле нет: выпуски начинаются с 29 января, поэтому каждый час февраля закрыт и прогнозом на сутки, и прогнозом на двое суток. Перевод в МВт·ч описан в docs/user-guide.md.

Документация

Документ	О чём
docs/architecture.md	Архитектура, контракты данных, масштабирование
docs/agent-design.md	Агентный контур: инструменты, промпт, пороги, журнал, бюджет LLM
docs/adr/	Восемь архитектурных решений с обоснованием и последствиями
docs/model-card.md	Карточка модели: данные, признаки, метрики, ограничения
docs/validation.md	Протокол честной валидации, доказательство отсутствия утечки, эталоны
docs/data-quality.md	Качество исходных данных: разрывы, выбросы, кривая мощности
docs/analysis.md	Разбор ТЗ и первичный анализ данных
docs/metrics.md, docs/metrics.json	Метрики в читаемом виде и машинном формате
docs/business-value.md	Ценность для эксплуатирующей организации, расчёт эффекта
docs/pitch.md	Сценарий защиты и ответы на вопросы
docs/user-guide.md	Руководство пользователя: установка, команды, разбор выходных файлов
docs/runbook.md	Регламент эксплуатации, мониторинг, реакции на отказы
docs/test-plan.md	Программа и методика испытаний с критериями приёмки
docs/compliance.md	Соответствие Положению: хронология коммитов, лицензии, раскрытие ИИ
docs/api.md	Справочник интерфейсов: HTTP-сервис и команды CLI с примерами ответов
docs/root-analysis/	Пять разборов корня задачи: метеорологический вход и физический потолок точности (01), целевая функция и рынок небалансов (02), смысл агентности (03), данные и эксплуатация станции (04), калибровка интервалов (05)
docs/tz-checklist.md	Требования ТЗ по подзадачам: как исполнено, чем доказывается, самооценка по критериям
docs/audit.md	Журнал независимых проверок «обещано против сделано» с историей прогонов
docs/submission-checklist.md	Требования Положения хакатона и что чем закрыто
docs/roadmap.md	План работ и хронология этапов
docs/brand.md	Фирменный стиль: палитра с проверкой контраста, типографика, знак
docs/index.md	Карта документации и маршруты чтения

Данные и интеграции

• data/raw/turbine_1.csv, data/raw/turbine_2.csv — данные организаторов, 10-минутные записи 11.03.2023–31.01.2026 (скорость ветра с гондолы, нормализованная мощность, температура). Разбор в docs/analysis.md и docs/data-quality.md.
• Open-Meteo Previous Runs API (previous-runs-api.open-meteo.com) — архивные прогнозы, покрытие с 16.02.2024. Обучение и тест идут на них.
• Open-Meteo Historical Forecast API — использовался при разведке данных, в итоговую модель не входит.
• OpenAI API — оркестрация агента и заключения. Ключи только через переменные окружения, .env в .gitignore.
• data/cache/weather/ — кэш архивных прогнозов, закоммичен ради запуска без сети.

Часовые пояса: данные ВЭС в местном времени, погода запрашивается с timezone=Asia/Almaty, стыковка по локальному часу (переход Казахстана на UTC+5 в марте 2024 учитывается источником погоды).

Стороннее и подготовленное до старта

Раскрытие по п. 5.4.4, 5.4.4.2 и 5.4.12 Положения, подробная хронология — в docs/compliance.md.

Коммиты f992796 и 573e6b8 (13:24 по времени Астаны) содержат инфраструктурную заготовку, подготовленную до начала хакатона: структура папок, .gitignore, .env.example, requirements.txt, Dockerfile, docker-compose.yml, app/config.py, app/llm.py (обёртка над OpenAI SDK), scripts/check_env.py, tests/test_smoke.py. Зафиксировать её раньше было физически нельзя: репозиторий команды выдан после старта. Логики кейса в заготовке нет, это проверяется командой git show f992796.

Вся предметная логика — загрузка и агрегация данных ВЭС, инструмент архивных прогнозов, признаки, модель, агент, бэктест, CLI, сервис — написана после старта, начиная с коммита b2b3b5b, и прослеживается по истории.

Open-source: библиотеки из requirements.txt (BSD, MIT, Apache-2.0; перечень с лицензиями в docs/compliance.md). Данные: организаторов и Open-Meteo (CC BY 4.0). Разработка велась с применением ИИ-агентов для генерации и анализа кода (п. 5.4.12 Положения); архитектурные решения, выбор источника данных и протокол валидации приняты командой, результаты проверены автотестами и численными экспериментами.

Ограничения

• Нулевой вес градиентного бустинга — не ошибка, а результат честного подбора. Прямое предсказание мощности проигрывает обоим физически осмысленным компонентам (MAE 0.158 против 0.147 у кривой и 0.149 у двухэтапной схемы), поэтому в рабочем прогнозе участвуют два компонента из трёх. Бустинг оставлен в модели как контрольный: он обучается и считается при каждом выпуске, его ошибка видна в docs/metrics.json, а на площадке, где физическая кривая работает хуже (другая турбина, другой рельеф, ограничения по мощности), подбор весов даст ему ненулевой вклад без изменения кода.

• Погода запрашивается одной точкой на обе турбины — серединой между ними. Координаты из задания (43.645150, 78.535604 и 43.643198, 78.538828) разделяют 400 метров, это глубоко внутри одной ячейки метеосетки: любой глобальный источник вернёт по ним идентичный прогноз, а лишний запрос удвоил бы нагрузку на бесплатный API без единого нового числа. Различаются турбины не погодой, а собственными кривыми мощности и простоями — поэтому модель обучается для каждой отдельно. Обоснование в docs/adr/0007-one-weather-point-two-models.md.

• Архив Previous Runs начинается с 16.02.2024, поэтому по календарю обучение охватывает 23 месяца, а не всю историю с марта 2023 года. Модель учится на парах «архивный прогноз → факт», и для компонентов, зависящих от прогноза, раннего архива не существует ни у кого. Строк при этом больше, а не меньше: на каждый час приходится два примера (прогноз за сутки и за двое), итого 31 078 и 33 710 против 23 тысяч часов факта.

  Данные до 16.02.2024 в проекте используются — на них построены анализ качества данных, статистика простоев, оценка затенения по направлениям ветра и эталон климатологии. Не используются они только в обучении, и мы проверили четыре способа это изменить (протокол парных сравнений, три месяца, docs/root-analysis/04-data-and-operations.md):

  Способ задействовать историю до 16.02.2024	Результат
  Кривая «ветер гондолы → мощность» на всей истории	14.33 против 14.31 % — в пределах шума
  Взвешивание по давности (полураспад 6, 12, 24 мес.)	ноль, максимум 0.08 пункта, знак разный по турбинам
  Кривая по холодным месяцам всей истории	выигрыш 0.02–0.36 пункта, но контрольный опыт снял его: та же кривая внутри архивного периода, без единой старой точки, даёт то же и местами лучше
  Гибрид: верх кривой из полной истории, низ из свежего периода	ноль, ±0.02 пункта

  Причина: медианы по бинам скорости расходятся между полной историей и архивным периодом не более чем на 0.008 во всём рабочем диапазоне, а редкие бины выше 12 м/с лежат там, где кривая уже на полке 0.97–0.99. Выборка в критичной зоне 3–12 м/с насыщена — 960–1500 часов на бин, удвоение объёма медиану не двигает.

• Факт выработки за февраль 2026 участникам не выдан, поэтому качество на тесте не измерялось. Все приведённые метрики относятся к январю 2026 и получены по тому же протоколу «прогноз как в прошлом».

• Январь 2026 оказался лёгким месяцем. Тот же контур по тому же протоколу даёт nMAE 16.2 % на ноябре 2025 и 19.2–19.7 % на декабре 2025 против 14.3–14.6 % на январе. Стандартная ошибка оценки на 720 часах — около 1 пункта (блочный бутстрап по суткам), то есть 14.31 % это результат на одном месяце, а не характеристика модели. Январь выбран не нами: это последний месяц перед тестовым периодом. Разбор в docs/root-analysis/04-data-and-operations.md.

• Потолок точности задаёт сам прогноз погоды: на идеальном ветре ошибка модели турбины составляет 0.032 MAE против нынешних 0.143. Дальнейший выигрыш даст ансамбль метеомоделей или коммерческий источник прогноза, а не усложнение модели турбины.

• Кривая мощности не учитывает плановые остановы и ограничения по команде диспетчера: в выданных данных нет журнала простоев. При внедрении нужны события SCADA.

• Оба интервала неопределённости построены на остатках января 2026 и на новых данных требуют перекалибровки. Почасовой покрывает 79.4 и 79.7 % при номинале 80 %, суточный — 73–77 % по проверке с исключением суток: выборка в 30 суток даёт стандартную ошибку покрытия около 7 пунктов, то есть суточный интервал слегка недопокрывает номинал. Январь — месяц низкого КИУМ, на ветреном месяце калибровку нужно повторить. Промышленный вариант — блочный conformal на отдельной калибровочной выборке (docs/root-analysis/05-interval-calibration.md).

• В бэктесте по архиву повторный опрос источника возвращает тот же срез (у архива суточная гранулярность), поэтому пересчёт меняет результат только через буревую защиту. В промышленной эксплуатации агент должен запускаться при каждом новом выпуске прогноза погоды, 4 раза в сутки; вызова оперативного API в коде нет.

• Путь NVIDIA NIM реализован переключением провайдера, но вживую не проверялся.

• Workflow .github/workflows/ci.yml настроен и корректен, но в этом репозитории не выполняется: организация-владелец заблокирована по биллингу, GitHub отвечает «The job was not started because your account is locked due to a billing issue». Поэтому бейджа сборки в шапке нет — красный значок вводил бы в заблуждение, а проверка выполняется локально контрольным сценарием.

• LLM-оркестрация зависит от внешнего API и лимитов, поэтому предусмотрен откат на детерминированный план; числовой результат от режима не зависит.

Развёрнутая версия

https://hack.technokod.kz — дашборд диспетчера: выбор даты выпуска из всех выпусков бэктеста, горизонт 24 или 48 часов, почасовой прогноз станции и обеих турбин с коридором P10–P90 и вчерашним выпуском для сравнения, панель трассы агента с вердиктом контроля входа и причиной пересчёта, сводка для заявки на рынок и блок надёжности по январю 2026. Методика решения — на /about. Статика на Cloudflare Workers, от рабочей машины не зависит, ключи не требуются. Исходник страницы — docs/index.html, данные — docs/demo/dashboard-data.js (собирается scripts/make_dashboard_data.py), docs/demo/validation-data.js (scripts/make_validation_data.py) и docs/demo/daily-interval.js (scripts/calibrate_daily.py), выкат командой npx wrangler deploy по конфигурации wrangler.jsonc. Страница не делает ни одного внешнего запроса: данные подключаются обычными <script>, поэтому она открывается и по ссылке, и прямо из файла.

Само решение остаётся исполняемым из репозитория по инструкции выше: развёрнутого промышленного сервиса прогнозирования нет, страница показывает результат его работы.

Куда развивать

Потолок нынешней точности измерен: 78 % ошибки создаёт сам прогноз погоды, а не модель турбины, и 1 м/с ошибки прогноза ветра стоит 6.3 пункта nMAE. Поэтому развитие идёт не в подбор гиперпараметров, а в данные, которых сейчас нет.

1. Телеметрия ветроагрегатов — поток SCADA: флаг доступности, уставки ограничений, обороты и угол лопастей, температуры узлов, вибрации. Снимает неопределённость, которую сегодня приходится восстанавливать статистически.
2. Учёт технического обслуживания — график регламентных работ, наряды, журнал отказов. Плановый ремонт это известное заранее обнуление выработки; его учёт даёт измеренные 1.6–2.3 пункта nMAE.
3. Прогнозирование на телеметрии и обслуживании — выработка с учётом состояния парка и деградации кривых, прогноз доступности, предиктивное обслуживание, оптимизация заявки на рынок.

Подробно, с числами и оценкой каждого шага: docs/product-roadmap.md.