hack-861ce405-eaglez

Hackathon team repository for EagleZ Astana Innovations

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

AI-симулятор городского управления для спец-трека Astana Innovations. Участник распределяет виртуальный бюджет между мерами для пяти синтетических районов, принимает ровно пять решений и получает рассчитанный Astana Quality of Life Score с объяснением сильных сторон, рисков и возможных улучшений.

Проект — учебный симулятор. Данные районов синтетические; баллы не являются оценкой или прогнозом для реальной Астаны.

Проблема и пользователи

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

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

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

• Бюджет 100 условных единиц, пять районов, десять показателей и каталог из 14 мероприятий.
• Выбор ровно пяти разных мероприятий с проверкой бюджета, обязательного выбора района и ограничений задания.
• Расчёт последствий мероприятий с учётом восьмиквартального горизонта, лагов, синергий и ограничений показателей от 0 до 100.
• Расчёт баллов районов и города, самого слабого района и критических показателей ниже 40.
• Каталог мероприятий с фильтрами и графики показателей районов.
• Сохранение сценариев в браузере, сравнение и экспорт выбранного сценария в JSON.
• Поиск трёх лучших найденных вариантов, полученных заменой одного решения за раз. Это локальный поиск, он не гарантирует глобально лучший набор.
• Распределение вклада пяти выбранных мер методом Шепли по 32 поднаборам. Эти поднаборы используются только для анализа и не являются допустимыми игровыми сценариями.
• Локальное объяснение без внешней модели; опциональный AI-анализ через OpenAI API или NVIDIA API Catalog.

Пользовательский сценарий

1. Откройте приложение и выберите готовый пример либо соберите свой набор мер.
2. Укажите район для районных мероприятий. Городские мероприятия применяются ко всем районам.
3. Примите ровно пять уникальных решений. Интерфейс показывает стоимость и валидирует ограничения.
4. Приложение отправляет выбранные ID мероприятий серверу. Сервер заново проверяет набор и сам рассчитывает показатели и Score.
5. Нажмите «Разобрать сценарий». Локальный анализ доступен всегда; при настроенном и доступном API модель выбирает объясняющие факты из рассчитанного сервером набора.
6. Изучите риски и найденные улучшения, задайте вопрос о сценарии или сравните сохранённые варианты.

Технологии и интеграции

Часть	Технология
Сервер и расчёты	Node.js 22+, встроенные модули http, fs, path; внешние npm-зависимости приложению не нужны
Интерфейс	HTML, CSS и браузерный JavaScript без внешних UI-библиотек
Автоматические тесты	Встроенный Node.js test runner (node:test)
OpenAI (опционально)	Responses API: https://api.openai.com/v1/responses
NVIDIA (опционально)	NVIDIA API Catalog Chat Completions: https://integrate.api.nvidia.com/v1/chat/completions

По умолчанию приложение работает в режиме offline и не вызывает внешние AI-сервисы. Для AI требуется отдельный API-ключ и доступная аккаунту текстовая модель. Подписка ChatGPT/Codex сама по себе не является API-ключом. Поддерживаемый model ID указывается участником в локальном .env; модель не зашита в проект.

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

Архитектура

Браузер (public/)
        │ HTTP, только выбранные решения и вопрос
        ▼
Локальный Node.js сервер (server.js)
        ├── src/engine.js     — данные, правила и точный расчёт Score
        ├── src/analysis.js   — объясняющие факты, вклад мер и улучшения
        ├── src/presets.js    — готовые примеры
        └── src/ai.js         — offline / OpenAI / NVIDIA

Сервер не принимает от браузера готовые Score, стоимость или эффекты: он пересчитывает результат по ID выбранных мер. AI-модель получает результат и проверенные факты, после чего выбирает их ID для объяснения. На экран выводится текст из сервера, а не свободно сгенерированные моделью значения. При отсутствии настройки, ошибке API или некорректном ответе приложение показывает локальное объяснение с причиной перехода в offline.

Основные маршруты локального сервера: GET /api/config, POST /api/validate, POST /api/analyze, POST /api/explain и POST /api/ask.

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

1. Установите Node.js версии 22 или новее: nodejs.org. При установке оставьте стандартные настройки.

2. Скачайте и распакуйте проект. В Проводнике откройте папку akim-simulator, внутри которой лежит package.json.

3. Нажмите на строку пути вверху окна Проводника, введите cmd и нажмите Enter. Откроется командная строка в папке проекта.

4. Выполните:

   npm start
   

5. Не закрывая командную строку, откройте в браузере http://localhost:3000.

Успешный запуск выводит адрес Аким на 5 часов: http://localhost:3000 и режим объяснений. Сообщение offline означает, что веб-приложение запущено без подключённого AI API; интерфейс и расчёт Score при этом работают. Чтобы остановить сервер, вернитесь в командную строку и нажмите Ctrl+C.

