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

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

Назначение: помочь городскому управленцу, аналитику или участнику учебной симуляции оценить последствия решений при ограниченном бюджете. Задача: «Аким на 5 часов» — AI-симулятор управления городом. Репозиторий команды: BAITC-Hacks/hack-55197c77-newbie.

Быстрый старт для проверяющего

Продукт запускается локально на компьютере проверяющего и открывается в браузере. Хостинг и аккаунт Render не нужны. Порядок проверки: получить код → настроить .env с тестовым ключом → запустить Python → проверить пример и AI-разбор.

Карта, численный расчёт, заключение по правилам и тесты работают без ключей. Для настоящего AI нужен интернет. Рабочий API-ключ и параметры подключения предоставлены командой в .env.example для пользователей приватного репозитория. Свой платный аккаунт OpenAI проверяющему не требуется. Статус передачи доступа указан в разделе «Доступ экспертов к AI» ниже. Заключение по правилам не выдаётся за ответ LLM.

Windows / PowerShell

Предварительно установите Python 3.10+ и Git. В новой папке выполните:

git clone https://github.com/BAITC-Hacks/hack-55197c77-newbie.git
cd hack-55197c77-newbie
py -3 --version
py -3 -m venv .venv
.\.venv\Scripts\python.exe -X utf8 -m unittest discover -s tests -v

Если py отсутствует, используйте python после проверки python --version. При получении проекта архивом распакуйте его и откройте терминал в папке с web_server.py, затем выполните команды создания окружения, тестов и запуска. Активировать окружение и менять ExecutionPolicy не требуется.

Linux / macOS

git clone https://github.com/BAITC-Hacks/hack-55197c77-newbie.git
cd hack-55197c77-newbie
python3 --version
python3 -m venv .venv
./.venv/bin/python -X utf8 -m unittest discover -s tests -v

Если в системе отсутствует venv, установите его средствами ОС либо запускайте проект установленным Python 3.10+; сторонних пакетов нет. Ожидаемый результат тестов: 28 тестов, OK, код завершения 0.

Настройка ключа для проверки AI

В корне проекта, рядом с web_server.py, скопируйте готовый .env.example в .env. В .env.example уже находятся действующий API-ключ, модель и адрес сервиса. Вручную вводить ключ не требуется. Следующие команды сохраняют существующий .env.

Windows / PowerShell:

if (!(Test-Path .env)) { Copy-Item .env.example .env }

Linux / macOS:

test -e .env || cp .env.example .env

Если .env уже существует, убедитесь, что в нём актуальные значения из .env.example: повторная команда копирования выше его не заменит. Файл должен называться именно .env, без дополнительного .txt. Python читает .env, а не .env.example. Пароль аккаунта участника не нужен.

В этой закрытой сдаче .env.example содержит действующий ключ и предназначен для проверяющих с доступом к репозиторию. Не переносите его в публичные материалы.

Запуск и проверка

Windows / PowerShell:

.\.venv\Scripts\python.exe -X utf8 web_server.py

Linux / macOS:

./.venv/bin/python -X utf8 web_server.py

Откройте http://127.0.0.1:8000, нажмите «Загрузить пример» → «Рассчитать сценарий». Ожидаются Score 56,54, остаток бюджета 5, критических показателей 0. Затем нажмите «Получить AI-анализ» и дождитесь надписи «Ответ AI получен» с моделью и временем. Должны появиться общий вывод, сильные стороны, риски, рекомендации и объяснения пяти выбранных мер и пяти направлений. Score после получения AI-разбора остаётся 56,54: текст модели не меняет формулу.

Для проверки собственного сценария измените район меры M7 с Нуры на Есиль, повторно рассчитайте и запросите AI. Ожидаются Score 55,30 и один критический показатель; предыдущий AI-разбор скрывается при изменении выбора.

Терминал оставьте открытым; остановка сервера — Ctrl+C. Адрес 127.0.0.1 относится к компьютеру, на котором запущена программа.

Если не запускается

Ситуация	Что проверить
py или python не найден	Установлен ли Python 3.10+; после установки открыть новый терминал
web_server.py не найден	Команды выполняются из папки hack-55197c77-newbie
Порт 8000 занят	Запустить с --port 8001 и открыть http://127.0.0.1:8001
«AI не настроен»	.env находится рядом с web_server.py, не имеет расширения .txt; ключ и модель заполнены
AI отклонил ключ / нет доступа к модели	Проверить выданные командой параметры; запросить у команды исправленный тестовый доступ
Лимит AI или баланс исчерпан	Команда должна восстановить тестовый доступ; расчёт по правилам продолжает работать
Нет связи или тайм-аут AI	Проверить доступ в интернет; повторить по кнопке, не меняя результаты расчёта

