WindAgent AI · AI Energy Agent

HackAlem AI 2026 · команда Anhalt ANY

Локальный ML-прогноз активной мощности ветрогенераторов, проверка физических ограничений и объяснение результатов. Числа рассчитывает ML-модель; LLM формирует пояснения и не изменяет прогноз. Интерфейс объединяет погоду, мощность, энергию, качество данных и рекомендации.

Состояние проекта

Состояние main на 23 сентября 2026 года:

Сценарий	Что доступно	Что означает результат
Goldwind T1/T2 — целевая ВЭС	Веб-интерфейс, API, проверки доступности данных, почасовой прогноз 24/48 ч и февральский replay реализованы в коде. Получены CSV с историей.	Реальный запуск заблокирован неподтверждённой семантикой данных, отсутствием обученного целевого artifact и подключённого проверенного погодного архива.
Kelmarsh — реальные наблюдения	Сохранённая модель, реальные SCADA, holdout, графики, метрики и анализ.	Проверенный дополнительный пример MODE A, не оценка качества Goldwind.
Синтетическое демо	Локальная модель, сохранённая погода и полный путь до интерфейса без внешних API.	Демонстрация работы программы, не подтверждение точности на реальной станции.

Общая сборка включает PR #1–#3, погодный модуль A из PR #4 и подготовку, обучение и провайдер Goldwind из PR #5. Ветки объединены через Git. Финальная модель Goldwind ещё не обучена. Проверка общей сборки и результаты.

Быстрый запуск интерфейса

Выполняйте команды из корня репозитория. Для общего UI/API используется Python 3.12 на Linux/macOS. На Windows запускайте общий сервис в WSL: текущий forecast orchestrator использует POSIX-модуль fcntl. Сам ML-слой отдельно проверен на Windows/Python 3.13.

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.lock.txt
cp .env.example .env
python scripts/run_ui.py

Откройте http://127.0.0.1:8000/ui/. Node.js и сборка frontend для запуска не нужны. Другой порт: python scripts/run_ui.py --port 8080.

Для воспроизведения ранее проверенного окружения Python 3.12/macOS arm64 сохранён requirements.lock.txt. Диапазоны зависимостей для других совместимых окружений — в requirements.txt; такое окружение требует отдельной проверки. Совместимость сериализованных моделей зависит от версий библиотек: Kelmarsh обучен со scikit-learn 1.9.1 и joblib 1.6.0; полный ML-список — requirements-trained.txt. При смене sklearn можно пересоздать только синтетическое демо командой python scripts/prepare_demo.py; Kelmarsh и его holdout менять для запуска не требуется.

Что показать в UI

1. «Прогноз ВЭС T1/T2» — основной режим по умолчанию. Показывает причины неготовности; расчёт недоступен до подключения обязательных входов.
2. «Синтетическое демо» — дата 10.02.2026, горизонт 24 или 48 часов. Нажмите «Рассчитать прогноз».
3. «Реальные данные Kelmarsh» — дата 08.11.2017, Kelmarsh 1, горизонт 24 часа. Показывает модель и факт по наблюдаемой погоде.

Веб-интерфейс показывает мощность в МВт, энергию в МВт·ч, позволяет скачать CSV и исходный JSON. В вычислительном/API-контракте используются кВт и кВт·ч. Пропуски не заменяются нулями. Подробности интерфейса и проверки: FINAL_UI.md.

Исходный Streamlit-интерфейс также сохранён: streamlit run src/app/streamlit_app.py.

Целевая станция и данные

Турбина	Модель	Номинал	Высота ступицы	Координаты
T1	Goldwind GW109/2500	2500 кВт	80 м	43.645150, 78.535604
T2	Goldwind GW109/2500	2500 кВт	80 м	43.643198, 78.538828

Общий номинал — 5 МВт. Параметры предоставлены командой и сохранены в config/turbines.json. Высота ступицы не подтверждает высоту измерения исходного ветра, а номинал не определяет формулу нормализации SCADA.