Команду npm start необходимо выполнять именно в папке, где находится package.json. Если появляется ошибка ENOENT с путём вроде C:\Users\...\package.json, откройте командную строку в папке проекта, а не в домашней папке Windows.

Устанавливать пакеты командой npm install для запуска не требуется. Чтобы выполнить автоматические тесты, откройте вторую командную строку в папке проекта и запустите:

npm test

Подключение AI API (необязательно)

1. В командной строке, открытой в папке проекта, создайте личный файл настроек:

   copy .env.example .env
   

2. Откройте файл .env в редакторе и настройте одного поставщика.

   Для NVIDIA:

   AI_PROVIDER=nvidia
   NVIDIA_API_KEY=ваш_личный_ключ
   NVIDIA_MODEL=точный_model_id_из_примера_API_модели
   

   Или для OpenAI:

   AI_PROVIDER=openai
   OPENAI_API_KEY=ваш_личный_ключ
   OPENAI_MODEL=точный_model_id_доступной_модели
   

3. Сохраните .env, остановите сервер сочетанием Ctrl+C и снова запустите npm start.

4. Выберите пример в приложении и нажмите «Разобрать сценарий». Метка успешного ответа ИИ: nvidia или ИИ: openai подтверждает, что сервер получил ответ от внешней модели. Наличие ключа в настройках само по себе соединение не подтверждает.

Ключ NVIDIA создаётся в NVIDIA API Keys; подходящую модель и её точный model ID нужно проверить в NVIDIA API Catalog. Для OpenAI API нужен отдельный ключ с доступом и квотой: API keys. Доступность модели, квоты и возможная стоимость зависят от соответствующего аккаунта и сервиса.

Файл .env содержит секрет. Не отправляйте его в чат, не добавляйте в GitHub и не вставляйте ключ в браузерный код. .gitignore исключает .env из Git. Не публикуйте скриншоты, на которых виден ключ.

Проверка для жюри

1. Запустите приложение по инструкции выше и откройте http://localhost:3000.
2. Нажмите «Пример задания». Должны появиться пять решений общей стоимостью 95.
3. Ожидаемый Score примера — около 56,54; исходный Score без действий — около 52,56. Разница связана с вкладом выбранных мер и синергией M10 + M12.
4. Нажмите «Разобрать сценарий». Без API-ключа появится объяснение с явной меткой offline. С рабочей API-настройкой успешный AI-ответ будет помечен названием провайдера.
5. Удалите или замените одну меру и проверьте, что интерфейс пересчитывает стоимость, показатели и Score. Для завершённого набора всегда требуется ровно пять решений.

Автоматические проверки запускаются командой npm test. На дату последней проверки в репозитории указано 24 теста; они покрывают правила и серверные маршруты, а AI-провайдеров тестируют имитациями. Автоматические тесты не подтверждают доступ к реальным аккаунтам NVIDIA или OpenAI.

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

• Данные синтетические, горизонт — восемь кварталов; симулятор не подключён к городским системам и реальным показателям Астаны.
• Расчёт показывает последствия правил модели, а не доказывает причинный эффект мер в реальном городе.
• AI не выполняет числовой расчёт и не является свободным чат-ботом: он выбирает объясняющие факты из подготовленного сервером списка.
• Поиск улучшений проверяет допустимые одиночные замены и не гарантирует глобальный максимум.
• События, рейтинг команд, общая онлайн-база сценариев и вход пользователей не реализованы.
• Приложение привязано к 127.0.0.1 и доступно на компьютере, где запущен сервер. Публичная версия не развёрнута.

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

Публичной deployed-версии сейчас нет. Для совместной онлайн-работы проекту потребуется размещённый Node.js сервер и отдельная настройка защиты API-ключей, лимитов и хранения данных.

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

Путь	Назначение
public/index.html, public/styles.css, public/app.js	Пользовательский интерфейс и его поведение
server.js	Локальный HTTP-сервер и API приложения
src/engine.js	Синтетические данные, проверка правил и формула Score
src/analysis.js	Проверенные факты, анализ вкладов и поиск улучшений
src/ai.js	Offline-объяснение и адаптеры OpenAI/NVIDIA
src/presets.js	Пример задания и экономный пример
dist/akim-standalone.html	Однофайловая демонстрация без внешнего AI API
scripts/build-standalone.py	Сборка однофайловой демонстрации из исходников
.env.example	Шаблон локальной AI-конфигурации без секретов
tests/	Автоматические тесты
docs/	Инструкции команде, демонстрационный сценарий и отчёт о проверках

Если меняются HTML, стили, логика интерфейса или расчёта, однофайловую демонстрацию можно пересобрать командой python3 scripts/build-standalone.py. Она намеренно работает offline и не должна содержать API-ключи.