🔱 ORCA — Open Retail Command Agent

A production-grade multi-agent AI system for retail inventory management.
Built with LangGraph · CrewAI · MCP · RAG · FastAPI · Streamlit · Docker

---

🎯 The Problem

During peak retail events — Ramadan, Dubai Shopping Festival, Eid — 200+ UAE retail stores face a critical operational bottleneck:

• Demand surges are unpredictable and event-driven
• Supplier lead times may not align with urgency
• Capital approval for large orders requires human sign-off
• Manual decisions are slow, inconsistent, and not auditable

Store managers spend hours on WhatsApp with suppliers, comparing spreadsheets, and escalating to finance — while stockouts happen and revenue is lost.

ORCA replaces this entire workflow with a 4-agent AI pipeline + one human decision.

---

🤖 How It Works

Alert Triggered (stock critical/at-risk)
         │
         ▼
┌─────────────────────────────────────────────────────────┐
│  Agent 1 — Demand Intelligence (CrewAI crew)            │
│  • Event uplift analysis (Ramadan 2.8×, DSF 1.9×)      │
│  • Supplier constraint discovery                        │
│  • Confidence scoring + demand forecasting              │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Agent 2 — Replenishment Options                        │
│  • Option A: Standard Replenishment                     │
│  • Option B: Profit Maximisation (Tier-1 stores)       │
│  • Option C: Expedite Air Freight                       │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Agent 3 — Capital Allocation & Scoring                 │
│  budget_score      = (1 - cost/budget) × 40            │
│  availability_score = availability_pct × 0.40 × 100   │
│  margin_score      = (1/margin_rank) × 20              │
│  lead_time_penalty = -20 if CRITICAL & lead > 30d     │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│  Route Decision Node                                    │
│  • AUTO_EXECUTE  → cost < pool auto-approve limit      │
│  • ESCALATE      → cost > limit → human required       │
│  • SUSPEND       → pool pressure HIGH                  │
└────────────────────┬────────────────────────────────────┘
                     │
              ┌──────┴──────┐
              ▼             ▼
         Human HITL     Auto Execute
         (Approve /     (reorder_triggered
          Reject)        = Yes → DB)

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Streamlit Dashboard                       │
│              (Command Centre / Pipeline Monitor / HITL)      │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTP (httpx)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                      FastAPI Layer                           │
│  POST /pipeline/run → 202 + background task                 │
│  GET  /pipeline/{id}/state → polling endpoint               │
│  POST /pipeline/{id}/approve → HITL resume                  │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                  LangGraph Pipeline                          │
│  agent1_node → agent2_node → agent3_node → route_node      │
│       ↓              ↓            ↓              ↓          │
│  CrewAI crew    Options Gen   Scoring     ESCALATE/AUTO     │
│  (3 AI agents)  (3 options)  (formula)    EXECUTE/SUSPEND   │
└──────────┬──────────────────────────────────────────────────┘
           │                    │
           ▼                    ▼
┌─────────────────┐    ┌─────────────────────┐
│   MCP Server    │    │    RAG Pipeline      │
│  (tool discovery│    │  ChromaDB + BGE     │
│   via stdio)    │    │  Reranker           │
└─────────────────┘    └─────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│               SQLite Database                                │
│  skus · stores · stock_positions · capital_pools            │
│  pipeline_log · supplier_data · events                       │
└─────────────────────────────────────────────────────────────┘

---

✨ Key Features

Feature	Description
🤖 Multi-Agent Pipeline	4 specialised LangGraph agents, each with a single responsibility
👥 CrewAI Integration	3-agent crew (Data Analyst, Market Analyst, Forecast Strategist) inside Agent 1
🔌 MCP Tool Discovery	Dynamic tool registration via Model Context Protocol — no hardcoded calls
📚 RAG Policy Retrieval	BGE reranker + ChromaDB for policy-grounded decisions
✋ HITL Approval Workflow	LangGraph interrupt → human reviews briefing → approve/reject
⚡ Async FastAPI	202 pattern — pipeline runs as background task, client polls state
🎨 Industrial Dashboard	Dark theme Streamlit UI — Command Centre / Pipeline Monitor / HITL tabs
🐳 Docker + Render	Fully containerised, deployed on Render free tier
📊 Audit Trail	Every decision logged with reviewer, timestamp, action taken

---

🛠️ Tech Stack

Layer              Technology
─────────────────────────────────────────────────
Orchestration      LangGraph 1.1.10
Multi-Agent        CrewAI 1.14.4
Tool Protocol      MCP (Model Context Protocol)
LLM                Groq / llama-3.1-8b-instant
Embeddings         nomic-ai/nomic-embed-text-v1.5
Reranker           BAAI/bge-reranker-v2-m3
Vector Store       ChromaDB 1.1.1
API Framework      FastAPI 0.136 + Uvicorn
Dashboard          Streamlit 1.57
HTTP Client        httpx 0.28
Database           SQLite + SQLAlchemy
Containerisation   Docker + docker-compose
Deployment         Render.com (free tier)
Observability      LangSmith (integrated — all LLM calls traced)

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Docker Desktop
• Groq API key (free at console.groq.com)

Option 1 — Docker (recommended)

