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

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

Проблема и для кого

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

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

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

• Каталог из 14 мероприятий по направлениям транспорта, экологии, социальной сферы, безопасности и городских сервисов.
• Выбор ровно пяти мероприятий при бюджете не более 100 условных единиц.
• Выбор района для районных мероприятий; городские мероприятия применяются ко всем районам.
• Проверка лимита не более двух мер на направление, повторов и заданных несовместимостей.
• Детерминированный расчёт показателей по пяти районам с учётом лагов мероприятий и заданных синергий.
• Расчёт Astana Quality of Life Score, вклада районов и слабейшего района, стоимости сценария и показателей ниже порога 40.
• Экран результатов с визуальным сравнением показателей «до / после», сработавшими синергиями, критическими значениями и текстовым объяснением.
• Сравнение рассчитанных сценариев в текущей сессии браузера.
• Офлайн-объяснение по шаблонам, если Anthropic API недоступен или ключ не задан.

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

1. Интерфейс загружает список мероприятий и районов из backend API.
2. Пользователь выбирает пять мероприятий, указывает районы для районных мер и укладывается в бюджет.
3. Frontend отправляет запрос POST /api/simulate со списком решений.
4. Backend проверяет входные данные. Если сценарий допустим, расчётный движок применяет эффекты мероприятий, масштабирует их с учётом лага, добавляет предусмотренные синергии и ограничивает показатели диапазоном 0–100.
5. Для каждого района вычисляется взвешенный показатель. Общий Score учитывает средний результат по населению, слабейший район и штраф за каждый показатель ниже 40.
6. Готовые числовые результаты передаются модулю объяснений. Он обращается к Anthropic Claude при наличии переменной окружения ANTHROPIC_API_KEY, иначе формирует шаблонный текст.
7. Интерфейс показывает итог, разницу с базовым сценарием, показатели районов и объяснение.

AI-модуль объясняет уже рассчитанные результаты и не выполняет числовой расчёт Score.

Технологии

• Python — backend и расчётная модель.
• FastAPI, Uvicorn, Pydantic — HTTP API, запуск ASGI-сервера и проверка структуры запросов.
• HTML, CSS, JavaScript без отдельного frontend-фреймворка — пользовательский интерфейс.
• Anthropic Python SDK и модель Claude Sonnet 4.6 (claude-sonnet-4-6) — необязательное текстовое объяснение.
• JSON — локальные исходные данные районов, мероприятий и правил.
• pytest — зависимость и тесты расчётного движка.

Список Python-зависимостей находится в Backend/requirements.txt.

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

Frontend/
  index.html       разметка интерфейса
  style.css        оформление
  app.js           загрузка данных, выбор мер и отображение результатов

Backend/
  api/main.py      HTTP API на FastAPI
  engine/
    data_loader.py чтение файлов с исходными данными
    validator.py   проверка сценария и правил
    calculator.py  детерминированный расчёт
    calculator_test.py тесты расчётного движка
  ai/explainer.py  объяснение готового результата через Anthropic или fallback
  data/
    districts.json районы и исходные показатели
    activities.json каталог мероприятий и эффекты
    rules.json     бюджет, лимиты, веса, синергии и несовместимости

data.py            отдельный Python-модуль с исходными данными

Поток запроса:

flowchart LR
    U[Пользователь] --> F[Frontend HTML/CSS/JS]
    F -->|HTTP JSON| A[FastAPI]
    A --> V[Валидация сценария]
    V --> C[Расчётный движок]
    D[(Локальные JSON-файлы)] --> V
    D --> C
    C -->|Готовые числа| X[AI-объяснение или fallback]
    X --> A
    A -->|Результат JSON| F

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

Требуются Python 3.10 или новее и Git. Все команды выполняются из корня репозитория.

1. Получите проект и установите зависимости

git clone https://github.com/BAITC-Hacks/hack-2e344b51-dg.git
cd hack-2e344b51-dg
python -m venv .venv

Активируйте виртуальное окружение:

