Vento — Agentic AI для двух турбин ВЭС

Почасовой прогноз нормализованной мощности на 24–48 часов: архив NOAA GFS → проверка доступности на момент запуска → подготовка реальной истории → эмпирическая кривая мощности → анализ OpenAI → обновление погоды и повторный расчёт при изменении входов.

В общей версии объединены Data Ильи, интерфейс Богдана (22Malish22) и backend с интеграцией Codex (сессия smmaff). Полный текст ТЗ и критерии оценки сохранены в docs/task-board.md. Архитектура: docs/architecture.md, интерфейсы: docs/api-contract.md.

Что работает

Температурная поправка доступна как опциональная надстройка через apply_temperature_correction: true в запросе /api/forecasts или /api/agent/forecasts, выключена по умолчанию и не меняет базовый расчёт по кривой ветер–мощность.

• История двух турбин за март 2023 — январь 2026: 291 859 исходных строк с контрольными суммами.
• 30 проверяемых погодных пакетов NOAA, включая 28 ежедневных запусков для покрытия февраля.
• API расчёта и агентного цикла; реальный OpenAI Responses API, без подстановки фиктивных ответов.
• UI: выбор даты/часа UTC, турбин, 24/48 часов; график, таблица, CSV, анализ и выполненные этапы.
• Февральский результат: 28 запусков по 48 часов, 2 688 точек; CSV первых суток каждого запуска содержит 1 344 строки, по 672 уникальных часа на турбину.

Запуск из чистого клона

Нужны Git, Python 3.11+ (проверено на 3.13), Node.js 22+. UI не требует npm install.

git clone https://github.com/BAITC-Hacks/hack-8df1dc64-inc.git
cd hack-8df1dc64-inc
python -m venv .venv

Активировать окружение:

# Linux/macOS
source .venv/bin/activate
# Windows PowerShell вместо строки выше
.\.venv\Scripts\Activate.ps1

python -m pip install -r data/requirements.txt

Куда проверяющему вставить ключ OpenAI

В корне репозитория (рядом с этим README.md) создайте локальный файл .env из шаблона .env.example, если файла ещё нет:

# Linux/macOS
cp .env.example .env
# Windows PowerShell: вместо команды выше
Copy-Item .env.example .env

Откройте .env и вставьте свой ключ в строку OPENAI_API_KEY после знака =:

OPENAI_API_KEY=ваш_ключ_OpenAI
OPENAI_MODEL=gpt-4o-mini

Не перезаписывайте существующий .env. OPENAI_MODEL можно изменить, если у ключа есть доступ к другой модели OpenAI. Сохраните файл и запустите backend по инструкции ниже; если сервер уже работает, перезапустите его. Для Docker Compose используется тот же .env. Ключ остаётся на backend: не вставляйте его в UI, код или Git.

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

Первый терминал, из корня репозитория:

python -m backend.server

Второй терминал, из того же корня:

node ui/server.mjs

Открыть http://127.0.0.1:3000. Backend: http://127.0.0.1:8000/api/health. Остановить процессы: Ctrl+C. Серверы предназначены для локального демо.

Сценарий проверки

1. Оставить 31 января 2026, 19:00 UTC, 24 часа, две турбины и явное допущение end.
2. Нажать «Сформировать прогноз». Ожидаются 48 точек, график, таблица, реальный анализ OpenAI и длительности этапов. Первый расчёт истории может занять 10–20 секунд.
3. Выбрать 14 февраля, 19:00 UTC, 48 часов и турбину 2: ожидаются 48 точек другого запуска.
4. «Обновить погоду и пересчитать» повторно загружает NOAA. Это может занять несколько минут. Неизменившийся архив может дать тот же прогноз: это нормальный результат проверки обновлений.
5. Скачать CSV и проверить поля времени, нормализованной мощности, ветра и температуры.

Без ключа остаются доступны численный /api/forecasts, пакетный расчёт и автоматические тесты. Агентный endpoint честно возвращает ошибку настройки, а не имитацию анализа.

Проверки

Финальная объединённая версия проверена из чистого клона с новым Python-окружением: 80 backend + 41 data + 30 UI тестов, два реальных HTTP-запроса с OpenAI (второй с новой загрузкой NOAA) и полный повтор февраля с побайтово одинаковым CSV; подробности — отчёт интеграции.

