🛍️ Shopify AI Operations Agent

Продакшен-агент автономных операций для электронной коммерции, построенный на LangGraph v1, Model Context Protocol (MCP 2026-07-28), FastAPI, PostgreSQL + pgvector, Redis, OpenTelemetry и строгой системе управления рисками Human-in-the-Loop (HITL).

📖 Полная техническая документация

Подробная архитектура, терминология и Architectural Decision Records (ADRs), написанные в стиле ASD-STE100 (Упрощённый технический английский), доступны здесь: 👉 DOCUMENTATION.md

Скачать PDF-презентацию визуальной архитектуры: 👉 architecture_diagram.pdf (или по адресу http://localhost:8000/architecture.pdf)

🏗️ Основные архитектурные инварианты

1. Предварительный шлюз рисков и политик: Деструктивные удаления, финансовые бюджеты и исходящие коммуникации запускают прерывание LangGraph (interrupt_before), требующее одобрения человека.

2. Развязанный слой MCP-инструментов: Все бизнес-возможности упакованы в 5 серверов статически безсостоятельных MCP-инструментов (Shopify, Analytics, Meta Ads, Communications, Trend Intelligence).

3. Детерминированная бизнес-аналитика: Финансовые метрики вычисляются с помощью детерминированных SQL-процедур, исключая арифметические галлюцинации LLM.

4. Сенсоры против преждевременной победы: Агент повторно запрашивает актуальное состояние, чтобы математически проверить, что мутации действительно произошли, прежде чем сообщать о завершении.

5. Смещённые влево эвалюации и трассировка: 28 автоматизированных наборов тестов pytest, 17-кейсовый золотой эталонный бенчмарк и независимый аудит Critic Agent (Оценка: 98.5/100, Оценка: A+).

📁 Структура репозитория

shopify-ai-ops-agent/
├── DOCUMENTATION.md           # Full technical documentation (ASD-STE100)
├── architecture_diagram.pdf   # 2-slide landscape architecture diagram
├── docker-compose.yml         # Postgres (pgvector) + Redis + Jaeger + API
├── pyproject.toml             # Dependencies & packaging
├── app/
│   ├── api/                   # FastAPI routes (agent, approvals, health)
│   ├── agent/                 # LangGraph state machine & specialized nodes
│   ├── mcp_servers/           # 5 Stateless MCP tool servers
│   ├── core/                  # Security (HMAC-SHA256), Idempotency, Database
│   ├── rag/                   # Hybrid Vector + BM25 search & brand guidelines
│   ├── static/                # Executive SaaS Cockpit UI & Command Palette
│   └── evals/                 # Golden datasets & Critic Agent audit
└── tests/                     # 28 automated unit, safety, and integration tests

🚀 Быстрый старт и настройка

1. Локальная разработка

# Install dependencies
pip install -r requirements.txt

# Start the application server & dashboard
python -m uvicorn app.api.main:app --reload --port 8000

• Панель управления (UI): http://localhost:8000/ (Нажмите Ctrl + K для палитры команд)

• Интерактивная документация API: http://localhost:8000/docs

• Архитектурный PDF: http://localhost:8000/architecture.pdf

🧪 Верификация и эвалюации

# Run full automated test suite (28 tests)
python -m pytest tests/ -v

# Run independent Critic Agent technical audit
python -m app.evals.judge_agent