Надпись «Настройки AI найдены» означает только наличие параметров. Успешная проверка AI подтверждается ответом модели, а не этой надписью и не текстом по правилам.

Технологии, системные требования и зависимости

Компонент	Требование / применение
Python	3.10 или новее; расчёт, HTTP API, вызов AI и тесты
Браузер	Современный Chrome, Edge или Firefox с JavaScript
Интерфейс	HTML, CSS, JavaScript и встроенная SVG-карта
Данные	JSON-файлы; база данных не требуется
AI	OpenAI Chat Completions; модель задаётся через AI_MODEL
Сеть	Для получения репозитория и новых AI-ответов; расчёт работает без сети

Внешних Python-зависимостей нет: используется стандартная библиотека (http.server, urllib, json, math, unittest и др.). pip install не нужен. Node.js, Java, Docker, IDE и API карт не требуются для запуска. Разработка и проверка выполнялись на Windows, Python 3.12.14. Инструкции для Linux/macOS приведены, отдельная проверка этих ОС пока не заявляется.

Текущее состояние

Реализованы исходный датасет, валидатор решений, воспроизводимый расчёт Score и локальный веб-интерфейс с интерактивной картой районов и письменным заключением. Добавлен модуль реального LLM-анализа через API: модель объясняет готовый расчёт, сочетание решений, риски и возможные реакции жителей. Для его работы нужно настроить доступ к AI-сервису. Без доступа работает явно обозначенный разбор по правилам. Интеграция проверена автоматическими тестами с подменой ответа провайдера и настоящим запросом к OpenAI API с моделью gpt-6-luna 23 сентября 2026 года. На примере организаторов получены пояснения всех пяти мер и пяти направлений, сильные стороны, риски и рекомендации. Контрольный Score остался 56,54307. Для локальной проверки экспертов действующие настройки включены в .env.example приватного репозитория. Статус проверки доступа по п. 5.6.6 указан ниже.

Интерактивная карта

В корне проекта запустите:

python -X utf8 web_server.py

Откройте http://127.0.0.1:8000 в браузере. Окно терминала оставьте открытым; Ctrl+C останавливает сервер. Если порт занят, используйте python -X utf8 web_server.py --port 8001 и откройте соответствующий адрес. В PyCharm можно запустить web_server.py или выполнить команду во встроенном Terminal.

1. Нажмите на район на карте или на кнопку с его названием под картой.
2. Справа появятся оценка района, доля населения и десять шкал по пяти направлениям. На широком экране паспорт закреплён рядом с картой и списком решений; если все шкалы не помещаются, прокрутите содержимое паспорта. На узком экране паспорт расположен под картой.
3. Показатели ниже 40 отмечены как критические; пунктир на шкале обозначает порог 40.
4. Нажмите «Загрузить пример», затем «Рассчитать сценарий».
5. Балл города должен стать 56,54, остаток бюджета — 5, критических значений — 0.
6. Выберите Нуру: школы изменятся с 38 до 48, поликлиники — с 35 до 43,75.
7. Переключайте «До / После», чтобы сравнивать результаты.
8. Под результатом расчёта нажмите «Читать заключение о последствиях»: отображаются общий вывод, изменения пяти направлений, нерешённые проблемы и объяснение каждого из пяти выбранных мероприятий.

Письменное заключение

Заключение воспроизводимо и работает без сети и ключей. Оно формируется модулем conclusions.py из готового расчёта и авторских пояснений всех 14 мероприятий. Это генерация по правилам, не LLM. Для AI-анализа нажмите отдельную кнопку после подключения модели, как описано ниже.

• Числа берутся из модели: бюджет, Score, дельты, задержки, критические показатели и синергии.
• Реакции жителей обозначены как возможные гипотезы, а не опрос или проценты довольных.
• Неизменившиеся направления не объявляются ухудшившимися из-за отсутствия расходов.
• Побочные эффекты между направлениями учитываются: например, M3 улучшает E2 даже при нулевых прямых расходах на экологию. Объёмы CO₂ не вычисляются.
• Для M1 возможны возражения автомобилистов, но текст не утверждает рост пробок: T1 в датасете растёт. Для M11, напротив, снижение T1 — явный компромисс модели.
• Эффекты отдельных мер показываются после учёта задержки, до ограничения 0–100; синергии выделены отдельно. Средние показателей по направлениям взвешены по населению.
• Порог 50 в списке остаточных проблем — пояснительный ориентир, а не новый штраф.
• При редактировании сценария старое заключение скрывается до нового расчёта.