Linux/macOS

source .venv/bin/activate

Windows PowerShell

.venv\Scripts\Activate.ps1

Установите зависимости:

python -m pip install -r Backend/requirements.txt

2. (Необязательно) включите объяснение через Anthropic

Без ключа приложение использует встроенный fallback и может работать без вызова AI API.

Linux/macOS

export ANTHROPIC_API_KEY="ваш-ключ"

Windows PowerShell

$env:ANTHROPIC_API_KEY = "ваш-ключ"

3. Запустите backend

uvicorn Backend.api.main:app --reload --port 8000

API будет доступен по адресу http://localhost:8000, интерактивная документация — http://localhost:8000/docs.

4. Запустите интерфейс

В отдельном терминале из корня репозитория выполните:

python -m http.server 5500 --directory Frontend

Откройте http://localhost:5500. Интерфейс по умолчанию обращается к backend на http://localhost:8000.

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

Проверка через интерфейс

1. Запустите backend и frontend по инструкции выше.
2. Откройте http://localhost:5500.
3. Выберите пять допустимых решений, например:
   • M1 — выделенные полосы для автобусов, район Есиль;
   • M2 — умные светофоры;
   • M8 — центр семейного здоровья / поликлиника, район Нура;
   • M10 — освещение и камеры, район Нура;
   • M12 — единая цифровая платформа обращений.
4. Общая стоимость этого набора — 86 из 100. Нажмите «Рассчитать сценарий».
5. Убедитесь, что появились Score, сравнение с базовым сценарием, показатели районов и объяснение. Для пары M1 + M2 должна отображаться заданная в правилах синергия.
6. Нажмите «Собрать новый сценарий», выберите другой допустимый набор и проверьте таблицу сравнения.

Проверка API запросом

При запущенном backend можно отправить тот же пример напрямую:

curl -X POST http://localhost:8000/api/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "decisions": [
      {"activity_id": "M1", "district_id": "esil"},
      {"activity_id": "M2"},
      {"activity_id": "M8", "district_id": "nura"},
      {"activity_id": "M10", "district_id": "nura"},
      {"activity_id": "M12"}
    ]
  }'

В ответе ожидается JSON с полями score, base_score, districts, total_cost, triggered_synergies, critical_pairs и explanation. Точное значение Score зависит от текущих данных и правил в репозитории.

Тесты расчётного движка

Из корня репозитория:

python -m pytest Backend/engine/calculator_test.py

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

• Расчётные данные поставляются вместе с проектом в Backend/data/districts.json, Backend/data/activities.json и Backend/data/rules.json; backend читает их локально.
• В данных указаны пять районов, десять показателей, доли населения, 14 мероприятий, их стоимость, лаги и эффекты.
• Правила задают горизонт 8 кварталов, бюджет 100 условных единиц, ровно пять решений, максимум две меры одного направления, веса показателей, синергии и несовместимости.
• Внешний сервис используется только для текстового объяснения: Anthropic API с моделью Claude Sonnet 4.6, если задан ANTHROPIC_API_KEY.
• Для локального запуска нужны только Python-зависимости из Backend/requirements.txt. Отдельная база данных, аккаунты и ключи для расчётного движка не используются.

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

• Значения показателей, стоимость и эффекты мер — статические модельные данные из репозитория; автоматического обновления из городских источников нет.
• Score отражает заданную формулу и принятые веса, а не подтверждённое измерение качества жизни или фактический прогноз.
• В приложении можно выбрать только ровно пять мероприятий; бюджет ограничен 100 условными единицами.
• Сравнение сценариев хранится только в состоянии текущей страницы браузера и не сохраняется между сессиями.
• AI-объяснение зависит от доступности Anthropic API и действующего ключа. Без них используется шаблонный fallback.
• API настроен на CORS для любых origin; механизм аутентификации в текущем коде не реализован.

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

Ссылка на deployed-версию в репозитории не указана. Для ознакомления и запуска доступен репозиторий проекта.