How sethum-vs/agentickapruka works
1. Overall shape
- This repo is a Python 3.12+ FastAPI application that serves a server-rendered, chat-first shopping experience for Kapruka.
- The architecture is split into: browser UI, HTTP/app layer, LangGraph orchestration, and external data/memory services.
2. Client/UI boundary
- The browser talks mainly through HTMX-driven HTML fragments and Server-Sent Events, not a SPA API.
- Core UI surfaces are the chat page, cart drawer, checkout forms, and small reusable partials under templates/ plus client scripts in static/js/.
3. FastAPI application layer
- app/main.py mounts route modules for chat, cart, checkout, session, partials, dev, and health.
- app/lifespan.py manages startup/shutdown for the service dependencies, while app/middleware/errors.py centralizes error handling.
- This layer is the boundary between HTTP requests and the agent/workflow logic.
4. Chat request pipeline
- The main conversational flow is in graphs/shopping_graph.py and its nodes.
- Each message is classified by intent, supervised by master_flow, then routed into one of a few paths: discovery, cart actions, checkout, tracking, or general/support.
- Responses are streamed back to the browser, which is why chat feels incremental rather than request/response only.
5. Discovery and retrieval path
- Shopping discovery uses a hybrid retrieval stack: query preprocessing, intent/specificity gating, Neo4j-based context expansion, and Zep memory for preferences.
- graphs/nodes/retrieve_hybrid_context.py and related helpers in lib/neo4j/ and lib/zep/ shape the search context before any live Kapruka tools are called.
- The design keeps vague requests from hitting the catalog blindly; the assistant may ask clarifying questions first.
6. Bounded agent loop
- After retrieval, the shopping graph enters a bounded agent loop that can call Kapruka tools, inspect results, and then generate a final answer.
- Product curation logic in lib/chat/ filters and ranks results so the UI shows gift-relevant items rather than raw catalog output.
- The loop is intentionally capped, which keeps browsing deterministic enough for a chat commerce flow.
7. Checkout as a separate deterministic workflow
- Checkout is not handled by the same open-ended shopping loop; it has its own LangGraph in graphs/checkout_graph.py.
- The checkout path is stepwise and ordered: cart, delivery city, delivery date, recipient, sender, review, finalize.
- State is persisted in Redis so the user can move through forms without losing progress, and the review/finalization steps are more controlled than discovery.
8. Live commerce integration
- All live product, delivery, and order actions go through the Kapruka MCP service abstraction in lib/kapruka/.
- The MCP client/tool executor wraps functions like search, get product, delivery validation, order creation, and tracking.
- This is the main boundary to the external commerce system; the app does not directly embed product data.
9. Data and memory layer
- Redis is the operational state store: sessions, cart, checkout state, cache, rate limiting, and LangGraph checkpointer behavior.
- Neo4j holds the gift/category ontology and vector-searchable graph context used for GraphRAG-style retrieval and recommendations.
- Zep provides longer-term conversational memory and customer preferences across sessions.
10. Model and AI routing
- Google Vertex AI Gemini powers intent classification and response generation.
- Model routing in graphs/model_router.py and lib/chat/model_router.py chooses lighter or heavier models depending on task complexity, with more capable models reserved for complex checkout/review turns.
- Embeddings also come from Vertex AI and feed the Neo4j hybrid retrieval pipeline.
11. Recommendations and background analytics
- There is a separate analytics path under lib/analytics/ that computes co-purchase communities using NetworkX, with an optional cuGraph path for GPU/local use.
- The output is written back into Neo4j as recommendation relationships, so recommendation generation is batch/background work rather than part of every chat turn.
12. Operational boundaries
- /health aggregates dependency state across Redis, Neo4j, Zep, and the Kapruka MCP endpoint.
- Deployment is containerized with Docker and targeted at Google Cloud Run, with Gunicorn used for serving in production.
- The repo also includes dedicated evals and a large test suite, which act as a quality boundary for the agent flows, checkout state machine, and integration with external services.
Main entry points: main.py App entry · shopping_graph.py Shopping graph · redis Redis state · checkout_graph.py Checkout graph
Components 29
Browser UI
Server-rendered chat, cart, and checkout surfaces driven by HTMX and SSE.
- Chat views · Chat page, message fragments, and empty state rendered server-side.
templates/chat - Checkout views · Stepwise checkout forms, review screen, and tracking fragments.
templates/checkout - UI parts · Reusable cart, product, navigation, and status components.
templates/components - Client scripts · HTMX-adjacent helpers for chat, SSE, cart drawer, and countdown widgets.
static/js
HTTP App
FastAPI entrypoints, routing, middleware, startup, and health boundary.
- App entry · Creates the web application and mounts route modules.
app/main.py - Lifespan · Initializes and tears down service dependencies.
app/lifespan.py - Error middleware · Centralized request error handling and response shaping.
app/middleware/errors.py - Chat route · Chat turn handling, streaming responses, and chat page entry.
app/routes/chat.py - Checkout route · Checkout form steps, review, finalize, and tracking endpoints.
app/routes/checkout.py - Cart route · Cart operations and drawer updates.
app/routes/cart.py
Agent Graphs
LangGraph orchestration for shopping discovery and checkout.
- Shopping graph · Main conversational workflow for discovery, cart actions, tracking, and support.
graphs/shopping_graph.py - Checkout graph · Deterministic checkout state machine for order completion.
graphs/checkout_graph.py - Master flow · Classifies intent and selects the shopping path.
graphs/nodes/master_flow.py - Hybrid context · Builds query context with Neo4j expansion and Zep memory.
graphs/nodes/retrieve_hybrid_context.py - Agent loop · Calls commerce tools, inspects results, and prepares final responses.
graphs/nodes/agent_loop.py - Checkout steps · Ordered checkout progression across cart, delivery, recipient, sender, review, and finalize.
graphs/nodes/checkout_steps.py
Service Layer
Chat helpers, commerce adapters, retrieval, memory, and persistence services.
- Chat logic · Intent heuristics, routing, streaming, curation, prompts, and chat session utilities.
lib/chat - Checkout logic · Form parsing, delivery validation, recipient/sender review, payment, and tracking helpers.
lib/checkout - Kapruka MCP · Tool executor and MCP client for live product, delivery, order, and tracking actions.
lib/kapruka - Neo4j graph · Ontology, vector search, traversal, and hybrid context support.
lib/neo4j - Redis state · Sessions, cart, checkout, cache, rate limits, and LangGraph checkpointing.
lib/redis - Zep memory · Conversation memory and user preference storage across sessions.
lib/zep - Gemini AI · Vertex AI client, fallback handling, and model routing support.
lib/genai - Analytics · Co-purchase community computation for recommendation relationships.
lib/analytics
External Systems
Outside dependencies the app integrates with at runtime.
- Vertex AI · Generates classifications, responses, and embeddings.
- Kapruka MCP · Live catalog, delivery, order creation, and tracking backend.
- Neo4j DB · Stores ontology, traversal context, and recommendation relationships.
- Redis · Operational state, cache, rate limiting, and checkpoint persistence.
- Zep · External memory service for long-term preferences.
Connections 32
- App entry → Chat route: mounts · Registers chat endpoints and page handlers.
- App entry → Cart route: mounts · Registers cart endpoints.
- App entry → Checkout route: mounts · Registers checkout endpoints.
- App entry → Lifespan: uses · Starts and stops dependencies with the app.
- App entry → Error middleware: uses · Applies centralized error handling.
- Chat route → Shopping graph: runs · Delegates conversational shopping turns to the graph.
- Checkout route → Checkout graph: runs · Delegates checkout progression to the checkout graph.
- Cart route → Redis state: reads/writes · Persists cart state and session-linked data.
- Shopping graph → Master flow: routes through · Classifies intent and chooses the next path.
- Shopping graph → Hybrid context: retrieves context · Builds hybrid search context before tool use.
- Shopping graph → Agent loop: continues with · Executes bounded tool-driven shopping turns.
- Shopping graph → Chat logic: uses · Relies on chat heuristics, streaming, and curation helpers.
- Checkout graph → Checkout steps: advances through · Moves through the deterministic checkout sequence.
- Checkout graph → Checkout logic: uses · Uses form, review, payment, and tracking helpers.
- Hybrid context → Neo4j graph: queries · Expands context from graph ontology and vector search.
- Hybrid context → Zep memory: loads memory · Adds long-term preferences to retrieval context.
- Agent loop → Kapruka MCP: calls tools · Searches products, resolves details, and creates orders.
- Agent loop → Gemini AI: generates · Uses Gemini-based reasoning and response generation.
- Chat logic → Gemini AI: routes models · Selects lighter or heavier models by task complexity.
- Chat logic → Redis state: uses · Stores session and rate-limit related chat state.
- Checkout logic → Redis state: persists · Stores checkout progress and cart-linked order state.
- Kapruka MCP → Kapruka MCP: bridges to · Wraps the external commerce service boundary.
- Neo4j graph → Neo4j DB: stores/queries · Reads and writes ontology and recommendation data.
- Redis state → Redis: backed by · Operational state is persisted in Redis.
- Zep memory → Zep: backed by · Long-term memory is stored in Zep.
- Gemini AI → Vertex AI: uses · Calls Vertex AI for language and embedding work.
- Analytics → Neo4j DB: writes · Persists co-purchase communities as graph relationships.
- Chat views → Chat route: rendered by · Chat route serves these server-rendered fragments.
- Checkout views → Checkout route: rendered by · Checkout route serves step templates and partials.
- UI parts → Cart route: shared with · Reusable UI parts support cart and product surfaces.
- Client scripts → Chat views: enhances · Client scripts power incremental interactions and SSE.
- Client scripts → Checkout views: enhances · Client scripts support form interactions and countdowns.