SORA.Earth AI 平台：ESG 评估与自主 MLOps 闭环

SORA.Earth AI Platform — полнофункциональная платформа для ESG‑оценки проектов, объяснимых ML‑предсказаний, страновой аналитики и автономного MLOps‑контурa с мониторингом и алертингом.

Платформа собирает вместе FastAPI, PostgreSQL, Redis, APScheduler, Prometheus, Grafana и Docker Compose в единый production‑стек: отдельный scheduler‑процесс, персистентные логи, AI‑агент, админ‑панель и готовый к развёртыванию docker‑композ.

Возможности

ESG‑оценка проектов
- Оценка по трём компонентам: Environment / Social / Economic.
- Итоговый ESG‑score и вероятность успеха проекта.
- What‑if анализ и предсказания с учётом неопределённости.
Аналитика и страновые данные
- /api/v1/analytics/country-benchmark/{country} — ESG‑бенчмарк страны против глобального контекста.
- /api/v1/analytics/country-ranking — глобальный ESG‑рейтинг стран с пагинацией.
- Монте‑Карло симуляции, сравнение моделей, калькулятор GHG Scope 1/2/3.
MLOps и пайплайны
- Drift detection (KS‑test) по ключевым фичам.
- Закрытый контур: drift → retrain → AUC‑валидация → promote / reject с decision log в PostgreSQL.
- Полный пайплайн: refresh внешних данных → drift → retrain → validate → promote.
Operations / Admin
- Админ‑панель, статус планировщика, журнал выкатов и ручные триггеры переобучения и полного пайплайна.
Наблюдаемость и прод
- Prometheus‑метрики на /metrics — реестр prometheus_client, HTTP + доменные sora_*. Это тот путь, который скрейпит infra/prometheus.yml. /api/v1/metrics/prometheus отдаёт тот же реестр.
- Grafana-дашборд “SORA MLOps Overview” и 5 алертов для операционного контура из grafana/provisioning/alerting/alerts.yml, названных так же, как там: Drift Detected, No Successful Retrain, Retrain Failed, High Prediction Latency, App Unreachable. Пять алертов качества старого ESG-прогноза удалены по #284: M2 закрыт с результатом «преимущество не доказано», а M3 имеет другую цель и ещё не достиг доказательного окна.
- Nginx reverse proxy (80 и 443, TLS от Let's Encrypt) с rate limiting, security‑заголовками, gzip и WebSocket‑проксированием.

Архитектура

┌─────────────┐     ┌──────────────────────────────────────────────────┐
│   Nginx     │────▶│              FastAPI Application                 │
│   :80       │     │                                                  │
│ rate limit  │     │  /api/v1/evaluate  /predict  /drift  /mlops      │
└─────────────┘     └──────────┬───────────────┬───────────────────────┘
                               │               │
                     ┌─────────▼──────┐  ┌────▼─────┐
                     │ PostgreSQL     │  │ Redis    │
                     │ логи/состояние │  │ кэш/локи │
                     └─────────┬──────┘  └────┬─────┘
                               │              │
                        ┌──────▼──────┐  ┌────▼─────────┐
                        │ Scheduler   │  │ Prometheus   │
                        │ отдельный   │  │ + Grafana    │
                        │ процесс     │  │ дашборды     │
                        └─────────────┘  └──────────────┘

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

Локально, для разработки:

git clone https://github.com/Evgeniy2001Poluhin/-SORA.Earth.git sora_earth_ai_platform
cd sora_earth_ai_platform

# .env с минимальными настройками
cat > .env << 'EOF'
POSTGRES_PASSWORD=sora2026
SORA_ADMIN_TOKEN=your-secret-token
GRAFANA_PASSWORD=sora2026
SECRET_KEY=your-jwt-secret
EOF

docker-compose up -d

Production разворачивается не этим. Единственный поддерживаемый способ — ./scripts/deploy_production.sh; он пересоздаёт nginx и prometheus после бэкенда, проверяет конфигурацию, сертификаты, публичный /health и то, что Prometheus действительно собирает объявленные цели. Причины записаны в CLAUDE.md, раздел «Production Server».

Требования

Python 3.11 или новее. Объявлено в pyproject.toml; на этом же собирается образ и работает CI. На более старом интерпретаторе пакет app не импортируется вовсе — app/rate_limit.py и app/secret_validation.py используют X | None в аннотациях, вычисляемых во время выполнения, — и почти половина тестов перестаёт собираться с ошибкой из файла, не имеющего отношения к запускаемому тесту.

tests/test_python_version_is_declared.py держит эту строку, pyproject.toml, CI и Dockerfile в согласии друг с другом.

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

Дополнительные материалы проекта:

Architecture diagrams

C4-style диаграммы в docs/diagrams/ (Mermaid, рендерятся прямо на GitHub).

Context — пользователи и внешние системы
Container — 7 Docker services + MLflow
Component — внутренности FastAPI
Data flow — sequence для /evaluate
Deployment — Docker Compose

Screenshots

Ни одного снимка в репозитории нет. docs/screenshots/ содержит только описания: восемь разделов с подписями и привязку к главам диплома — и ноль файлов. Из семи названных там имён шесть не существуют нигде; седьмое, 02-evaluate.png, принадлежит другому набору. В истории git этих файлов не было ни разу, так что восстановить их из репозитория нельзя (#297).

Эта строка обещала «9 thesis-grade артефактов с подписями» и вела на документ, описывающий девять несуществующих картинок — первое, что открывал читатель, пришедший за доказательствами.

Описания и что на каждом снимке должно быть: docs/screenshots/README.md
Что действительно лежит в репозитории: assets/screenshots/ — семь снимков DEMO-сценария, docs/DEMO.md

Production: https://sora-earth.online — health at /health.