Interactive Demo UI

Time to Run: 5 minutes | What You'll See: Live RAG agent in action

🎯 Why Run the Demo?

The Problem: Reading docs is helpful, but you learn best by trying it yourself. You want to:

• See RecoAgent in action with real queries
• Understand what hybrid retrieval actually looks like
• Experience the user interface
• Try evaluation metrics live
• See response times and quality

The Demo Solves: Interactive, hands-on experience with a working RAG system in your browser.

⚡ TL;DR - Run in 2 Minutes

cd docs/demo-app
pip install -r requirements.txt
export OPENAI_API_KEY="your-key"  # Optional - works in mock mode too
python app.py

# Open browser: http://localhost:8080

What You'll See: Full Q&A interface with 3 knowledge bases, live evaluation, conversation history!

---

🖥️ What the Demo Looks Like

┌─────────────────────────────────────────────────────────┐
│  RecoAgent Interactive Demo                             │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Knowledge Base: [IT Support ▼]  [Run Evaluation]      │
│                                                          │
│  ┌──────────────────────────────────────────────────┐  │
│  │ Your Question:                                    │  │
│  │ How do I reset my password?                       │  │
│  └──────────────────────────────────────────────────┘  │
│                                          [Ask] ←Click   │
│                                                          │
│  ┌─── Response (850ms, $0.012) ──────────────────────┐ │
│  │ To reset your password:                           │ │
│  │ 1. Go to the login page                           │ │
│  │ 2. Click "Forgot Password"                        │ │
│  │ 3. Enter your email                               │ │
│  │ 4. Check email for reset link                     │ │
│  │                                                    │ │
│  │ 📄 Sources: IT_Support_Guide.pdf (p. 12)         │ │
│  │ 🎯 Confidence: 0.92                               │ │
│  │ 🔍 Retrieved: 5 docs, Used: 2 docs               │ │
│  └────────────────────────────────────────────────────┘ │
│                                                          │
│  [View Conversation History] [Clear]                    │
└─────────────────────────────────────────────────────────┘

🎮 Interactive Features

1. Live Q&A - Type and Get Instant Answers

Try these questions:

• "How do I reset my password?" (simple retrieval)
• "I have VPN and email issues, help!" (multi-step reasoning)
• "What is hybrid search?" (conceptual explanation)

You'll See:

• Response time (e.g., 850ms)
• Cost per query (e.g., $0.012)
• Source documents cited
• Confidence score
• Retrieved vs used document count

2. Three Knowledge Bases - Switch Between Domains

Knowledge Base	Documents	Example Questions	Use Case
IT Support	15 IT docs	Password reset, VPN issues	Internal helpdesk
Product Docs	12 RecoAgent docs	Feature questions, integration	Product documentation
Technical FAQs	20 technical docs	RAG concepts, deployment	Developer docs

3. Live Evaluation - See RAGAS Metrics

Click "Run Evaluation" to test on 10 queries:

Evaluation Results:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Context Precision:  0.82 ✅
Context Recall:     0.75 ✅
Faithfulness:       0.88 ✅
Answer Relevancy:   0.85 ✅
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Avg Response Time:  920ms
Total Cost:         $0.09
Success Rate:       90%

4. Conversation History - Track Your Session

See all your questions and answers in a timeline view.

🏗️ Demo Architecture

The demo application demonstrates RecoAgent's full capabilities:

• RAG-based Question Answering - Ask questions about your knowledge base
• Hybrid Retrieval - Combines BM25 and vector search for better results
• Multi-step Reasoning - Complex questions that require multiple steps
• Custom Tools Integration - Extend agents with new capabilities
• Real-time Evaluation - Measure and improve system performance
• Safety Guardrails - Input/output filtering and PII detection

🎬 Demo Scenarios - Try These Queries

Scenario 1: Simple Factual Question

Try: "How do I reset my password?"

What Happens:

1. Hybrid retrieval finds password reset documentation
2. Agent extracts step-by-step procedure
3. Returns answer with source citation

Expected: ~800ms response, high confidence (0.9+)

Scenario 2: Multi-Step Problem

Try: "I can't access shared drives and VPN keeps disconnecting"

What Happens:

1. Agent recognizes two separate issues
2. Retrieves docs for both problems
3. Prioritizes troubleshooting steps
4. Provides comprehensive answer

Expected: ~1.5s response, shows reasoning steps

Scenario 3: Conceptual Explanation

Try: "What is hybrid search and why is it better?"

What Happens:

1. Retrieves conceptual documentation
2. Synthesizes explanation from multiple sources
3. Includes examples and comparisons

Expected: ~1.2s response, multiple sources cited

📊 What You'll Learn

By running the demo, you'll understand:

Concept	What You'll See	Why It Matters
Hybrid Retrieval	Same query returns different doc ranks with different α values	Need both keyword + semantic
Response Quality	Confidence scores vary by query type	Some queries are harder
Source Attribution	Every answer cites specific documents	Verifiable, trustworthy
Performance	Real latency and cost metrics	Plan your budget
Evaluation	RAGAS scores show system quality	Measure improvements

Running the Demo

Quick Start

1. Navigate to demo directory:

   cd apps/demo_ui

2. Run the setup script:

   ./run_demo.sh

3. Open your browser: Navigate to http://localhost:8080

Alternative Setup

If you prefer manual setup:

# Navigate to demo directory
cd apps/demo_ui

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

# Install dependencies
pip install -r requirements.txt

# Create environment file
echo "OPENAI_API_KEY=your_api_key_here" > .env
echo "DEMO_MODE=true" >> .env

# Run the demo
python app.py

Demo Setup

The demo setup script will:

