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

AI-симулятор управления городом команды AVM AI. HackAlem AI, задача 12, спец-трек Astana Innovations. Условия задачи и данные организатора: техническое задание и дополнительный документ с датасетом, каталогом мер и формулой.

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

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

Требования и зависимости

• Python 3.11+ с pip и модулем venv; Windows, Linux или macOS.
• Современный браузер с JavaScript. Фронтенд — HTML, CSS и JavaScript без сборки; Node.js, Docker и база данных не требуются.
• Интернет нужен для установки зависимостей и внешней AI-модели. Основной сценарий работает без ключей и аккаунтов.

Прямые зависимости зафиксированы в requirements.txt: FastAPI 0.115.0, Uvicorn 0.30.6, Pydantic 2.9.2, openai 1.51.0, python-dotenv 1.0.1, HTTPX 0.27.2, pytest 8.3.3. Полного lock-файла транзитивных зависимостей пока нет.

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

Получите репозиторий и выполняйте команды из его корня, где находится app.py.

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --no-cache-dir -r requirements.txt
.\.venv\Scripts\python.exe -m uvicorn app:app --host 127.0.0.1 --port 8000

Linux / macOS:

python3 -m venv .venv
./.venv/bin/python -m pip install --no-cache-dir -r requirements.txt
./.venv/bin/python -m uvicorn app:app --host 127.0.0.1 --port 8000

В Debian/Ubuntu при отсутствии venv установите системный пакет python3-venv. Активация виртуального окружения не требуется. После установки для каждого запуска достаточно последней команды.

• Приложение: http://127.0.0.1:8000/.
• Проверка сервера: http://127.0.0.1:8000/api/health.
• Интерактивная документация API: http://127.0.0.1:8000/docs.
• Остановка: Ctrl+C.

Открывайте страницу через сервер, а не как файл static/index.html. Для режима без ключа не создавайте .env и не задавайте OPENAI_API_KEY в окружении. При наличии ключа приложение использует внешнюю модель.

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

Настройки перечислены в .env.example. Для живого AI скопируйте его в .env (Copy-Item .env.example .env в PowerShell, cp .env.example .env в Bash), заполните поля и перезапустите сервер. Переменные процесса имеют приоритет над .env; файл с ключами исключён из Git.

Переменная	Назначение
OPENAI_API_KEY	Ключ модели; без ключа объяснение строится из фактов расчёта
OPENAI_MODEL	Имя модели, по умолчанию gpt-4o-mini
LLM_TIMEOUT_S	Таймаут запроса, по умолчанию 15 секунд
OPENAI_BASE_URL	Необязательный адрес OpenAI-совместимого API; модель и ключ должны соответствовать провайдеру

Ключ можно ввести в настройках интерфейса. Он хранится в sessionStorage вкладки, передаётся серверу заголовком X-OpenAI-Key и имеет приоритет над серверным. Приложение не записывает его в файлы или журналы. «Убрать ключ» очищает значение в браузере. Совместимость всех функций с каждым сторонним провайдером отдельно не проверена.

Проверка основного сценария

1. Откройте приложение и нажмите «Сброс», если восстановился прежний план. Бюджет — 100, Score без решений — 52.55768, критических показателей в Нуре — 2.
2. Нажмите «Готовый сценарий». Набор: M7 Нура, M8 Нура, M10 Нура, M12 город, M5 Сарыарка. Стоимость — 95, Score — 56.54307, критических показателей — 0. Интерфейс округляет Score до двух знаков.
3. Нажмите «Объяснить». Без ключа появится «автоматический разбор» с сильными сторонами, рисками и рекомендациями. С ключом приложение попробует получить ответ модели.
4. Нажмите «Найти улучшение». Лучший вариант меняет M5 Сарыарка на M3 Нура: стоимость 100, Score 57.20556. «Применить» пересчитывает план.
5. Удалите одну меру: результат неполного набора не рассчитывается. Каталог запрещает шестую меру, превышение бюджета, повторы и несовместимые решения.
6. В Swagger вызовите POST /api/evaluate с набором M3 Есиль, M13 Алматы, M5 Сарыарка, M7 Нура, M12 город. Стоимость 121: ожидаются valid: false, score: null и ошибка budget_exceeded.

План сохраняется в localStorage браузера. Для одинаковых стартовых условий используйте «Сброс».

Пример расчёта через PowerShell:

$city = Invoke-RestMethod http://127.0.0.1:8000/api/city
$body = @{ decisions = $city.example_scenario } | ConvertTo-Json -Depth 10
Invoke-RestMethod http://127.0.0.1:8000/api/evaluate -Method Post -ContentType 'application/json' -Body $body

