«Аким на 5 часов» — AI-симулятор управления городом

HackAlem AI · Astana Innovations Special Track · команда AI4EDU

Бюджет 100, 5 районов Астаны, 14 мер и ровно 5 решений. Пользователь задаёт цель обычным языком или вручную выбирает мероприятия. Четыре AI-роли — мастер, независимый аудитор цели, планировщик и рецензент — готовят и проверяют план. Детерминированный Go-движок рассчитывает Astana Quality of Life Score, расходы и последствия для районов.

Данные синтетические; Score измеряется в баллах модели, не в процентах. Реальных действий в городе приложение не выполняет.

Проблема и решение

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

1. Проверка сценария: бюджет, ровно 5 уникальных решений, не больше 2 мер одного направления, районные и городские меры, несовместимости.
2. Расчёт: эффекты с учётом лага (8 − L) / 8, синергии, ограничение [0, 100], районные Score, итог 0.7 × среднее по населению + 0.3 × худший район − критические.
3. AI-объяснение: сильные стороны, риски и компромиссы на русском языке.
4. Лучший план: точный оптимум полным перебором всех 694 395 допустимых сценариев.

AI-автопилот и проверка чисел

Цель пользователя → мастер + независимый аудитор → согласованные ограничения
                  → полный поиск Go → планировщик → рецензент → готовый план
                                             ↑       │
                           исправления цели/объяснения

Аудитор получает только исходную цель и сценарий, без выводов мастера. Разногласие возвращается мастеру; ошибка объяснения — планировщику. Явные численные ограничения бюджета дополнительно проверяет код. Пользователю не нужно выбирать пять решений. Результат, ход работы, оценка расходов и история доступны в AI-автопилоте.

Go проверяет числа и допустимость, а полный поиск подтверждает оптимум для формализованной цели. LLM может ошибаться даже после рецензии: действия и числа нужно сверять с результатом Go. Без ключа доступны ручной расчёт и шаблонное объяснение; автопилот отключён. Прежний /api/advise также сохранён. Подробные протоколы, ограничения и реальные проверки: docs/autopilot.md.

Результаты

Сценарий	Стоимость	Score	Критических
Ничего не делать (база)	0	52.558	2
Всё вложить в богатый Есиль	93	53.577	2
Полезная мера в неудачном месте (M11 в Алматы)	93	55.144	1
Сбалансированный golden: M7, M8, M10 → Нура; M12 город; M5 → Сарыарка	95	56.543	0
Лучший план: M2, M14 город; M3, M8, M9 → Нура	98	57.237	0

Потолок текущей фиксированной модели — 57.236735 балла при максимизации городского Score и бюджете 100. Он не означает «57% качества»: нельзя честно обещать более высокий Score без изменения данных, мер или формулы.

Все числа таблицы независимо пересчитывает make verify (scripts/verify_scores.py): вторая реализация формулы на Python в точных дробях, без общего кода с Go-движком, плюс полный перебор для проверки оптимума.

Вклад в один район почти не повышает Score: 30% веса у худшего района и штраф за каждый показатель ниже 40 не дают «забыть» Нуру. Сценарий показа с командами: docs/demo.md.

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

• docs/task.md — постановка задачи
• docs/scoring.md — данные, меры и формула Score
• docs/api.md — контракт HTTP API
• docs/autopilot.md — четыре роли, ограничения, стоимость и проверки
• docs/ai-integration.md — прежний советник и опциональная NVIDIA
• docs/demo.md — сценарий показа для жюри
• web/README.md — фронтенд

Быстрый запуск

docker compose up --build

Открыть http://localhost:8080 — сайт и API на одном адресе. Время сборки и фонового поиска зависит от компьютера; до готовности поиска API возвращает 503 not_ready. Для AI задайте OPENAI_API_KEY в серверном .env. Создавайте .env из .env.example только если файла ещё нет; существующие ключи не перезаписывайте. Без ключа работает шаблонное объяснение. NVIDIA для автопилота не нужна.

Для разработки: Go 1.22+, Make, Node.js 22.22.2+ или 24.15+, npm. Запустите make run; во втором терминале — cd web, npm ci, npm run dev. make run загружает .env; прямой go run читает только окружение процесса.

Демо для жюри

