AKIM

Проверяемая лаборатория бюджетных решений для городского управления

Python 3.11+ · FastAPI · React + TypeScript · Docker Compose

Запуск · Демо · Архитектура · API · Планы

Городские решения конкурируют за один бюджет, а их эффект трудно проверить до запуска. AKIM рассчитывает Astana Quality of Life Score (AQOL) по условию «Аким на 5 часов» и показывает проверяемые причины изменения результата.

AKIM в действии — видеообзор

Короткое знакомство с AKIM и интерфейсом городской лаборатории — за одну минуту.

▶ Смотреть видеообзор · 60 секунд · Full HD

Два режима

V1 сохраняет исходные правила без изменений. V2 получает отдельные версии данных, моделей и метрик. Модельные реакции жителей не меняют официальный Score V1.

Текущий статус

Реализован бэкенд V1: API, evaluator, Data Gate, локальный поиск альтернатив, отчёт с evidence. Фронтенд из актуального main подключён к API через адаптер; Compose поднимает оба слоя. В этой ветке добавлен бэкенд V2-demo: отдельный worker, PostgreSQL, события, часы, checkpoint/ветки, парные эксперименты и экспорт. Интерфейс из codex/aygerim-v2-preview объединён с этим бэкендом: кнопка «Снегопад · V2» запускает реальный worker через API. Остальные исследовательские экраны пока остаются preview; расчёт V1 доступен по /?mode=v1. AI и альтернативы V1 пока доступны через API/Swagger, но не подключены к кнопкам текущего интерфейса. LLM-адаптер проверен тестовыми ответами; живой вызов провайдера в этом прогоне не выполнялся. Без ключа явно возвращается mode: rule-based.

Полная исследовательская платформа из ТЗ не объявляется завершённой: транспорт пока агрегированный, нет мультимодального графа, калибровки, модулей озеленения/безопасности и полного десятилетнего политико-бюджетного сценария. Реализованное и ограничения V2 · Контракт для фронтенда.

Быстрый старт

Нужно: запущенный Docker Desktop в режиме Linux containers (или Docker Engine) с Docker Compose v2.20+ (или v5), Git и интернет для первой сборки. Python/Node на хосте для этого способа не нужны. Объединённая версия находится в main:

git clone --branch main https://github.com/BAITC-Hacks/hack-d4922f7f-attractor.git
cd hack-d4922f7f-attractor
docker compose up --build -d --wait

После клонирования запуск всего проекта — одна последняя команда, без обязательного .env и без ключей. Compose собирает web (React + nginx) и api (FastAPI + engine + Data Gate), worker V2 и db (PostgreSQL); ждёт healthcheck. База не публикует порт на хост. Для стабильного V1 без V2 сохранена ветка fix/backend-readiness.

В новом интерфейсе выберите «Снегопад · V2» и дождитесь 360 / 360 мин · completed. Для V1 откройте «Расчёт V1» → «Загрузить контрольный сценарий» → «Рассчитать»: ожидаемый Score — 56.54307.

Проверьте сквозной сценарий (каталог → расчёт → альтернативы → отчёт):

docker compose exec -T api python -m scripts.demo_backend
docker compose exec -T api python -m scripts.demo_backend --url http://web/api
docker compose exec -T api python -m scripts.demo_v2

Вторая команда проверяет также nginx-прокси, которым пользуется браузер. Ожидается score: 56.54307, cost: 95, analysisMode: rule-based. Третья воспроизводит снегопад, ветку с переброской бригады, сравнение по трём seed, evidence-отчёт и проверяет ZIP-экспорт. Она не вызывает платный LLM.

docker compose ps
docker compose logs --tail=100 api worker db
docker compose down
docker compose up --build -d --wait

Запуск без Docker

Нужно: Python 3.11+, доступ к PyPI для установки. БД и ключ LLM для demo не нужны. Из корня клонированного репозитория, PowerShell:

python -m venv .venv
.venv/Scripts/python -m pip install -c requirements.lock ".[test]"
.venv/Scripts/python -m unittest discover -s tests -t .
.venv/Scripts/python -m uvicorn services.api.app:app --host 127.0.0.1 --port 8000

python3 -m venv .venv
.venv/bin/python -m pip install -c requirements.lock ".[test]"
.venv/bin/python -m unittest discover -s tests -t .
.venv/bin/python -m uvicorn services.api.app:app --host 127.0.0.1 --port 8000

