# 🛍️ Shopify AI Operations Agent

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-009688.svg)](https://fastapi.tiangolo.com)
[![LangGraph](https://img.shields.io/badge/LangGraph-v1-orange.svg)](https://langchain-ai.github.io/langgraph/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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`**](DOCUMENTATION.md)

Download the visual presentation PDF:
👉 [**`architecture_diagram.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
```bash
# 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

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

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