Zippling — AI-Powered E-Commerce Support

Multi-agent customer support automation using Google A2A Protocol, Nebius AI, and ClickHouse. Built at the Nebius.Build SF Hackathon.

---

What It Does

Zippling fully automates e-commerce customer support. When a customer emails about a wrong item, refund, or order status, a pipeline of 6 specialized AI agents classifies the complaint, looks up the order, makes a policy-based decision, and drafts a professional reply — all in under 30 seconds, with zero human involvement unless the case genuinely requires escalation.

---

Screenshots

Login Page

Admin Dashboard — Live Analytics

Admin — Resolution Detail

Customer Portal — Shop & Orders

Customer — Dispute Resolution

---

Architecture

                        ┌─────────────────────────────┐
                        │     Inbound Email / POST      │
                        │         /webhook              │
                        └──────────────┬──────────────┘
                                       │
                               ┌───────▼────────┐
                               │  Intake Agent  │  ← Nebius DeepSeek-V3
                               │  (Classify +   │    Classifies intent,
                               │  Extract)      │    extracts order ID
                               └───────┬────────┘
                                       │ A2A Task Dispatch
              ┌──────────────┬─────────┴──────────┬──────────────┐
              │              │                    │              │
     ┌────────▼──────┐ ┌─────▼──────┐ ┌──────────▼───┐ ┌────────▼───────┐
     │ Order Status  │ │   Refund   │ │  Wrong/Dmg   │ │  Escalation    │
     │    Agent      │ │   Agent    │ │    Agent     │ │    Agent       │
     │               │ │            │ │              │ │                │
     │ SQLite lookup │ │Policy check│ │Vision AI     │ │ Tendem human   │
     │ tracking info │ │Tavily      │ │Qwen2.5-VL    │ │ review queue   │
     └────────┬──────┘ └─────┬──────┘ └──────────┬───┘ └────────┬───────┘
              └──────────────┴────────────────────┴──────────────┘
                                       │ A2A TaskResult
                               ┌───────▼────────┐
                               │ Response Agent │  ← Nebius DeepSeek-V3
                               │ (Draft reply + │    Drafts empathetic
                               │  Log ticket)   │    email reply
                               └───────┬────────┘
                                       │
                    ┌──────────────────┴──────────────────┐
                    │                                     │
             ┌──────▼──────┐                    ┌─────────▼────────┐
             │   SQLite     │                    │    ClickHouse    │
             │              │                    │                  │
             │ tickets      │                    │ ticket_events    │
             │ orders       │                    │ (analytics store)│
             │ refunds      │                    │ turnaround times │
             │ products     │                    │ cost/time saved  │
             │ policies     │                    │ live feed        │
             └─────────────┘                    └──────────────────┘

---

Agent Responsibilities

Agent	Role	Model
Intake	Classifies email intent (order / refund / wrong item / escalation), extracts order ID and customer email	DeepSeek-V3
Order Status	Looks up order in SQLite, returns status + tracking number	DeepSeek-V3
Refund	Checks return window against policy, auto-approves or denies, logs refund record	DeepSeek-V3 + Tavily
Wrong/Damaged Item	Assesses severity, runs Qwen2.5-VL vision analysis on complaint image, decides replacement vs refund	DeepSeek-V3 + Qwen2.5-VL
Escalation	Routes high-value, legal-threat, and fraud cases to Tendem human review queue	DeepSeek-V3 + Tendem
Response	Synthesizes all specialist results, drafts professional customer reply, logs ticket + pushes to ClickHouse	DeepSeek-V3

---

Technology Stack

Nebius AI (Token Factory)

• Models used: deepseek-ai/DeepSeek-V3-0324-fast for all text agents, Qwen/Qwen2.5-VL-72B-Instruct for complaint image analysis
• How: OpenAI-compatible API (base_url swap) — all 6 agents call Nebius for inference
• Metrics driven: Auto-resolve rate, reply quality, intent classification accuracy

Google A2A Protocol

• How: Each agent exposes a typed A2A task endpoint (POST /agents/<name>); the intake agent dispatches a Task object and receives a TaskResult back
• Metrics driven: Agent routing trace log visible in real-time on the admin dashboard, per-hop latency in milliseconds

ClickHouse

• How: Every resolved ticket is inserted into ticket_events table with turnaround time, refund amount, and agent chain; the analytics dashboard queries this for aggregates
• Metrics driven: Avg / P50 / P95 turnaround time, total cost saved, total time saved, hourly load heatmap, live resolution feed

Tavily

• How: Used inside the Refund and Wrong-Item agents to search for policy nuances and product availability when the local database is insufficient
• Metrics driven: Policy compliance accuracy, replacement viability decisions

Tendem (Toloka)

• How: Escalation agent submits ambiguous/high-risk tickets to a Tendem human review task queue and polls for a decision before drafting the reply
• Metrics driven: Escalation rate, human override decisions

SQLite

