WindCast — agentic-прогноз выработки ВЭС на 24–48 часов

Диспетчер ветропарка получает почасовой прогноз выработки на двое суток вперёд — с полосой неопределённости, обоснованием каждого шага агента и проверкой допустимости погодных данных по принятому правилу исторической доступности. Трек «Энергетика», кейс: «Agentic AI для прогнозирования выработки ВЭС», кейсодатель АО «Самрук-Казына» (docs/TASK.md).

• Демо: платформа — https://ctrlx-hackalem.vercel.app; лёгкая страница и API — https://windcast-api-production.up.railway.app (та же страница, что на localhost:8000; Swagger — /docs; без логина). Локальный запуск — раздел «Установка и запуск», ключи не нужны.

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

В Казахстане на ВЭС приходится около 82% всех дисбалансов возобновляемой генерации, а почасовое отклонение факта от заявленного графика достигает ~50% (QazaqGreen, 2025). График на сутки вперёд подаётся до 08:00, скорректировать его можно лишь за два часа — значит цена ошибки прогноза платится деньгами за дисбаланс.

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

Объект кейса — вся ВЭС «Нурлы» 5 МВт (2 × Goldwind GW109/2500, ТОО «Samruk-Green Energy», дочка «Самрук-Энерго»): координаты из ТЗ совпадают с турбинами в OpenStreetMap с точностью до 10 м. Выпуск делается в полночь по итогам дня D; его вторые сутки (D+2) — готовый черновик суточной заявки, которую ВИЭ подаёт до 08:00 D+1, а пересчёт в 12:00 — внутрисуточная корректировка не позже чем за 2 часа до часа (Правила оптового рынка, п. 51, 97–99). Сравнение с наивным прогнозом — в таблице метрик ниже. Полное описание решения, архитектуры и источников — docs/SOLUTION.md.

При воспроизведении прошлого выбираются архивные прогнозные поля по правилу config.safe_previous_day, а не фактическая погода за целевой час. Время публикации оценивается с принятой задержкой: это допущение, а не полный исторический журнал источника. Тесты проверяют соблюдение правила; график и таблица происхождения показывают выбранные поля, но сами по себе отсутствие утечки не доказывают.

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

• R1 — история двух турбин с шагом 10 минут приведена к часам: время SCADA (фиксированный UTC+5) → UTC, флаги дыр и простоев.
• R2 — агент сам получает архивные прогнозы Open-Meteo Previous Runs по координатам парка; кэш-first, по умолчанию без сети; правило day1/day2/day3 против утечки, проверенное тестом.
• R3 — три модели: кривая мощности (MOS), градиентный бустинг с квантилями p10/p90 и конформной калибровкой, климатология как последний рубеж.
• R4 — ретроспектива: 28 выпусков за тестовый период, по 48 часов каждый.
• R5 — agentic-цикл замкнут, и вклад агентского слоя измерен — раздел «Как проверить агентность».
• R6 — воспроизводимость: расчёт без ключей и без сети после установки, тесты, линтер, smoke со свежего клона.
• R7 — метрики на валидационных периодах: январь 2026 и февраль 2025; значения и ограничения — в таблице ниже.
• R8 — API по контракту и одностраничный интерфейс: выбор выпуска, график 48 ч с полосой p10–p90, лента шагов агента, сводка диспетчеру, таблица метрик.
• R10 — второй источник погоды gfs_seamless: переключение при провале валидации доказано в outputs/evidence/faults.json.

Частично: R9 — сводку диспетчеру может переписывать LLM (OpenAI или NVIDIA, второй провайдер — запасной); каждое число в тексте LLM сверяется с фактами выпуска, иначе остаётся шаблон. Без ключа работает шаблон. Статусы по каждому требованию — в таблице «Трассировка требований».

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