После успешного расчёта в разделе «Что изменят ваши решения» доступна кнопка «Скачать отчёт .txt». Файл в UTF-8 содержит текущие меры и районы, бюджет, Score, показатели районов до и после и заключение по правилам. Если настоящий AI-ответ уже получен, в отчёт добавляются его полный текст, модель и время ответа; если доступен вариант А — численное сравнение А/Б. Скачивание не обращается к AI и не требует нового ключа. Кнопка недоступна во время AI-запроса и после изменения решений до повторного расчёта.

Можно составить собственный набор из 14 мероприятий и выбрать районы их реализации. Над списком закреплена панель «Осталось на решения»: остаток из 100 усл. ед., шкала и число выбранных мер. При остатке 25 и меньше панель становится жёлтой, при 10 и меньше — красной. Меры дороже остатка недоступны: карточка показывает, сколько средств не хватает. При пяти выбранных мерах остальные блокируются. Снять выбранную меру можно всегда — её стоимость сразу возвращается в бюджет. При выборе районной меры паспорт показывает район её реализации.

Расчёт запрещён при неполном наборе. Сервер дополнительно проверяет бюджет и остальные ограничения: он возвращает причины, если сценарий невалиден. При изменении выбора предыдущий результат сбрасывается, чтобы не показывать устаревшие показатели. Текущий несохранённый выбор Б хранится в памяти страницы и сбрасывается при обновлении. Сохранённый вариант А остаётся доступен в том же браузере.

Карта — авторская приближённая SVG-схема Астаны: Есиль, левый и правый берег, пять районов, проспект Кабанбай батыра и несколько ориентиров. Взаимное расположение районов опирается на официальную схему 2023 года. Контуры, дороги и положения ориентиров обобщены; это не точная географическая карта. Сохранены именно пять районов задания; карта не заявляет актуальные административные границы города. Показатели и население берутся только из учебного датасета. Внешние карты, интернет и API-ключи для карты и численного расчёта не нужны. Цвет района соответствует оценке D: ниже 50, от 50 до 60, от 60. Это отдельная визуальная шкала; официальный критический порог 40 применяется к каждому из десяти показателей. HTML/CSS/JavaScript отображают интерфейс, все итоговые расчёты выполняет Python. Сервер доступен только на этом компьютере.

Сохранение и сравнение сценариев А/Б

После успешного расчёта нажмите «Сохранить как А». Измените решения или районы и рассчитайте текущий вариант Б: таблица покажет Score города, затраты, остаток бюджета, число критических показателей и оценки пяти районов для обоих вариантов, а также разницу Б − А. При редактировании Б его устаревшие результаты скрываются до нового расчёта; сохранённый А не меняется. Кнопка «Заменить вариант А» сохраняет вместо него текущий рассчитанный сценарий.

«Восстановить А» возвращает выбранные меры и районы и заново рассчитывает их через Python. Сохранение и восстановление не отправляют запросов к AI: для нового объяснения нажмите «Получить AI-анализ» отдельно.

Вариант А хранится в localStorage браузера для того же адреса и порта. Сохраняются только решения и время сохранения, без API-ключа и текста AI. После обновления страницы А снова проходит проверку и расчёт на сервере; несохранённый Б не восстанавливается. Если браузер запрещает сохранение, интерфейс сообщает об этом: сравнение доступно в текущем сеансе, но новый А не сохранится после обновления страницы.

Пример проверки: загрузите пример организаторов, рассчитайте и сохраните А, затем поменяйте район M7 с Нуры на Есиль и рассчитайте Б. Score изменится с 56,54307 на 55,29777 (Б − А: −1,24530), число критических показателей — с 0 на 1. В обоих вариантах затраты равны 95, остаток бюджета — 5.

Консольная проверка и тесты

Нужен Python 3.10 или новее. Сторонние библиотеки не требуются. Карта, расчёт и заключение по правилам работают без сети. Для AI-анализа нужен интернет и API-ключ. Все команды выполнять в корне репозитория.

python --version
python main.py
python main.py examples/organizer.json
python -m unittest discover -s tests -v

Для Linux/macOS используйте python3, если python отсутствует. Вывод — JSON с показателями, оценками районов, расходами и итоговым score. Некорректный сценарий возвращает valid: false, score: null, причины в errors и код завершения 2. Он не получает фиктивный числовой балл.

Контрольный пример

Без действий: Score 52.55768; среднее города 56.8624; минимальная оценка района 49.18; критических показателей 2.

examples/organizer.json: M7, M8, M10 в Нуре, M12 по городу, M5 в Сарыарке. Стоимость 95, остаток 5, Score 56.54307, критических показателей 0. Это соответствует примеру организаторов.

