README.md

metadata

title: SupportCopilot
emoji: 💬
colorFrom: green
colorTo: blue
sdk: docker
app_port: 8000
pinned: true
short_description: AI e-commerce support automation + ROI dashboard

SupportCopilot

An AI agent that automates first-line e-commerce customer support and proves the ROI. It's grounded in your own catalog and policies, with a provider-agnostic LLM layer.

Demo note: the deflection and ROI figures are measured on a seeded 20-ticket eval set; the public demo runs a deterministic stub (add an ANTHROPIC_API_KEY / OPENAI_API_KEY for a live model).

The problem

E-commerce support teams drown in repetitive tier-1 tickets: "where's my order?", "what's your return policy?", "can I get a refund?". Each one costs an agent ~5–8 minutes and ~$0.50–$3 in loaded labour, and customers wait in a queue for answers that already exist in the catalog and policy pages. Generic chatbots either hallucinate policy (creating refund liability) or escalate everything (saving nothing). Teams need automation that is grounded in their own data, makes policy-correct refund decisions, knows when to hand off to a human, and can prove the savings to the people who sign off on it.

What it does

SupportCopilot is a vertical support agent for an example store (Northwind Outdoors). It:

• Answers inquiries with citations using RAG over the store's product catalog and policy documents, every answer linked to the exact policy section or product it used.
• Looks up order status via a mock Orders API (swap in a real OMS/Shopify endpoint in one file).
• Drafts return/refund decisions with deterministic, unit-tested logic that respects the written policy (return window, final-sale, worn/used, return-shipping fee, defect → warranty).
• Escalates to a human when confidence is low or the situation is sensitive (defect claims, billing disputes, manager requests), so it never auto-approves money it shouldn't.
• Proves ROI on an ops dashboard whose numbers are computed by replaying seeded tickets through the live agent, not hard-coded.

flowchart TD
    A[Customer message] --> B{Intent router}
    B -->|order status| C[Mock Orders API]
    B -->|refund / return| D[Refund decision engine<br/>policy rules]
    B -->|general question| E[RAG retrieval<br/>TF-IDF over catalog + policies]
    C --> F[LLM provider<br/>real API or offline stub]
    D --> F
    E --> F
    F --> G{Confident & in-policy?}
    G -->|yes| H[Auto-resolved answer<br/>+ citations]
    G -->|no| I[Escalate to human]
    H --> J[(ROI dashboard:<br/>deflection, time &amp; cost saved)]
    I --> J

Results / impact

Metrics below are produced by replaying the 20 seeded support tickets in data/tickets.json through the live agent (make roi). Change the policies, catalog, or ticket set and the numbers move. They are earned, not hard-coded.

Metric	Value
Tickets handled	20
Auto-resolved (deflection rate)	80% (16 / 20)
Escalated to human	20% (4 / 20): both defect claims, the billing dispute, the manager demand
Baseline human handle time	7 min / ticket
Agent handle time saved (sample)	1.87 h
Loaded agent cost	$28 / hr
Projected monthly savings	≈ $7,840 at 3,000 tickets/mo

At a typical mid-market volume of 3,000 tickets/month, an 80% deflection rate frees roughly 280 agent-hours per month. The agent's conservative escalation policy means the 20% that do reach a human are the genuinely hard cases (unverified physical defects, billing/fraud, irate customers), exactly where human judgement adds value.

The vertical is swappable. Replace the knowledge base (catalog/policies) to retarget legal intake, real-estate lead handling, or healthcare admin. The agent, retrieval, escalation, and ROI machinery stay the same; only data/ changes.

Quickstart

Runs fully offline with a deterministic stub provider. No API keys required.

# 1. install (CPython 3.10+)
python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt

# 2. run the test suite (offline, green)
make test           # or: python -m pytest -q

# 3. see the ROI report in your terminal
make roi

# 4. launch the app (prints the URL)
make demo           # -> http://localhost:8000/  (chat)  +  /dashboard  (ROI)

Ask it things from the command line, too:

python -m supportcopilot.cli ask "what is your return policy?"
python -m supportcopilot.cli ask "return my tent, it's unused" --order NW-1001 --email alex@example.com

Using a real LLM (optional). Install the provider extras and set a key; the app switches from the stub automatically:

pip install -r requirements-llm.txt
export ANTHROPIC_API_KEY=sk-ant-...     # or OPENAI_API_KEY=sk-...
make demo

Tech stack

• Python 3.10+, with FastAPI + Jinja2 + htmx as a single-container web app (chat UI + dashboard), no JS build step.
• scikit-learn TF-IDF cosine retrieval, with a dependency-free pure-Python fallback so retrieval never breaks the build.
• Provider interface with real Anthropic/OpenAI backends and a deterministic offline stub, zero-key by default.
• pytest (49 tests: retrieval, policy/refund logic, agent routing, ROI math, web layer).
• Docker + docker-compose, GitHub Actions CI (tests on 3.10–3.12 + container smoke test).

Deploy

Single container, deployable anywhere that runs a Docker image. The container needs no secrets to run (it uses the offline stub); add ANTHROPIC_API_KEY/OPENAI_API_KEY to enable a real model.

Local Docker

make docker && make docker-run        # http://localhost:8000
# or: docker compose up --build

Render / Fly.io. Point at the Dockerfile; the app binds 0.0.0.0:$PORT (both platforms set $PORT). On Fly: fly launch then fly deploy. On Render: new Web Service → Docker → no start command needed. Set provider keys as environment variables if you want a real model.

Hugging Face Spaces (Docker SDK). Create a Docker Space, push this repo; Spaces sets $PORT (usually 7860) and the container honours it. Add keys under Settings → Secrets to enable a real provider.

Screenshots

Screenshots placeholder. Add docs/chat.png and docs/dashboard.png. Run make demo and open http://localhost:8000/ (chat) and /dashboard (ROI) to capture them.

Chat (grounded answers + citations)	ROI dashboard (deflection, time & cost saved)
docs/chat.png	docs/dashboard.png