Astana AI — Urban Decision Intelligence

Проблема

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

Решение

• Deterministic simulation engine проверяет ограничения и рассчитывает последствия сценария.
• Scenario optimizer ищет допустимые комбинации и ранжирует альтернативы под цель пользователя.
• AI advisor интерпретирует запрос, анализирует текущий план и объясняет результаты.
• Frontend dashboard позволяет собрать план, увидеть before/after, сравнить альтернативы и применить предложение к конструктору.

Ключевой принцип

LLM не рассчитывает числа. Score, бюджет, значения показателей, эффекты, синергии, критические показатели и районные оценки поступают из simulateScenario(input: ScenarioInput): SimulationResult.

Optimizer сравнивает готовые результаты; стоимость из каталога используется только для отсечения заведомо недопустимых вариантов. AI выбирает акценты среди проверенных фактов, а числовой текст формируется приложением из результатов движка. Frontend отображает результаты и не воспроизводит формулы.

Архитектура

Frontend
  → Advisor API / Scenario Builder
  → Optimizer
  → Simulation Engine
  → Synthetic Track Dataset

Ручной конструктор вызывает движок напрямую. Advisor использует POST /api/advisor. Общие типы: src/types/domain.ts; контракт Advisor: docs/advisor-api.md.

Данные

Источник — синтетический датасет, предоставленный организаторами кейса Astana Innovations «Аким на 5 часов».

• 5 районов: Есиль, Алматы, Сарыарка, Байконур, Нура.
• 10 показателей качества жизни.
• 14 мер в 5 направлениях.
• Бюджет: 100 условных единиц.
• Ровно 5 уникальных решений в сценарии.
• Горизонт: 8 кварталов.

Формула симуляции

Эффекты мер корректируются с учётом задержки: effect × (8 − lag) / 8. Затем добавляются заданные синергии, а значения показателей ограничиваются диапазоном 0–100. Совместимость, район/город, бюджет и лимит двух мер одного направления проверяются до расчёта.

Районный Score — взвешенная сумма показателей. Средний городской результат учитывает доли населения. Итоговый QoL Score:

Score = 0.7 × средний районный Score
      + 0.3 × Score слабейшего района
      − количество показателей строго ниже 40

Контрольный сценарий: M7, M8, M10 в Нуре; M12 на весь город; M5 в Сарыарке. Движок возвращает стоимость 95, остаток 5, Score 52.55768 → 56.54307 и критические показатели 2 → 0.

AI / Agent flow

Natural language goal
  → validated structured objective
  → deterministic search
  → simulate candidates
  → Top-3
  → grounded explanation

Поддерживаются maximize_city_score, improve_district, reduce_critical_indicators, balanced_development. При reduceCritical=true первично уменьшение числа критических показателей, затем район и целевые показатели, затем общий Score, стоимость и стабильный tie-breaker. Для сбалансированного развития дополнительно приоритетен результат слабейшего района. Top-3 содержит разные наборы мер.

Одинаковая структурированная цель и версия датасета дают одинаковое ранжирование. Интерпретация свободного текста внешней моделью может варьироваться.

Анализ текущего плана

Если передан currentScenario, сервер повторно вызывает настоящий simulateScenario() и добавляет необязательное поле currentScenarioAnalysis. Анализ содержит исходный SimulationResult, сильные стороны, слабые места, оставшиеся критические показатели, минимальные изменения по цели и сравнение с каждой альтернативой. Старые поля ответа сохранены.

Стоимость сравнивается с результатом цели по готовым сценариям; система не приписывает отдельной мере неподтверждённую неэффективность. Невалидный план получает диагностику движка без выдуманного after-state. Русское объяснение и сравнение доступны также без OpenAI.

Tech stack

Next.js 16 (App Router, Turbopack), React 19, TypeScript 5, Vitest 4. OpenAI Responses API вызывается серверным fetch; дополнительный SDK не требуется. Стили — CSS Modules.

Системные требования

Node.js >= 20.9.0 и npm. Для разработки и проверки используется корень репозитория.

Установка

npm install

Для воспроизводимой установки по package-lock.json:

npm ci

Создайте .env.local по образцу .env.example:

OPENAI_API_KEY=...
OPENAI_MODEL=gpt-4o-mini

Ключ нужен только для внешней модели. Без ключа применяется deterministic fallback. Пустой OPENAI_MODEL использует gpt-4o-mini. Не используйте префикс NEXT_PUBLIC_ для ключа и не коммитьте .env.local.

npm run dev

Откройте локальный адрес, показанный Next.js в терминале.

Проверка

npm test
npm run typecheck
npm run build

typecheck сначала создаёт Next.js-типы маршрутов, поэтому работает и без существующей .next. Тесты проверяют reference scenario, ограничения, приоритеты optimizer, анализ текущего плана, API errors и fallback при недоступности OpenAI. Тесты модели используют подменённый HTTP и не тратят API-кредиты.

Demo flow

1. Показать baseline: Score 52.56, слабейший район Нура, два критических показателя.
2. Выбрать пять инициатив контрольного сценария.
3. Нажать «Рассчитать сценарий».
4. Показать before/after: около 56.54, бюджет 95, критические 2 → 0.
5. Спросить AI: «Улучши Нуру и убери критические социальные показатели, не выходя за бюджет 100».
6. Показать trace, анализ текущего плана и Top-3.
7. Выбрать альтернативу и нажать «Сравнить с моим планом».
8. Нажать «Использовать этот сценарий» и пересчитать его в конструкторе.

Дополнительные запросы: «Максимизируй общий Astana Quality of Life Score» и «Предложи более сбалансированный сценарий, чтобы не оставить слабый район».

Ограничения

• Данные синтетические; результаты относятся только к правилам кейса.
• Это decision-support, не реальный прогноз политики Астаны.
• При отсутствии ключа, ошибке или таймауте OpenAI используется deterministic fallback.
• Общегородской поиск перебирает больше вариантов, чем районный, и может занимать заметно больше времени.
• Финальное решение принимает человек.
• LLM не является источником числовой истины и не оценивает риски, которых нет в данных симулятора.

Проверка AI жюри

Основной simulator и полный путь Advisor работают без ключа. Для проверки реального LLM задайте собственный OPENAI_API_KEY в .env.local (не в репозиторий) и перезапустите сервер. .env.example содержит только пустые плейсхолдеры.

Запросы к Responses API выполняются только на сервере с таймаутом 8 секунд на вызов. Structured output проверяется приложением. Модель интерпретирует цель и выбирает ключи подтверждённых фактов для объяснения; произвольные числа и факты из её текста не отображаются. Успешный fallback сам по себе не доказывает, что внешний API был вызван успешно.

Чеклист перед демо:

1. Отозвать любой ранее раскрытый ключ в OpenAI API keys и создать новый.
2. Прописать новый ключ только в .env.local, перезапустить npm run dev.
3. Вызвать POST /api/advisor с демо-запросом и убедиться, что ответ приходит при наличии ключа (не только fallback без ключа).
4. Пройти UI: расчёт → советник → сравнение → применение → пересчёт.
5. Контракт ошибок: см. docs/advisor-api.md § Errors.

Сторонние компоненты

Next.js, React, React DOM, TypeScript, Vitest, типы Node.js/React/React DOM из package.json; необязательный внешний сервис — OpenAI API. Базы данных, аутентификации и иных внешних сервисов нет.