Аким на 5 часов

AI-симулятор управления городом для кейса HackAlem AI: бюджет, пять решений по районам Астаны, Astana Quality of Life Score и консилиум AI-агентов, который объясняет результат и выносит резолюцию.

Как играть за минуту. Вы аким. У вас 100 условных единиц и 14 мер по пяти направлениям. Выбираете ровно пять, движок сразу показывает Score, консилиум объясняет и выносит резолюцию.

Словарь. Score — Astana Quality of Life Score по формуле кейса, 0–100. Консилиум — цепочка AI-агентов: шесть экспертов по направлениям, синтезатор заключения, ревизоры и арбитр. Ревизоры — шесть проверок заключения (C1–C6), первые две делает код: числа в тексте совпадают с расчётом, рекомендация валидна. Арбитр — итоговая резолюция: утвердить, утвердить с условиями, вернуть. Фолбэк — режим без ключа OpenAI, тексты из заготовки, числа те же.

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

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

Для кого. Городской управленец, аналитик или пользователь симулятора (формулировка кейса), а также студенты и участники деловых игр, которым нужно быстро прогнать сценарий, увидеть его цену и услышать аргументы «за» и «против».

Принцип. Код считает, LLM говорит. Валидация, Score, дельты по районам, поиск улучшений и исход резолюции считаются детерминированно. Языковая модель получает пронумерованные факты и объясняет их, спорит и пишет резолюцию. Ни одно число не приходит из модели, и это проверяется кодом. Так требует сам кейс, раздел «Роль ИИ» датасета: «LLM получает результат расчёта (дельты по районам и показателям, вклад каждой меры) и объясняет его, сравнивает наборы, советует. Числа он не считает и не придумывает».

Соответствие кейсу

Must have из задания:

Требование кейса	Как закрыто
Единый виртуальный бюджет для всех пользователей	100 у.е. и одинаковые исходные данные для всех команд, константы в src/lib/types.ts и src/lib/data/
Решения по 5 направлениям: транспорт, озеленение, социальная инфраструктура, безопасность, городской сервис	каталог из 14 мер датасета, сгруппированный по пяти направлениям; ровно 5 решений, не больше 2 на направление
Автоматический контроль превышения бюджета	валидатор блокирует отправку набора дороже 100 у.е., полоса бюджета краснеет и показывает перерасход
AI-анализ принятых решений	консилиум: 6 экспертов, синтезатор, ревизоры, арбитр (OpenAI API)
Расчёт итогового Astana Quality of Life Score	детерминированный движок по формуле датасета, живой пересчёт в кабинете
Объяснение сильных сторон, рисков и возможных последствий	черновик заключения с разделами «сильные стороны / риски / последствия» и резолюция арбитра

Опционально:

Опция кейса	Статус
Сравнение результатов нескольких команд	есть: лидерборд /leaderboard по сохранённым прогонам
Визуализация изменений показателей районов	есть: схема районов Астаны с цветом по оценке района, радар «до / после», таблица показателей со стрелками
AI-рекомендации по улучшению сценария	есть: улучшения считает оптимизатор, арбитр оформляет их в поручения, блок «Что сделать дальше» с кнопкой «Применить»
Неожиданные городские события	есть: после вердикта событие бьёт по показателю района, Score пересчитывается тем же набором, предлагается лучшая замена и кнопка «Перераспределить бюджет»
Генерация краткой презентации решения	есть: «Скачать краткую презентацию (.md)» на странице вердикта

Критерии проверки из кейса и где их увидеть:

1. Одинаковый бюджет и исходные данные: брифинг / показывает базу 52.56 и бюджет 100 для любой команды.
2. Бюджет нельзя превысить: в /play набор дороже 100 у.е. не отправляется, причина названа (п. 7 ниже).
3. Решения влияют на показатели: вердикт показывает изменения каждого показателя по районам и вклад каждой меры.
4. Понятное объяснение и компромиссы: зал заседаний (эксперты, споры, резолюция с обоснованием).
5. Другой набор даёт другой Score: замена одной меры в кабинете сразу меняет Score (п. 7 ниже).

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