Пример через Bash:

curl -sS http://127.0.0.1:8000/api/evaluate \
  -H 'Content-Type: application/json' \
  -d '{"decisions":[{"measure_id":"M7","district_id":"nura"},{"measure_id":"M8","district_id":"nura"},{"measure_id":"M10","district_id":"nura"},{"measure_id":"M12"},{"measure_id":"M5","district_id":"saryarka"}]}'

Тесты и терминальное демо

Windows PowerShell:

.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m pip check
.\.venv\Scripts\python.exe scripts/demo.py

Linux / macOS:

./.venv/bin/python -m pytest -q
./.venv/bin/python -m pip check
./.venv/bin/python scripts/demo.py

Демо показывает расчёт, отклонение неверных наборов, улучшения, рейтинг и объяснение без запуска сервера. При наличии ключа в окружении или .env оно обращается к модели; без ключа работает локально.

Архитектура и структура

Браузер: static/ → HTTP JSON → FastAPI: app.py → engine/ → data/
                                                   ↓
                                       внешняя AI-модель (опционально)

Файл или каталог	Назначение
app.py	API и раздача интерфейса с одного сервера
engine/model.py, validator.py, scoring.py	Загрузка данных, проверка решений, расчёт Score
engine/advisor.py, ranking.py	Замены одной меры, полный перебор и ранжирование
engine/facts.py, templates.py, explain.py	Факты, локальное объяснение и работа с моделью
data/city.json	Данные, меры и правила из ТЗ
data/top_sets.json	Готовый индекс: топ-100, квантили и Парето-граница
static/	Интерфейс, изображения и демонстрация патруля
scripts/demo.py, scripts/rank_all.py	Терминальное демо и пересчёт индекса
tests/	Тесты расчёта, правил, советника, API и демо

API: GET /api/health, /api/city, /api/top; POST /api/evaluate, /api/improvements, /api/explain, /api/chat, /api/ai/check. Схемы доступны в /docs.

Правила расчёта и роль AI

По подробным правилам ТЗ принимаются ровно пять разных мер, не более двух из одного направления. Для районной меры обязателен район; городская действует на все районы. Бюджет, направления и несовместимости проверяет сервер. Невалидный набор не получает Score.

Эффект каждой меры умножается на (8 − лаг) / 8; синергии добавляются без масштабирования. Значения показателей ограничиваются диапазоном 0–100. Далее:

D_района = сумма(вес показателя × новое значение)
D_города = сумма(доля населения × D_района)
Score = 0.7 × D_города + 0.3 × min(D_района) − N_crit

N_crit — число пар «район × показатель» со значением строго ниже 40. Все числа считает Python; модель получает готовые факты. Ответ объяснения проверяется по JSON-схеме, ссылкам на факты и допустимым числам. При ошибке или отсутствии ключа используется локальное объяснение template. Проверка не гарантирует смысловую точность каждой фразы. Свободный чат доступен только с ключом.

Поиск улучшений возвращает до трёх лучших замен одной меры. Полный перебор содержит 694 395 допустимых планов, лучший Score — 57.236735 за 98 единиц. Процентиль приближённый, по квантилям; Парето-граница показывает лучшие соотношения стоимости и Score. Индекс включён в проект, пересчитывать его для запуска не нужно.

Демонстрационные возможности и ограничения

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

Рейтинг сравнивает математические сценарии, а не зарегистрированные команды.

Сторонние материалы

• FastAPI — MIT; Uvicorn — BSD-3-Clause; Pydantic — MIT; openai-python — Apache-2.0; python-dotenv и HTTPX — BSD-3-Clause; pytest — MIT. Зависимости устанавливаются штатными пакетами с их лицензиями.
• Данные, каталог мероприятий, формула, синергии и ограничения предоставлены организатором в условиях трека 12 (ссылки в начале README) и перенесены в data/city.json без изменений.
• Карта, иконки и изображения персонажей и камеры сгенерированы командой с помощью Nano Banana Pro. Это иллюстрации, а не съёмка реального патруля.
• Код разработан с использованием Claude Code и Codex. Правила стиля AI-ответов адаптированы из skill humanizer, основанного на материале Wikipedia «Signs of AI writing»; источник отмечен в engine/explain.py. Co-Authored-By сохранён в истории коммитов.

Команда

• Алибек Абдеков — капитан, фронтенд.
• Канат Тәжіхан — бэкенд.