Kapu — Kapruka AI Shopping Agent
Kapu is a full-screen conversational shopping companion built for Kapruka, Sri Lanka’s largest e-commerce platform. Shoppers chat naturally in English, Singlish, or Sinhala to browse the live catalog, get Kapu’s opinion, check delivery, and complete guest checkout — powered by the public Kapruka MCP API and OpenAI.
The architecture splits a Next.js 15 chat UI from a FastAPI backend that proxies MCP calls (`search_products`, `list_categories`, `check_delivery`, `kapruka_create_order`). A rule-first router sends each turn to a specialist agent — shopper (everyday buys), gift (occasions & recipients), or companion (small talk) — with deterministic special flows for compare, surprise-me, gift clarify, and vague Singlish asks (`mokada meka?`). Ambiguous turns can optionally use Fireworks; most routing stays rule-based to keep latency and cost down.
Beyond text chat, Kapu supports English voice input via OpenAI Whisper, bilingual reply matching, shopping-session state (occasion, recipient, budget, city, language) persisted in localStorage, product carousels and sticky detail sheets, gift-message writing with live card preview, partial-cart checkout, and real Kapruka pay links. Deployed as Vercel (frontend) + Render (backend) with CORS and health-check wiring for demos.
Year
Features
Technologies
- Routing everyday vs gift vs companion turns without overusing the LLM on every message
- Keeping search useful when the model forgets to call tools
- Supporting mixed-language input against an English-leaning product catalog
- Wrapping a live third-party MCP surface (search, delivery, orders) behind a stable REST API
- Wiring CORS and Render cold starts so Vercel demos work end-to-end
- Persisting shopping context across refresh without a heavy backend session store
- Deterministic rule signals for most turns; optional Fireworks only when ambiguous
- Search fallback path when expected tool calls are missing
- Match reply language to the user; keep search queries English-heavy for recall
- FastAPI layer with typed endpoints, MCP proxying, session merge, and structured JSON
- Render Blueprint + documented CORS_ORIGINS / health wake checklist for demos
- Client-side shopping session in localStorage synced into each chat request
Key Features
Conversational product search with budget filters, exclusions, and tool-call fallback
Multi-agent routing: kapu_shopper, kapu_gift, kapu_companion
Special flows: compare verdict cards, Surprise me, vague-query clarify, gift clarify
Categories-on-ask with tappable chips from live MCP category list
Delivery reality check via MCP check_delivery (city + date)
Full guest checkout and partial-cart checkout with Kapruka pay links + pay deadline card
AI gift-message writer (Write for me / Tell Kapu) with live gift-card preview
Voice input (English STT) via OpenAI Whisper; Kapu replies in text
Visual product UI: Embla carousels, sticky add-to-cart sheets, mobile cart/checkout
Shopping session persistence in localStorage (occasion, recipient, budget, city, language)
Conversion nudges after browsing without adding to cart
Landing page with animated Kapu mascot → full-screen chat at /chat
Language baseline evals under backend/evals
Technologies
Learnings
Built an end-to-end shopping agent against a live third-party MCP catalog and order API
Designed rule-first multi-agent routing with optional LLM fallback only for ambiguous turns
Handled English / Singlish / Sinhala replies while keeping catalog search English-heavy
Shipped production deploy wiring: Vercel frontend, Render Blueprint backend, CORS, cold starts
Structured chat responses with agent metadata, session merge, and telemetry latency
Combined OpenAI tool-calling with deterministic special flows (compare, surprise, clarify)
Highlights
3 Specialist Agents
Live MCP Catalog
Guest Checkout + Voice
Next Project