Полученные файлы лежат в data/goldwind/incoming/received_20260923. В основном CSV — 50 784 почасовые строки с метками T1/T2 за 11.03.2023–31.01.2026. Данные 1–10 марта отсутствуют. У 48 452 строк sample_count=6 и конечные погодные/целевые значения; сам счётчик ещё не доказывает корректное покрытие часа.

До финального обучения автор CSV или организаторы должны подтвердить:

• timezone и историческую политику перевода часов, начало/конец интервала;
• единицы ветра, температуры и мощности, формулу нормализации и её знаменатель;
• соответствие исходных меток физическим T1/T2;
• метод агрегации, смысл sample_count, пропусков, остановок и предварительной очистки;
• высоту/место измерения ветра и время доступности SCADA;

Расписание команды уже выбрано: первый forecast_origin — 2026-01-31T23:00:00+05:00 (18:00 UTC), затем ежедневно 23:00 Asia/Almaty, первый lead — 1 час. Оба интерфейса берут время из forecast_schedule.json. Календарь выполнения не определяет timezone исходных CSV.

Диапазон значений не позволяет достоверно восстановить эти определения. Исходные CSV сохраняются для аудита. Подробности: проверка поставки, машинный отчёт.

Goldwind: условия запуска

python scripts/run_target_forecast.py --check

Команда возвращает готовность конфигурации и блокеры; код 2 ожидаем при отсутствии обязательных входов. Такая проверка не заменяет проверку исторической доступности каждого выпуска погоды.

Для реального расчёта требуются:

1. Подтверждённый forecast protocol: timezone, час запуска, первый lead, интервальная и целевая семантика. confirmed нельзя включать без основания.
2. Архивные прогнозы погоды с фактическими weather_issued_at, weather_available_at, valid_time, моделью/продуктом, версией, высотой ветра и временным шагом. Доступность проверяется для конкретной ревизии на момент origin. Успешная загрузка файла этого не доказывает; реанализ и наблюдения не заменяют прогноз, доступный в прошлом.
3. Отдельная модель, обученная на подтверждённых данных Goldwind, и manifest с SHA-256, входной схемой, единицами, происхождением данных, границами fit/selection и их доступностью. Все использованные данные должны быть доступны не позже первого origin.

Интегрированные обучение и провайдер B используют скорость ветра, температуру, календарные признаки и явный ID турбины. Направление ветра не обязательно. Реализованы mean baseline и sklearn HistGradientBoosting, временная валидация, без февраля 2026 в подборе. Преобразования сохраняются внутри pipeline; провайдер возвращает raw кВт без clipping. Команды scripts/train_goldwind.py и scripts/evaluate_goldwind.py доступны; для полученного CSV нужен config/goldwind_hourly.template.json с подтверждёнными полями. Контракт и запуск B.

Модуль A предоставляет очистку истории и ECMWF Single Runs с кэшем: python scripts/prepare_data.py, python scripts/cache_weather.py --mode runs. Проверены 58 загрузок выпусков; их доступность на прошлый origin ещё требует доказательства. Контракт данных и погоды.

Переменная окружения	Назначение
FORECAST_DATA_MODULE	По умолчанию src.data.weather (A)
FORECAST_ML_MODULE	По умолчанию src.ml.goldwind_provider (B), raw кВт
FORECAST_MODEL_PATH	models/goldwind/power_model.joblib — целевой artifact пока отсутствует
FORECAST_MANIFEST_PATH	models/goldwind/forecast_manifest.json — создаётся с целевым artifact
FORECAST_PROTOCOL_PATH	config/forecast_protocol.json
FORECAST_CACHE_DIR	data/cache/forecast_v2
FORECAST_RESULTS_DIR	results/forecast_v2

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

FORECAST_ORIGIN=2026-01-31T23:00:00+05:00
python scripts/run_target_forecast.py --origin "$FORECAST_ORIGIN" --horizon 48 --output results/target.json
python scripts/run_target_forecast.py --origin "$FORECAST_ORIGIN" --horizon 24 --refresh

