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

Городской AI-симулятор Астаны — хакатонный проект команды Hackmonsters.

Пользователь собирает план из пяти городских мероприятий при бюджете 100 условных единиц и сравнивает его последствия для пяти районов. Математическое ядро проверяет ограничения и рассчитывает показатели качества жизни, AI-аналитик объясняет результат, а AI-агент предлагает и сравнивает альтернативные планы.

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

Главный принцип: числа считает Python, а не языковая модель. Калькулятор, экспорт JSON и четыре шаблонных слайда работают без API-ключей. AI-функции требуют настроенного внешнего провайдера.

Для жюри: запуск → контрольный сценарий → ограничения → развёрнутая версия.

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

Компонент	Возможности текущей версии
Каталог и план решений	14 мероприятий, 5 направлений, выбор районов, контроль расходов и остатка бюджета
Строгая валидация	Ровно 5 уникальных мер, бюджет не выше 100 у.е., максимум 2 меры одного направления, проверка назначений и несовместимостей
Математическое ядро	Лаги, синергии, изменения 10 показателей каждого района, критические показатели ниже 40 и итоговый Astana Quality of Life Score
Визуализация	Исходный и итоговый Score, районные баллы, диаграмма показателей и таблица точных дельт
AI-аналитика	Общая оценка, сильные стороны, риски и штрафы, рекомендации; выбор OpenAI, NVIDIA или автоматического резервирования
AI-агент	Подбор и сравнение допустимых планов по одной из трёх целей; журнал инструментов и применение только после подтверждения пользователя
Представление результата	Скачивание полного JSON расчёта, четыре слайда по шаблону, копирование текста и печать слайдов через браузер
API и проверки	FastAPI, интерактивная OpenAPI-документация, автоматические тесты математики, API, LLM-прослойки и агента

Правила выбора

• Мера типа District требует назначения одного существующего района. Мера типа City действует во всех районах и оплачивается один раз; назначать ей район нельзя.
• M1 + M3 несовместимы независимо от районов.
• M4 + M7 и M5 + M13 несовместимы только в одном районе.
• Синергии M1 + M2, M10 + M12, M5 + M6 действуют в районе соответствующей районной меры. В текущем датасете их бонусы не масштабируются лагом.
• Сервер берёт стоимость, эффекты и ограничения из своего каталога. Клиент передаёт ID мер и назначения, а не готовые баллы.

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

1. Интерфейс получает с сервера каталог мероприятий, районы, правила и исходные показатели.
2. Пользователь выбирает пять мер и районы либо загружает контрольный пример.
3. FastAPI проверяет запрос. Некорректный план получает ошибки валидации; такой запрос не отправляется в LLM.
4. CitySimulator применяет эффекты мер, лаги и синергии, рассчитывает районные показатели, штрафы, бюджет и городской Score.
5. Интерфейс показывает результат; полный расчёт можно скачать в JSON или представить четырьмя слайдами.
6. По отдельной команде AI-аналитик получает проверенный серверный контекст и формирует объяснение на русском языке.
7. При необходимости AI-агент сравнивает альтернативы. Предложение не меняет текущий выбор до нажатия «Применить предложенный план»; после применения калькулятор снова проверяет план.

Математика

Параметры находятся в data/rules.json, реализация и подробные docstrings — в city_simulator.py.

H = 8 кварталов
f(L) = max(0, (H - L) / H)