Чтобы проверить другой сценарий, скопируйте JSON-пример, замените меры/районы и передайте путь к новому файлу в python main.py путь/сценарий.json. Для городской меры поле district не требуется; null также означает отсутствие района.

Дополнительные проверки

• Поменяйте в примере район M7 с Нуры на Есиль. Старый отчёт скроется, после пересчёта изменится Score, а школьный показатель Нуры останется критическим.
• Выберите четыре меры: кнопка расчёта недоступна.
• Выберите M3, M2, M13, M9: останется 10 усл. ед., панель станет красной. M10 за 12 будет недоступна, M11 за 10 останется доступна. После добавления M11 остаток равен 0; после снятия M13 — 28, и доступные по цене меры снова можно выбрать.
• M1, M3, M4, M9, M10 стоят 85, но сервер должен отклонить конфликт M1/M3.
• При отсутствии AI-ключа численный расчёт работает, а кнопка AI показывает сообщение о настройке доступа. Это не считается успешной проверкой LLM.

Независимый запуск из копии отслеживаемых файлов описан в протоколе проверки.

Доступ экспертов к AI — п. 5.6.6 Положения

Выбранный способ: локальный запуск по этому README. Действующий ключ команды и параметры модели находятся в .env.example приватного репозитория; проверяющий копирует файл в .env. Размещение публичного сайта не используется.

Статус: локальный запрос OpenAI проверен; файл настроек заполнен и проверен загрузчиком приложения. После получения актуальной версии репозитория эксперты могут использовать эти настройки. Успешный запуск на компьютере эксперта ещё не подтверждён. Команда обеспечивает доступный лимит на период проверки.

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

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

Для карты, численного расчёта и тестов параметры не обязательны. Для нового AI-ответа требуются первые две переменные:

Переменная	Назначение / значение
AI_API_KEY	Секретный ключ проверочного AI-доступа; обязателен для LLM
AI_MODEL	Идентификатор модели; в .env.example указан gpt-6-luna
AI_BASE_URL	По умолчанию https://api.openai.com/v1; HTTPS-адрес без параметров и ключей в URL
AI_OUTPUT_FORMAT	json_schema по умолчанию; json_object для совместимого API без JSON Schema

Используются простые строки KEY=value в .env; пустые строки и комментарии с # допускаются. Подстановка переменных и исполнение команд в файле не выполняются. Переменные окружения имеют приоритет над .env. Изменения читаются при запросе. Порт задаётся аргументом --port, а не переменной окружения.

Подключение AI

1. Для проверки используйте готовые настройки из .env.example этого приватного репозитория. Ключ, модель и адрес относятся к одному сервису.

2. Создайте локальный .env из готового файла (существующий файл не перезаписывается):

   if (!(Test-Path .env)) { Copy-Item .env.example .env }
   

3. Ключ уже заполнен. В файле выбрана AI_MODEL=gpt-6-luna — экономичная модель OpenAI с поддержкой structured outputs. Доступность в вашем API-проекте проверяется реальным запросом; при необходимости укажите другую доступную совместимую модель. Для OpenAI оставьте AI_BASE_URL=https://api.openai.com/v1; для другого совместимого сервиса укажите его документированный HTTPS-адрес. Модель должна поддерживать Chat Completions и max_completion_tokens. По умолчанию используется AI_OUTPUT_FORMAT=json_schema; если сервис поддерживает только JSON mode, задайте json_object. Это адаптер совместимого API, не поддержка любых моделей.

4. Настройки перечитываются при запросе, перезапуск не требуется. .env исключён из Git; .env.example намеренно включён в закрытую сдачу. Переменные окружения с теми же именами имеют приоритет над .env.

5. В интерфейсе загрузите пример, рассчитайте сценарий и нажмите «Получить AI-анализ». Дождитесь надписи «Ответ AI получен» с моделью и временем. Наличие настроек само по себе не подтверждает доступ к API.

Для Linux/macOS создайте файл командой test -e .env || cp .env.example .env.

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

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

Ошибки ключа, лимита, сети, отказ или неполный ответ показываются отдельно. Автоматических повторов нет. Повторная попытка — по кнопке; одновременно выполняется не более одного AI-запроса. При смене решений ответ старого сценария скрывается. Сервис ожидается до 60 секунд на сетевую операцию; очень медленный ответ может занять дольше. Ответ ограничен по размеру, проверяется наличие ровно пяти выбранных мер и всех пяти направлений. Проверка структуры не гарантирует фактическую точность текста модели.

