BuyWise Agent MVP 🤖🛒

A LangGraph multi-agent RAG assistant for warranty/return decisions — local-first, demo-ready.

🎯 What It Does

Upload a receipt + warranty card + policy → ask "can I still return/warranty this?" → system runs 4 agents to produce an evidence-backed answer with action drafts.

This is the MVP (Minimum Viable Product). It covers the warranty/return decision scenario end-to-end. Price monitoring, review summarization, and async workers are planned for later phases (see Roadmap).

🧠 Architecture (MVP)

🎬 Live Demo

Click the image above to watch the interactive terminal demo — project structure overview + headphone warranty/return case run.

🚀 Quickstart

# 1. Install (MVP core deps only). The Makefile uses $(PYTHON), which defaults to
#    `python3` — activate the venv so it resolves to the project interpreter, or
#    override per run: make demo PYTHON=python3.10
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# 2. Run the test suite
make test

# 3. Run the warranty demo
make demo

# 4. Try the laptop return case
make demo-laptop

# 5. Run eval (2 cases, 4 metrics)
make eval

# 6. Start FastAPI server
make dev

# 7. (optional) Full stack: API + PostgreSQL + Redis via Docker
cp .env.example .env   # docker compose requires this file to exist
make up                # web UI (3000) is NOT included — see Roadmap Phase 7

📸 Demo Output

  BuyWise Agent MVP — Warranty/Return Demo

  📄 Source: headphone_warranty_case/
  💬 Query:  My headphones stopped charging after 7 months.
             Can I claim warranty?

  ────────────────────────────────────────────────────────
  📊 ANALYSIS RESULT
  ────────────────────────────────────────────────────────
  Intent:        warranty_or_return
  Evidence used: 15 chunks
  Confidence:    1.0

  📋 Key Facts:
    ⚠️  [0.9] Intent classified as: warranty_or_return
    ✅ [0.6] Purchase date: 2025-11-10
    ✅ [0.7] Warranty period: 1 year

  📝 Suggested Actions:
    🔓 [draft_email] Draft return/refund request to merchant
    🔓 [export_report] Collect these items before contacting support

📡 API Usage

POST /api/chat

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "query": "My headphones stopped charging after 7 months. Can I claim warranty?",
    "source_dirs": ["sample_data/headphone_warranty_case"]
  }'

Response (JSON):

{
  "status": "complete",
  "intent": "warranty_or_return",
  "summary": "Your product appears to be within the warranty period. You can file a warranty claim.",
  "key_facts": [
    {
      "text": "Purchase date: 2025-11-10",
      "confidence": 0.6,
      "supported": true
    },
    {
      "text": "Warranty period: 1 year",
      "confidence": 0.7,
      "supported": true
    }
  ],
  "actions": [
    {
      "action_id": "act_warranty_claim",
      "type": "draft_email",
      "description": "Draft warranty claim email to merchant",
      "requires_approval": false
    }
  ],
  "evidence_count": 6,
  "confidence": 1.0
}

GET /health

curl http://localhost:8000/health
# {"status": "ok", "service": "buywise-agent-mvp"}

📊 Eval (current)

• Evidence Recall: 0.8 — 80% of gold keywords found in retrieved evidence
• Forbidden Claim Avoidance: 1.0 — no hallucinated claims
• Action Generation: 1.0 — expected action types all present
• Confidence Reported: 1.0 — confidence always populated

📁 Structure

buywise-agent/
├── agent/              # LangGraph workflow
│   ├── graph.py        # 7-node graph with loop guard
│   ├── state.py        # Pydantic data models
│   └── agents/         # supervisor + 5 specialists (order, policy, product, verifier, action)
├── assets/             # Architecture diagram (SVG + HTML)
├── ingestion/parsers/  # File parsers (PDF, CSV, EML, HTML, TXT)
├── retrieval/          # Keyword search + rerank + compress
├── apps/api/           # FastAPI backend (2 endpoints)
├── eval/               # Eval suite (2 cases, 4 metrics)
├── tests/              # Pytest suite (intent, routing, ingestion parsers)
├── sample_data/        # 3 synthetic demo cases
├── scripts/demo.py     # CLI demo runner
├── docker-compose.yml  # API + PostgreSQL + Redis (no web UI / worker — see Roadmap)
└── Makefile

🛣️ Roadmap (post-MVP)

• Phase 4: Full pgvector + BM25 hybrid retrieval. The in-memory retriever is
  budget-bound, not rank-bound: it is keyword-only (query_terms = query.split(), no
  stemming or stop-word removal) and a chunk that shares no term with the query scores
  zero and is dropped. Retrieval recall now reads 1.00: 0.60 → 0.90 came from raising the
  measured budget (top_k=20 / max_chunks=15), and the last 0.10 from correcting a gold
  keyword that never matched the data — the case asked for "May 15" while the files store
  ISO dates (2026-05-15). The real ceiling is the ranking, not the budget: a query whose
  terms never overlap a chunk still retrieves nothing.
• Phase 5: Price monitor + deadline watch agents → proactive alerts
• Phase 6: Async workers (Celery) + review summarization agent
• Phase 7: Web UI (Streamlit/Next.js) + real EML/PDF upload
• Phase 8: Replace the keyword-based intent classifier with an LLM/embedding
  classifier. Substring matching cannot generalise — every inflection whose stem is
  respelled (charging, broke, warranties, stopped working) has to be listed by
  hand, and an unseen phrasing such as "my phone just died" still falls through to
  general_qa. The keyword list is a stop-gap, not a classifier.

To install extras for later phases:

# For vector DB / async workers (Phase 4+)
pip install -e ".[pgvector]"

# For advanced eval metrics (Phase 3+)
pip install -e ".[evalextra]"

⚠️ What This MVP Does NOT Do

• ❌ No multi-user / auth
• ❌ No real-time Gmail/Amazon integration
• ❌ No PostgreSQL/vector DB (runs with in-memory keyword search)
• ❌ No async background workers
• ❌ No purchase-decision flow (intent is detected, but returns unsupported_intent)
• ❌ No price monitoring or review analysis
• ❌ No web frontend (API + CLI only)

All of these are scoped for post-MVP phases.

⚠️ Disclaimer

BuyWise Agent provides evidence-backed consumer suggestions, not legal advice. Users must review all drafts before acting.