• Единый бюджет 100 и синтетический датасет организаторов: 5 районов, 10 показателей, 14 мер с ценой, лагом и эффектами, 3 синергии, 3 несовместимости.
• Валидатор восьми правил кейса, возвращает все нарушения списком: ровно 5 решений, бюджет, повторы, район для локальных мер, не более 2 мер на направление, конфликты.
• Движок Score по формуле датасета: лаг, синергии, обрезка 0..100, веса, штраф за критические значения. Золотой тест воспроизводит базу 52.56 и пример организаторов 56.54.
• Факты с ID (F1…Fn): каждое изменение показателя, вклад каждой меры, слабейший район, критические значения, остаток бюджета.
• Оптимизатор: полный перебор всех 694 395 валидных наборов за ~0.4 с с кэшем на диске. Даёт глобальный оптимум (57.24), перцентиль набора среди всех валидных и до трёх улучшений заменой одной меры.
• Консилиум из восьми стадий: 6 экспертов (транспорт, экология, соцсфера, безопасность, сервисы, финансы) параллельно → синтезатор → ревизоры (6 условий, порог 5 из 6, до 2 кругов пересмотра) → арбитр с резолюцией «утвердить / утвердить с условиями / вернуть».
• Стриминг прогресса по SSE, сохранение прогона в JSON, страница результата открывается по ссылке.
• Режим без ключа OpenAI: движок и оптимизатор работают, консилиум отвечает детерминированным фолбэком с пометкой.
• Внезапное городское событие после вердикта: шок по показателю района (авария теплосетей, смог, паводок и др.), пересчёт Score и предложение перераспределить одну меру.
• Экспорт краткой презентации решения команды в markdown одной кнопкой.
• Таймлайн 8 кварталов на вердикте: ползунок показывает, как растут показатели и Score по мере срабатывания лагов (линия ЛРТ с лагом 4 ничего не даёт до пятого квартала). Считается той же моделью, на 8-м квартале совпадает с итогом.
• Разрыв с оптимумом: под Score видно лучший возможный набор, на сколько он выше и какими заменами отличается, кнопка «Открыть оптимум».
• Песочница: импорт своего датасета в формате кейса на странице /sandbox. Шаблон public/dataset-hackalem.json это данные кейса; можно поменять показатели и доли районов, цены, лаги и эффекты мер, веса, синергии и конфликты. Файл проверяется схемой (значения 0–100, сумма весов и долей населения 1, все 5 районов и 14 мер). Весь конвейер, включая полный перебор и консилиум, работает на загруженных данных. Прогоны песочницы помечены и не попадают в лидерборд, поэтому соревнование остаётся на одинаковых данных для всех команд.
• Озвучка резолюции: кнопка «Озвучить резолюцию» читает постановление арбитра голосом (OpenAI TTS, gpt-4o-mini-tts), аудио кэшируется на прогон.
• Интерфейс: брифинг со схемой районов, кабинет решений с живым Score, экран заседания со стадиями по мере готовности, вердикт с залом заседаний, лидерборд команд.

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

1. Брифинг (/): 3D-модель Байтерека, схема районов Астаны с цветом по оценке района, пять карточек районов, базовый Score 52.56, два критических провала Нуры (школы 38, поликлиники 35). Команда вводит название.
2. Кабинет решений (/play): каталог мер по пяти направлениям, выбор района, бюджетная полоса, лимиты по направлениям, живой Score прямо в браузере тем же движком. Невалидный набор блокирует отправку и называет причины.
3. Заседание (/result/live): восемь стадий пайплайна отмечаются построчно по мере событий SSE, карточки экспертов, ревизия и резолюция появляются по ходу. По событию done открывается вердикт.
4. Вердикт (/result/[runId]): Score и дельта, перцентиль, схема районов и радар района до и после, таблица показателей, блок «Как считалось» с формулой, консилиум: эксперты, «Ревизия: N из 6 условий», «Черновики заключения» (отклонённые фразы подсвечены), резолюция и «Споры и поручения арбитра». Блок «Что сделать дальше» с кнопкой «Применить» подставляет улучшение в кабинет для нового прогона. Ниже карточка внезапного события и ссылка на презентацию.
5. Лидерборд (/leaderboard): все сохранённые прогоны на данных кейса, выше тот, чей набор дал больший Score.
6. Песочница (/sandbox): скачать шаблон, изменить данные, загрузить файл, посмотреть превью районов и базового Score, играть на своих данных. Плашка «Песочница» видна в кабинете и на вердикте.

Брифинг	Кабинет решений	Вердикт

Полная страница вердикта с залом заседаний: docs/screenshots/verdict-full.png.

