Smart Retail Assistant

A highly capable, production-ready conversational AI agent designed for an e-commerce platform. It handles product catalog searches, order status queries, and autonomously enforces strict business policies regarding returns and refunds.

• Conversational UI: A sleek, user-friendly Streamlit chat interface with real-time feedback and state retention.
• Provider Agnostic: Seamlessly swap between models. Out-of-the-box support for OpenRouter (access Anthropic, Gemini, OpenAI lite models) and Native OpenAI.
• Data Privacy via Function Calling: Catalog and order data (products.json, orders.json) are strictly accessed dynamically via tool calls. The raw database is never blindly dumped into the LLM prompt.
• Mutable In-Memory State: Order statuses can be updated during the session (e.g., initiating a return updates the order to "return_initiated"), enabling true multi-step conversational reasoning.

This assistant is engineered to handle "dirty" real-world inputs and complex multi-step reasoning reliably:

1. Fuzzy Product Searching: Standard substring matching breaks when users make typos or combine features (e.g., "ergonomic mouse"). Our search_catalog tool employs a split-word overlap algorithm, guaranteeing robust fallback matches even if the exact string isn't found.
2. Regex ID Normalization: Users rarely type exact IDs. Whether a user inputs "order # 12345", "ord12345", or "ORD-12345", the get_order_details tool automatically normalizes the input to strictly match database standards (ORD-XXXXX).
3. Dual-Layer Constraint Enforcement (Returns Policy): The business requirement demands that an order must be "delivered" to be returned, and the agent must verify this first.
   • Layer 1 (Prompting): The LLM is strictly instructed on the rules and refund conditional mapping.
   • Layer 2 (Python Engine Guard): The orchestrator explicitly checks the conversation history. If the LLM attempts to fire initiate_return without previously calling get_order_details for that specific order, the orchestrator forcefully intercepts and denies the tool call.
4. Null-Safety & Hallucination Prevention: Orders without a delivery date (null) are intercepted by the tool and parsed into safe, explicit strings ("Not yet delivered") before the LLM sees them, eliminating the risk of the LLM hallucinating a fake date.
5. Context Summarization & State Preservation: To prevent token limit overflow while maintaining context, when the conversation history reaches 10 visible turns, the earliest messages (excluding the last 2 turns) are summarized. This summary explicitly preserves critical state information (such as verified Order IDs, tool outcomes, and user constraints) and is prepended to the message history as a system checkpoint.

This project implements a clean, layered microservice architecture:

• data/: Holds the JSON datasets (products.json, orders.json).
• src/: Contains all modular Python logic.
  • database.py: The Data Access Object (DAO) layer for data ingestion and mutable in-memory state tracking.
  • tools.py: The LLM capabilities wrapped as callable functions.
  • agent.py: The central orchestrator that connects to the LLM API, evaluates responses, executes tool routing securely, and manages conversation history summarization.
  • app.py: A clean, streamlined Streamlit UI serving as the presentation layer.

• Docker and docker-compose (Recommended)
• An OpenRouter or OpenAI API Key.

We strongly recommend using Docker to launch this application seamlessly with zero local environment friction.

1. Clone the repository and navigate into it.
2. Set up your environment variables:

   cp .env.example .env

3. Open .env and provide your API Key (e.g., OPENROUTER_API_KEY=your_key).
4. Build and launch the container:

   docker-compose up --build

5. Open your browser and navigate to http://localhost:8501.

If you prefer not to use Docker, you can run the app locally:

# 1. Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate

# 2. Install dependencies
pip install -r requirements.txt

# 3. Setup Environment
cp .env.example .env
# Edit .env with your API key

# 4. Run the app
streamlit run src/app.py

To evaluate the strength of this architecture, please copy-paste the following test prompts into the chat interface to witness the system's strict edge-case handling in action:

Test 1: Context Retention & State Mutation

• Prompt A: "Where is my order? It's #12345"
• Prompt B: "Actually, I want to return it."
• Expected Behavior: The system remembers the order ID from Prompt A, initiates the return, and mutates the status.

Test 2: Security Guardrails & ID Normalization

• Prompt: "Please initiate a return for order # 45678."
• Expected Behavior: The system normalizes the messy ID, checks the order, realizes it is "shipped" (not delivered), and gracefully refuses to process the return.

Test 3: Complex Multi-step Logic & State Mapping

• Prompt: "I want to buy a wireless mouse, but only if my refund for order #999 has been processed."
• Expected Behavior: The system will check ORD-999, see that it is still "processing", realize that the condition for a refund is unmet (mapped via business logic), and accurately inform you of both the mouse and the unmet condition.