Kapruka AI Shopping Assistant

An enterprise-grade, multilingual agentic shopping assistant powered by the Model Context Protocol (MCP) and Zero-Cost In-Flight Vector Intelligence for Sri Lanka's largest e-commerce marketplace.

---

🚀 Overview

Kapruka AI is an intelligent conversational commerce assistant designed for Kapruka. It allows shoppers to search live inventory, explore curated categories, verify courier delivery windows, personalize recommendations based on past purchases, manage carts with concurrency protection, and initiate one-click checkouts—all from a single cohesive workspace.

Core Highlights

• Model Context Protocol (MCP) Core: Live JSON-RPC tool binding to Kapruka's official catalog, inventory, delivery verification, and order tracking services.
• Zero-Cost In-Flight Vector Intelligence: On-the-fly dense embeddings (FastEmbed ONNX Runtime on CPU) for time-decayed customer taste profiling and candidate reranking in <3ms with $0 cloud vector DB cost.
• Real-Time SSE Thinking Stream: Live reasoning trace (thought_delta) with collapsible progressive disclosure and phase-aware Jakub Antalik ThinkingOrb avatar animations.
• Trilingual & Colloquial Support: Native understanding of English, Sinhala, Tamil, Singlish, and Tanglish with strict Latin-script output contracts for romanized vernacular.
• Direct Cached Catalog API: In-memory TTL caching for categories and featured collections (<20ms response time) with live instant search filtering.
• Optimistic Concurrency Control (OCC): Revision-tracked cart manager with distributed locking to prevent multi-tab and human-agent mutation conflicts.

---

🛠️ Technology Stack

Layer	Technology	Purpose & Capabilities
Frontend	Next.js 16 (Turbopack) + React 19	App Router, Server Components, SSR/Static hydration, responsive mobile-first UI.
Styling	Vanilla CSS + Tailwind CSS Tokens	Tailored warm paper light theme, accessible focus rings, zero double-border artifacts.
Backend	FastAPI (Python 3.12)	Async SSE streaming endpoints, multi-provider LLM routing, and MCP tool execution.
Vector Engine	FastEmbed (ONNX Runtime CPU)	25MB quantized bge-small-en-v1.5 embeddings running in-memory on standard CPU (<3ms).
Tool Protocol	Model Context Protocol (MCP)	JSON-RPC 2.0 interface to remote Kapruka e-commerce tools.
LLM Routing	OpenRouter / Gemini / Groq	Multi-provider fallback architecture supporting Google Gemma, Claude 3.5 Haiku, and Llama 3.3.
Audio & Speech	Web Speech API + ElevenLabs	Multilingual speech-to-text dictation and natural neural text-to-speech output.
State Persistence	Redis / In-Memory Fallback	24-hour cart TTL, 7-day conversation retention, and atomic distributed mutex locks.

---

📐 System Architecture & Data Flow

sequenceDiagram
    autonumber
    actor User as Client (Web / Mobile)
    participant FE as Next.js 16 (App Router)
    participant BE as FastAPI Backend
    participant Vec as In-Flight FastEmbed (ONNX)
    participant LLM as LLM Provider (Gemma / Claude)
    participant MCP as Kapruka MCP Server

    User->>FE: Prompt / Dictation ("Chocolate cake under 6000 for Colombo")
    FE->>BE: POST /api/chat (SSE Request)
    BE->>LLM: Stream Inference with System Contract & Tools
    LLM-->>BE: thought_delta (Reasoning Tokens)
    BE-->>FE: SSE event: thought_delta
    FE-->>User: Renders compact ThinkingBlock & Orb Animation

    LLM->>BE: Call Tool: kapruka_search_products
    BE->>MCP: POST /mcp (Execute tool with search args)
    MCP-->>BE: Raw Catalog Candidates (10-15 items)
    BE->>Vec: In-Flight Cosine Reranking + Taste Centroid (<3ms)
    Vec-->>BE: Ranked Candidates with Semantic Confidence
    BE->>LLM: Return Filtered Tool Results
    LLM-->>BE: text_delta (Conversational Guidance)
    BE-->>FE: SSE event: text_delta + products payload
    FE-->>User: Displays Text + Interactive Product Cards

