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

AI-симулятор управления Астаной: пять решений, бюджет 100 единиц и сравнение качества жизни до и после. Детерминированный движок рассчитывает результат, AI объясняет его по отдельному запросу.

React + Python API: запуск двумя терминалами

Терминал 1, из корня репозитория (Python 3.11, существующее окружение .venv):

.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python -m uvicorn api.app:app --reload --port 8000

Если окружения ещё нет, сначала выполните python -m venv .venv. Без активации используйте .\.venv\Scripts\python.exe вместо python.

Терминал 2, также из корня (Node.js 22.18+ или 24+):

cd ui
npm ci
npm run dev

Откройте http://localhost:5173. Backend: http://localhost:8000; описание API: http://localhost:8000/docs. Vite использует фиксированный порт 5173. Каталог загружается из Python; симуляция и проверка решений выполняются engine. Кнопка «Загрузить демо-сценарий» заполняет пять решений; затем нажмите «Симулировать». Изменение решений очищает прежние результаты и отменяет ожидание устаревшего ответа.

Симуляция работает без ключа. AI запускается только кнопкой «Сформировать AI-анализ». Для него задайте OPENAI_API_KEY в окружении терминала 1 до запуска API; OPENAI_MODEL необязателен. Ошибка AI сохраняет результаты симуляции на экране. Ключ никогда не передаётся React. Python автоматически не читает .env.

FRONTEND_ORIGIN на сервере по умолчанию равен http://localhost:5173. VITE_API_URL в ui/.env.local по умолчанию равен http://localhost:8000 (образец: ui/.env.example). При изменении адресов согласуйте эти настройки и перезапустите процессы. Все переменные VITE_* публичны: секреты в них запрещены.

Проверки из корня, без настоящего OpenAI-запроса:

python -B -m unittest discover -s tests
cd ui
npm test
npm run build

Frontend-тесты получают fixtures через Python API TestClient; выбирают Python из корневого .venv или переменной PYTHON, иначе используют python из PATH. Контракт endpoints описан в api/README.md.

Эталонный сценарий: Score 52.56 → 56.54, изменение +3.99, бюджет 95 / 100, остаток 5, критические показатели 2 → 0, слабейший район — Нура, 49.18 → 52.96. Синергия: M10 + M12 в Нуре.

AI smoke test

Ручная проверка настоящего OpenAI API на эталонном сценарии. Запускайте из корня репозитория в окружении с установленными зависимостями из requirements.txt. В PowerShell:

.\.venv\Scripts\Activate.ps1
$env:OPENAI_API_KEY="your-api-key"
$env:OPENAI_MODEL="gpt-5.6-terra"
python scripts/ai_smoke_test.py

OPENAI_MODEL необязателен: по умолчанию AI layer использует gpt-5.6-terra. Ответ запрашивается на русском языке. Скрипт выводит рассчитанные движком значения, название модели и разделы AI-анализа. Без ключа запрос не выполняется, выводится сообщение об отсутствующем OPENAI_API_KEY, код завершения — 2. Другие коды ошибок: 1 — невалидная/неполная симуляция, 3 — ошибка запроса, 4 — некорректный ответ AI; успешный запуск возвращает 0.

Переменные читаются только из окружения; .env.example служит примером, файл .env автоматически не загружается. Удалить ключ из текущей сессии PowerShell:

Remove-Item Env:OPENAI_API_KEY

Unit tests работают без сети и не выполняют реальные API-запросы. Ручной smoke test находится вне tests/ и не запускается этой командой:

python -B -m unittest discover -s tests