python -m unittest discover -s backend/tests -t . -v
python -m unittest discover -s data/tests -v
node --test ui/tests/*.test.mjs

Эквивалентные Linux/Git Bash команды: ./backend/test.sh, ./data/test.sh, ./ui/test.sh. Реальная проверка UI-клиента через HTTP при работающем backend (выполняет платные вызовы OpenAI):

node ui/smoke-api.mjs http://127.0.0.1:8000

Для проверки повторной загрузки NOAA установить LIVE_REFRESH=1 перед этой командой. Внешние API изолируются только в unit-тестах; этот smoke-сценарий использует настоящие сервисы.

Повторить февраль без OpenAI

python -m backend.batch_forecast --output-dir backend/runtime/february-recheck --timestamp-role end

Каталог результата должен быть новым. Сохраняются 28 JSON, february.csv и summary.json. Используются реальные архивы; февральских фактических мощностей нет, поэтому результат не содержит метрик точности февраля. Это численный пакетный режим, агентный анализ доступен отдельно через UI/API.

Docker Compose

Подготовлены два контейнера и общий запуск:

docker compose up --build

Предварительно заполнить локальный .env. UI: http://127.0.0.1:3000. Остановка: docker compose down. Погодный кэш хранится в именованном томе; .env исключён из контекста сборки и ключ передаётся только backend. Сборка и запуск контейнеров ещё не проверены: на рабочей машине отсутствует Docker Engine. Нативный запуск описан выше.

Настройки

Переменная	Значение по умолчанию / назначение
OPENAI_API_KEY	Требуется для реального анализа OpenAI
OPENAI_MODEL	gpt-4o-mini
WEATHER_ARCHIVE_DIR	data/weather
WEATHER_CACHE_DIR	backend/runtime/weather
UI_ORIGINS	http://127.0.0.1:3000,http://localhost:3000
PORT, HOST	UI: 3000, 127.0.0.1; задаются в окружении Node

Стек: Python stdlib HTTP/JSON, ecCodes 2.48.0 для GRIB, JavaScript ES modules/Node static server, OpenAI Responses API, NOAA GFS public S3. Постоянное хранение — исходные gzip, JSON с provenance и CSV; отдельный сервер БД не нужен.

Известные ограничения

• Смысл временной метки в исходных данных выбран как допущение, не подтверждён организатором.

• Высота исторического измерения ветра неизвестна, поправка высоты не применена.

• Время публикации телеметрии неизвестно, используется допущение "конец интервала".

• Часть скоростей ветра в прогнозе выходит за диапазон исторической кривой обучения, используется ближайшее крайнее значение (экстраполяция).

• Прогнозируется нормализованная мощность 0–1; без номинальной мощности нет честного перевода в кВт/кВт·ч.

• Роль метки 10-минутного интервала пока не подтверждена организатором. end — рабочее допущение; ответ всегда содержит timestamp_role_confirmed=false.

• Архив GFS имеет сетку 0.5°, поэтому близкие турбины получают одинаковую погоду. Историческая высота анемометра неизвестна, поправка высоты не применяется.

• Историческая доступность погоды проверяется по выпуску и Last-Modified конкретных объектов S3. Это доказательство времени текущей версии объекта, не журнал фактических запросов в прошлом.

• Baseline — эмпирическая кривая ветер–мощность, без обучения сложной ML-модели. Январские проверки Data показывают MAE около 0.267–0.388 в нормализованной шкале; это ограниченная проверка, не оценка февраля. Подробнее: Data handoff.

• Февральская фактическая мощность отсутствует. Тесты совместимости не доказывают точность прогнозирования.

• Автоматические проверки DOM/HTTP не заменяют визуальную приёмку в браузере; она ещё требуется.

Проверка малых скоростей: распределение истории и отклик модели. Около 13,4% обучающих часов имеют ветер ≤2 м/с; низкие значения мощности согласуются с историей.

Доступ для экспертов и вклад

История, погодные пакеты, provenance и февральский расчёт доступны без аккаунта. Для live-анализа команда должна передать экспертам тестовый ключ отдельным закрытым каналом либо показать запущенный локальный стенд с настроенным ключом. Общедоступный стенд пока не опубликован; секретов в репозитории нет.

Шаблоны инструкций и .claude/ подготовлены заранее. Код Data, backend и UI создан во время работы над кейсом при помощи Codex; история и объяснение изменений — docs/progress.md. Исходный шаблон README и план сохранены в docs/archive. Все изменения ведутся в репозитории организатора.