Loading

---

⚡ Key Architectural Capabilities

1. Zero-Cost In-Flight Vector Personalization

Rather than maintaining an expensive static vector database that suffers from stale inventory and pricing drift, the system utilizes In-Flight Vectors:

• Customer Taste Centroid: Automatically computes a time-decayed preference vector ($\vec{P}_{user} = \sum w_i \vec{v}_i$) from past Kapruka orders.
• Candidate Reranking: When MCP returns live candidate items, FastEmbed generates on-the-fly embeddings on standard CPU in 2.6ms, scoring candidates against the prompt and user taste.
• Mathematical Hybrid Scoring: $$\text{FinalScore} = \text{LexicalScore} + 3.0 \cdot \text{SemanticSimilarity} + \text{TasteBoost}$$

2. BeautifulUI PromptBar & Autocomplete

The floating composer includes:

• @ Sources Menu: Quick context references (@cart, @delivery, @profile).
• / Slash Commands: Instant workflow shortcuts (/gift, /track, /categories, /offers, /status, /clear).
• Integrated Voice Dictation: One-tap microphone recording with live audio pulse state.

3. Jakub Antalik Dynamic ThinkingOrb System

Assistant avatars display real-time single-orb animations corresponding to the agent's active internal state:

• searching: Radar sweep during catalog and category queries.
• solving: Rubik scramble during cart updates, delivery verification, and checkout.
• composing: Flowing ribbon during streaming responses.
• shaping: Smooth morphing sphere in idle state.
• listening: Amber pulsing orb during voice dictation.

4. Dual Workspace Isolation

• Demo Mode (customer_mode: "demo"): Pre-seeded with customer profile ("Praveen Gunaratne"), saved delivery addresses, order history, and luxury gifting taste profile.
• Anonymous Mode (customer_mode: "anon"): Clean, isolated guest shopping session.

---

💻 Local Development & Setup

Prerequisites

• Node.js: v18.18+ or v20+
• Python: v3.11 or v3.12

Quick Start (Automated Script)

# Start both backend and frontend development servers
powershell -ExecutionPolicy Bypass -File scripts/dev.ps1

# Reload development servers with changes
powershell -ExecutionPolicy Bypass -File scripts/dev.ps1 -Reload

# Stop servers
powershell -ExecutionPolicy Bypass -File scripts/dev.ps1 -Stop

Manual Setup

1. Backend Setup

cd backend
python -m pip install -r requirements.txt
python -m uvicorn main:app --reload --port 8000

2. Frontend Setup

cd frontend
npm install
npm run dev

Local Service URLs

• Frontend App: http://127.0.0.1:3000
• Backend API: http://127.0.0.1:8000
• API Documentation: http://127.0.0.1:8000/docs

---

🧪 Comprehensive Verification Suite

Run the full end-to-end test suite across backend and frontend:

# 1. Backend Unit Tests (175 tests: MCP client, tools, routes, vector engine)
python -m pytest backend/tests/ -v

# 2. Frontend Unit & Session Storage Tests
npm --prefix frontend run test:session-store
npm --prefix frontend run test:assistant-presentation
npm --prefix frontend run test:cart-revision

# 3. Code Quality & Production Build
npm --prefix frontend run lint
npm --prefix frontend run build

---

📚 Technical Documentation & Whitepapers

Detailed architecture guides and production blueprints are available in the repository root:

• SYSTEM_ARCHITECTURE_DEMO_GUIDE.md: Executive overview, numerical parameters, TTLs, session retention, and production microservices scaling roadmap.
• ZERO_COST_VECTOR_PERSONALIZATION_GUIDE.md: Deep-dive into in-flight vector mathematics, FastEmbed ONNX benchmarks, and zero-cost customer taste centroids.
• DEPLOYMENT.md: Production containerization, Vercel frontend deployment, and cloud infrastructure guide.

---

👨‍💻 Author

Built with ❤️ by HimanM

• GitHub: github.com/HimanM
• LinkedIn: linkedin.com/in/HimanM