Сценарий → Валидатор → Движок + Факты → Оптимизатор
        → 6 экспертов (LLM, параллельно) → Синтезатор (LLM)
        → Ревизоры: C1, C2 код · C3–C6 LLM ──┐ провал, круг ≤ 2
                 ↑___________________________│
        → Таблица исходов (код) → Арбитр (LLM) → Запись прогона → SSE done

4. Технологии

• Next.js 16.3 (App Router, route handlers, SSE), React 19.2, TypeScript 5
• Tailwind 4 + shadcn/ui, Recharts 3, lucide-react, three.js (3D-Байтерек на главной, грузится лениво только на /)
• Vercel AI SDK 7 + @ai-sdk/openai 4, structured outputs через zod 4 (strict JSON schema)
• OpenAI API через OPENAI_EXPERT_MODEL и OPENAI_JUDGE_MODEL: по умолчанию gpt-5-mini и gpt-5; прогоны и числа в этом README сделаны на gpt-5.4-mini (эксперты) и gpt-5.5 (синтезатор, ревизоры, арбитр)
• Vitest 5, Docker (standalone-сборка Next)

5. Архитектура

src/lib/data/        датасет как константы (районы, меры, веса, синергии, конфликты)
src/lib/engine/      validator, engine (Score), facts (факты с ID), optimizer — чистые функции
src/lib/consilium/   llm (единая точка вызовов), experts, synthesizer, reviewers, arbiter, pipeline
src/lib/store/       прогоны в JSON: data/runs/<id>.json
src/app/api/run      POST → поток событий ConsiliumEvent (SSE)
src/app/api/runs     GET список, GET по id, GET /event (событие), GET /pitch (презентация .md), GET /voice (озвучка .mp3)
src/app/             брифинг, кабинет, заседание, вердикт, лидерборд
src/components/      экраны UI: briefing, play, live, result, consilium, map, leaderboard, landing (3D-Байтерек), shell, ui
src/lib/ui/          форматтеры, разбор SSE, сборка прогона из событий
src/lib/types.ts     контракт между UI и бэком
fixtures/            полный образец прогона для разработки UI

Что	Кто делает	Почему
Валидация, Score, дельты, вклад мер	код	воспроизводимость, критерии 2, 3, 5 кейса
Поиск улучшений, глобальный оптимум, перцентиль	код, полный перебор	694 395 наборов за 0.4 с, детерминированно и воспроизводимо
Мнения экспертов, черновик, споры, резолюция	LLM	нужен язык, а не арифметика
Проверка чисел в тексте (C1), валидность рекомендации (C2)	код	LLM не проверяет сам себя там, где может код
Полнота и честность текста (C3–C6)	LLM-ревизор	условия, а не «оценка уверенности»
Исход резолюции	код, таблица условий	один ответ на вопрос «почему утвердили»

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

git clone https://github.com/BAITC-Hacks/hack-4fbaf6fd-hahatun.git
cd hack-4fbaf6fd-hahatun
yarn install
cp .env.example .env        # вписать OPENAI_API_KEY, без него работает фолбэк
yarn dev                    # http://localhost:3000

Docker:

cp .env.example .env
docker compose up --build   # http://localhost:3000, прогоны в volume runs

Проверки: yarn test (движок, валидатор, ревизоры, пайплайн), yarn typecheck, yarn lint. Приёмка в браузере: npx playwright install chromium один раз, затем yarn test:e2e при запущенном yarn dev (брифинг → кабинет → консилиум → вердикт → лидерборд → презентация → событие, 5 тестов, около минуты с ключом).

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

Через интерфейс

1. Открыть /play, собрать пример организаторов: M7 Нура, M8 Нура, M10 Нура, M12, M5 Сарыарка. Стоимость 95, живой Score показывает 56.54 (в документе кейса ≈ 56.5). Тот же набор открывается ссылкой /play?s=M7.nura,M8.nura,M10.nura,M12,M5.saryarka.
2. Заменить M5 на M3 (ЛРТ) в Нуре: Score меняется на 57.21. Убрать одну меру: кнопка «На консилиум» блокируется, панель набора показывает «4 из 5» и причину «Нужно ровно 5 решений, сейчас 4». Выбрать вместе M1 и M3: причина «„Выделенные полосы для автобусов“ и „Линия ЛРТ / расширение“ несовместимы» (в кабинете меры названы по имени, коды остаются в API и презентации).
3. Превысить бюджет: в примере заменить M12 на M3 в Нуре (/play?s=M7.nura,M8.nura,M10.nura,M3.nura,M5.saryarka). Стоимость 111, полоса бюджета красная с подписью «перерасход на 11 у.е.», причина «Бюджет 100 превышен: стоимость набора 111», отправка заблокирована.
4. Нажать «На консилиум». На экране заседания стадии отмечаются по мере готовности, затем на вердикте появляются шесть экспертов, черновик, ревизия и резолюция. С ключом прогон занимает 30–60 секунд и стоит около 4 центов; без ключа около секунды, тексты помечены как фолбэк.