• How: Operational database for orders, customers, products, policies, tickets, refunds, and demo orders; seeded with realistic fake data on startup
• Tables: orders, customers, products, policies, tickets, refunds, demo_orders

FastAPI

• How: Hosts all agent endpoints, the /webhook email ingestion endpoint, admin REST APIs, and customer portal APIs
• Key endpoints: POST /webhook, GET /analytics/summary, POST /customer/order, GET /customer/orders

React + Vite

• How: Frontend with two separate portals (admin + customer) behind session-based auth; polls the analytics endpoint every 5 seconds for live updates
• Libraries: TanStack Query (data fetching), Recharts (charts), React Router, Lucide icons

---

User Workflows

Customer Flow

1. Login at /login with any email address
2. Shop — browse products and place a demo order (system deliberately ships a wrong item)
3. My Orders — see a side-by-side comparison of what was ordered vs what was received, with a red "Wrong Item" badge
4. Click Report Wrong Item to Support — complaint form is pre-filled with order context
5. Submit — AI pipeline processes the complaint in ~20 seconds
6. The order card auto-updates with a green "Dispute Resolved" panel showing the resolution in plain English and any refund amount

Admin Flow

1. Login with code admin
2. Dashboard — live KPI cards (total tickets, resolved, escalated, auto-resolve rate, hours saved, cost saved), daily volume chart, intent breakdown, ClickHouse-backed turnaround metrics, and live resolution feed
3. Incidents — all open/escalated tickets with pulsing red live indicators; expand any row to see full resolution prose and agent chain
4. Resolved — searchable history of all resolved tickets with expandable detail
5. Products — inventory management (only products with images shown)
6. Policies — per-category return policies with toggle-based editing (return window, refund allowed, replacement allowed, partial refund %)
7. Test Email — fire sample emails directly into the pipeline to demo any intent type

---

Key Metrics the System Tracks

Metric	Source	Where shown
Auto-resolve rate	SQLite / ClickHouse	Dashboard KPI card
Avg turnaround time	ClickHouse	Dashboard impact card
P50 / P95 turnaround	ClickHouse	Dashboard impact cards
Hours saved vs human agents	ClickHouse (15 min baseline)	Dashboard KPI card
Cost saved	ClickHouse ($8/ticket baseline)	Dashboard KPI card
Total refunds approved + amount	SQLite / ClickHouse	Dashboard impact card
Tickets by intent	SQLite / ClickHouse	Pie chart
Daily ticket volume	SQLite / ClickHouse	Bar chart
Turnaround by hour of day	ClickHouse	Line chart
Live resolution feed	ClickHouse	Dashboard live feed
A2A inter-agent traces	In-memory	Dashboard trace log

---

Local Setup

# 1. Clone
git clone https://github.com/ParthGala2k/zippling_ai_commerce.git
cd zippling_ai_commerce

# 2. Python environment
python -m venv venv
venv/Scripts/pip install -r requirements.txt   # Windows
# source venv/bin/activate && pip install -r requirements.txt  # Mac/Linux

# 3. Environment variables
cp .env.example .env
# Fill in: NEBIUS_API_KEY, CLICKHOUSE_HOST, CLICKHOUSE_PASSWORD

# 4. Start backend
venv/Scripts/python main.py

# 5. Start frontend
cd frontend
npm install
npm run dev

Open http://localhost:5173

---

Project Structure

zippling_ai_commerce/
├── main.py                  # FastAPI app, all REST endpoints
├── config.py                # API keys and configuration
├── requirements.txt
├── a2a/
│   ├── protocol.py          # A2A Task, TaskResult, AgentCard types
│   └── router.py            # Routes tasks to correct agent
├── agents/
│   ├── intake.py            # Email classification + dispatch
│   ├── order.py             # Order status lookup
│   ├── refund.py            # Refund policy engine
│   ├── wrong_item.py        # Wrong/damaged item assessment + vision AI
│   ├── escalation.py        # Escalation + Tendem human review
│   └── response.py          # Reply drafting + ticket logging
├── db/
│   ├── schema.sql           # SQLite schema
│   └── seed.py              # Seed data (products, orders, policies)
├── tools/
│   ├── nebius_client.py     # Nebius Token Factory wrapper
│   ├── tavily_client.py     # Tavily search wrapper
│   └── clickhouse_client.py # ClickHouse analytics client
├── frontend/
│   └── src/
│       ├── pages/           # Dashboard, Incidents, Resolved, Products,
│       │                    # Policies, TestEmail, Login, CustomerPortal
│       ├── components/      # Layout, AgentTrace, Badge
│       ├── contexts/        # AuthContext (session-based role + email)
│       └── lib/             # api.ts, utils.ts
└── screenshots/
    ├── login_page.png
    ├── admin_dashboard.png
    ├── admin_resolution_page.png
    ├── customer_homepage.png
    └── dispute_resolution_page.png

---

Built at Nebius.Build SF Hackathon

Powered by Nebius AI · Google A2A Protocol · ClickHouse