🛍️ Shopify AI Operations Agent

A production-grade autonomous ecommerce operations agent built with LangGraph v1, Model Context Protocol (MCP 2026-07-28), FastAPI, PostgreSQL + pgvector, Redis, OpenTelemetry, and strict Human-in-the-Loop (HITL) risk governance.

---

📖 Complete Technical Documentation

For in-depth architecture, terminologies, and Architectural Decision Records (ADRs) written in ASD-STE100 (Simplified Technical English), see: 👉 DOCUMENTATION.md

Download the visual presentation PDF: 👉 architecture_diagram.pdf (or at http://localhost:8000/architecture.pdf)

---

🏗️ Core Architectural Invariants

1. Pre-Execution Risk & Policy Gate: Destructive deletions, financial budgets, and outbound communications trigger a LangGraph interrupt (interrupt_before) requiring human approval.
2. Decoupled MCP Tool Layer: All business capabilities are packaged as 5 stateless MCP tool servers (Shopify, Analytics, Meta Ads, Communications, Trend Intelligence).
3. Deterministic Business Analytics: Financial metrics are computed using deterministic SQL routines, eliminating LLM arithmetic hallucinations.
4. Anti-Early-Victory Sensors: The agent re-queries live state to mathematically verify that mutations occurred before reporting completion.
5. Shift-Left Evals & Tracing: 28 automated pytest test suites, 17-case golden eval benchmark, and an independent Critic Agent audit (Score: 98.5/100, Grade: A+).

---

📁 Repository Structure

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

---

🚀 Quickstart & Setup

1. Local Development

# Install dependencies
pip install -r requirements.txt

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

• Dashboard UI: http://localhost:8000/ (Press Ctrl + K for Command Palette)
• Interactive API Docs: http://localhost:8000/docs
• Architecture PDF: http://localhost:8000/architecture.pdf

---

🧪 Verification & Evaluations

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

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