🛍️ Agente de Operaciones de IA para Shopify

Un agente autónomo de operaciones de comercio electrónico de nivel de producción construido con LangGraph v1, Model Context Protocol (MCP 2026-07-28), FastAPI, PostgreSQL + pgvector, Redis, OpenTelemetry y una estricta gobernanza de riesgos con Human-in-the-Loop (HITL).

📖 Documentación Técnica Completa

Para una arquitectura en profundidad, terminologías y Registros de Decisiones Arquitectónicas (ADR) escritos en ASD-STE100 (Inglés Técnico Simplificado), consulta: 👉 DOCUMENTATION.md

Descarga el PDF de presentación visual: 👉 architecture_diagram.pdf (o en http://localhost:8000/architecture.pdf)

🏗️ Invariantes Arquitectónicos Centrales

1. Puerta de Riesgo y Política Pre-Ejecución: Las eliminaciones destructivas, los presupuestos financieros y las comunicaciones salientes activan una interrupción de LangGraph (interrupt_before) que requiere aprobación humana.

2. Capa de Herramientas MCP Desacoplada: Todas las capacidades de negocio se empaquetan como 5 servidores de herramientas MCP sin estado (Shopify, Analytics, Meta Ads, Communications, Trend Intelligence).

3. Analítica de Negocio Determinista: Las métricas financieras se calculan mediante rutinas SQL deterministas, eliminando las alucinaciones aritméticas del LLM.

4. Sensores Anti-Victoria-Prematura: El agente vuelve a consultar el estado en vivo para verificar matemáticamente que las mutaciones ocurrieron antes de informar la finalización.

5. Evaluaciones y Trazabilidad Shift-Left: 28 suites de pruebas automatizadas pytest, un benchmark de evaluación dorado de 17 casos y una auditoría independiente del Agente Crítico (Puntuación: 98.5/100, Calificación: A+).

📁 Estructura del Repositorio

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

🚀 Inicio Rápido y Configuración

1. Desarrollo Local

# Install dependencies
pip install -r requirements.txt

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

• Panel de Control: http://localhost:8000/ (Presiona Ctrl + K para la Paleta de Comandos)

• Documentación Interactiva de la API: http://localhost:8000/docs

• PDF de Arquitectura: http://localhost:8000/architecture.pdf

🧪 Verificación y Evaluaciones

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

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