🛒 NeoStats Retail Competitor Scout

A production-grade Streamlit application that combines Retrieval-Augmented Generation (RAG) with Live Web Search to provide intelligent retail price competitive analysis. Powered by OpenRouter API (Meta Llama models) and HuggingFace embeddings.

---

📋 Table of Contents

• Features
• Screenshots
• Project Structure
• Quick Start
  • Installation
  • Configuration
  • Generate Test Data
  • Run the Application
• How to Use
• Test Data
• Technical Stack
• Configuration
• Response Modes
• Troubleshooting
• License
• Contributing

---

🎯 Features

• 📄 PDF Catalog Processing: Upload your product catalog and leverage RAG for instant price lookups
• 🌐 Live Market Intelligence: Real-time web search for current competitor pricing
• 🤖 AI-Powered Analysis: LangChain agent with dual tools (Internal Knowledge + Market Search)
• 💬 Interactive Chat Interface: Natural language queries with conversation history
• 🎚️ Dual Response Modes:
  • Concise: Executive 2-sentence summaries
  • Detailed: Comprehensive analysis with sources and strategic recommendations

📸 Screenshots

Main Interface

Clean, modern interface with dashboard statistics and easy navigation

Settings Panel

Configure response mode, upload catalogs, and manage API settings

Chat Interaction

AI-powered chat interface with natural language queries and intelligent responses

📁 Project Structure

neo_retail_scout/
├── config/
│   ├── config.py           # Environment variables & constants
│   └── prompts.py          # System prompts for Concise/Detailed modes
├── data/                   # Folder for storing PDF catalogs
├── models/
│   ├── llm.py             # LLM initialization (OpenRouter with Llama)
│   └── embeddings.py      # HuggingFace embedding model setup
├── utils/
│   ├── document_loader.py # PDF loading & FAISS vectorization
│   └── search_tool.py     # DuckDuckGo search tool wrapper
├── scripts/
│   └── generate_mock_data.py  # Generate test PDF catalog
├── app.py                 # Main Streamlit UI
├── requirements.txt       # Dependencies
└── .env                   # API Keys (create from .env.example)

🚀 Quick Start

1. Installation

# Clone or navigate to the project directory
cd neo_retail_scout

# Install dependencies
pip install -r requirements.txt

2. Configuration

Create a .env file with your OpenRouter API key:

# Copy the example file
cp .env.example .env

# Edit .env and add your API key
OPENROUTER_API_KEY=your_openrouter_api_key_here

Get your API key from: https://openrouter.ai/keys

3. Generate Test Data

# Generate the mock product catalog PDF
python scripts/generate_mock_data.py

This creates data/NeoStats_Spring_Catalog.pdf with intentionally high prices for testing.

4. Run the Application

streamlit run app.py

The app will open in your browser at http://localhost:8501

📖 How to Use

1. Upload your product catalog PDF (or use the generated test catalog)
2. Select response mode:
   • Concise: Quick 2-sentence executive summary
   • Detailed: Full analysis with markdown tables and sources
3. Ask pricing questions:
   • "What is the price of Sony WH-1000XM5 Headphones?"
   • "Is our Logitech MX Master 3S Mouse price competitive?"
   • "Compare our Samsung T7 Shield SSD pricing with the market"

Example Interaction

You: "Is our Sony WH-1000XM5 Headphones price competitive?"

Agent:

1. 🔍 Searches internal catalog → Finds: $450.00
2. 🌐 Searches live web → Finds: Market average ~$348
3. 📊 Analyzes gap → Recommends: Price reduction to stay competitive

🧪 Test Data

The generated mock catalog includes "trap items" with intentionally high prices:

Product	Our Price	Market Price	Gap
Sony WH-1000XM5 Headphones	$450.00	~$348	+$102
Logitech MX Master 3S Mouse	$130.00	~$99	+$31
Samsung T7 Shield 2TB SSD	$200.00	~$160	+$40

These items are designed to test the agent's ability to detect non-competitive pricing.

🛠️ Technical Stack

• Frontend: Streamlit
• LLM: Meta Llama (via OpenRouter API)
  • Primary: meta-llama/llama-3.3-70b-instruct
  • Alternative: meta-llama/llama-3.1-70b-instruct
• Framework: LangChain
• RAG: FAISS vector store + HuggingFace embeddings
  • Embedding Model: sentence-transformers/all-MiniLM-L6-v2
• Web Search: DuckDuckGo
• PDF Processing: PyPDF
• Document Generation: ReportLab

🔧 Configuration

Key settings in config/config.py:

• DEFAULT_MODEL: LLM model (default: meta-llama/llama-3.3-70b-instruct)
• TEMPERATURE: Response creativity (default: 0.7)
• MAX_TOKENS: Maximum response length (default: 2048)
• CHUNK_SIZE: Text splitting size (default: 1000)
• CHUNK_OVERLAP: Chunk overlap (default: 200)

📝 Response Modes

Concise Mode

Perfect for executives who need quick insights:

• 2-sentence format
• Direct recommendation
• No extra details

Detailed Mode

For strategic decision-making:

• Markdown comparison table
• Source citations
• Price gap analysis
• Strategic recommendations
• Risk assessment

🐛 Troubleshooting

Issue: "OPENROUTER_API_KEY not found"

• Solution: Create a .env file with your OpenRouter API key

Issue: "No content found in PDF"

• Solution: Ensure the PDF contains text (not just images)

Issue: "Error initializing search tool"

• Solution: Check internet connection for DuckDuckGo search

📄 License

This project is for demonstration and educational purposes.

🤝 Contributing

This is a case study demo project. Feel free to fork and customize for your needs!

---

Built with ❤️ for Retail Pricing Managers