x'[d,k] = clip(x[d,k] + сумма эффектов мер с лагом + сумма бонусов синергий, 0, 100)
D[d] = сумма(weight[k] * x'[d,k])
D_avg = сумма(population_share[d] * D[d])
N_crit = количество пар «район × показатель», где x'[d,k] < 40

Score = 0.7 * D_avg + 0.3 * min(D[d]) - N_crit

Показатель	T1	T2	E1	E2	S1	S2	B1	B2	C1	C2
Вес	0.10	0.10	0.09	0.11	0.11	0.11	0.09	0.09	0.10	0.10

T — транспорт, E — экология, S — соцсфера, B — безопасность, C — сервисы. Все показатели направлены одинаково: больше означает лучше.

Лаг усредняет эффект за горизонт: при L = H эффект меры равен нулю. Штраф — один балл за каждую критическую пару — вычитается из городского Score, без взвешивания по населению и без уменьшения районного D. Ровно 40 не считается критическим значением. Диапазоном 0–100 ограничиваются показатели, но не итоговый Score. Базовое и итоговое состояния рассчитываются одинаково; округление выполняется на границе JSON-ответа.

Название «5 часов» не задаёт горизонт математической модели: в текущих правилах он равен восьми кварталам.

Технологии

Слой	Используется в репозитории
Интерфейс	TypeScript, React 19, Vite 8, CSS
Визуализация и текст	Recharts, Lucide React, react-markdown, remark-gfm, rehype-sanitize
Backend	Python 3.11+, FastAPI, Pydantic 2, Uvicorn, asyncio
LLM	OpenAI Python SDK (AsyncOpenAI), Chat Completions; OpenAI API и совместимый NVIDIA API
Модели	OpenAI: gpt-4o по умолчанию; NVIDIA: ID задаётся в NVIDIA_MODEL, конкретная модель в репозитории не выбрана
Конфигурация и данные	python-dotenv, JSON; PostgreSQL-совместимый SQL seed для отдельного использования
Проверки и сборка	pytest, HTTPX и HTTP-моки, TypeScript compiler, pnpm

Зависимости перечислены в package.json, requirements.txt и requirements-dev.txt. Frontend-зависимости зафиксированы в pnpm-lock.yaml; Python-зависимости заданы диапазонами версий.

Архитектура проекта

Браузер: React + TypeScript
        │ HTTP JSON: ID мер, районы, выбранный провайдер/цель
        ▼
FastAPI — api.py
        ├── CitySimulator ── data/city.json + data/rules.json
        │       └── проверка плана и детерминированный JSON расчёта
        ├── LLMRouter ── OpenAI / NVIDIA ── проверенное пояснение
        └── CityPlanningAgent
                ├── модель выбирает следующий разрешённый инструмент
                └── инструменты вызывают CitySimulator и сравнивают планы

В собранном режиме FastAPI также раздаёт dist/, поэтому интерфейс и API работают с одного адреса. В режиме разработки Vite проксирует /api на backend.

Путь	Назначение
src/	Каталог, корзина решений, визуализация, AI-панель, агент и слайды
api.py	Маршруты, жизненный цикл LLM-клиентов, раздача frontend
city_simulator.py	Модели данных, проверки, формулы и сериализация результата
llm_integration.py	Адаптеры провайдеров, строгий формат пояснения, ссылки на числовые факты и резервирование
city_agent.py	Ограниченный цикл вызовов инструментов, сравнение кандидатов и предложение плана
data/	Канонические JSON-данные и параметры расчёта
dataset.sql, examples/export_sql.py	SQL seed и его генератор из JSON
examples/	Запросы, полный пример результата и CLI для его объяснения
tests/	Проверки математики, API и поведения AI-интеграции

HTTP API

После запуска доступны Swagger UI и OpenAPI JSON.

Метод	Путь	Результат
GET	/api/health	Статус приложения и настроенные провайдеры; не проверяет действительность ключей
GET	/api/catalog	Каталог, ограничения, методика и исходное состояние
POST	/api/simulate	Полный JSON расчёта, schema_version="2.0"
POST	/simulate	Совместимый адрес того же калькулятора
POST	/api/analyze	simulation, assessment и фактический provider_used
POST	/api/agent/plan	proposed_plan, simulation, сравнение с базой/текущим планом, журнал, счётчики и requires_confirmation: true

Коды ошибок: 422 — неверный план или структура запроса; 503 — AI не настроен; 502 — AI не завершил корректный ответ; 429 — исчерпан лимит одновременных запусков агента. Ошибка AI не делает отдельный калькулятор недоступным.

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

1. Подготовить окружение

Нужны Git, Python 3.11+ (для команд ниже — 3.12), Node.js 22.12+ и pnpm. В package.json указан [email protected].

Если pnpm ещё не установлен:

npm install --global [email protected]

Клонируйте репозиторий и откройте его папку в VS Code:

git clone https://github.com/BAITC-Hacks/hack-92a11647-hackmonsters.git
cd hack-92a11647-hackmonsters

2. Установить зависимости

Windows / PowerShell, из корня проекта:

py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
pnpm install --frozen-lockfile

Linux / macOS:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
pnpm install --frozen-lockfile

Существующую .venv пересоздавать не нужно. В pnpm-workspace.yaml настроены nodeLinker: hoisted и локальное хранилище, чтобы установка на Windows не зависела от прав на создание символьных ссылок.

3. Собрать интерфейс и запустить один сервер

Windows / PowerShell:

pnpm run build
.\.venv\Scripts\python.exe -m uvicorn api:create_app --factory --host 127.0.0.1 --port 8000

Linux / macOS, с активной .venv:

pnpm run build
python -m uvicorn api:create_app --factory --host 127.0.0.1 --port 8000

Откройте http://127.0.0.1:8000/. На этом этапе уже работают расчёт, JSON и шаблонные слайды. PostgreSQL и API-ключи не нужны. Если порт занят, замените 8000 на 8010 в команде и адресе браузера. Сборка должна существовать до запуска FastAPI; после обновления кода или конфигурации перезапустите сервер.

4. Подключить AI — необязательно для проверки калькулятора

Создайте .env из .env.example, не перезаписывая существующий файл.

if (-not (Test-Path .env)) { Copy-Item .env.example .env }

Для Linux / macOS:

test -f .env || cp .env.example .env

Заполните настройки одного или обоих провайдеров из раздела интеграций и перезапустите backend. Сервер и examples.explain автоматически загружают .env; переменные окружения процесса имеют приоритет. Сам LLMRouter.from_env() читает уже заданное окружение.

Ключи остаются на сервере. .env исключён из Git; не добавляйте ключам префикс VITE_ и не вставляйте их в frontend. Без конфигурации интерфейс показывает недоступность AI, а не подставляет вымышленный ответ.

5. Режим разработки

В первом терминале PowerShell:

.\.venv\Scripts\python.exe -m uvicorn api:create_app --factory --reload --host 127.0.0.1 --port 8000

Во втором терминале:

pnpm dev

Откройте Vite на порту 4173. Прокси в vite.config.ts направлен на 127.0.0.1:8000; если backend использует другой порт, обновите прокси. pnpm preview не заменяет backend. На Linux / macOS используйте python из активной .venv вместо Windows-пути.

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

Сценарий для жюри без ключей

1. Запустите приложение и нажмите «Загрузить контрольный пример».
2. Убедитесь, что выбраны M7, M8, M10 в Нуре, M12 для всего города и M5 в Сарыарке.
3. Сравните результат с контрольными значениями:

Показатель	Ожидаемое значение
Количество мер	5
Расходы / остаток	95 / 5 у.е.
Базовый Score	52.55768
Итоговый Score	56.54307
Изменение Score	+3.98539
Критических показателей	2 → 0
Штраф города	2 → 0

4. Нажмите «Скачать JSON расчёта»: файл содержит показатели и дельты всех пяти районов, бюджет, штрафы, вклады мер и синергий, методику, допущения и предупреждения.
5. Нажмите «Собрать слайды расчёта»: откроются четыре слайда по шаблону, без обращения к LLM.
6. Смените район одной районной меры: расчёт должен обновиться, а старое AI-пояснение, если оно было, будет отмечено как устаревшее.

Контрольный запрос хранится в examples/official_request.json:

{
  "measure_ids": ["M7", "M8", "M10", "M12", "M5"],
  "district_assignments": {
    "M7": "nura",
    "M8": "nura",
    "M10": "nura",
    "M5": "saryarka"
  }
}

Его можно выполнить через Swagger или из второго терминала PowerShell:

$body = Get-Content examples/official_request.json -Raw
$result = Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/api/simulate -ContentType 'application/json' -Body $body
$result.score
$result.budget

Для Linux / macOS:

curl -sS http://127.0.0.1:8000/api/simulate \
  -H 'Content-Type: application/json' \
  --data-binary @examples/official_request.json

Фрагмент ответа для контрольного запроса, не полный JSON-контракт:

{
  "schema_version": "2.0",
  "is_valid": true,
  "budget": {"limit": 100, "spent": 95, "remaining": 5, "unit": "у.е."},
  "score": {"base": 52.55768, "final": 56.54307, "delta": 3.98539}
}

Для отрицательной проверки в Swagger замените один ID повтором другого: API должен вернуть 422, без нового Score и вызова LLM. Полный сохранённый examples/response.json относится к другому запросу — examples/request.json, с мерами M1, M2, M4, M10, M12.

Сценарий с AI

1. Настройте провайдера и выполните контрольный расчёт. Нажмите «Запустить AI-анализ»: ожидаются оценка, сильные стороны, риски/штрафы и рекомендации. Интерфейс показывает фактически ответившего провайдера.
2. В панели «AI-агент: планировщик» выберите цель: городской Score, слабейший район или число критических показателей.
3. Нажмите «Предложить план с AI-агентом». Рассмотрите предложенные меры, районы, расходы, сравнение и журнал инструментов.
4. До подтверждения корзина не должна меняться. Нажмите «Применить предложенный план» для замены и повторного расчёта.

Агент может стартовать с пустого выбора или улучшать полный допустимый план. Частичный план нужно сначала завершить либо сбросить. Пример запроса — examples/agent_request.json. Результат AI не фиксирован: он зависит от модели и доступности API; при сбое приложение возвращает ошибку, не фиктивный успех.

Автоматические проверки

Windows / PowerShell:

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -q
pnpm run typecheck
pnpm run build

На Linux / macOS в активной .venv замените путь к Python на python.

Тесты проверяют формулы и порог 40, ограничения планов, совпадение SQL seed с JSON, контракт API и примеры, точность передаваемого LLM-контекста, резервирование, обработку ошибок, таймауты, отмену и изоляцию запусков агента. AI-тесты используют HTTP-моки и подменённые провайдеры, включая реальный OpenAI SDK, без платных запросов. Их успешное выполнение не подтверждает доступность реальных ключей или конкретной NVIDIA-модели.

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

Данные симулятора

• data/city.json — пять районов: Есиль, Алматы, Сарыарка, Байконур и Нура; доли населения, десять исходных показателей каждого района, 14 мер, три синергии и три конфликта.
• data/rules.json — горизонт, веса показателей и формула Score; версия hackalem-district-dataset-v1, статус confirmed.
• dataset.sql — PostgreSQL seed для пустой базы. Он генерируется из JSON командой python -m examples.export_sql, которая печатает SQL в stdout. Сам сервер читает JSON; соединение с PostgreSQL не реализовано и для запуска не требуется.
• Dataset.from_records(...) принимает уже загруженные строки БД, но не устанавливает соединения и не выполняет SQL. Другие пути к JSON можно задать серверными переменными CITY_DATA_PATH и CITY_RULES_PATH.

Код ссылается на командный документ «Датасет районов.docx», однако самого документа и ссылки на первичный статистический источник в отслеживаемых файлах нет. Поэтому воспроизводимой основой этой версии являются данные и правила внутри репозитория. Статус confirmed — поле конфигурации, не свидетельство официального подтверждения городом. Подключения к актуальной муниципальной статистике, картографическим API или данным в реальном времени нет.

AI-провайдеры

Переменная	Назначение
OPENAI_API_KEY	Серверный ключ OpenAI
OPENAI_MODEL	Модель OpenAI, по умолчанию gpt-4o
NVIDIA_API_KEY	Серверный ключ NVIDIA
NVIDIA_MODEL	Точный ID модели; обязателен при настройке NVIDIA
NVIDIA_BASE_URL	По умолчанию https://integrate.api.nvidia.com/v1
NVIDIA_OUTPUT_MODE	json_object по умолчанию; также поддержаны адаптером json_schema и nvext, если их принимает endpoint

Достаточно одного настроенного провайдера. Режим auto в HTTP API выбирает OpenAI, затем NVIDIA при ошибке, если она настроена; при наличии только NVIDIA используется она. Явный выбор провайдера не включает резервирование. Некорректная конфигурация LLM может отключить AI целиком, но не калькулятор.

AI-аналитика: сервер отправляет полный результат расчёта и каталог числовых фактов. Модель возвращает четыре поля: general_assessment, strengths, risks_and_penalties, recommendations. Числовые значения цитируются через ссылки вида {{number:0}}; сервер проверяет ссылки и подставляет исходные числа. Лишние поля, неверная схема и числовые символы вне ссылок отклоняются. На провайдера отведено 20 секунд, общий лимит — 45 секунд; внутренние повторы SDK отключены.

AI-агент: модель вызывает только get_catalog, simulate_plan, improve_plan, finish_plan. Поиск сравнивает ограниченное соседство — замену одной меры или перенос районной меры. Завершить можно только одним из лучших уже проверенных кандидатов после сравнения. Цели ранжируются по приоритету:

• city_score: Score → меньше критических показателей → минимальный районный D → остаток бюджета;
• weakest_district: минимальный D → Score → меньше критических → остаток;
• critical_metrics: меньше критических → Score → минимальный D → остаток.

Один запуск ограничен шестью запросами модели, шестью вызовами инструментов и 600 попытками расчёта кандидатов; проверка исходного плана в этот счётчик не входит. Лимиты времени — 25 секунд на провайдера и 60 секунд всего. Резервный провайдер использует тот же общий бюджет. Одновременно разрешены два запуска агента на процесс. Модель NVIDIA должна поддерживать вызовы инструментов: одного JSON-режима для агента недостаточно.

Ограничения

• Это сценарная модель с фиксированными эффектами, а не прогноз фактического развития города. Данные не обновляются автоматически, статистическая достоверность эффекта мер в репозитории не обоснована.
• Формат датасета рассчитан ровно на пять районов и 14 мер. Произвольный город и произвольный размер каталога потребуют изменения схемы.
• Агент не гарантирует глобально оптимальный план. Улучшение выбранной цели может ухудшить другие показатели; дельты показаны отдельно.
• Проверка числовых ссылок защищает происхождение чисел, но не доказывает смысловую правильность объяснения: LLM может неверно интерпретировать факт. Текст требует критической оценки.
• AI зависит от сети, доступности модели, ключей, квот и тарификации провайдера. При AI-запросах контекст симуляции передаётся выбранному внешнему сервису.
• Нет аккаунтов, авторизации, постоянного хранения пользовательских планов, общего rate limiting или контроля расходов по пользователям. Лимит параллелизма агента не заменяет эти механизмы; перед публичным размещением они необходимы.
• Агент не имеет инструментов для shell, файлов, произвольного доступа к сети или изменения БД. Его кандидаты и история существуют в рамках одного запроса.
• Ответы передаются обычным HTTP JSON, не SSE-потоком. Отмена в интерфейсе прекращает ожидание; уже отправленный провайдеру запрос может продолжить выполняться и тарифицироваться.
• Слайды собираются в браузере по шаблону. Генерация дизайна презентации моделью и экспорт в PPTX не реализованы.

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

Подтверждённая ссылка на публичную deployed-версию в репозитории не указана. Конфигурации публичного развёртывания и CI/CD среди отслеживаемых файлов нет.

После локального запуска приложение доступно по http://127.0.0.1:8000/, документация API — по http://127.0.0.1:8000/docs. Эти адреса работают только на компьютере, где запущен сервер, и не являются публичной демо-ссылкой.

Исходный код: BAITC-Hacks / hack-92a11647-hackmonsters.