Swagger UI · Каталог. API сам импортирует и публикует официальный исходник. Хранилище: var/data-gate относительно текущего каталога. Запускать один worker. Для V2 запустите ещё один терминал из того же каталога: .venv/Scripts/python -m engine.v2.infrastructure.worker (Linux/macOS: .venv/bin/python -m engine.v2.infrastructure.worker). Без AKIM_DATABASE_URL API и worker используют локальный SQLite-файл var/v2/state.sqlite3; в Compose всегда используется PostgreSQL. AKIM_RUN_TOKEN защищает изменяющие V2-запросы; пустое значение допустимо только для локального однопользовательского демо. AKIM_ADMIN_TOKEN отдельно защищает Data Gate. Это запуск только API. Для локальной разработки интерфейса дополнительно нужны Node.js 22 и npm: в apps/web выполните npm ci и запустите npm run dev с VITE_API_PROXY=true в окружении. Без этого переключателя калькулятор /?mode=v1 использует fixtures; новый preview всегда обращается к локальному API через /api. В Compose нужный адрес /api встраивается автоматически при сборке. Основная точка входа — services.api.app:app; старый api.main оставлен как legacy, Compose его не запускает. Прототип api/v2.py из preview-ветки также сохранён как legacy: он не подключён к production-router и не подменяет сохраняемые прогоны V2.

Демо бэкенда

Во втором терминале, пока сервер запущен:

.venv/Scripts/python -m scripts.demo_backend

Проверяются каталог/версии → контрольный расчёт → отказ неполному набору → альтернативы → evidence-backed report. Сохранённый реальный HTTP-прогон: backend-demo.json.

Для POST /v1/evaluate в Swagger:

{
  "selections": [
    {"measureId": "M7", "districtId": "nura"},
    {"measureId": "M8", "districtId": "nura"},
    {"measureId": "M10", "districtId": "nura"},
    {"measureId": "M12", "districtId": null},
    {"measureId": "M5", "districtId": "saryarka"}
  ]
}

Результат: valid: true, cost: 95, score: 56.54307. aqolScore — алиас Score. Для интеграции передавайте также versions целиком из GET /catalog.

Архитектура

Домен/application движка не импортируют FastAPI, OpenAI SDK или Data Gate. Composition root services/api/runtime.py переводит опубликованный payload в immutable модель. Пользовательские импорты не подменяют официальный V1. create_official_service() оставлен как загрузчик эталонного fixture.

Брифы для будущих изображений: README-VISUALS.md. Целевая архитектура с V2: docs/02-architecture.md.

Как считается V1

I′ = clip(I + Σ effect × (8 − lag) / 8 + synergy, 0, 100)
Ddistrict = Σ weight × I′
Score = 0.7 × Davg + 0.3 × min(Ddistrict) − Ncritical

Нужно ровно пять мер, не больше двух одного направления, а не по одной каждой категории. Промежуточные значения не округляются. Критичность — строго ниже 40; остаток бюджета бонуса не даёт. LLM не считает Score. Полная спецификация.

Проверенные результаты

Локально: Windows/Python 3.12.10; проверены Linux-контейнеры через Docker Desktop. CI для Python 3.11/3.12 и Compose добавлен; удалённый результат пока не подтверждён.

V2-числа — результат синтетического опыта за 840 модельных минут, а не прогноз реального города. Интервал по трём seed иллюстрирует воспроизводимость, но слишком мал для исследовательского вывода. Полный протокол и исходы: v2-demo.json. Бюджет выполним в обеих ветках; равенство фактических расходов не заявляется.

API-first контракты

Неверная структура → 422; устаревшие версии / запрещённая публикация → 409; нет доступа → 403; body >1 200 000 байт → 413. Ошибки: error: {code, field, message}. Контракты и расхождения с черновым frontend-клиентом.

AI и конфигурация

LLM выбирает/упорядочивает готовые evidence IDs. Сервер проверяет категорию, обязательные риски и полноту, затем подставляет собственные числа и фразы. Это ограниченный evidence-аналитик, не свободный городской агент. Невалидный ответ: один repair, затем шаблон. Ошибка провайдера не ломает расчёт.