Результат хранит origin, время выпуска и доступности погоды, начало прогнозного часа, lead, версии входов, значения T1/T2 и сумму ВЭС. Raw-мощность сохраняется до физических проверок. Отрицательные значения и превышение номинала получают флаги. При отсутствии или невалидности одной турбины мощность/энергия станции — null; конечная raw-сумма сохраняется отдельно для метрик. Почасовая энергия равна средней мощности × 1 час.

--refresh проверяет допустимые обновления и создаёт новую версию результата при изменении входов. Более поздний выпуск не допускается в старый origin. Автономное расписание опроса внешних API пока не настроено. Точный контракт: TARGET_FORECAST_CONTRACT.md.

Февральский replay и оценка качества

MODE A: наблюдаемая погода → мощность. Оценивает зависимость мощности от погодных признаков.

MODE B: архивный прогноз погоды → мощность. Оценивает погоду и ML-модель как полную прогнозную систему. Метрики этих режимов не взаимозаменяемы.

После подключения целевых входов:

python scripts/replay_february.py --horizon 48 --output-dir results/february-48h
python scripts/replay_february.py --horizon 24 --output-dir results/february-24h
# Только при наличии реальных фактов организаторов:
python scripts/replay_february.py --horizon 48 --actuals data/actuals.csv --output-dir results/february-evaluated

Origins идут ежедневно с 31 января по 28 февраля 2026 включительно в часу подтверждённого протокола. Февральские метрики учитывают только интервалы с 1 февраля до 1 марта в том же timezone. Все origins и перекрывающиеся прогнозы сохраняются; лучший выпуск постфактум не выбирается.

Выход: predictions.csv, farm.csv, manifest.json с покрытием, версиями, хэшами и ошибками. Actuals CSV должен содержать timestamp,turbine_id,actual_power_kw: timestamp с timezone означает начало часа, мощность — средние raw кВт, ID — T1/T2. MAE/RMSE считаются по совпавшим конечным raw-парам с указанием покрытия.

Факты февраля нужны для метрик, но не для выпуска прогноза. Если это скрытая тестовая выборка организаторов, собственные февральские метрики остаются неизвестными (null). Пока отсутствуют обязательные входы, replay создаёт blocked manifest и CSV с заголовками; это не готовый прогноз. Реальный полный февральский запуск пока не подтверждён.

Kelmarsh: воспроизводимый пример на реальных данных

Шесть Senvion MM92 по 2050 кВт, исходный шаг 10 минут. Модель и holdout уже сохранены; переобучение и погодный API для примера не нужны.

python scripts/run_observed.py --date 2017-11-08 --turbine "Kelmarsh 1" --output results/observed.json
python scripts/run_observed_backtest.py --turbine "Kelmarsh 1"
python -m scripts.verify_ml_provider --report results/provider_verification.json

Доступные полные сутки holdout: 2017-11-08…2017-12-31. По всем 47 006 holdout-строкам сохранённый отчёт проверки воспроизводит raw MODE A:

MAE	RMSE	R²
82,9047 кВт	145,1903 кВт	0,953016

Метрики отдельного дня/турбины отличаются. Они не относятся к Goldwind и не подтверждают качество оперативного прогноза. Провайдер src.ml.provider принимает только Kelmarsh 1…6; T1/T2 не подменяются ими и не масштабируются молча.

Источник: Charlie Plumley, Roberta Takeuchi / Cubico Sustainable Investments Ltd, Kelmarsh SCADA, CC BY 4.0. Подготовка данных — data/README.md; модель и интерфейс — README_ML.md, ML_INFERENCE_CONTRACT.md.

CLI, API и объяснения

Автономное синтетическое демо из CLI:

python scripts/run_forecast.py --demo --date 2026-02-10 --turbine T1 --horizon 24 --output results/demo.json
python scripts/run_backtest.py --demo

Демо включается явно. Его T1/T2 используют один синтетический погодный ряд; пространственные различия не моделируются.

scripts/run_ui.py одновременно поднимает API. Основные маршруты:

