The Problem
E-commerce customers repeatedly ask the same operational questions—order status, return policy, and how to reach a human. Each query costs support time, and answers live in separate systems (databases, policy documents, contact workflows). Ari centralizes those three intents into a single chat interface backed by Google Gemini for intent detection, so routine questions resolve without an agent.
What This Does
Ari is a Gradio chat application with a modular agent architecture. The src/agents/ directory contains three intent-specific handlers—orderstatusagent.py, returnpolicyagent.py, and humanrepagent.py—coordinated by src/core/conversation.py. Order lookups query a SQLite database through SQLAlchemy (src/db/), return policy answers come from data/policies.json, and human handoff collects contact details via src/services/contactservice.py.
The LLM layer is a thin abstraction. src/llm/geminiservice.py handles primary inference, while fallbackllmservice.py and groqservice.py provide alternatives. The app.py entry point launches the Gradio interface defined in src/ui/gradioapp.py. Docker support exists via Dockerfile and docker-compose.yml, and CI runs through .github/workflows/ci.yml.
How To Use It
Setup — Clone the repo, create a virtual environment, and install dependencies. The README prescribes uv for package installation, but note that requirements.txt is the only dependency manifest. No lockfile exists, so builds are not fully reproducible.
Configuration — Required environment variables live in .env.example. The critical one is the Google Gemini API key; the code also supports Groq as an alternative provider. Copy .env.example to .env and populate it before running.
Running it — app.py is the entry point. The README documents launching via Gradio directly. A Docker path also exists if you prefer containerized execution.
Local development (from README)
pip install uv uv venv source .venv/bin/activate # macOS/Linux uv pip install -r requirements.txt python app.py
Or via Docker
docker-compose up
Real-World Use
A small-to-mid-size e-commerce operation with a SQLite order database and a static return policy document can deploy this as a first-line support channel. A customer asks "Where is my order?"—Gemini classifies the intent, orderstatusagent.py queries the database by the 32-character order ID, and the response returns in the chat. If the customer asks for a person, humanrepagent.py collects their contact details and contactservice.py queues a follow-up. The Gradio UI means non-technical staff can monitor or test the bot without a custom frontend.
Code Health & Issues
Med — No dependency lockfile. requirements.txt declares direct dependencies only, so transitive versions drift across installs. Use uv lock or pip freeze to pin. Med — data/cachedorders.csv and data/policies.json ship in-repo. If the CSV contains real customer data (order IDs, names), that is a privacy exposure. Verify contents before public deployment. Low — The README mentions a chatbotdata.db file in data/, but the file listing shows only cachedorders.csv and policies.json. Either the DB is generated at runtime via src/db/setupdb.py or the README is stale. Low — Tests exist (tests/testmainflows.py, tests/testfallback_llm.py) and CI is configured. Coverage appears thin but present. The src/llm/interface.py abstraction is a reasonable pattern for swapping providers. Low — No input validation visible beyond what SQLAlchemy and the agent logic enforce. Order ID format is checked per the README, but free-text prompt injection into Gemini is not addressed.
The Bottom Line
This is a solid, well-structured starter for an LLM-backed support chatbot. The agent separation is clean, the fallback LLM layer is a thoughtful touch, and the Docker/CI setup makes it deployable. It is not production-hardened—no lockfile, potential data exposure in the repo, and limited test coverage—so treat it as a working prototype to harden rather than a finished product. Best suited for a team wanting a working reference architecture for Gemini-based conversational agents.