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

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

QalaBalance — интерактивный симулятор управления Астаной с AI-помощником. Вы выбираете проекты, распределяете 100 бюджетных единиц между пятью сферами и сравниваете состояние города через один и три года.

Проект для HackAlem AI, кейс Astana Innovations «Аким на 5 часов».

Русский · Қазақша · English

Быстрый запуск · Настройка AI · Карта 2ГИС · Проверки · Документация

Все показатели, бюджеты, коэффициенты и результаты являются демонстрационными. Симулятор не представляет официальную оценку или прогноз развития Астаны.

Возможности

Как проходит симуляция

1. Ознакомьтесь с исходным состоянием города: стартовый AQLS — 58,3.
2. Выберите пять проектов — по одному в каждой сфере.
3. Распределите ровно 100 единиц, от 5 до 40 на сферу. Условный курс: 1 единица = 2 млрд ₸.
4. Запустите расчёт и сравните горизонты 1 год / 3 года.
5. Изучите эффекты, риски и объяснение результата, затем измените решения и сравните новую стратегию.

Результат рассчитывает детерминированный движок в браузере: одинаковый выбор и бюджет дают одинаковые показатели. AI объясняет расчёт и помогает с решениями; предлагаемые изменения применяются только по кнопке пользователя.

Быстрый запуск

Понадобятся Git, Node.js 22.12+ и Python 3.12. Команды ниже предназначены для Windows PowerShell.

1. Получите проект

git clone https://github.com/BAITC-Hacks/hack-e9acc52d-bezdarez.git
cd hack-e9acc52d-bezdarez

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

Выполните из корня проекта:

python -m venv backend/.venv
backend/.venv/Scripts/python.exe -m pip install -r backend/requirements-dev.txt
if (-not (Test-Path -LiteralPath .env)) { Copy-Item -LiteralPath .env.example -Destination .env }
backend/.venv/Scripts/python.exe -m uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000

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

Откройте второй терминал в корне проекта:

npm.cmd --prefix frontend ci
npm.cmd --prefix frontend run dev

Откройте localhost:5173. Если порт занят, используйте адрес, который напечатает Vite. Запросы /api автоматически направляются на backend по адресу http://127.0.0.1:8000.

Симулятор работает без ключей API. Для диалога подключите модель по инструкции ниже; без неё результаты сопровождаются встроенным объяснением. Для карты 2ГИС нужен отдельный браузерный ключ; без ключа доступна схема районов.

При следующих запусках достаточно команд uvicorn и npm.cmd --prefix frontend run dev — повторная установка зависимостей не требуется.

python3 -m venv backend/.venv
backend/.venv/bin/python -m pip install -r backend/requirements-dev.txt
test -f .env || cp .env.example .env
backend/.venv/bin/python -m uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000

npm --prefix frontend ci
npm --prefix frontend run dev

docker compose up --build

AI-помощник

Помощник поддерживает свободный диалог: объяснения, математику, программирование, работу с текстом и вопросы о симуляторе. Он получает последние сообщения разговора, а для вопросов об игре — контекст проектов, бюджета и результатов. Доступны отмена запроса, повтор и начало нового диалога.

Полная инструкция подключения AI →

История сохраняется в браузере; сообщения и необходимый контекст отправляются выбранному провайдеру модели. Смена языка влияет на новые ответы, прежние сообщения остаются на исходном языке. Модель может ошибаться и не имеет встроенного интернет-поиска.

Если модель недоступна, чат показывает сообщение об ошибке и кнопку повтора. Экран результата при этом продолжает работать со встроенным объяснением, а подсказки по решениям доступны без AI.

Карта 2ГИС

Скопируйте шаблон из корня проекта:

if (-not (Test-Path -LiteralPath frontend/.env.local)) { Copy-Item -LiteralPath frontend/.env.example -Destination frontend/.env.local }

В frontend/.env.local укажите свой ключ с доступом к Map Tiles / MapGL JS API:

VITE_DGIS_API_KEY=ваш_браузерный_ключ

Перезапустите Vite. Для production ключ задаётся перед сборкой frontend. Это браузерный ключ: ограничения доменов и квоты настраиваются в кабинете 2ГИС.

Без ключа или при ошибке загрузки приложение использует SVG-схему. Контуры пяти районов модели приблизительные и не являются актуальными официальными административными границами.

Подключение и поведение карты →

Конфигурация

Корневой .env читает backend. Файл frontend/.env.local содержит настройки сборки frontend. Оба файла исключены из Git; примеры доступны в .env.example и frontend/.env.example.

Если backend работает на другом порту, задайте адрес перед запуском frontend, например:

$env:VITE_PROXY_TARGET = 'http://127.0.0.1:8011'
npm.cmd --prefix frontend run dev

Расчёт и архитектура

Индекс Astana Quality of Life Score (AQLS) объединяет пять показателей:

AQLS = Мобильность × 0,25 + Экология × 0,20
     + Социальный комфорт × 0,20 + Безопасность × 0,20
     + Городские сервисы × 0,15 − штрафы

Отдача от бюджета растёт по формуле min(1.15, sqrt(бюджет / рекомендованный бюджет)). Движок учитывает эффекты проектов, синергии, перекос финансирования, долгосрочные множители и обслуживание. Коэффициенты и исходные данные находятся в frontend/src/data, расчёт — в calculateSimulation.ts.

flowchart LR
    UI[Интерфейс и решения] --> Engine[Движок симуляции]
    Data[Каталог и коэффициенты] --> Engine
    Engine --> Result[Показатели и результат]
    Result --> Fallback[Встроенное объяснение]
    Result --> API[FastAPI]
    UI -->|Диалог| API
    API <--> LLM[Локальная модель или облачный API]
    API --> Reply[Ответ и предложения]
    Reply --> UI

Структура проекта

frontend/src/
  pages/                   Старт, выбор проектов, результаты
  components/              Карта, помощник, обучение, графики и настройки
  data/                    Проекты, районы, коэффициенты и переводы
  lib/                     Расчёт, локализация, хранение и API-клиенты
  types/                   Типы данных
backend/app/
  main.py                  Приложение FastAPI
  explain.py               API объяснений и помощника
  assistant.py             История, контекст и проверка действий
  llm.py                   Клиент языковых моделей
  local_ai.py              Запуск локальной модели
backend/tests_explain/     Тесты API
scripts/setup_local_ai.py  Установка локальной модели для Windows
docs/                     Инструкции, ТЗ и скриншоты

API

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

Проверки

Из корня проекта после установки зависимостей:

npm.cmd --prefix frontend test
npm.cmd --prefix frontend run build
npm.cmd --prefix frontend run lint -- src
backend/.venv/Scripts/python.exe -m pytest -c backend/pytest.ini backend/tests_explain -q

На Linux/macOS используйте npm и backend/.venv/bin/python. Автотесты API используют подставные ответы провайдера; действующий ключ и запущенная модель для них не требуются.

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

Скриншоты

Сохранённые примеры интерфейса; внешний вид отдельных элементов может отличаться от текущей версии.

Выбор проектов	Карта районов
Результат на английском	Тёмная тема на казахском

Документация

• AI-помощник и подключение моделей
• Настройка карты 2ГИС
• Техническое задание
• Шаблон конфигурации backend
• Шаблон конфигурации карты

Контуры районов основаны на данных © участников OpenStreetMap, лицензия ODbL. Комплектная модель ISSAI Qwen3.5-9B-Kazakh распространяется по Apache 2.0, llama.cpp — по MIT; ссылки на источники приведены в инструкции AI. Каталог проектов и параметры симуляции подготовлены командой на основе ТЗ.