1. Выпуск. «Прогноз на день D» делается в D+1 00:00 по Алматы: наблюдения доступны до D 23:50, горизонт — следующие 48 часов (0–23 ч — текущие сутки D+1, 24–47 ч — сутки D+2, черновик заявки до 08:00).
2. Погода. Агент берёт из кэша (или, с --refresh, из Open-Meteo) архивные прогоны для координат парка и на каждый целевой час выбирает разрешённое поле previous_dayN.
3. Подготовка. История двух турбин с шагом 10 минут приводится к часам: время SCADA (UTC+5) → UTC, флаги дыр и простоев; признаки из прогноза погоды на 48 часов.
4. Модель. По прогнозному ветру считается выработка каждой турбины и парка, плюс квантили p10/p90 как мера неопределённости.
5. Анализ. Агент проверяет результат (диапазон, скачки, покрытие часов) и при провале спускается по лестнице фолбэков: другой источник погоды → кривая мощности → климатология, записывая решение и причину.
6. Пересчёт. Через 12 часов после выпуска появляются более свежие прогоны — агент перевыпускает прогноз (ревизия 1) на часы, которые ещё разрешено корректировать (не раньше чем через 2 ч). На графике видно и новую кривую, и то, что она заменила.
7. Самопроверка. Агент сравнивает свои опубликованные выпуски с фактом, когда он появляется, и поднимает флаг дрейфа с рекомендацией переобучения; модель молча не меняется. В тестовом феврале факта нет — агент честно пишет, что память заморожена на 31.01.

Технологии

Слой	Решение
Язык	Python 3.12, менеджер зависимостей uv (версии зафиксированы в uv.lock)
API и страница	FastAPI 0.141, pydantic 2.13, статика без сборки — инлайновый SVG, ноль внешних запросов
Данные	pandas 3.0, pyarrow (parquet)
Модели	scikit-learn (HistGradientBoostingRegressor, квантильная потеря + CQR) — намеренно без нативных зависимостей: LightGBM требует системный OpenMP, которого нет в lock-файле
Погода	Open-Meteo Previous Runs API, модели best_match и gfs_seamless
LLM (опционально)	OpenAI-совместимый клиент openai — только для сводки диспетчеру; без ключа работает шаблон
Проверки	pytest, ruff, scripts/smoke.sh

Архитектура проекта

flowchart LR
  CLI[CLI: forecast / backtest] --> AG[Агент-оркестратор]
  UI[Страница] --> API[FastAPI /api]
  API --> AG
  AG --> WX[app.weather<br/>Open-Meteo Previous Runs]
  WX -. кэш-first .-> CACHE[(data/weather_cache)]
  AG --> DATA[app.data<br/>часовые ряды турбин]
  AG --> MODEL[app.models<br/>power_curve / GBM]
  MODEL -. провал валидации .-> PC[фолбэк: кривая мощности]
  AG --> OUT[(outputs/forecasts<br/>runs/agent_log.jsonl)]
  API --> OUT

Агент — детерминированный цикл plan → fetch_weather → validate_weather → prepare → run_model → analyze → recompute_if_updated → write_report. Каждый шаг пишет строку в runs/<run_id>/agent_log.jsonl со статусом, решением и причиной, поэтому любой вывод можно проследить до данных. API только читает результаты с диска и потому не зависит от того, чем именно был получен прогноз; страница целиком строится на этих же публичных эндпоинтах.

Установка и запуск

Быстрый старт (без ключей)

uv sync --frozen
uv run python -m app.cli backtest          # 28 выпусков 31.01–27.02 заново
uv run uvicorn app.main:app --port 8000    # http://localhost:8000

Откроются 28 выпусков февраля 2026, посчитанные агентом: график, лента шагов агента, сводка диспетчеру, точность и доказательства агентности. Готовые результаты уже лежат в репозитории (outputs/, runs/), вторая команда пересчитывает их с сохранённой моделью. Первая установка требует интернет или заполненный кэш зависимостей; дальнейший расчёт работает из погодного кэша без сети. Проверка полного обучения с нуля описана ниже. Без LLM_API_KEY проект работает в DEMO-режиме — прогноз считается кодом, сводка собирается шаблоном; LLM-сводка не меняет числовой прогноз. Отдельный диагностический супервизор описан в docs/AGENTIC.md.

Платформа для диспетчера (по желанию)

Веб-интерфейс на Next.js поверх того же API: февраль по часам, прогноз на 48 часов с уточнением в 12:00, заявка на завтра в МВт·ч с выгрузкой CSV, шаги агента, точность, вопрос агенту и раздел для ИТ-службы. Без него решение работает полностью.

