How yufanpeter/e-commerce-ai-agent works
CartPilot is a conversational shopping assistant: the iOS user sends text, voice, or image input; the backend routes each turn to a shopping tool, retrieves grounded product results when needed, and returns structured results and composed responses. Users can refine or compare recommendations, inspect products, and manage a persistent cart and preferences. The README documents the major capabilities; sampled excerpts confirm key orchestration and retrieval ownership, but do not expose every tool or route implementation.
Main entry points: FrontendServices.swift Frontend Services · main.py FastAPI Routes · orchestrator.py Turn Orchestrator · search_service.py Hybrid Search
Components 27
iOS Client
- SwiftUI App
client/AIShoppingGuide/AIShoppingGuideApp.swift - Shopping Guide
client/AIShoppingGuide/GuideView.swift - Frontend Services
client/AIShoppingGuide/FrontendServices.swift - Product Details
client/AIShoppingGuide/ProductDetailView.swift - Comparison View
client/AIShoppingGuide/ComparisonView.swift - Cart View
client/AIShoppingGuide/CartView.swift - Preference View
client/AIShoppingGuide/PreferenceView.swift
HTTP API
- FastAPI Routes
backend/api/main.py - Product Routes
backend/api/products.py
Agent Workflow
- Turn Orchestrator
backend/agent/orchestrator.py - Intent Router
backend/agent/intent_router.py - Shopping Tools
backend/agent/tools - Answer Composer
backend/agent/composer.py
Search and Retrieval
- Hybrid Search
backend/search/search_service.py - Query Understanding
backend/search/query_understanding.py - LLM Query Parser
backend/search/llm_parser.py - Chroma Retriever
backend/rag/retriever.py - Optional Reranker
backend/rag/reranker.py
Product and State
- Chroma Index
backend/rag/chroma_store.py - Product Store
backend/store/product_store.py - Session Store
backend/store/session_store.py - Cart Store
backend/store/cart_store.py - Preference Memory
backend/store/user_memory_store.py
Other components
- Shopper
- Chat Model API
- Embedding API
- Reranking API
Connections 35
- Shopper → SwiftUI App: uses
- SwiftUI App → Shopping Guide: shows
- Shopping Guide → Frontend Services: requests
- Frontend Services → FastAPI Routes: REST and SSE
- FastAPI Routes → Turn Orchestrator: handles turns
- Turn Orchestrator → Intent Router: routes intent
- Intent Router → Chat Model API: classifies intent
- Turn Orchestrator → Shopping Tools: dispatches tool
- Turn Orchestrator → Answer Composer: composes response
- Answer Composer → Chat Model API: generates narrative
- Shopping Tools → Hybrid Search: searches products
- Hybrid Search → Query Understanding: interprets query
- Query Understanding → LLM Query Parser: extracts intent
- LLM Query Parser → Chat Model API: parses query
- Hybrid Search → Chroma Retriever: retrieves chunks
- Chroma Retriever → Chroma Index: queries vectors
- Chroma Retriever → Embedding API: embeds query
- Hybrid Search → Optional Reranker: optionally reranks
- Optional Reranker → Reranking API: scores candidates
- Hybrid Search → Product Store: grounds product facts
- Shopping Tools → Product Store: reads product data
- Turn Orchestrator → Session Store: persists sessions
- Shopping Tools → Cart Store: updates cart
- FastAPI Routes → Cart Store: reads cart
- FastAPI Routes → Product Routes: mounts routes
- Product Routes → Product Store: reads product data
- FastAPI Routes → Preference Memory: reads preferences
- Shopper → Product Details: inspects products
- Shopper → Comparison View: compares products
- Shopper → Cart View: manages cart
- Shopper → Preference View: sets preferences
- Product Details → Frontend Services: fetches details
- Comparison View → Frontend Services: requests comparison
- Cart View → Frontend Services: loads cart
- Preference View → Frontend Services: loads preferences