How rumeshmohan/kapruka_agent_challenge works
1. Overall shape
- This is a Python, Streamlit-based conversational agent app packaged for Docker deployment.
- The repository is organized around a single user-facing chat interface that delegates work to a router + specialist agents architecture, with shared memory and an LLM/tooling layer underneath.
2. Entry points and deployment
- app.py is the declared Streamlit entrypoint in the README metadata.
- ui/app.py appears to hold the main UI implementation, while main.py likely provides an alternate startup path or non-UI bootstrap.
- Dockerfile and .streamlit/config.toml define the runtime container and Streamlit execution settings.
3. Presentation layer
- The ui/ package is the front end boundary: it gathers user input, displays agent responses, and likely manages session state for the chat experience.
- The README describes the product as supporting localized trilingual voice and dialect queries, so the UI is the place where language/dialect entry and conversational output are surfaced.
4. Conversation routing
- agents/router.py is the central orchestration point.
- It likely inspects the user’s message, conversation context, and possibly profile state to decide which specialist agent should handle the request.
- This is the main architectural boundary between “chat UI” and “domain logic.”
5. Specialist agents
- The agent layer is split into domain-focused modules:
- catalog_agent.py for product discovery / item lookup
- checkout_agent.py for purchase or ordering flows
- logistics_agent.py for delivery, shipping, or fulfillment questions
- preference_agent.py for user preference handling / personalization
- chitchat_agent.py for general conversation and fallback social interaction
- This suggests a multi-agent decomposition rather than a single monolithic assistant.
6. Quality control loop
- agents/reflection_loop.py is a separate post-processing step.
- Architecturally, this implies generated answers may be reviewed, refined, or retried before being shown to the user.
- That makes the response pipeline: input → routing → specialist agent → reflection/improvement → final response.
7. State and memory
- memory/session_buffer.py holds per-session conversational state.
- This is the main persistence boundary for short-term context: user history, intermediate decisions, and possibly selected agent state.
- data/profiles.json looks like static profile or seed data used for personalization or testing.
8. LLM and tool integration
- utils/llm_services.py centralizes model access, so all agents likely call through a common LLM abstraction instead of talking to providers directly.
- utils/mcp_client.py indicates integration with MCP (Model Context Protocol) services, which is the likely bridge to external tools/data sources.
- In practice, specialist agents probably invoke the LLM layer first, then call MCP-backed tools when domain data is needed.
9. Configuration boundary
- config/model.yaml and config/params.yaml hold model/runtime settings such as provider choice, inference parameters, or agent behavior tuning.
- utils/config.py likely loads and normalizes these settings for the rest of the application.
- This keeps prompts, model selection, and runtime parameters outside the agent code.
10. Repository-level technology signals
- pyproject.toml, requirements.txt, and uv.lock show the project is managed as a modern Python application with locked dependencies.
- .example and .gitignore imply environment-variable-based configuration for secrets and deployment-specific values.
- The Streamlit/Hugging Face-style metadata in README.md suggests the app is intended to run as a hosted interactive demo or production prototype.
11. End-to-end data flow
- User input enters through the Streamlit UI.
- The router chooses the best agent using the current session context.
- The selected agent consults shared memory, LLM services, and, when needed, MCP tools.
- The reflection loop can refine the draft answer.
- The final response is returned to the UI and stored back into the session buffer.
12. Key architectural boundaries to diagram
- UI boundary: Streamlit frontend vs. backend reasoning
- Orchestration boundary: router vs. specialist agents
- State boundary: short-term session memory vs. stateless processing
- Model/tool boundary: LLM abstraction vs. MCP external services
- Configuration boundary: YAML/config files vs. runtime code
13. What is most distinctive here
- The repository is not a generic chatbot; it is a domain-routed, multi-agent assistant with a dedicated reflection step and external tool connectivity.
- The architecture is designed to support localized commerce assistance: product catalog, checkout, logistics, and personalized preference handling all live as separate agents under one conversational surface.
Main entry points: router.py Router · app.py Chat UI · config.py Config Loader · llm_services.py LLM Services
Components 19
Presentation
User-facing Streamlit chat interface and startup entrypoints
Agents
Routing, specialist agents, and response refinement
- Router · Selects the right specialist agent
agents/router.py - Catalog · Product discovery and item lookup
agents/catalog_agent.py - Checkout · Purchase and ordering flows
agents/checkout_agent.py - Logistics · Shipping and fulfillment support
agents/logistics_agent.py - Preferences · Personalization and user preferences
agents/preference_agent.py - Chitchat · General conversation and fallback
agents/chitchat_agent.py - Reflection · Refines or retries draft answers
agents/reflection_loop.py
State
Session memory and personalization data
- Session Memory · Per-session chat context and state
memory/session_buffer.py - Profiles · Static profile data for personalization
data/profiles.json
Services
Shared LLM, tool, and config access
- LLM Services · Shared abstraction for model calls
utils/llm_services.py - MCP Client · Connects agents to external tools and data
utils/mcp_client.py - Config Loader · Loads and normalizes runtime settings
utils/config.py - Model Config · Model/provider configuration
config/model.yaml - Params Config · Inference and agent tuning parameters
config/params.yaml
Deploy
Container and Streamlit runtime setup
- Dockerfile · Container runtime definition
Dockerfile - Streamlit Config · Streamlit execution settings
.streamlit/config.toml
Connections 34
- app.py → Chat UI: starts · Entry point launches the chat UI
- main.py → Chat UI: boots · Alternate startup path reaches the UI
- Chat UI → Router: send message · User input is routed to a specialist
- Router → Catalog: dispatch · Routes product queries
- Router → Checkout: dispatch · Routes ordering flows
- Router → Logistics: dispatch · Routes delivery questions
- Router → Preferences: dispatch · Routes personalization requests
- Router → Chitchat: dispatch · Routes general conversation
- Catalog → Session Memory: context · Uses conversational state
- Checkout → Session Memory: context · Uses conversational state
- Logistics → Session Memory: context · Uses conversational state
- Preferences → Session Memory: context · Uses conversational state
- Chitchat → Session Memory: context · Uses conversational state
- Catalog → LLM Services: model call · Generates or interprets responses through shared LLM access
- Checkout → LLM Services: model call · Generates or interprets responses through shared LLM access
- Logistics → LLM Services: model call · Generates or interprets responses through shared LLM access
- Preferences → LLM Services: model call · Generates or interprets responses through shared LLM access
- Chitchat → LLM Services: model call · Generates or interprets responses through shared LLM access
- Catalog → MCP Client: tools · Fetches external data when needed
- Checkout → MCP Client: tools · Fetches external data when needed
- Logistics → MCP Client: tools · Fetches external data when needed
- Preferences → MCP Client: tools · Fetches external data when needed
- Router → Reflection: review · Draft responses may be refined before return
- Reflection → Chat UI: final response · Refined answer is returned to the user interface
- Chat UI → Session Memory: store state · Chat turns are persisted in session memory
- Preferences → Profiles: personalize · Uses profile seed data for user-specific behavior
- Config Loader → Model Config: load · Reads model settings
- Config Loader → Params Config: load · Reads runtime parameters
- Chat UI → Config Loader: settings · Uses shared application configuration
- Router → Config Loader: settings · Uses shared application configuration
- LLM Services → Config Loader: settings · Resolves provider and runtime configuration
- MCP Client → Config Loader: settings · Uses connection and runtime configuration
- Dockerfile → app.py: run · Container launches the Streamlit app
- Streamlit Config → Chat UI: runtime · Controls Streamlit behavior