.env.example — шаблон для необязательного .env. Compose читает .env автоматически, прямой Python — нет (экспортируйте переменные в оболочку). Ключи не коммитьте: .env исключён из Git и Docker build context. Лимиты LLM: один одновременный анализ, deadline 20 секунд, ≤3 вызовов включая repair, ≤800 output tokens/вызов; SDK retries отключены. Это не денежный лимит: настройте бюджет проекта провайдера.

Data Gate

Поддержаны исходник задания, City JSON, GeoJSON WGS84, синтетический V2 City, CSV/XLSX/JSON для нормализованных наблюдений с единицами, provenance и тремя временами. Это определённые схемы, не автоматическое понимание произвольной таблицы. Дубли JSON-ключей, NaN/Infinity, неверные типы/даты/ссылки не исправляются молча. Критические ошибки блокируют публикацию; checksum staging и snapshot проверяется при чтении. Идентичность импорта учитывает байты, формат, паспорт и transform version.

.venv/Scripts/python -m data_gate --store var/data-gate bootstrap

CLI и правила миграции.

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

engine/v1/          правила, evaluator, application service, локальный search
engine/v2/domain/   scheduler и чистые переходы синтетического города
engine/v2/application/ прогоны, команды, checkpoint, ветки, replay, эксперименты
engine/v2/infrastructure/ Data Gate adapter, PostgreSQL/SQLite, отдельный worker
data_gate/          import, quality, snapshots, файловые/in-memory adapters, CLI
services/api/       HTTP-модели, маршруты, доступ, composition root
ai/                 evidence policy и Responses adapter
packages/contracts/ domain JSON Schema и генерируемый OpenAPI
data/               исходник и эталонный fixture (входят в wheel)
tests/              golden, regression, integration, search, AI contract tests
scripts/            HTTP demo, OpenAPI export, wheel smoke
apps/web/           React UI и адаптер HTTP-контрактов
compose.yaml        API + worker + PostgreSQL + существующий web; volumes и healthchecks
deploy/             nginx reverse proxy для web → API
docs/               спецификации, аудит, evidence
assets/             логотип и будущие изображения README

Что дальше

Перед защитой: подключить кнопки AI/альтернатив, записать демо, проверить живую LLM-модель и сравнить пользу с rule-based baseline, получить зелёный CI. Сроки не зафиксированы.

Следующий этап: расширить engine/v2/domain графом маршрутов и полным бюджетным циклом; вынести event log из JSON-документа в отдельную PostgreSQL-таблицу, добавить RBAC и измерить задержки на длинном горизонте. Очередь, worker и replay уже есть.

Дальше: реальные разрешённые данные, калибровка/holdout, новые SourceParser adapters и анализ параметрической неопределённости поверх ансамблей V2. Первое ограничение роста — размер полного run-документа и журналов; масштабирование обосновывается измерениями, не числом нарисованных агентов.

Ограничения

• V1 — синтетическое задание, не прогноз и не доказательство причинного эффекта.
• Поиск локальный: глобальный максимум не заявляется.
• Live LLM и пользовательские исследования не подтверждены этим прогоном. UI собирается и связан с API; это ещё не полная UX-приёмка.
• V2 — частичный V2-demo, не полная реализация всех MUST ТЗ. Коридорное время поездки — модельный proxy, не измеренный P90; интервалы seed не являются confidence interval. В стратегическом режиме услуги агрегируются по суткам, месяц равен 30 дням. Субсуточную погоду проверяйте в оперативном режиме.
• Файловый Data Gate: один процесс-писатель; не запускайте CLI/API одновременно на одном хранилище. Lock API не заменяет межпроцессные транзакции.
• Нет готового публичного production deployment, RBAC, постоянного бюджета LLM или нагрузочного отчёта. Compose — локальный demo-профиль, не production.
• npm audit обнаруживает critical XSS в пришедшем из main [email protected] (GHSA-jrc7-96c5-q579). Исправление начинается с 6.4.1; перед публичным показом нужен проверенный major upgrade. Внешний стиль карты использует затронутый attribution-путь; localhost не устраняет XSS.
• Отдельная лицензия и состав команды пока не опубликованы.

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

Продукт · Архитектура · V1 · V2 · Данные · AI · Исследования · План.

Оценка по обеим рубрикам, исправления и приоритеты: BACKEND-AUDIT.md.

Данные предоставлены в условии задачи. «Исследовательская платформа» означает воспроизводимые гипотезы и прозрачные допущения, а не подтверждённую точность на реальном городе.