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

Спец-трек Astana Innovations, HackAlem AI 2026. Команда: Commit and Pray.

Основной код и финальная версия — в ветке main. Промежуточные почасовые снапшоты доступны в ветках codex/frontend-and-features (~14:55) и codex/design-mobile (~16:43) — параллельная работа над UI/AI-фичами, позже слитая в main.

1. Описание

Городской бюджет (100 условных единиц) нужно разложить по 5 направлениям — транспорт, экология, соцсфера, безопасность, сервисы — с учётом того, что ресурсы ограничены и эффект от мер проявляется не сразу. Игрок выбирает ровно 5 мероприятий из каталога (14 шт.), распределяя их по 5 условным районам Астаны, и получает итоговый Astana Quality of Life Score с объяснением от «Аким-AI»: что получилось хорошо, какие риски и компромиссы остались.

Данные и формула — из официального ТЗ и датасета районов, предоставленных организаторами (владелец задачи: Astana Innovations).

Методология

Ядро — детерминированная численная модель городских показателей (10 индикаторов × 5 районов), построенная по логике городских цифровых двойников (в духе UrbanSim, в упрощённом виде): каждое управленческое решение имеет заданный лаг внедрения, каскадно затрагивает несколько показателей одновременно (например, перевод района на чистое топливо снижает не только загрязнение воздуха, но и нагрузку на теплосети) и может усиливаться синергией с другими мерами или штрафоваться за критически низкие показатели в отстающих районах. LLM в этой модели — слой интерпретации и рекомендаций поверх честного расчёта, а не источник чисел: это осознанный баланс между «игровым» интерактивным опытом и воспроизводимой аналитикой.

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

Подробная схема, формула Score и роль LLM — в docs/architecture.md.

Frontend (React + Vite + Tailwind)  ⇄  Backend (FastAPI)  ⇄  LLM (опционально)
  /api/districts, /api/measures, /api/preview, /api/simulate, /api/recommend

• /api/preview — мгновенный пересчёт тем же движком для неполного набора мер (без LLM): при наведении на меру карточка её района показывает «до/после» — дельты показателей, изменение балла района, пунктирный контур на радаре.

• /api/simulate — финальный расчёт набора из 5 мер с полной валидацией правил и объяснением «Аким-AI».

• /api/recommend — альтернативные сценарии (что-если анализ).

• backend/app/simulation/data.py — официальный датасет районов и каталог мероприятий.

• backend/app/simulation/validator.py — проверка правил набора решений.

• backend/app/simulation/scoring.py — детерминированный расчёт Score (каскад эффектов по показателям/районам).

• backend/app/simulation/recommendations.py — генерация альтернативных сценариев (что-если анализ), каждый честно пересчитан через compute_score().

• backend/app/simulation/narrative.py — LLM-объяснение готового результата.

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

Слой	Технологии
Backend	Python 3.12+, FastAPI, Pydantic, Uvicorn, pytest
Frontend	React 19, TypeScript, Vite, TailwindCSS v4, Recharts, Framer Motion
AI	OpenAI API — LLM-объяснение уже посчитанного результата (не сам расчёт)
Хранилище	Не используется — расчёт полностью детерминирован (см. раздел «Методология») и не требует базы данных или персистентного состояния между запросами
Деплой	Docker Compose (backend + nginx-frontend), либо локальный запуск

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

Вариант A — Docker Compose (рекомендуется для проверки)

cp .env.example .env
docker compose up --build

• Frontend: http://localhost:8080
• Backend API: http://localhost:8000/api

Вариант B — локально, без Docker

Backend:

cd backend
python -m venv .venv
.venv/Scripts/activate      # Windows; на Linux/Mac: source .venv/bin/activate
pip install -r requirements.txt
cp ../.env.example ../.env
uvicorn app.main:app --reload --port 8000

Frontend (в отдельном терминале):

cd frontend
npm install
npm run dev

Frontend откроется на http://localhost:5173 и проксирует /api на http://localhost:8000 (настроено в vite.config.ts).

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

См. .env.example. Ключевые:

Переменная	Назначение	Обязательна?
LLM_API_KEY	Ключ LLM для генерации объяснений	Нет — без ключа работает детерминированный fallback-текст, демо не ломается
LLM_BASE_URL	Эндпоинт LLM (любой OpenAI-совместимый провайдер)	Нет, есть значение по умолчанию
LLM_MODEL	Название модели	Нет
CORS_ORIGINS	Разрешённые origin для backend	Нет, по умолчанию http://localhost:5173

6. Автономность запуска и тестовые доступы

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

• Расчёт Score, превью эффекта мер, валидация набора решений и генерация альтернативных сценариев (/api/preview, /api/simulate, /api/recommend) — полностью детерминированный код, работает без единого внешнего API и без ключей.
• Единственная опциональная интеграция — LLM_API_KEY для текстового объяснения от «Аким-AI». Без ключа (пустое значение в .env, как в .env.example по умолчанию) приложение автоматически переключается на детерминированный fallback-текст, собранный из тех же чисел — демо и проверка работают end-to-end без единого ключа.
• Если эксперты захотят увидеть именно LLM-версию объяснений — достаточно любого личного ключа OpenAI (или другого OpenAI-совместимого провайдера) в .env, специальных прав/доступов от команды не требуется.
• База данных не используется, персистентных внешних сервисов нет — единственная зависимость на этапе запуска: pip install / npm install.

7. Проверка (Verification Steps)

1. Убедиться, что формула Score реализована корректно:

   cd backend
   pytest -q
   

   Все тесты сверяются с контрольными числами из официального ТЗ, включая базовый Score = 52.56 и пример из документа (набор M7+M8+M10+M12+M5 в Нуре/Сарыарке, бюджет 95, Score ≈ 56.5).
2. Запустить backend и frontend (см. раздел 4).
3. В интерфейсе выбрать меру (например, M1 → район Алматы) и навести на неё курсор: карточка Алматы покажет эффект меры (T1/T2 и балл района с дельтами). Недоступные меры (превышение бюджета, лимит 2 на направление, несовместимость M1/M3, 5 мер уже выбрано) блокируются с указанием причины — превысить бюджет из интерфейса нельзя.
4. Выбрать ровно 5 мероприятий (для мер типа «Район» — указать район), нажать «Утвердить бюджет города».
5. Убедиться, что:
   • при превышении бюджета/нарушении правил (повтор меры, несовместимость M1+M3, >2 мер на направление и т.д.) выводится понятная ошибка вместо Score;
   • при валидном наборе Score и показатели районов обновляются, а «Аким-AI» даёт текстовое объяснение результата;
   • в блоке «Сценарии от Аким-AI» появляются 2-3 альтернативных набора мер с разным составом и разным, честно пересчитанным Score (не дубликаты друг друга и не дубликат текущего результата) — это и есть что-если анализ поверх основного сценария.

8. Open Source & AI Declarations

• AI-модель: LLM (OpenAI-совместимый API) используется исключительно для генерации текстового объяснения уже посчитанного результата — числа Score считаются детерминированным кодом (scoring.py), LLM их не вычисляет и не придумывает.
• Данные: синтетический датасет районов и каталог мероприятий, предоставлены организаторами трека (Astana Innovations), не содержат персональных данных.
• Открытый код: FastAPI, Pydantic, Uvicorn, React, Vite, TailwindCSS, Recharts, Framer Motion, OpenAI Python SDK — все используемые библиотеки распространяются под открытыми лицензиями (MIT/Apache-2.0/BSD).