Skip to content

README.md

Latest commit

 

History

History
382 lines (257 loc) · 5.28 KB

README.md

File metadata and controls

382 lines (257 loc) · 5.28 KB
Raw

ID: 001

🛒 Target Superstore AI Assistant

An AI-powered shopping assistant built with Streamlit, LangGraph, and LangChain for the fictional US retail chain Target Superstore.

The assistant supports:

  • 🔍 Product search and filtering
  • 🛍️ Cart management
  • 👤 User loyalty lookup
  • 💰 Final price calculation with loyalty points
  • ✅ Human-in-the-loop approval for cart additions
  • 🤖 Tool-calling AI agent using LangGraph
  • 💬 Conversational UI with Streamlit

🚀 Features

✅ AI Shopping Assistant

Users can chat naturally in English or Urdu to:

  • Search products
  • Add/remove products from cart
  • View cart contents
  • Checkout
  • Ask pricing questions

✅ Human-in-the-Loop (HITL) Approval

Before adding products to the cart, the system pauses execution and asks for explicit approval using LangGraph interrupts.

Example flow:

  1. User says:

    Add Nestle Milk Pack

  2. AI triggers add_to_cart

  3. Graph pauses with:

    • Approve ✅
    • Reject ❌

  4. Execution resumes after user decision

✅ Tool-Based Architecture

The assistant uses LangChain tools:

Tool Description
get_product_info Product search/filtering
get_user_data Retrieve customer profile
calculate_final_price Loyalty discount calculation
add_to_cart Add item with approval workflow
view_cart Show cart
remove_from_cart Remove item from cart

🏗️ Tech Stack

  • Python
  • Streamlit
  • LangGraph
  • LangChain
  • Pandas
  • OpenAI / LLM Provider
  • dotenv

📂 Project Structure

project/
│
├── app.py
├── llm.py
├── users_data.json
├── superstore_products.xlsx
├── .env
├── requirements.txt
└── README.md

⚙️ Installation

1. Clone Repository

git clone <your_repo_url>
cd <project_name>

2. Create Virtual Environment

python -m venv venv

Activate it:

Mac/Linux

source venv/bin/activate

Windows

venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

🔐 Environment Variables

Create a .env file:

OPENAI_API_KEY=your_api_key_here

You may also configure your custom LLM provider inside llm.py.

▶️ Run the App

streamlit run app.py

🧠 How It Works

LangGraph Workflow

User Input
    ↓
LLM Node
    ↓
Tool Decision
    ↓
Tool Execution
    ↓
Interrupt (if approval needed)
    ↓
Resume Execution
    ↓
Assistant Response

🛍️ Cart Workflow

Add Product

User → "Add product X"
       ↓
AI calls add_to_cart
       ↓
Interrupt triggered
       ↓
User approves/rejects
       ↓
Cart updated

📊 Product Search

The assistant supports filtering by:

  • Product Name
  • Product ID
  • Brand
  • Category
  • Subcategory
  • Price Range
  • Tags

Example queries:

Show me imported chocolates
Find organic products under 1000 PKR
Search for Nestle products

👤 User Data Example

get_user_data(user_id) returns:

{
  "user_id": "U1001",
  "name": "Ali Khan",
  "loyalty_points": 2500,
  "tier": "Gold"
}

💰 Loyalty Price Calculation

calculate_final_price(price=5000, loyalty_points=1200)

Output:

Discount applied: 1200 PKR.
Final price: 3800 PKR.

🧩 Key LangGraph Concepts Used

StateGraph

Defines the agent workflow graph.

ToolNode

Executes LangChain tools automatically.

interrupt()

Pauses execution for human approval.

Command(resume=...)

Resumes graph execution after approval/rejection.

InMemorySaver

Persists conversation state across Streamlit reruns.

🎨 UI Components

Main Chat Area

  • User/assistant conversation
  • Approval prompts
  • Tool responses

Sidebar Cart

Displays:

  • Cart items
  • Quantity
  • Total price

📌 Example Commands

Show me snacks under 500 PKR
Add P1001 to cart
View my cart
Remove P1001
Checkout

🔒 System Prompt Rules

The AI strictly follows rules such as:

  • Only one cart tool per turn
  • Approval required for add-to-cart
  • No approval for remove-from-cart
  • Checkout triggered only on explicit request

🛠️ Future Improvements

  • Persistent database storage
  • Real payment integration
  • Inventory updates
  • Voice assistant support
  • Multi-user authentication
  • Recommendation engine
  • Order history
  • WhatsApp integration

📦 Example Requirements

streamlit
pandas
langchain
langgraph
python-dotenv
openpyxl

📸 Demo Flow

User: Add Milk Pack

AI:
Approval Required
[Approve] [Reject]

User clicks Approve

AI:
Added Milk Pack x1 to cart.
Cart total: PKR 450

🤝 License

MIT License

🙌 Acknowledgements

Built with: