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

О проекте

«Аким на 5 часов» — локальный симулятор для задачи Hackeron. Он помогает городскому управленцу, аналитику или участнику команды проверить последствия распределения ограниченного виртуального бюджета между инициативами по транспорту, экологии, социальной инфраструктуре, безопасности и городским сервисам.

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

Быстро для жюри

• Что решает продукт: позволяет сравнить последствия пяти городских решений при фиксированном бюджете и увидеть влияние на районы, слабые места и критические показатели.
• Публичная демо-версия: https://hackalemai.amrosia.dev/.
• Как запустить локально: нужен Python 3.10+; выполните python3 -m src.web, затем откройте http://127.0.0.1:8000. Установка зависимостей и ключи API не нужны.
• Технологии: Python 3.10+, стандартная библиотека (http.server, json, unittest), HTML/CSS/JavaScript и локальные JSON-данные. Расчёт не использует внешние API или сервисы.
• Как проверить: воспроизведите эталонный сценарий из раздела «Как проверить решение» (Score 56.54) или запустите PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -p '*_test.py' -v.

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

• Локальный веб-интерфейс на русском языке: пять карточек решений, выбор района для районных мер, текущий бюджет и кнопка расчёта.
• Каталог из 14 мероприятий и синтетические исходные данные для 5 районов.
• Проверка правил до расчёта:
  • бюджет не выше 100;
  • ровно 5 решений;
  • без повторов мероприятий;
  • район обязателен для районной меры и не допускается для городской;
  • не более двух мер одного направления;
  • контроль несовместимых пар.
• Детерминированный расчёт Astana Quality of Life Score с лагами, синергиями, ограничением шкалы 0–100 и штрафом за критические показатели.
• Визуальный дашборд результата: SVG-сравнение районных оценок «до/после» и интерактивный просмотр всех 10 показателей выбранного района.
• Локальное сохранение сценариев и их сравнение в браузере, экспорт Markdown-отчёта, три моделируемых события-риска и три рекомендации однократной замены меры от детерминированной модели.
• Локальное фактологическое объяснение результата на русском языке. Для внешней LLM предусмотрен внедряемый адаптер, но готовая интеграция с провайдером в репозитории отсутствует.
• Терминальный интерфейс и необязательный модуль исчерпывающего ранжирования допустимых сценариев.
• Автоматические тесты модели, CLI, API, объяснений и ранжирования.

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

1. В браузере пользователь выбирает пять мероприятий и при необходимости район.
2. Интерфейс показывает суммарную стоимость и остаток от бюджета.
3. После нажатия «Рассчитать сценарий» браузер передаёт только выбранные идентификаторы в локальный JSON API.
4. Валидатор проверяет набор. Если есть нарушение, Score не рассчитывается и выводятся причины.
5. Для допустимого набора движок применяет эффекты с учётом лага и синергий, затем вычисляет районные оценки, среднее по городу, минимум района, число критических значений и итоговый Score.
6. Веб-интерфейс отображает аудит результата по районам и фактологическое текстовое объяснение, сформированное из уже рассчитанных чисел.

Технологии

Область	Использовано
Язык	Python 3.10+
Веб-сервер и API	Стандартная библиотека Python: http.server, json
Клиент	HTML, CSS, JavaScript без сторонних библиотек
Данные	Локальные JSON-файлы
Тестирование	unittest из стандартной библиотеки
AI-слой	Локальное фактологическое объяснение; опциональный интерфейс адаптера для LLM
Внешние API/сервисы	Не используются

Проект не требует установки пакетов, ключей API или сетевого доступа для запуска основной версии.

Архитектура

data/*.json
    │
    ▼
src/data ──► src/validator ──► src/engine ──► src/ai
                                  │               │
                                  └────► src/web ◄┘
                                            │
                                     браузер / JSON API

src/solver ──► validator + engine
src/app    ──► validator + engine + ai

• data/ — исходные синтетические данные: районы, мероприятия, веса, правила, синергии и несовместимости.
• src/data/ — загрузка JSON и проверка структуры набора.
• src/validator/ — чистая проверка пользовательского набора решений.
• src/engine/ — чистый расчёт Score и полный журнал расчётных изменений.
• src/ai/ — объяснение только по готовому ScoreResult; арифметику не выполняет.
• src/web/ — локальный HTTP-сервер, JSON API и статический интерфейс; не дублирует правила или расчёты.
• src/app/ — альтернативный CLI.
• src/solver/ — необязательное ранжирование допустимых сценариев.
• tests/ — тесты правил, расчёта, API, интерфейсов, объяснения и ранжирования.

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

Требование: Python 3.10 или новее.

git clone https://github.com/BAITC-Hacks/hack-15801fec-hackeron.git
cd hack-15801fec-hackeron
python3 -m src.web

Откройте в браузере: http://127.0.0.1:8000.

Если порт занят:

python3 -m src.web --port 8765

Тогда интерфейс будет доступен по адресу http://127.0.0.1:8765.

Также доступен CLI:

python3 -m src.app

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

Проверка в веб-интерфейсе

Выберите следующие пять мер:

Мера	Район
M7 — Школа + детсад	Нура
M8 — Центр семейного здоровья / поликлиника	Нура
M10 — Освещение и камеры	Нура
M12 — Единая цифровая платформа обращений	город
M5 — Чистое топливо	Сарыарка

Ожидаемый результат из текущей модели:

• бюджет: 95 / 100;
• Score: 56.54;
• изменение к базовому сценарию: +3.99;
• критических значений: 0.

Это соответствует примеру из задания, где ожидается Score около 56.5.

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

PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -p '*_test.py' -v

Тесты проверяют базовый Score, эталонный набор, лаги, синергии, независимость от порядка мер, обработку недопустимых наборов, CLI, JSON API, объяснения и ранжирование.

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

Все данные лежат в репозитории и не загружаются из внешних источников во время работы:

• data/districts.json — 5 районов, доли населения и 10 показателей.
• data/measures.json — 14 мероприятий, стоимость, лаг и эффекты.
• data/rules.json — бюджет, веса, горизонт, критический порог, синергии и несовместимости.

Числа транскрибированы из части II INSTRUCTIONS.md. Исходные документы сохранены в task/original/, текстовые версии — в task/txt/; происхождение и контрольные суммы описаны в DOCUMENTATION.md.

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

Ограничения текущей версии

• Публичная демо-версия доступна, но не заменяет локальный воспроизводимый запуск и не содержит многопользовательского режима.
• Объяснение по умолчанию локальное и фактологическое, а не ответ от подключённой LLM.
• Интерфейс не содержит многопользовательского сравнения команд, PDF/презентации и подключения к реальному набору городских данных.
• Ранжирование сценариев исчерпывающее и может выполняться десятки секунд.
• Датасет синтетический и предназначен для хакатонной демонстрации, а не для управления реальным городом.

Ссылка на deployed-версию

Публичный развёрнутый экземпляр: https://hackalemai.amrosia.dev/.

Для воспроизводимой локальной проверки используйте запуск по инструкции выше.