uv run uvicorn app.main:app --port 8000            # терминал 1: API
cd web && pnpm install && pnpm build && pnpm start  # терминал 2: http://localhost:3000

Нужны Node.js 22+ и pnpm 11 (corepack enable). Адрес API задаёт WINDCAST_API_URL, по умолчанию http://localhost:8000; запросы /api/* проксируются, CORS не нужен.

Установка

• Требования: Python 3.12 и uv — или pip, или Docker
• uv sync (версии зафиксированы в uv.lock); без uv: pip install -r requirements.txt
• Docker: docker build -t ctrlx . && docker run -p 8000:8000 ctrlx
• Ключи — по желанию: cp .env.example .env.local

Запуск

• API и страница: uv run uvicorn app.main:app --port 8000 → http://localhost:8000
• Один выпуск: uv run python -m app.cli forecast --issue 2026-01-31
• Ретроспектива за февраль: uv run python -m app.cli backtest --from 2026-01-31 --to 2026-02-27
• Обучение моделей: uv run python -m app.cli train
• Метрики на отложенном месяце: uv run python -m app.cli evaluate --holdout 2026-01
• Тесты и линтер: uv run pytest -q && uv run ruff check .
• Живая сверка архивного окна с источником (нужна сеть): добавить --refresh; это не режим прогнозирования на сегодняшнюю дату.

Зависимости

Список — pyproject.toml / requirements.txt: fastapi, uvicorn, pydantic, pandas, pyarrow, scikit-learn, openai, python-dotenv; разработка — pytest, httpx, ruff.

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

Переменная	Обязательна	По умолчанию	Назначение
DEMO_MODE	нет	auto	auto — LLM, если заданы ключ и модель; 1 — всегда без LLM
LLM_API_KEY	нет	—	ключ OpenAI или NVIDIA; без него включается DEMO-режим
LLM_BASE_URL	нет	https://api.openai.com/v1	для NVIDIA: https://integrate.api.nvidia.com/v1
LLM_MODEL	с ключом	—	имя модели
LLM_FALLBACK_API_KEY, LLM_FALLBACK_BASE_URL, LLM_FALLBACK_MODEL	нет	—	второй провайдер: вызывается, если первый не ответил

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

• На развёрнутой версии (без установки, 2 минуты): https://ctrlx-hackalem.vercel.app → «Прогноз на 48 ч». Любой февральский день — готовый выпуск с графиком и лентой шагов агента; «Пересчитать» повторяет прогон на сервере. Новые данные: в поле «Новая дата» выбрать любой прошедший день после февраля (например, вчера) → «Прогноз на новую дату»: агент сам запросит у Open-Meteo архивные прогоны, доступные на момент выпуска, и через 3–5 с покажет прогноз на 48 ч и журнал, где в шаге «fetch_weather» видно «архив не покрывает этот выпуск — окно погоды докачано». Завтрашняя дата честно отклоняется: выпуск делается по итогам дня. То же через API: curl -X POST https://windcast-api-production.up.railway.app/api/run -H 'content-type: application/json' -d '{"issue_date":"2026-09-20"}'. Новые фактические данные ВЭС (SCADA) проверяются локально — раздел «Прогноз на новую дату».
• Локально: ключи и личные аккаунты не нужны. Для первой установки зависимостей требуется сеть или готовый кэш пакетов.

1. uv sync && uv run uvicorn app.main:app --port 8000
2. Открыть http://localhost:8000 — страница показывает выпуск, график с полосой p10–p90 и ленту шагов агента.
3. Проверить API напрямую:

curl -s http://localhost:8000/api/health
# → {"ok":true,"mode":"demo","commit":"dev"}

curl -s http://localhost:8000/api/issues
# → [{"issue_date":"2026-01-31","run_id":"20260201T0000-…","model_name":"gbm","revisions":2,…}]

curl -s http://localhost:8000/api/forecast/2026-01-31 | head -c 400
# → ForecastIssue: rows (почасовые строки), summary, warnings