# Clone
git clone https://github.com/ankitv42/orca-retail.git
cd orca-retail

# Create .env
cat > .env << EOF
GROQ_API_KEY=your_groq_key_here
GROQ_MODEL=llama-3.1-8b-instant
LLM_PROVIDER=groq
LANGCHAIN_TRACING_V2=false
EOF

# Build and run
docker-compose up --build

Open:

• Dashboard: http://localhost:8501
• API Docs: http://localhost:8080/docs

Option 2 — Local Development

# Clone and setup
git clone https://github.com/ankitv42/orca-retail.git
cd orca-retail
python -m venv venv
venv\Scripts\activate  # Windows
pip install -r requirements.txt

# Create .env (same as above)

# Terminal 1 — API
uvicorn api.main:app --port 8080 --reload

# Terminal 2 — Dashboard
streamlit run dashboard/app.py

---

📁 Project Structure

orca-retail/
├── agents/
│   ├── graph.py          # LangGraph pipeline — all 4 agents + route logic
│   ├── prompts.py        # Agent prompts + scoring formula
│   ├── crew.py           # CrewAI crew (3 agents)
│   ├── llm_factory.py    # LLM provider abstraction
│   └── tools.py          # MCP tool definitions
│
├── api/
│   ├── main.py           # FastAPI app — 7 endpoints
│   └── models.py         # Pydantic schemas
│
├── dashboard/
│   ├── app.py            # Streamlit UI — 3 tabs
│   └── api_client.py     # HTTP client wrapper
│
├── docs/
│   ├── rag/
│   │   ├── ingest.py         # PDF → chunks → ChromaDB
│   │   └── retriever.py      # BGE reranker retrieval
│   └── adr/                  # Architecture Decision Records (ADR-001 to ADR-005)
│
├── db/
│   ├── queries.py        # SQLite query layer
│   ├── pipeline_log.py   # Audit log
│   └── schema.sql        # Database schema
│
├── mcp_server/
│   └── server.py         # MCP stdio server
│
├── data/
│   └── scheduler.py      # Alert generation scheduler
│
├── Dockerfile.api         # API container
├── Dockerfile.dashboard   # Dashboard container
├── docker-compose.yml     # Orchestration
└── requirements.txt       # Dependencies

---

🔌 API Reference

Base URL: https://orca-retail.onrender.com

Method	Endpoint	Description
GET	/health	System status — DB, RAG, LLM, MCP
GET	/api/v1/alerts	102 critical/at-risk SKU alerts
POST	/api/v1/pipeline/run	Trigger pipeline → returns 202 + pipeline_id
GET	/api/v1/pipeline/{id}/state	Poll pipeline state (progressive)
GET	/api/v1/pipeline/{id}/briefing	HITL briefing text
POST	/api/v1/pipeline/{id}/approve	Approve or reject HITL decision
GET	/api/v1/pipelines	Session audit log

Full interactive docs: https://orca-retail.onrender.com/docs

---

🎬 Demo Flow

1. Open https://orca-dashboard.onrender.com
2. Command Centre tab → click Analyse on any SKU (try Ajwa Dates 1kg — Class A, Ramadan event)
3. Pipeline Monitor tab → watch 4 agents complete progressively (auto-refreshes every 3s)
4. If pipeline is ESCALATED → go to HITL Approval tab
5. Enter your email → read the briefing → click APPROVE
6. reorder_triggered = Yes is written to the database

⚠️ Free tier note: Render free instances spin down after inactivity. First load may take 30–60 seconds to wake up.

---

📐 Architecture Decision Records

Full ADR documents are in docs/adr/.

ADR	Decision	Choice
ADR-001	Graph framework	LangGraph — stateful, interruptible, production-grade checkpointing
ADR-002	Tool protocol	MCP — dynamic discovery vs hardcoded tool calls
ADR-003	Eval metrics	Native RAGAS metrics over RAGAS library
ADR-004	ChromaDB index	Committed to repo for reproducible CI
ADR-005	HITL routing	Cost vs auto-approve limit — pure Python, no LLM

---

🗺️ Sprint Roadmap

Sprint	Focus	Status
Sprint 1	Data Foundation (SQLite, 100 SKUs, 200 stores, scheduler)	✅ Complete
Sprint 2	LangGraph Pipeline + MCP Integration	✅ Complete
Sprint 3	RAG (ChromaDB + BGE) + CrewAI	✅ Complete
Sprint 4	FastAPI + Streamlit HITL Dashboard	✅ Complete
Sprint 5	Docker + Render Deployment	✅ Complete
Sprint 6	LangSmith Tracing + ADRs ✅ · Redis 🔜	🔄 In Progress

---

🤝 About

Built by Ankit Kumar Verma
Data Science Manager @ Accenture | Palantir Foundry | GCP Professional Data Engineer

This project is an open-source rebuild of the Retail Command Centre (RCC) — a production HITL multi-agent inventory system deployed across 200+ UAE retail stores on Palantir Foundry.

ORCA is my bridge from proprietary enterprise AI to portable, open-source agentic systems.

---

📄 License

MIT License — see LICENSE for details.

---

_{If this project helped you, give it a ⭐ — it helps others find it.}