Через API

Сервер на 3000:

curl -N -X POST http://localhost:3000/api/run -H 'Content-Type: application/json' \
  -d '{"teamName":"Демо","scenario":{"decisions":[{"measureId":"M7","districtId":"nura"},{"measureId":"M8","districtId":"nura"},{"measureId":"M10","districtId":"nura"},{"measureId":"M12"},{"measureId":"M5","districtId":"saryarka"}]}}'

Ожидаемый поток: stage validate/engine/optimize, событие engine со score: 56.54 и 32 фактами, optimizer с улучшением «M5 Сарыарка → M3 Линия ЛРТ, Нура, 57.21», шесть событий expert, draft, review (с ключом обычно 6 из 6), resolution с исходом approve и поручением, done с runId. Затем GET /api/runs/<runId> возвращает сохранённый прогон, GET /api/runs/<runId>/event — внезапное событие с пересчётом, GET /api/runs/<runId>/pitch — презентацию в markdown. Реальный прогон с LLM сохранён как образец в fixtures/live-run.json.

Три сида с ожидаемыми результатами

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

Набор	Стоимость	Score	Крит. значений	Исход арбитра
M7 Нура, M8 Нура, M10 Нура, M12, M5 Сарыарка (пример кейса)	95	56.54	0	утвердить
M2, M3 Нура, M8 Нура, M9 Нура, M14 (глобальный оптимум)	98	57.24	0	утвердить, перцентиль 100%
M9 Нура, M11 Есиль, M10 Нура, M12, M4 Сарыарка (самый дешёвый)	61	55.17	1 (Нура S2)	утвердить с условиями, поручение заменить меру на M8 Нура

Тесты: yarn test — 141 тест, среди них золотой тест формулы (база 52.56, пример 56.54, синергия M10+M12), валидатор по каждому правилу, проверка чисел ревизора C1, цикл пересмотра с cap 2, хранилище с защитой от path traversal.

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

• Синтетический датасет организаторов (docs/source/dataset.md), перенесён в код без изменений. Персональных данных нет.
• OpenAI API через Vercel AI SDK. Ключ только в .env, в репозитории его нет.
• Внешних БД и сервисов нет, прогоны хранятся файлами.
• Защита командного ключа от расхода: не более 3 одновременных прогонов и пауза 5 секунд между запусками с одного адреса (429), тело запроса ограничено, порт в Docker слушает только localhost. Секреты только в .env, yarn audit без уязвимостей.

9. Ограничения

• Кэш перебора data/optimum.json (5.5 МБ) создаётся при первом прогоне, это добавляет около секунды к первому запросу.
• Ревизия ограничена двумя кругами, после них результат отдаётся с бейджем «проверено N из 6».
• Один город, один датасет, без авторизации и мультиплеера. Лидерборд показывает прогоны, сохранённые на этом сервере.
• Мобильная вёрстка не приоритет, целевой экран от 1024px.

10. Потенциал развития

• Реальные данные районов и открытые источники акимата вместо синтетики.
• Замена LLM-ревизоров быстрым классификатором (например, Laya на ModernBERT) после накопления размеченных вердиктов.
• Импорт реальных данных акимата через песочницу с расширением схемы: новые меры и районы, а не только изменение значений.
• Каталог событий шире шести штук и события в середине горизонта, а не после вердикта; экспорт презентации в PDF/PPTX.
• Вход по ЭЦП через NCA Node для внедрения в акимате.

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

Пока нет, запуск локально или через Docker.

Команда

• Амир Бауржанов — движок Score и полный перебор, консилиум (эксперты, синтезатор, ревизоры, арбитр), SSE API и хранилище, события и экспорт презентации, README, ревью и приёмка.
• Мирас Есеналы — дизайн-система и оформление в стиле бланка акимата (DESIGN.md), 3D-Байтерек на three.js, брифинг со схемой районов, кабинет решений с живым Score, экран заседания и вердикт с консилиумом, лидерборд, клиент SSE и тесты UI-логики.