Content
<div align="center">
<br/>
<h1>🛍️ CommerceOS AI</h1>
<p><strong>Autonomous Multi-Agent E-Commerce Operations System</strong></p>
<br/>
<p>
<img src="https://img.shields.io/badge/Python-3.13-%233776AB?logo=python&logoColor=white" alt="Python 3.13"/>
<img src="https://img.shields.io/badge/LangGraph-0.4-%2300B4D8?logo=langchain&logoColor=white" alt="LangGraph"/>
<img src="https://img.shields.io/badge/CrewAI-0.105-%23FF6B35" alt="CrewAI"/>
<img src="https://img.shields.io/badge/LangChain-0.3-%231F2937" alt="LangChain"/>
<img src="https://img.shields.io/badge/FastAPI-0.115-%23009688?logo=fastapi&logoColor=white" alt="FastAPI"/>
<img src="https://img.shields.io/badge/Next.js-14.2-%23000000?logo=next.js&logoColor=white" alt="Next.js"/>
<img src="https://img.shields.io/badge/Streamlit-1.40-%23FF4B4B?logo=streamlit&logoColor=white" alt="Streamlit"/>
<br/>
<img src="https://img.shields.io/badge/coverage-80%25-%23a0c334" alt="Coverage 80%"/>
<img src="https://img.shields.io/badge/code%20style-ruff-%23D32F2F" alt="Ruff"/>
<img src="https://img.shields.io/badge/license-MIT-%23blue" alt="MIT License"/>
</p>
<br/>
</div>
<!-- Hero screenshot -->
<p align="center">
<img src="docs/images/01-storefront.png" alt="CommerceOS AI Storefront" width="90%"/>
</p>
---
## 📋 Overview
CommerceOS AI is an **autonomous, event-driven e-commerce platform** where **five specialized AI agents** collaborate to run a complete storefront. A **LangGraph supervisor** routes customer intents to the right agent, a **CrewAI sequential crew** handles fraud analysis, and an **EventBus** enables agent-to-agent workflows — all without human intervention.
> *"Not just a storefront — an AI-powered experience with 5 specialist agents working in sync."*
### What Makes This Different
| Typical E-Commerce Demo | CommerceOS AI |
|------------------------|---------------|
| CRUD app with a chatbot | **5 agents** with LangGraph orchestration |
| Hardcoded business logic | **Dynamic routing** via AgentRegistry |
| Single LLM call for everything | **CrewAI multi-agent pipeline** for fraud |
| No memory between turns | **MemorySaver** per-session context |
| Static pricing | **Dynamic pricing** via Pricing Agent |
| Human reviews fraud | **AI Signal Analyst → Adjudicator** debate |
---
## 👀 See It In Action — A Complete AI Shopping Journey
Watch how all 5 agents collaborate through a real customer conversation:
### 🏠 1. The Storefront
A fully functional e-commerce store with real product photography, category filters, and AI-powered recommendations.
<p align="center">
<img src="docs/images/01-storefront-full.png" alt="Storefront" width="90%"/>
</p>
---
### 🤖 2. AI Assistant — Where the Magic Happens
The **AI Assistant** is the heart of the system — a LangGraph supervisor routes each query to the right specialist agent automatically.
#### 🎧 Customer Support — Store Info & Orders
The customer asks about the store, how to place orders, and delivery tracking. The **Support Agent** uses **RAG (ChromaDB)** to provide accurate, policy-grounded responses.
<p align="center">
<img src="docs/images/02-agent-support.png" alt="Support Agent" width="80%"/>
</p>
#### 📦 Inventory Agent — Check Product Availability
The customer asks about specific products in stock. The **Inventory Agent** queries the live database and responds with real-time stock levels.
<p align="center">
<img src="docs/images/03-agent-inventory.png" alt="Inventory Agent" width="80%"/>
</p>
#### 🏷️ Pricing Agent — Find Deals & Sales
The customer looks for ongoing promotions. The **Pricing Agent** analyzes current sales and slow-moving inventory to suggest the best deals.
<p align="center">
<img src="docs/images/04-agent-pricing.png" alt="Pricing Agent" width="80%"/>
</p>
#### 📋 Order Management — Track a Real Order
An order is placed through the storefront, then the **Order Agent** is asked to check its status — showing real order lifecycle management with tracking.
<p align="center">
<img src="docs/images/05-agent-order.png" alt="Order Agent" width="80%"/>
</p>
#### 🛡️ Fraud Agent — CrewAI Multi-Agent Analysis ⭐
The same order is sent to the **Fraud Agent** for security analysis. The **CrewAI sequential crew** (Signal Analyst → Risk Adjudicator) debates the signals and produces a risk decision.
<p align="center">
<img src="docs/images/06-agent-fraud.png" alt="Fraud Agent - CrewAI Analysis" width="80%"/>
</p>
---
### ⚙️ 3. Admin Dashboard — Real-Time Operations
The operations dashboard shows live fraud alerts, stock levels, and a complete audit trail of all agent activity.
<p align="center">
<img src="docs/images/08-admin-dashboard.png" alt="Admin Dashboard" width="90%"/>
</p>
---
### 📖 4. API Documentation
Every agent capability is also exposed through a REST API with full Swagger documentation.
<p align="center">
<img src="docs/images/09-api-docs.png" alt="API Documentation" width="90%"/>
</p>
---
## 🧠 System Architecture
```
┌─────────────────────────────────────────┐
│ NEXT.JS STOREFRONT │
│ Products · Cart · AI Chat · Admin │
└───────────────┬─────────────────────────┘
│ HTTP / SSE
┌───────────────▼─────────────────────────┐
│ FASTAPI REST LAYER │
│ (9 MCP tools · streaming chat) │
└───────────────┬─────────────────────────┘
│
┌────────────────────▼────────────────────────┐
│ LANGGRAPH SUPERVISOR │
│ AgentRegistry routing · MemorySaver │
│ (keyword pre-check → LLM fallback) │
└──────┬──────┬──────┬──────┬──────┬──────────┘
│ │ │ │ │
┌──────▼┐ ┌──▼──┐ ┌─▼──┐ ┌─▼───┐ ┌▼──────────┐
│Support│ │Inv. │ │Frau│ │Order│ │Pricing │
│(RAG) │ │(LLM)│ │(Crw│ │(LLM)│ │(LLM) │
└──────┘ └─────┘ └────┘ └─────┘ └───────────┘
│ │ │ │ │
┌──────▼──────▼──────▼──────▼──────▼──────────┐
│ MCP TOOL LAYER (SQLAlchemy) │
│ Products · Orders · Customers · Logs │
└───────────────────┬──────────────────────────┘
│
┌───────────────────▼──────────────────────────┐
│ EVENT BUS + WORKFLOWS │
│ order.created → fraud check → deduct stock │
│ → low-stock alert → status update → log │
└──────────────────────────────────────────────┘
```
---
## 🤖 The Five Agents
| Agent | Framework | Core Capability | Example Query |
|-------|-----------|----------------|---------------|
| **🎧 Support** | LangChain + ChromaDB RAG | Policy Q&A grounded in actual documents | *"Can I return a damaged item?"* |
| **📦 Inventory** | LangChain + Groq LLM | Live stock queries, low-stock alerts | *"Do you have white t-shirts?"* |
| **🛡️ Fraud** | CrewAI (2-role sequential) | Signal Analyst → Risk Adjudicator pipeline | *"Check order O2004 for fraud"* |
| **📋 Order** | LangChain + Groq LLM | Full lifecycle: tracking, cancellation, shipment | *"Where is my order O2001?"* |
| **🏷️ Pricing** | LangChain + Groq LLM | Sale suggestions, slow-mover analysis | *"Any items on sale?"* |
### Agent Collaboration in Action
When a customer places an order, the system orchestrates a multi-agent workflow:
```
Order Placed
│
├─▶ Fraud Agent (CrewAI) analyzes 4 signals
│ ├─ Velocity check (15-min window)
│ ├─ Country mismatch detection
│ ├─ New-account + high-value scoring
│ └─ Disposable email detection
│
├─▶ Inventory Agent deducts stock
│ └─ Triggers low-stock alert if threshold hit
│
├─▶ Order status → confirmed
│
└─▶ All steps logged to AgentLog
└─ Admin Dashboard updates in real-time
```
---
## 🧩 Technology Deep Dive
### LangGraph — Orchestration Spine
The entire agent routing system uses **LangGraph's StateGraph** — a stateful, graph-based orchestration framework. Each user query flows through a directed graph:
```python
graph = StateGraph(GraphState)
graph.add_node("supervisor", supervisor_node) # Routing decision
graph.add_node("fraud", fraud_node) # Agent execution
graph.add_conditional_edges("supervisor", route_decision, route_map)
compiled = graph.compile(checkpointer=MemorySaver())
```
**MemorySaver** enables per-session conversation history — context-aware multi-turn interactions without external databases.
### CrewAI — Multi-Agent Fraud Pipeline
The Fraud Detection Agent runs a **CrewAI sequential crew** — two AI agents debating each flagged order:
```python
analyst = Agent(role="Fraud Signal Analyst", ...)
adjudicator = Agent(role="Risk Adjudicator", ...)
crew = Crew(agents=[analyst, adjudicator], tasks=[analyze, adjudicate])
result = crew.kickoff() # Two agents → one decision
```
| Role | Responsibility |
|------|---------------|
| **Signal Analyst** | Objectively interprets raw fraud signals |
| **Risk Adjudicator** | Makes final call: `APPROVE` / `HOLD` / `REJECT` |
This mirrors real-world fraud operations — analyst prepares evidence, senior reviewer makes the call.
### RAG (ChromaDB) — Grounded Support
The Support Agent uses **retrieval-augmented generation** with ChromaDB. Customer queries are embedded with sentence-transformers, matched against policy documents, and the LLM response is grounded in actual policy text:
```python
vectorstore = load_vectorstore() # ChromaDB with policy embeddings
docs = vectorstore.similarity_search(query, k=3) # Top-3 policy chunks
# LLM generates answer grounded in retrieved policy text
```
### MCP Tool Layer — Decoupled Data Access
Nine database-backed tools sit behind a unified `call_tool()` interface. Agents never touch the database directly:
```python
def call_tool(tool_name: str, **kwargs):
return get_tool(tool_name)(**kwargs)
# Any agent queries any data through the same interface:
products = call_tool("search_products", query="t-shirt")
signals = call_tool("get_fraud_signals", order_id="O2004")
```
**Registered tools:** `get_all_products`, `search_products`, `get_low_stock_products`, `get_product_by_id`, `get_order_by_id`, `get_orders_by_email`, `get_fraud_signals`, `get_all_flagged_orders`, `append_order`
### EventBus — Agent-to-Agent Collaboration
The in-process pub/sub system enables **decoupled, event-driven workflows**:
```python
event_bus.emit("order.created", {"order_id": "O2042"})
# Auto-triggers (no human in loop):
# 1. Fraud Agent runs CrewAI analysis
# 2. Inventory Agent deducts stock
# 3. Stock alert if threshold exceeded
# 4. Order status updated to confirmed
```
---
## 🚀 Quick Start
### Prerequisites
- Python 3.13+ · Node.js 18+ · Groq API key ([free](https://console.groq.com))
### Docker (one command)
```bash
docker compose -f infrastructure/docker-compose.yml up
```
Visit **http://localhost:3000**
### Manual Setup
**Terminal 1 — Backend:**
```bash
git clone https://github.com/hamidnaseem3549/commerceos-ai.git
cd commerceos-ai
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # Add your GROQ_API_KEY
python scripts/seed.py
python rag/vectorstore_setup.py
uvicorn backend.main:app --reload --port 8000
```
**Terminal 2 — Frontend:**
```bash
cd commerceos-ai/frontend
npm install && npm run dev
```
Open **http://localhost:3000** 🎉
---
## 🧪 Testing & Quality
```bash
pytest tests/ -v --cov=commerceos # 33 tests, 80%+ coverage
ruff check . # Lint check — clean
```
| Metric | Status |
|--------|--------|
| Tests | ✅ **33 passing** |
| Linting | ✅ **Ruff clean** (108 issues resolved) |
| Coverage | ✅ **80%+** |
| Test Suite | Agents · Tools · Workflows · Supervisor |
| CI | ✅ GitHub Actions (lint + test + coverage) |
---
## 🏗️ Project Structure
```
commerceos-ai/
│
├── commerceos/ # 🧠 Core AI Engine
│ ├── agents/ # 5 pluggable agents (BaseAgent)
│ ├── orchestration/ # LangGraph supervisor + EventBus
│ ├── mcp/ # 9 unified data access tools
│ ├── database/ # SQLAlchemy ORM + SQLite seeding
│ └── observability/ # JSON logging + activity tracking
│
├── frontend/ # 🎨 Next.js 14 storefront
├── backend/ # 🌐 FastAPI REST API
├── pages/ # 🖥️ Streamlit views (legacy)
├── ui/ # Shared components & assets
├── infrastructure/ # 🐳 Docker + docker-compose
├── tests/ # 🧪 33 integration tests
├── rag/ # 📚 ChromaDB vector store
└── data/ # 📦 CSV seed data
```
---
## 🛠️ Tech Stack
| Category | Technology |
|----------|-----------|
| **AI Orchestration** | LangGraph (StateGraph + MemorySaver) |
| **Agent Framework** | LangChain, CrewAI (sequential crews) |
| **Vector Store (RAG)** | ChromaDB + sentence-transformers |
| **LLM Provider** | Groq (llama-3.3-70b) |
| **Backend** | FastAPI, SQLAlchemy 2.0, Pydantic |
| **Frontend** | Next.js 14, React 18, Tailwind CSS |
| **Database** | SQLite (dev) / PostgreSQL-ready |
| **Infrastructure** | Docker, docker-compose |
| **CI/CD** | GitHub Actions (lint + test + coverage) |
| **Quality** | Ruff (linting), pytest-cov (coverage) |
---
## 👨💻 Author
**Hamid Naseem** — Aspiring AI Engineer
[GitHub](https://github.com/hamidnaseem3549) · [LinkedIn](https://www.linkedin.com/in/hamid-naseem-354h)
---
## 📄 License
MIT
---
<div align="center">
<p>
<strong>Built with LangGraph · CrewAI · LangChain · FastAPI · Next.js</strong>
</p>
<p>
<a href="#-overview">Overview</a> ·
<a href="#-see-it-in-action">Demo</a> ·
<a href="#-system-architecture">Architecture</a> ·
<a href="#-the-five-agents">Agents</a> ·
<a href="#-technology-deep-dive">Tech Deep Dive</a> ·
<a href="#-quick-start">Quick Start</a>
</p>
<br/>
</div>
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available