• ✅ Check prerequisites (Python, Node.js, Docker)
• ✅ Create demo directory structure
• ✅ Generate demo configuration
• ✅ Create sample datasets
• ✅ Set up the web application
• ✅ Install required dependencies

Configuration

The demo uses these configuration options:

# demo_config.json
{
  "name": "RecoAgent Demo",
  "version": "1.0.0",
  "features": [
    "rag",
    "hybrid_search", 
    "multi_step",
    "evaluation"
  ],
  "datasets": [
    "it_support",
    "product_docs", 
    "technical_faqs"
  ],
  "endpoints": {
    "api": "http://localhost:8000",
    "ui": "http://localhost:3000",
    "demo": "http://localhost:8080"
  }
}

Demo Architecture

The demo consists of several components:

🖥️ Web Interface

• Flask Application - Simple web server
• HTML Templates - Clean, responsive UI
• JavaScript - Interactive question handling
• Real-time Updates - Live response streaming

🤖 RecoAgent Backend

• RAG Agent - Core question answering
• Hybrid Retriever - BM25 + vector search
• Multi-step Reasoning - Complex question handling
• Evaluation Engine - Performance measurement

📊 Monitoring & Observability

• LangSmith Integration - Request tracing
• Performance Metrics - Latency and throughput
• Error Tracking - Failed requests and issues
• Usage Analytics - Popular questions and patterns

Demo Scenarios

Scenario 1: Simple Q&A

Goal: Answer straightforward questions about the knowledge base

Example Questions:

• "How do I reset my password?"
• "What is RecoAgent?"
• "How does hybrid search work?"

Expected Behavior:

• Quick response (< 2 seconds)
• High confidence score (> 0.8)
• Relevant source citations
• Clear, actionable answers

Scenario 2: Multi-step Reasoning

Goal: Handle complex questions requiring multiple steps

Example Questions:

• "I'm having trouble with both VPN and email access. What should I do first?"
• "How do I evaluate my RAG system and what metrics should I focus on?"
• "What are the security implications of using RecoAgent in production?"

Expected Behavior:

• Multi-step reasoning process
• Tool usage for complex operations
• Intermediate reasoning steps
• Comprehensive final answer

Scenario 3: Evaluation & Improvement

Goal: Measure system performance and identify areas for improvement

Evaluation Metrics:

• Context Precision - How relevant are retrieved documents?
• Context Recall - Are all relevant documents retrieved?
• Faithfulness - How accurate are the generated answers?
• Answer Similarity - How similar are answers to ground truth?

Expected Results:

• Context Precision: > 0.7
• Context Recall: > 0.6
• Faithfulness: > 0.8
• Answer Similarity: > 0.7

Customization

Adding New Datasets

# Add your own dataset
custom_dataset = [
    "Your custom document 1",
    "Your custom document 2",
    "Your custom document 3"
]

agent.add_documents(custom_dataset)

Custom Tools

# Add custom tools to the agent
from recoagent.tools import Tool

def custom_search(query: str) -> str:
    # Your custom search logic
    return f"Custom search results for: {query}"

agent.add_tool(Tool(name="custom_search", function=custom_search))

Custom Evaluation

# Define custom evaluation metrics
def custom_metric(response, ground_truth):
    # Your custom evaluation logic
    return similarity_score

evaluator.add_metric("custom_metric", custom_metric)

Troubleshooting

Common Issues

Demo won't start:

• Check that all prerequisites are installed
• Verify API keys are set correctly
• Ensure ports 8080, 8000, and 3000 are available

Questions return errors:

• Verify your LLM API key has sufficient quota
• Check that documents are loaded correctly
• Review the browser console for detailed errors

Evaluation fails:

• Ensure test questions are provided
• Check that the evaluation dataset is compatible
• Verify RAGAS dependencies are installed

Getting Help

If you encounter issues:

1. Check the logs - Review console output for error messages
2. Verify configuration - Ensure all settings are correct
3. Test components - Try individual features separately
4. Community support - Contact support@recohut.com for assistance

Next Steps

After exploring the demo:

1. Tutorials - Learn the fundamentals
2. How-To Guides - Set up your own instance
3. Examples - See working code
4. Reference - Detailed API documentation

Contributing

Want to improve the demo? We welcome contributions!

1. Report Issues - Found a bug or have a suggestion?
2. Submit PRs - Have a fix or improvement?
3. Add Scenarios - Want to showcase a specific use case?
4. Improve UI - Better user experience ideas?

🎓 What You'll Accomplish

After 30 minutes with the demo:

✅ See RAG in action - Understand how retrieval + generation works
✅ Try hybrid search - Experience the quality difference
✅ Run evaluations - See actual RAGAS metrics
✅ Understand costs - See real $ per query
✅ Gauge performance - Know what latency to expect
✅ Plan your build - Know if RecoAgent fits your needs

🚀 Quick Start Commands

# Option 1: Automated setup (recommended)
cd apps/demo_ui && ./run_demo.sh

# Option 2: Manual setup
cd apps/demo_ui
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
export OPENAI_API_KEY="sk-your-key"  # Optional - works without!
python app.py

# Open: http://localhost:8080

No API key? Demo works in mock mode - you can still explore the UI and understand the workflow!

💡 Why This Demo Matters

Before Demo	After Demo	Value
"Will RAG work for my use case?"	"Yes! I just tried it with my questions"	Confidence to proceed
"How fast will it be?"	"850ms for simple, 1.5s for complex"	Set realistic SLAs
"What will it cost?"	"$0.01-0.05 per query"	Budget planning
"Is the quality good enough?"	"0.82 precision - better than expected!"	Quality validation
"Can it handle complex queries?"	"Yes, saw multi-step reasoning work"	Feature validation

Bottom Line: 30 minutes with the demo can save you weeks of uncertain development!