# run_id берём из ответа выше, а не из этой инструкции: он меняется при перегенерации
run=$(curl -s http://localhost:8000/api/issues | python3 -c 'import json,sys; print(json.load(sys.stdin)[0]["run_id"])')
curl -s "http://localhost:8000/api/runs/$run/log"
# → шаги агента: tool, status, decision, reason, duration_ms

4. Проверить выбранное архивное поле wx_field и журнал validate_weather. Расчётный запас доступности основан на правиле задержки, точное историческое время публикации не утверждается. Тесты погоды проверяют временные границы; «отравленный» тест проверяет, что замена недопустимых будущих значений не меняет прогноз.
5. На лёгкой странице открыть «Происхождение погоды по часам», сравнить пунктир первоначального прогноза с новой ревизией и скачать CSV всех ревизий. Мощности в CSV — доли номинала 0…1; времена содержат UTC-смещение. Экспорт не является торговой заявкой.
6. Статус «Готов к рассмотрению» означает отсутствие замечаний в загруженном журнале. При резервном пути или недоступном журнале показано предупреждение; окончательное решение остаётся за диспетчером.

Результат за февраль 2026

Главный файл для сравнения с фактом — outputs/forecasts/february_2026.csv: 672 строки, по одной на каждый час 01–28.02.2026.

Колонка	Смысл
target_time_utc, target_time_local	час прогноза (UTC и Алматы, UTC+5)
power_farm_plan, power_t1_plan, power_t2_plan	последний прогноз на этот час: опережение 0–23 ч из выпуска, сделанного в начале этих суток, с ревизией 1 после пересчёта в 12:00
p10_plan, p90_plan	коридор неопределённости p10–p90
plan_revision, plan_run_id	какая ревизия и какой прогон агента дали значение (журнал — runs/<run_id>/)
power_farm_bid, bid_mw	суточная заявка: опережение 24–47 ч из выпуска предыдущей ночи, готова до 08:00; для 01.02 пусто — её делал бы выпуск за 30.01, который не входит в тестовый период
plan_mw	план в МВт (номинал ВЭС «Нурлы» 5 МВт)

Мощность — доля номинала 0…1, как в данных кейса. Полная история каждого выпуска и ревизии — outputs/forecasts/issue_YYYY-MM-DD.csv; черновик заявки на D+2 в МВт·ч по часам — runs/<run_id>/bid_YYYY-MM-DD.csv.

Живая сверка. uv run python -m app.cli forecast --issue 2026-02-10 --refresh — агент сам запрашивает у Open-Meteo окно выпуска по координатам обеих турбин и сверяет с архивом из репозитория; пример в runs/live_check/: ответ API совпал с архивом на всех 48 часах (live_match).

Прогноз на новую дату

Агент не ограничен февралём. Для любой даты после периода обучения он сам запрашивает у Open-Meteo архивные прогоны для окна выпуска по координатам обеих турбин и считает выработку на 48 часов; закоммиченный архив погоды при этом не меняется:

uv run python -m app.cli forecast --issue 2026-09-22   # нужна сеть: погода докачивается сама

Флаг --refresh не обязателен: докачка включается сама, когда архив не покрывает дату; для февраля прогноз всегда строится по закоммиченному архиву. Для новых дат идентификатор прогона не фиксирует содержимое живого ответа Open-Meteo: два запуска в разное время могут дать разные прогоны. То же делает кнопка «Прогноз на новую дату» на экране «Прогноз на 48 ч» платформы. Даты внутри периода обучения модели агент отклоняет: для проверки прошлого по факту служит replay. Новые фактические данные кладутся в data/raw/turbine1.csv и turbine2.csv в том же формате; часовые ряды пересобираются автоматически, uv run python -m app.cli train переобучает модель, evaluate --holdout YYYY-MM считает точность за новый месяц.

Правило против утечки данных

ТЗ требует использовать «архивные прогнозы погоды, доступные на соответствующий момент времени, а не фактические погодные значения, ставшие известными позднее». Open-Meteo отдаёт поле previous_dayN — значение, предсказанное за 24·N часов до целевого часа (по документации, по исходному коду Open-Meteo и по сверке с Single Runs API). Прогон появляется в Open-Meteo с задержкой: для ECMWF IFS мы измерили 7,0 ч, для GFS 5,5–6,5 ч, для ICON 3,8 ч. Принята задержка 7 часов (PUBLISH_DELAY_H): прогон допустим, если init + 7 ч ≤ t0.

Горизонт от t0	Разрешённое поле
0–16 ч	previous_day1
17–40 ч	previous_day2
41–47 ч	previous_day3

При пересчёте в t0 + 12 ч (ревизия 1) граница сдвигается на 12 часов: 0–28 ч → previous_day1, 29–47 ч → previous_day2. Поэтому строка ревизии 1 с опережением 28 ч и полем day1 — не утечка: к 12:00 этот прогон уже опубликован.

Правило реализовано в config.safe_previous_day(lead_h, hours_since_issue) — одной функцией, которую используют обучение, агент и тесты. Если нужного поля нет, берётся только более старый прогон, никогда не более свежий. При внутрисуточном пересчёте (hours_since_issue = 12) граница сдвигается, потому что к этому моменту опубликованы более свежие прогоны. Реанализ (ERA5), Historical Forecast API и поле без суффикса не используются нигде.

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

«Агент» легко заявить и трудно доказать. Поэтому вклад агентского слоя измерен: мы прогоняем один и тот же месяц четырьмя вариантами, от простейшего к полному, и сравниваем с фактом.

uv run python -m app.cli replay --month 2026-01   # → outputs/evidence/replay_2026-01.json
uv run python -m app.cli faults                   # → outputs/evidence/faults.json

Абляция — январь 2026, 31 выпуск, 1 464 пары «выпуск × час», обучение закончено до начала месяца:

Вариант	MAE
A — персистентность	0,3066
B — кривая мощности без пересчёта	0,1953
C — GBM без пересчёта	0,1536
D — опубликованный план: D+1 обновлён, D+2 из t0	0,1519

Видно, где сколько выигрыша: главный вклад даёт модель (B → C), а агентский слой добавляет сверху ещё немного (C → D). Мы не выдаём второе за первое.

Журнал решений — каждое решение агента с доверительным интервалом, а не «стало лучше»:

Решение	Сработало	Δ MAE	95% ДИ	Выигрышей
Проектный выбор GBM против кривой мощности	31	-0,0427	[-0,0582; -0,0272]	25
Пересчёт по свежей погоде	31	-0,0060	[-0,0143; 0,0016]	18

Отрицательная Δ означает, что решение уменьшило ошибку. Честно отмечаем: доверительный интервал пересчёта пересекает ноль — на спокойном январе выигрыш не доказан, а два защитных решения в нормальном режиме не срабатывали ни разу. Их ценность проверяется отдельно.

Устойчивость к сбоям — app.cli faults ломает входные данные и сравнивает агента с фиксированным пайплайном на выпуске 09.02.2026:

Сбой	Агент	Фиксированный пайплайн
в основном источнике нет 6 часов ветра	48 ч, переключился на gfs_seamless	42 ч
выброс 100 м/с во всех прогонах основного источника	48 ч, переключился на gfs_seamless	48 ч, но 6 часов посчитаны по битому входу
выброс 100 м/с только в самом свежем прогоне	48 ч, взял более старый прогон того же источника (older_run), модель осталась основной	48 ч, но 6 часов посчитаны по битому входу
основной источник недоступен	48 ч, переключился на gfs_seamless	0 ч
оба источника сломаны	48 ч, перешёл на климатологию	42 ч

Агент выдал полный горизонт в 5 случаях из 5 и в каждом записал решение и причину в runs/<run_id>/agent_log.jsonl. Фиксированный пайплайн либо теряет часы, либо — что хуже — молча считает прогноз по испорченному входу.

Тесты и метрики

uv run pytest -q          # API, CLI, погода и правило утечки
uv run ruff check .       # линтер
scripts/smoke.sh          # свежий clone → install → тесты → запуск → основной сценарий

scripts/smoke.sh проверяет опубликованную версию в отдельном клоне: установка → проверка SHA-256 входов → удаление готовых модели и прогнозов в клоне → обучение → полный backtest → 28 выпусков, 672 часа → тесты, линтер и HTTP всех выпусков. При ошибке останавливается. scripts/smoke.sh --local проверяет локальный коммит, без незакоммиченных правок. Bash-сценарий рассчитан на macOS/Linux; на Windows основные Python-команды выполняются отдельно. Node необязателен для Python: без него пропускается только дополнительный тест JavaScript.

Журнал, ограничения и сценарий демонстрации на 3–4 минуты — docs/TESTING.md. Тестовый клон и логи сохраняются по напечатанному пути; рабочая модель не перезаписывается.

Качество на валидационных месяцах. Обучение заканчивается до каждого месяца, но эти периоды ранее использовались при выборе подхода и не являются полностью независимым тестом. MAE ниже — доля номинала; nMAE = MAE × 100 %, не процент верно угаданных часов. Точные границы и ограничения — docs/METRICS.md.

Модель	Январь 2026 MAE	Февраль 2025 MAE
Персистентность	0,3066	0,3386
Климатология	0,3039	0,3205
Кривая мощности	0,1953	0,2070
GBM	0,1536	0,1778

Покрытие p10–p90: 80,5 % / 82,0 %; средняя ширина: 49,1 / 58,2 п.п. номинала. Это измеренные значения на этих периодах, не гарантия покрытия на новых данных.

Сценарная стоимость отклонений. Используются допущения расчёта: мощность 5 МВт, цена 22,68 ₸/кВт·ч и коэффициент 0,3 на каждое абсолютное отклонение заявки D+2; считается только по часам заявки (горизонт 24–47 ч). Освобождение в пределах ±5 % и взаимозачёт не моделируются. Это не фактический счёт станции и не измеренная экономия.

Модель	Январь, млн ₸	Февраль, млн ₸
Персистентность	7,44	7,81
Кривая мощности	5,10	4,48
GBM	3,88	3,84

Источник таблиц — outputs/metrics/holdout_2026-01.json и holdout_2025-02.json. Факта февраля 2026 нет, точность на тестовом феврале не заявляется.

Трассировка требований

R-ID	Требование	Где реализовано	Как проверить	Статус
R1	История турбин → часовые ряды, флаги дыр и простоев	app/data.py	data/processed/hourly.parquet создан (964 КБ)	✅
R2	Агент сам получает архивные прогнозы, правило против утечки	app/weather.py, data/weather_cache/	uv run pytest tests/test_weather.py -q	✅
R3	Модели выработки с квантилями p10/p90	app/models.py, app/train.py	models/windcast.pkl (4,5 МБ); кривая мощности, бустинг + CQR, климатология	✅
R4	Ретроспектива: выпуск на каждый день февраля	app/service.py	28 файлов outputs/forecasts/issue_*.csv + february_2026.csv	✅
R5	Agentic-цикл с анализом и пересчётом, работает без ключей	app/agent/	28 прогонов в runs/; вклад слоя измерен — раздел «Как проверить агентность»	✅
R6	README и воспроизводимость в 3 команды без ключей	README.md, scripts/smoke.sh, docs/TESTING.md	scripts/smoke.sh → SMOKE PASS	✅
R7	Метрики на отложенных периодах против базовых моделей	app/evaluate.py	outputs/metrics/holdout_2026-01.json (nMAE 15,4 %) и holdout_2025-02.json (17,8 %)	✅
R8	API по контракту и страница с графиком и лентой агента	app/api/routes.py, static/index.html	curl /api/forecast/2026-01-31; открыть http://localhost:8000	✅
R9	Сводка диспетчеру от LLM с проверкой чисел	app/llm.py, app/agent/orchestrator.py	forecast --issue 2026-02-01 --llm --demo-dir runs/llm_demo при LLM_API_KEY	🚧
R10	Второй источник погоды: разброс и фолбэк	app/weather.py	gfs_seamless в кэше; переключение доказано в outputs/evidence/faults.json (GFS в 3 из 5 сценариев, полный горизонт в 5 из 5)	✅

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

Из ТЗ. Две турбины в Алматинской области, ~300 м друг от друга (одна ячейка погодной сетки): турбина 1 — 43.645150, 78.535604; турбина 2 — 43.643198, 78.538828. Это вся ВЭС «Нурлы» 5 МВт (OpenStreetMap relation 14072944). Период 11.03.2023 00:00 – 31.01.2026 23:50, шаг 10 минут; февраля 2026 в данных нет. Колонки: время (часы SCADA, фиксированный UTC+5: 01.03.2024 они не переводились — фаза суточного хода температуры сдвинулась на 6 минут, а не на 60), средняя скорость ветра м/с, нормализованная активная мощность 0…1, средняя температура °C.

SHA-256 файлов в репозитории (переводы строк LF, как их отдаёт git clone); у оригиналов с Google Drive (CRLF) суммы c4c341582fb2dd348b7187f0128cff265fe055f469413871ebb5db50eef58b5b и 820578cd18bb557cd30c2e102f3ae5a386dfc6c489a5a15743339c2b017305e5, данные те же.

Файл	Размер	SHA-256
data/raw/turbine1.csv	5,9 МБ	d82def7e56c0a1eed3f2f68eb29fd66e4299999921c9703720a880a5cf7d6703
data/raw/turbine2.csv	6,2 МБ	16a844db949562290c96a86efa20178a71540ff6252275c003db4715edb9434a

Открытые источники. Прогнозы погоды — Open-Meteo Previous Runs API, бесплатно для некоммерческого использования, атрибуция CC BY 4.0. Архив загружен в data/weather_cache/ вместе с meta.json (URL запроса, время загрузки, SHA-256), поэтому результат воспроизводится без сети и без ключей.

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

Ограничения

• Прогноз ветра — главный источник ошибки. Модель выработки работает на прогнозном ветре, поэтому её точность ограничена точностью NWP, особенно на горизонте 41–47 часов, где по правилу утечки доступен только трёхсуточный прогон.
• Станция из двух турбин. Это вся ВЭС «Нурлы»; кривой мощности производителя и данных об ограничениях сети нет, поэтому «выработка станции» — среднее по двум турбинам, нормализованное к 1 (× 5 МВт в сводке).
• Простои неотличимы от штиля по причине. Мы помечаем часы с нулевой мощностью при ветре выше 5 м/с как простой, но причину (ремонт, ограничение сети) данные не содержат.
• Задержка публикации прогонов принята равной 7 часам — измерена для ECMWF IFS по meta.json Open-Meteo (7,0 ч); у других моделей она меньше, значит правило консервативное. Точные времена инициализации дал бы Single Runs API — это следующий шаг.
• Источник best_match сменился 01.10.2025 (ICON → ECMWF IFS, у IFS ветер в среднем на 1,35 м/с ниже). Модель видит это через признак эпохи, агент пишет источник в журнал.
• Февраль 2026 проверяется только по прогнозу. Фактической выработки за тестовый период в данных нет, поэтому качество измеряется на отложенных периодах (январь 2026, февраль 2025).
• Куда развивать: добавить ансамбль из нескольких моделей NWP и сетку точек вокруг парка (замер на наших данных дал MAE 0.229 → 0.180), учитывать направление ветра и стратификацию, подключить факт по SCADA для дообучения и калибровки квантилей.

Масштабирование

Замеры на этой машине (Apple M-series, один процесс, без GPU), на том же клоне, что проверяет scripts/smoke.sh:

Операция	Замер
Обучение модели с нуля	11 с
Ретроспектива за весь тестовый период — 28 выпусков × 48 ч	9 с
Один выпуск в API (POST /api/run), модель уже в памяти	0,24 с
Первый выпуск после старта (загрузка модели)	2,8 с
SCADA на входе	142 360 строк × 2 турбины = 989 суток по 10 минут

Почти всё время выпуска — фиксированный старт: пять выпусков считаются столько же, сколько два. Значит узкое место не в математике, а в том, сколько раз мы платим за старт и чтение файлов.

Как это переносится на объёмы больше нашего:

Объём	Оценка по замерам	Что меняется в архитектуре
Одна ВЭС, месяц	9 с	ничего, текущий код
Одна ВЭС, год	~2 мин	ничего
50 ВЭС, год	~1,5–2 ч в один процесс	обучение и ретроспектива — по парку параллельно; это независимые задачи, распараллеливаются линейно
Оперативный режим: 50 ВЭС, выпуск каждый час	~12 с расчёта в час	прогон вынести из HTTP в очередь, API только читает готовое

Где ломается текущая реализация и что делать:

• Чтение файлов на каждый запрос. GET /api/issues перебирает все файлы выпусков: на 28 это 11 мс, на годе по 50 паркам — это 18 тысяч файлов. Нужен индекс выпусков в SQLite или Postgres; API уже отдаёт только чтение, поэтому замена хранилища не затрагивает ни агента, ни страницу.
• Прогон внутри HTTP-запроса. POST /api/run считает синхронно. При очереди с воркерами запрос возвращает run_id, а страница опрашивает статус.
• Один воркер uvicorn. Путь чтения не зависит от стека моделей — он специально отвязан, — поэтому API и страницу можно масштабировать репликами отдельно от расчётного контура.
• Погодный кэш один на парк. Турбины одного парка попадают в одну ячейку сетки, но 50 парков — это 50 запросов к Open-Meteo; нужен общий кэш с ключом по ячейке, иначе упрёмся в лимиты провайдера.
• Чего не хватает для эксплуатации: аутентификация (диспетчер видит свой парк), приём факта по SCADA для дообучения и калибровки квантилей, журнал решений в неизменяемом виде — это требование ст. 19-1 ПДн и Цифрового кодекса к авторешениям.

Ссылка на развёрнутую версию

• Платформа для диспетчера: https://ctrlx-hackalem.vercel.app (Next.js на Vercel; /api/* проксируется на бэкенд).
• Лёгкая страница и API агента: https://windcast-api-production.up.railway.app — на корне та же страница, что на localhost:8000; Swagger на /docs, например GET /api/issues, POST /api/run (Docker-образ из Dockerfile на Railway).
• Экран «Для ИТ» показывает режим сервиса (LLM или сводки по шаблону) и версию API: переменная COMMIT контейнера, без неё — dev. Локальный запуск без аккаунтов — раздел «Установка и запуск».

Команда

Участник	Роль	Вклад
Мустафа	лид-интегратор	контракт и зоны, данные и часовые ряды, модели, agentic-оркестратор, ретроспектива, метрики
Амирхан	данные погоды и идеи	Open-Meteo Previous Runs, кэш и правило против утечки, ресерч по ансамблю NWP
Ансар	платформа	API по контракту, страница, README, тесты API/CLI, smoke

Как мы работали с AI-агентами

• Направляющие: AGENTS.md и CLAUDE.md — правила, контракт, зоны ответственности; скиллы в .agents/skills/ — разбор ТЗ, checkpoint, критики, сдача, UI.
• Сенсоры: автотесты, линтер, smoke-тест со свежего клона (scripts/smoke.sh), проверка секретов и зон в pre-commit, критики со свежим контекстом, независимый прогон по README (scripts/judge.sh). Журнал — docs/TESTING.md.
• Трое разработчиков, у каждого свой агент (Claude Code или Codex), один main, результат каждый час — docs/PROGRESS.md. Сообщения между агентами — отдельная ветка team-chat (scripts/msg.sh).

Заранее подготовленное, заимствования и AI-инструменты

• Подготовлено до старта (п. 5.4.4.2): см. docs/PREPARED.md — инструменты разработки и пустой каркас без логики задачи.
• Заимствования: данные турбин — из ТЗ кейсодателя; прогнозы погоды — Open-Meteo Previous Runs API (CC BY 4.0). Сторонний код: компоненты shadcn/ui (MIT) в web/components/ui/ и скиллы агентов с лицензиями — перечислены в docs/PREPARED.md.
• AI-инструменты разработки: Claude Code, OpenAI Codex.

Проверенные возможности LLM

В runs/llm_demo/ сохранён пример реальной LLM-сводки старой версии модели. Это исторический пример работы со сводкой, не текущий эталон точности и не доказательство вызовов инструментов супервизором. Native-tool супервизор проверен локальными тестами; успешный внешний цикл не заявляется. Для запуска основного сценария ключи не нужны.

Финальная проверка опубликованного среза 4bfb7ed на macOS: полный scripts/smoke.sh прошёл, включая обучение с нуля и 205 тестов. По отчёту Амирхана, тот же сценарий на Windows для 51be5d5 также прошёл (205 тестов). Подробности — docs/TESTING.md.