Маршрут	Назначение
GET /health	Работоспособность API, не готовность целевого прогноза
GET /readiness	Блокеры и готовность конфигурации T1/T2
GET /dashboard/config	Конфигурация режимов веб-интерфейса
POST /target-forecast	Строгий прогноз T1/T2 на origin, 24/48 ч
POST /demo-forecast	Явное синтетическое демо для интерфейса
POST /observed	Kelmarsh по наблюдаемой погоде
POST /forecast	Сохранённый интерфейс совместимости/demo

Интерактивная схема запросов: http://127.0.0.1:8000/docs.

Ключ OpenAI для локальных расчётов и объяснений не требуется. Для опционального LLM-анализа задайте OPENAI_API_KEY и OPENAI_MODEL в окружении/.env, затем используйте --with-agent в поддерживающих его CLI. При недоступности API используется локальное объяснение. Реальный LLM-вызов без ключа не подтверждён; сценарии интеграции проверяются подставными ответами. Секреты не коммитятся.

FORECAST_* управляет целевым сценарием. DATA_MODULE, ML_MODULE, MODEL_PATH, DEMO_MODE относятся к сохранённому интерфейсу/demo — полный список находится в .env.example. Сервис рассчитан на локальную демонстрацию; публичная аутентификация и deployment не настроены.

Архитектура

Погода + происхождение/доступность
    → проверка на forecast_origin
    → признаки → локальная ML-модель → raw кВт
    → физические правила → статистика T1/T2 и ВЭС
    → локальное/LLM-объяснение → API / UI / CSV / JSON

Каталог	Ответственность
src/data/	История T1/T2, очистка, ECMWF Single Runs/кэш, признаки, demo и Kelmarsh
src/ml/	Обучение/оценка Goldwind, преобразования, raw-кВт провайдеры Goldwind и Kelmarsh
src/forecast/	Временные контракты, архивные выпуски, целевой orchestrator и replay
src/agent/	Физические правила, статистика, анализ и сценарии совместимости
src/api/	FastAPI и раздача интерфейса
src/app/web/	Основной WindAgent UI: HTML/CSS/JavaScript
src/app/streamlit_app.py	Сохранённый Streamlit UI
config/, data/, models/, reports/	Протоколы, исходные данные, artifacts и результаты проверки

Стек: Python, pandas, NumPy, scikit-learn, joblib, matplotlib, Pydantic, FastAPI, Streamlit; OpenAI SDK для опциональных объяснений. Численный прогноз работает локально без cloud ML services.

Проверки и документация

python -m pytest -q
node tests/test_dashboard_data.cjs
node tests/test_dashboard_state.cjs

Node.js нужен только для двух frontend-тестов. Проверки общего приложения выполняйте в окружении Linux/macOS/WSL с полными зависимостями.

Общая сборка проверена: 293 Python-теста passed, 1 skipped, две JavaScript-проверки, CLI и браузерное демо. Добавлена совместная проверка адаптеров A/B и orchestrator C на 24/48 часов с искусственными программными fixtures. Демо-backtest: по 29 дней, 696/696 часов для T1 и T2, без ошибок; это не измерение качества Goldwind. Строгий replay отдельно оценивает 672 часа февраля. Полный отчёт и сохранённые результаты.

Документ	Содержание
FINAL_UI.md	Интерфейс, режимы, запуск и проверка UI
TARGET_FORECAST_CONTRACT.md	Единицы, origin, выпуски погоды, manifest и replay
GOLDWIND_DELIVERY_REVIEW.md	Что установлено по полученным CSV и что требует ответа автора
TARGET_ACCEPTANCE.md	Проверки требований и текущие блокеры
README_ML.md	Существующий ML-слой и Kelmarsh
CONTRACTS.md	Контракты существующих DATA/ML-интерфейсов

Следующий шаг для целевого результата — получить описание CSV, доказать доступность исторических погодных версий, обучить Goldwind и выполнить реальный replay. Пороговые скорости 3/25 м/с пока являются настройками правил, а не подтверждёнными характеристиками GW109. Неопределённость прогноза, контекст ограничений генерации/ремонтов и автоматическое расписание опроса источников пока не реализованы. Флаги служат поводом для проверки и не являются диагнозом неисправности.