Для проверки без расходов на API запустите общий набор тестов: ответы провайдера в тестах заменены явно обозначенными фикстурами. В рабочем приложении тестовых AI-ответов нет. Настоящий запрос на примере организаторов и качество его текста проверены 23 сентября 2026 года: ответ охватил все выбранные меры, реакции жителей были обозначены как возможные, отсутствие вложений не объявлялось ухудшением. Сброс устаревшего разбора при смене сценария проверен отдельно с тестовым ответом. После изменения ключа, модели или окружения повторите проверку реального запроса.

Протокол: Structured Outputs в OpenAI API.

Правила и формула

• Бюджет 100, ровно пять уникальных мероприятий, не более двух из одного направления.
• Район обязателен для районной меры. Городская мера действует на все районы.
• Учитываются все три несовместимости и три синергии из датасета.
• Эффект меры умножается на (8 - lag) / 8; бонус синергии не масштабируется.
• Показатели ограничиваются диапазоном 0–100 после сложения всех эффектов.
• Оценка района — сумма показателей с заданными весами.
• Score = 0.7 * population_weighted_average + 0.3 * minimum_district_score - critical_count.
• Критическим считается значение строго меньше 40. Округление внутри расчёта не применяется.

Принятая трактовка: используются подробные правила датасета: пять мер могут охватывать не все пять направлений. Это соответствует контрольному примеру. В общем ТЗ формулировка про пять направлений отличается; трактовку необходимо подтвердить у организаторов.

Архитектура

Браузер: выбранные меры и районы
             |
             v
web_server.py -> simulator.py -> валидация -> расчёт по data/city.json
             |                                  |
             +-> conclusions.py <---------------+
             |   пояснения по правилам           |
             +-> ai_analysis.py <---------------+
                 OpenAI API -> проверка JSON -> объяснение в интерфейсе

Сервер повторно проверяет и рассчитывает сценарий перед вызовом AI; готовый Score от браузера не принимается. Ответ AI не изменяет числовую модель.

• data/city.json — неизменяемые исходные условия, веса, каталог мер и правила.
• simulator.py — проверка сценария и детерминированная математика.
• conclusions.py — письменный разбор рассчитанного сценария.
• ai_analysis.py — настройки, промпт, вызов LLM и проверка структуры AI-ответа.
• .env.example — готовые настройки с действующим ключом для закрытой проверки; копируется в локальный .env.
• data/measure_explanations.json — логика 14 мер и гипотезы реакции жителей.
• main.py — консольный интерфейс и чтение JSON.
• web_server.py — локальный HTTP-сервер и API расчёта на стандартной библиотеке Python.
• web/ — интерактивная SVG-карта, карточки районов, выбор мер и шкалы до/после.
• examples/organizer.json — проверочный сценарий.
• tests/test_simulator.py — контрольные расчёты и проверки ограничений.
• tests/test_web.py — проверка HTTP-запуска, расчёта и обработки ошибочных запросов.
• tests/test_conclusions.py — фактическая согласованность заключений с расчётом и покрытие всех мер.
• tests/test_ai_analysis.py — контракт LLM, ошибки сервиса, конфигурация и отсутствие утечек ключа.

LLM-модуль объясняет готовые расчёты и компромиссы; он не является источником чисел или заменой валидатора. Вклад отдельных мер выводится как изменение показателей до ограничения диапазона, а не как аддитивный вклад в нелинейную итоговую формулу Score.

Источники и ограничения

• ТЗ организаторов
• Датасет и правила организаторов
• Положение Хакатона
• Сторонние компоненты, источники и использование AI

Данные синтетические. Результат — учебная модель, не прогноз реальных последствий городских инвестиций. Каталог, значения и формула перенесены из документов организаторов. Код, интерфейс, тесты, пояснения и документация разработаны с существенной помощью OpenAI Codex; это использование AI раскрывается по п. 5.4.4 Положения. Используется только стандартная библиотека Python. .env и .venv исключены из Git; действующий проверочный ключ намеренно включён в .env.example приватной сдачи.

Поиск оптимума и случайные события пока не реализованы. Локальный HTTP-сервер текущей версии не предназначен для публичного production-размещения без отдельной настройки серверной части.

Подготовка к сдаче

Презентация и материалы выступления находятся в папке presentation.

Чек-лист Положения содержит соответствие обязательных материалов требованиям и незавершённые организационные действия. По предоставленному участником п. 5.4.13 финальная версия фиксируется 23 сентября 2026 в 18:00 по времени Астаны. Код и документы должны быть отправлены в репозиторий Организатора до этого момента. Оформление README не подтверждает автоматически check-in, присутствие, почасовые результаты и выполнение дополнительных требований канала сдачи.