Аким на 5 часов — симулятор управления Астаной

1. Что делает проект

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

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

• Режим allocation: алгоритм получает лимиты по транспорту, озеленению, соцсфере, безопасности и городским сервисам. Он перебирает каталог M1–M14 и выбирает лучший допустимый набор ровно из пяти мер, не превышая каждый лимит и общий бюджет.
• Режим measures: пользователь сам выбирает пять уникальных мер и районы. Перед оценкой проверяются бюджет, число мер на сферу и несовместимости.
• Общая формула Astana Quality of Life Score для обоих режимов.
• Оптимизатор полного перебора, просмотр каталога, интерактивный CLI и машинный JSON-вывод.
• Локальный HTTP JSON API для оценки и симуляции сценариев.
• Четыре роли: Analytics & Math Engine, Astana Urban Expert, Social & Risk Agent и Akim Chief Advisor.
• Offline-отчёт без API-ключа; AI-объяснения через OpenAI Structured Outputs при наличии ключа.

3. Технологии и архитектура

Стек: Python 3.10+, OpenAI Python SDK (openai), Pydantic, python-dotenv; для тестов — pytest. Внешний агентский фреймворк не используется.

JSON / CLI → Pydantic-валидация → математический движок
                                      ↓
                           Analytics & Math Engine
                                      ↓
                       Urban Expert ∥ Social & Risk
                                      ↓
                      Akim Chief Advisor → JSON-отчёт

Python детерминированно проверяет решения, выбирает допустимый портфель и считает все числа. Urban Expert и Social & Risk получают рассчитанные факты и формируют объяснения. Chief Advisor объединяет результаты двух профильных ролей и Analytics в итоговый отчёт. Два профильных AI-вызова выполняются параллельно, затем запускается оркестратор. AI не меняет Score.

Для машинной интеграции предусмотрены POST /score (численная оценка), POST /simulate (отчёт агентов), а также /config, /validate и /optimal. API запускается локально на 127.0.0.1:8000; CORS выключен по умолчанию. При необходимости задайте Bearer-токен AKIM_API_TOKEN. Подробности модели: docs/ADVANCED.md.

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

Python 3.10 или новее. В терминале из корня проекта:

python -m venv .venv
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

Примеры локального запуска без API:

python main.py --input example_allocation.json --offline --json
python main.py --input example_measures.json --offline --json
python -m akim_sim --optimize

Для AI-объяснений скопируйте .env.example в .env, укажите OPENAI_API_KEY и уберите --offline. По умолчанию используется модель gpt-4o-mini; её можно переопределить через OPENAI_MODEL или --model. Ключ не добавляется в репозиторий. Без него отчёт строят правила, а численный Score остаётся тем же.

Запуск API: python -m akim_sim --serve. Параметры --host, --port и --api-token позволяют настроить локальный сервер и Bearer-аутентификацию. Не выставляйте API наружу без ограничения доступа.

5. Пример проверки

Запустите пример лимитов:

python main.py --input example_allocation.json --offline --json

В примере лимиты 25 / 15 / 25 / 15 / 20. Проверочные значения из текущего кода:

Astana Quality of Life Score: 56.015 / 100
Фактический расход: 85 условных единиц
Базовый Score: 52.558

Ручной пример из каталога даёт 56.543 при расходе 95. Полный перебор находит лучший допустимый портфель со Score 57.237 при расходе 98. Эти величины — условные игровые единицы, не смета в тенге. Полный перебор учитывает 694 395 допустимых размещений.

Для запуска тестов:

python -m pip install -r requirements-dev.txt
python -m pytest -q tests

example_allocation.json, example_measures.json и example_report.json содержат повторяемые примеры и результат.

6. Данные, внешние сервисы и ограничения

• Используются учебные районные показатели, доли населения, каталог мер, эффекты, лаги и синергии из проекта и переданных материалов кейса. Ссылки организаторов: описание кейса и датасет районов.
• При включённых AI-объяснениях используются OpenAI API и заданная модель; пользователь предоставляет OPENAI_API_KEY. Живой вызов API без пользовательского ключа не проверялся. Без ключа доступен локальный offline-режим.
• Соцсети, обращения жителей, погодные, дорожные и ЖКХ API не подключены. Индексы аварий, заторов и недовольства — модельные прокси, не реальные вероятности или измеренное мнение жителей.
• Данные и эффекты учебные. Анализ чувствительности изменяет веса показателей, а не моделирует реальный буран или паводок. Для решений городской политики нужны проверенные измерения и калибровка.
• В режиме allocation суммы являются верхними лимитами, а не прямыми расходами. Неиспользованный лимит сам по себе не повышает Score. Если правила каталога не позволяют выбрать ровно пять мер, расчёт не выдаёт Score.
• Не помещайте настоящий .env или секретный ключ в архив и исходники; используйте .env.example как шаблон.

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

Публичная развёрнутая версия и веб-интерфейс пока не опубликованы, поэтому ссылки на live-демо нет. Команда --serve запускает локальный JSON API на 127.0.0.1:8000.