1. Запустить проект с OpenAI-ключом и открыть AI-автопилот. Ввести: «Максимизируй городской Score при бюджете 100, устрани все критические показатели». Показать четыре роли, результат 57.236735 / стоимость 98 / критических 0 и историю. Следующие шаги показывают ручной сценарий и детерминированный резерв.
2. Открыть http://localhost:8080: исходные показатели районов, в Нуре два критических значения (S1, S2 < 40). Базовый Score 52.56 виден на экране результата как «До».
3. «Составить план» → добавить M7, M8, M10 → Нура, M12 (город), M5 → Сарыарка → «Рассчитать результат»: Score 56.54, стоимость 95, критических 0, сработала синергия M10 + M12, объяснение с меткой AI или шаблона.
4. «Лучший план по модели»: точный оптимум 57.24 (M2, M14; M3, M8, M9 → Нура). Пока фоновый поиск не завершён, интерфейс показывает «Считается…».
5. Попробовать нарушить правила (M1 + M3, третью меру соцсферы, перерасход бюджета): Score не выдаётся, показывается причина.

Те же шаги через curl и дополнительные сценарии: docs/demo.md.

Проверка

make check                      # Go: формат, vet, тесты, race
make verify                     # независимый пересчёт на Python + полный перебор
cd web && npm ci && npm test     # тесты фронтенда

Архитектура

• internal/simulation — данные, валидация и детерминированный расчёт Score.
• internal/explanation — AI-объяснение результата и шаблонный fallback.
• internal/autopilot — четыре роли, аудит цели, цикл исправлений, бюджет и фоновые задачи.
• internal/advisor — прежний OpenAI-советник с инструментом симуляции.
• internal/httpapi — HTTP API расчёта, объяснения и рекомендаций.
• internal/optimizer — полный перебор сценариев через simulation.Simulate.
• internal/httpapi/web.go — раздача собранного сайта рядом с API.
• web/ — React + TypeScript + Vite; числа получает от API.
• cmd/server — запуск сервера и настройка из переменных окружения.

Настройки

Переменная	По умолчанию	Назначение
ADDR	:8080	Адрес Go API
OPENAI_API_KEY	пусто	Ключ для живого AI
OPENAI_MODEL	gpt-4.1-mini	Модель объяснения и резервная модель ролей
OPENAI_MASTER_MODEL, OPENAI_AUDITOR_MODEL, OPENAI_PLANNER_MODEL, OPENAI_REVIEWER_MODEL	через OPENAI_AGENT_MODEL / OPENAI_MODEL	Индивидуальные модели ролей
AUTOPILOT_RUN_BUDGET_USD	0.10	Оценочный лимит одного запуска
AUTOPILOT_TOTAL_BUDGET_USD	50	Общий лимит локального учёта автопилота
AUTOPILOT_MAX_ITERATIONS	3	Общий лимит итераций, допустимо 1–5
AUTOPILOT_BUDGET_FILE	.autopilot/usage.json	Постоянный журнал расходов
CORS_ORIGIN	пусто	Разрешённый origin отдельного фронтенда
WEB_DIR	пусто; /web в Docker	Каталог собранного сайта
HOST_PORT	8080	Внешний порт Docker

По умолчанию: до двух одновременных запусков и 180 секунд на задачу. Четыре вызова в обычном успешном цикле; до 12 при трёх итерациях, до 20 при пяти. Повторная формализация не сбрасывает время, итерации и бюджет. Журнал расходов сохраняется между перезапусками, в Docker — в томе autopilot-state. Это локальный лимит автопилота, не баланс OpenAI; другие API-вызовы он не учитывает. Неизвестные модели требуют явных тарифов в переменных из .env.example.

API-ключи хранятся только на сервере. Пользовательская аутентификация не реализована; для публичного доступа нужен внешний контроль доступа к платным маршрутам. Результаты задач хранятся в RAM, история интерфейса — в браузере. Текущие правила допускают несколько мер одного направления, поэтому пять решений не гарантируют охвата всех пяти направлений; это ограничение описано в задании и модели.

Разработка

make web-install — установить зависимости фронтенда; make run — запустить Go API на :8080. make web-dev — сайт на http://127.0.0.1:5173 с прокси /api (в другом терминале). make help — все цели.