Add application files

.claude/settings.local.json

@@ -24,7 +24,11 @@
       "Bash(git -C D:/cx_ai_agent/cx_ai_agent diff --stat HEAD)",
       "Bash(git -C D:/cx_ai_agent/cx_ai_agent pull)",
       "Bash(git config:*)",
-      "Bash(del \"D:\\cx_ai_agent\\cx_ai_agent\\Dockerfile\")"
+      "Bash(del \"D:\\cx_ai_agent\\cx_ai_agent\\Dockerfile\")",
+      "Bash(del /f \"design_notes.md\" \"DEPLOYMENT.md\" \"MIGRATION_SUMMARY.md\" \"UPGRADE_GUIDE.md\" \"DYNAMIC_DISCOVERY_README.md\" \"QUICK_START.md\" \"DEPENDENCY_FIX.md\" \"GRADIO_5_FIX.md\" \"HF_SPACES_DEPLOYMENT.md\" \"RATE_LIMIT_FIX.md\" \"DEMO_MODE.md\" \"SKIP_WEB_SEARCH_FIX.md\" \"FINAL_SOLUTION.md\" \"README_HF_SPACES.md\" \"MIGRATION.md\" 2)",
+      "Bash(del /f \"ENTERPRISE_UPGRADE_PLAN.md\" \"ENTERPRISE_DEPLOYMENT.md\" \"WHATS_NEW_ENTERPRISE.md\" \"ABOUT.md\" \"IMPLEMENTATION_SUMMARY.md\" \"DEPLOYMENT_CHECKLIST.md\" \"AI_REPLY_HANDLER_GUIDE.md\" \"BUGFIX_SUMMARY.md\" \"PRODUCTION_READY_IMPLEMENTATION.md\" \"DEPLOYMENT_FIX.md\" \"QUICK_FIX_SUMMARY.md\" \"ENHANCED_CONTACT_FINDER.md\" \"SETUP_REAL_CONTACTS.md\" \"CRITICAL_SETUP.md\" \"DEBUGGING_GUIDE.md\" 2)",
+      "Bash(del /f \"FIXES_SUMMARY.md\" \"TUTORIAL.md\" \"MCP_ENTERPRISE_UPGRADE_GUIDE.md\" \"ENTERPRISE_UPGRADE_SUMMARY.md\" \"MCP_HACKATHON_GUIDE.md\" \"MCP_ANALYSIS_AND_FIXES.md\" \"QUICK_ANSWERS.md\" \"MCP_PROPER_IMPLEMENTATION.md\" \"IMPLEMENTATION_COMPLETE.md\" \"QUICK_START_MCP.md\" \"FINAL_IMPLEMENTATION_GRANITE4.md\" \"README_GRANITE4_MCP.md\" \"README_HUGGINGFACE_MCP.md\" \"ENTERPRISE_EXPANSION_PROPOSAL.md\" 2)",
+      "Bash(powershell -Command \"Get-ChildItem -Path . -Filter ''*.md'' | Where-Object { $_Name -ne ''README.md'' } | Remove-Item -Force\")"
     ],
     "deny": [],
     "ask": []

ABOUT.md

@@ -1,1109 +0,0 @@
-# CX AI Agent - Complete Platform Guide
-
-## 🎯 What Is This Application?
-
-**CX AI Agent** is a comprehensive, AI-powered B2B sales automation and customer experience platform. It serves two primary purposes:
-
-1. **🎯 B2B Sales Automation (CORE)** - Automated prospect discovery and personalized email generation FROM your client company TO their prospects
-2. **📊 Complete CX Platform** - Full-featured ticketing, knowledge base, live chat, and analytics for customer support operations
-
----
-
-## 💼 B2B Sales Automation - Core Workflow
-
-### The Problem We Solve
-
-Your client company (e.g., "Shopify") needs to find potential customers (prospects) and reach out to them with personalized sales emails. Manually researching prospects, finding contacts, and writing emails is time-consuming.
-
-### The Solution: Automated CLIENT → PROSPECT → EMAIL Pipeline
-
-**Input:** Your CLIENT company name (e.g., "Shopify")
-
-**Process:**
-1. **Research the CLIENT** - AI searches the web to understand what your client offers, their value propositions, and target customers
-2. **Find PROSPECTS** - AI discovers companies that would benefit from your client's services
-3. **Research PROSPECTS** - AI analyzes each prospect's pain points and business challenges
-4. **Find Contacts** - AI identifies decision-makers at each prospect company (CEOs, VPs, Directors)
-5. **Generate Emails** - AI creates personalized outreach emails FROM your client TO each prospect contact
-
-**Output:** Ready-to-send sales emails with full content
-
-### Real-World Example
-
-**Input:**
-```
-Client Company: Shopify
-Number of Prospects: 3
-```
-
-**What Happens:**
-
-**Step 1: Research Shopify**
-- AI discovers: "Shopify provides e-commerce platform, payment processing, inventory management"
-- Target customers: "Small to medium online retailers, DTC brands, dropshippers"
-
-**Step 2: Find Prospects**
-- AI searches: "companies that could use Shopify potential customers businesses"
-- Finds:
-  - Small Fashion Boutique (e-commerce startup)
-  - Artisan Coffee Roasters (looking to sell online)
-  - Handmade Jewelry Store (needs better storefront)
-
-**Step 3: Research Each Prospect**
-- For "Small Fashion Boutique":
-  - Pain points: "struggling with outdated website, poor mobile experience, manual inventory"
-
-**Step 4: Find Contacts**
-- Searches: "Small Fashion Boutique CEO VP contact"
-- Finds: "Sarah Johnson, Founder & CEO"
-
-**Step 5: Generate Personalized Email**
-```
-To: [email protected]
-From: [email protected]
-Subject: Quick question about Small Fashion Boutique's growth strategy
-
-Hi Sarah,
-
-I hope this email finds you well. I'm reaching out on behalf of Shopify.
-
-I've been following Small Fashion Boutique and noticed you're doing great work
-in your space. I wanted to reach out because Shopify has helped similar
-companies tackle challenges like: struggling with outdated website, poor
-mobile experience, manual inventory.
-
-We've seen companies like yours achieve:
-• 40% reduction in operational costs
-• 25% improvement in customer satisfaction
-• 30% faster time-to-market
-
-Would you be open to a brief 15-minute conversation to explore if Shopify
-could help Small Fashion Boutique achieve similar results?
-
-Best regards,
-Shopify Sales Team
-```
-
-### Key Features
-
-- ✅ **Correct Direction**: Emails are FROM your client TO prospects (not the other way around)
-- ✅ **Personalized**: Each email references the prospect's specific pain points
-- ✅ **Compliant**: Includes unsubscribe language and AI disclosure
-- ✅ **Scalable**: Process 1-5 prospects in a single pipeline run
-- ✅ **Real-time**: Uses live web search for current company information
-
----
-
-## 🏗️ Architecture Overview
-
-### System Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    GRADIO WEB INTERFACE                      │
-│  Pipeline | Tickets | Knowledge Base | Chat | Analytics     │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                ┌─────────────┴─────────────┐
-                │                           │
-        ┌───────▼──────┐          ┌────────▼────────┐
-        │  8-Agent      │          │  CX Modules     │
-        │  Pipeline     │          │  (4 Modules)    │
-        └───────┬──────┘          └────────┬────────┘
-                │                           │
-        ┌───────▼──────────────────────────▼────────┐
-        │           MCP SERVER LAYER                 │
-        │  Search | Email | Calendar | Store         │
-        └───────┬────────────────────────────────────┘
-                │
-        ┌───────▼──────────────────────────┐
-        │    DATA & INTELLIGENCE LAYER     │
-        │  SQLite | FAISS | Vector Store   │
-        └──────────────────────────────────┘
-```
-
-### Technology Stack
-
-- **Frontend**: Gradio 5.x (Web UI Framework)
-- **Backend**: Python 3.10+ with async/await
-- **Database**: SQLite with SQLAlchemy ORM (15+ tables)
-- **Vector Store**: FAISS with sentence-transformers
-- **LLM**: Hugging Face Inference API
-- **Search**: Serper API (Google Search)
-- **Protocol**: MCP (Model Context Protocol) for tool integration
-
----
-
-## 🔄 The 8-Agent Pipeline Workflow
-
-### Overview
-
-The pipeline autonomously discovers and processes companies for sales outreach. It takes company names as input and produces enriched prospect data, personalized content, and ready-to-send emails.
-
-### Agent Flow Diagram
-
-```
-Input: Company Names (e.g., "Shopify, Stripe")
-    │
-    ▼
-┌───────────────────────────────────────────────────┐
-│ 1. HUNTER AGENT                                   │
-│ Discovers company domain and basic info           │
-│ Tools: Serper API (Google Search)                 │
-│ Output: Domain, industry, size                    │
-└───────────────┬───────────────────────────────────┘
-                ▼
-┌───────────────────────────────────────────────────┐
-│ 2. ENRICHER AGENT                                 │
-│ Gathers facts, news, pain points                  │
-│ Tools: MCP Search Server                          │
-│ Output: Company facts, recent news, challenges    │
-└───────────────┬───────────────────────────────────┘
-                ▼
-┌───────────────────────────────────────────────────┐
-│ 3. CONTACTOR AGENT                                │
-│ Finds decision-makers at the company              │
-│ Tools: MCP Search, Store (suppression list)       │
-│ Output: List of contacts with titles              │
-└───────────────┬───────────────────────────────────┘
-                ▼
-┌───────────────────────────────────────────────────┐
-│ 4. SCORER AGENT                                   │
-│ Calculates fit score based on criteria            │
-│ Tools: MCP Store                                  │
-│ Output: Fit, engagement, intent scores (0-1)      │
-└───────────────┬───────────────────────────────────┘
-                ▼
-┌───────────────────────────────────────────────────┐
-│ 5. WRITER AGENT                                   │
-│ Generates personalized content                    │
-│ Tools: HF Inference (LLM), Vector Store (RAG)     │
-│ Output: Company summary, personalized email       │
-└───────────────┬───────────────────────────────────┘
-                ▼
-┌───────────────────────────────────────────────────┐
-│ 6. COMPLIANCE AGENT                               │
-│ Enforces email regulations                        │
-│ Tools: MCP Store (suppression check)              │
-│ Output: Pass/Fail with reason                     │
-└───────────────┬───────────────────────────────────┘
-                ▼
-┌───────────────────────────────────────────────────┐
-│ 7. SEQUENCER AGENT                                │
-│ Creates email sequence and thread                 │
-│ Tools: MCP Email Server                           │
-│ Output: Email thread ID, scheduled sends          │
-└───────────────┬───────────────────────────────────┘
-                ▼
-┌───────────────────────────────────────────────────┐
-│ 8. CURATOR AGENT                                  │
-│ Prepares handoff packet for sales                 │
-│ Tools: MCP Calendar (meeting slots), Store        │
-│ Output: Complete prospect package                 │
-└───────────────┬───────────────────────────────────┘
-                ▼
-Output: Enriched Prospects Ready for Outreach
-```
-
-### Data Flow
-
-**Input → Hunter → Enricher → Contactor → Scorer → Writer → Compliance → Sequencer → Curator → Output**
-
-Each agent adds intelligence and enriches the prospect data before passing to the next agent.
-
----
-
-## 📦 CX Platform Modules
-
-### Module 1: 🎫 Ticket Management System
-
-**Purpose**: Manage customer support tickets with SLA tracking and AI-powered categorization.
-
-**Features**:
-- Create, view, update, and assign tickets
-- Multi-threaded conversations (customer ↔ agent)
-- SLA tracking with breach detection
-- AI sentiment analysis and auto-categorization
-- Priority-based routing (urgent, high, medium, low)
-- Internal notes vs. customer-visible messages
-
-**Workflow**:
-```
-Customer submits issue → Ticket created → AI analyzes sentiment
-→ Auto-categorizes → Calculates SLA → Routes to agent
-→ Agent responds → Tracks response time → Resolves
-→ Updates customer → Tracks resolution time
-```
-
-**Database Tables**:
-- `cx_tickets` - Ticket master data
-- `cx_ticket_messages` - Conversation threads
-- `cx_ticket_attachments` - File uploads
-
-### Module 2: 📚 Knowledge Base with RAG
-
-**Purpose**: Semantic search-powered knowledge base for self-service and agent assistance.
-
-**Features**:
-- Article management with categories
-- **RAG-Powered Semantic Search**:
-  - FAISS vector embeddings
-  - Sentence-transformers (all-MiniLM-L6-v2)
-  - Hybrid search (semantic + keyword)
-- Article versioning and change tracking
-- Helpfulness voting (thumbs up/down)
-- View analytics and popular articles
-- Markdown content support
-
-**Search Workflow**:
-```
-User query → Encode with sentence-transformers
-→ Search FAISS index → Retrieve top-k similar articles
-→ Hybrid search combines with keyword results
-→ Rank by relevance → Display results
-```
-
-**RAG Integration**:
-```
-Chatbot receives question → Retrieve relevant KB articles
-→ Use article content as context → Generate AI response
-→ Cite source articles
-```
-
-**Database Tables**:
-- `cx_kb_categories` - Article categories
-- `cx_kb_articles` - Articles with metrics
-- `cx_kb_article_versions` - Version history
-
-### Module 3: 💬 Live Chat with AI Bot
-
-**Purpose**: Real-time customer chat with AI-powered bot and human handoff.
-
-**Features**:
-- AI chatbot with intent detection
-- Sentiment analysis (positive, neutral, negative)
-- RAG-powered responses from knowledge base
-- Automatic escalation triggers
-- Bot-to-human handoff workflow
-- Chat session management
-- Satisfaction ratings and feedback
-
-**Chat Workflow**:
-```
-Customer starts chat → Bot greets
-→ Customer asks question → Bot detects intent
-→ Bot searches KB (RAG) → Generates response
-→ IF (negative sentiment OR complex query):
-    → Bot hands off to human agent
-ELSE:
-    → Bot continues conversation
-→ Chat ends → Customer rates experience
-```
-
-**Intent Detection**:
-- Greeting, Farewell, Question, Complaint, Escalation Request
-
-**Database Tables**:
-- `cx_chat_sessions` - Chat sessions
-- `cx_chat_messages` - Message history
-
-### Module 4: 📊 Analytics Dashboard
-
-**Purpose**: Real-time metrics and reporting across all CX operations.
-
-**Features**:
-- Overview metrics (customers, tickets, chats, KB)
-- Ticket analytics (by status, priority, category)
-- SLA performance tracking
-- Customer segmentation analytics
-- Weekly trend analysis
-- Custom date range reports
-
-**Metrics Tracked**:
-- Total/Active customers, Average CSAT
-- Open/Resolved tickets, Avg resolution time
-- Active chats, Avg chat rating
-- KB views, Article helpfulness
-- SLA breach/at-risk/on-track counts
-
-**Database Tables**:
-- `cx_analytics_daily` - Daily snapshots
-- `cx_agent_stats` - Agent performance
-
----
-
-## 🎯 Real-World Use Cases
-
-### Use Case 1: Sales Team - Lead Discovery
-
-**Scenario**: Sales team wants to find and research 10 SaaS companies in the e-commerce space.
-
-**Process**:
-1. **Input**: Enter company names in Pipeline tab
-   ```
-   Shopify, Stripe, BigCommerce, WooCommerce, Magento
-   ```
-
-2. **Pipeline Execution**: 8 agents autonomously:
-   - Search web for company info (domain, size, industry)
-   - Find recent news and challenges
-   - Discover 3-5 decision-makers per company
-   - Calculate fit scores
-   - Generate personalized outreach emails
-   - Create email threads
-   - Prepare handoff packets
-
-3. **Output**: For each company:
-   - Company profile with key facts
-   - 3-5 decision-maker contacts
-   - Fit score (0.0 - 1.0)
-   - Personalized email draft
-   - Meeting slot suggestions
-   - Ready-to-send email thread
-
-**Time Saved**: Manual research: 2-3 hours → Automated: 2-3 minutes
-
-### Use Case 2: Support Team - Ticket Management
-
-**Scenario**: Customer reports a bug via email. Support team needs to track and resolve.
-
-**Process**:
-1. **Ticket Creation**:
-   - Email auto-creates ticket
-   - AI detects sentiment: "negative"
-   - AI categorizes: "technical"
-   - AI suggests priority: "high"
-
-2. **Routing**:
-   - SLA calculated: First response due in 1 hour
-   - Auto-assigned to technical support agent
-   - Agent receives notification
-
-3. **Resolution**:
-   - Agent investigates, adds internal notes
-   - Agent responds to customer
-   - Ticket tracks response time (45 minutes - SLA met ✓)
-   - Issue resolved, ticket closed
-   - Resolution time tracked (2 hours)
-
-4. **Analytics**:
-   - Metrics updated in real-time
-   - Agent performance tracked
-   - Customer satisfaction surveyed
-
-### Use Case 3: Customer - Self-Service via KB
-
-**Scenario**: Customer wants to reset password at 2 AM.
-
-**Process**:
-1. **Search**:
-   - Customer searches: "forgot password"
-   - Semantic search finds: "How to Reset Your Password"
-   - Also suggests: "Account Security Guide"
-
-2. **Self-Resolution**:
-   - Customer reads article
-   - Follows steps successfully
-   - Votes article "helpful" 👍
-
-3. **Analytics**:
-   - KB view count +1
-   - Helpful vote +1
-   - Ticket avoided (cost savings)
-
-### Use Case 4: Customer - Live Chat Support
-
-**Scenario**: Customer has billing question during business hours.
-
-**Process**:
-1. **Chat Start**:
-   - Customer: "Why was I charged twice?"
-   - Bot detects intent: "complaint"
-   - Bot detects sentiment: "negative"
-
-2. **Escalation**:
-   - Bot recognizes billing + negative sentiment
-   - Auto-escalates to human agent
-   - Agent receives chat with full context
-
-3. **Resolution**:
-   - Agent reviews account
-   - Explains charge, issues refund
-   - Customer satisfied
-   - Chat rated 5/5 ⭐
-
-4. **Follow-up**:
-   - Ticket created for refund tracking
-   - Email confirmation sent
-   - Interaction logged in customer history
-
-### Use Case 5: Manager - Performance Analytics
-
-**Scenario**: Support manager needs weekly team performance report.
-
-**Process**:
-1. **Analytics Dashboard**:
-   - View overview metrics
-   - Filter: Last 7 days
-   - Review trends
-
-2. **Insights**:
-   - Tickets created: 150 (↑ 12% vs. last week)
-   - Resolution rate: 92% (↓ 3% vs. last week)
-   - Avg response time: 35 min (↑ 10 min vs. last week)
-   - SLA breaches: 5 (investigate)
-   - Chat bot resolution: 68% (no human needed)
-
-3. **Actions**:
-   - Identify bottleneck: Technical category
-   - Assign more agents to technical team
-   - Review SLA-breached tickets
-   - Create KB articles for common issues
-
----
-
-## 📖 How to Use This Application
-
-### Setup & Installation
-
-#### For Local Development:
-
-```bash
-# 1. Clone repository
-git clone <repo-url>
-cd cx_ai_agent
-
-# 2. Install dependencies
-pip install -r requirements_gradio.txt
-
-# 3. Set up environment variables
-cp .env.example .env
-# Edit .env and add:
-# - HF_API_TOKEN=your_huggingface_token
-# - SERPER_API_KEY=your_serper_api_key
-
-# 4. Run application
-python app.py
-
-# 5. Open browser
-# http://localhost:7860
-```
-
-#### For HuggingFace Spaces:
-
-1. Create new Space (Gradio app)
-2. Upload all files
-3. Add Secret: `SERPER_API_KEY`
-4. Space auto-deploys (HF_TOKEN provided automatically)
-
-### Using Each Module
-
-#### 🚀 Pipeline Tab - Lead Discovery
-
-**Step 1**: Enter company names
-```
-Input: Shopify, Stripe, Zendesk
-```
-
-**Step 2**: Click "Discover & Process"
-
-**Step 3**: Watch real-time execution
-- Agent workflow appears on right
-- Generated content streams in chat
-
-**Step 4**: Review results
-- Each company gets a result card
-- Shows: contacts, scores, email drafts
-- Click thread ID to view email
-
-**Expected Output**:
-```
-## 🏢 Shopify
-
-**Industry:** E-commerce Platform
-**Size:** 10,000 employees
-**Domain:** shopify.com
-
-**👥 Contacts Found:** 3
-- Tobias Lütke - CEO
-- Harley Finkelstein - President
-- ...
-
-**📊 Fit Score:** 0.85
-- Industry Fit: 0.90
-- Engagement: 0.80
-- Intent: 0.85
-
-**📝 Summary:**
-Shopify is a leading e-commerce platform...
-
-**✉️ Email Draft:**
-*Subject:* Quick question about Shopify's customer experience strategy
-
-Hi Tobias,
-
-I noticed Shopify recently...
-[personalized content]
-
-Best regards,
-Sales Team
-
-**📧 Email Thread:** thread_shopify_abc123
-**📋 Handoff Status:** Ready for sales team
-```
-
-#### 🎫 Tickets Tab - Support Management
-
-**Create Ticket**:
-1. Go to "Create Ticket" sub-tab
-2. Fill in:
-   - Customer Email: `[email protected]`
-   - Subject: "Cannot login to account"
-   - Description: "Getting error when trying to login"
-   - Priority: high
-   - Category: technical
-3. Click "Create Ticket"
-
-**View Tickets**:
-1. Go to "All Tickets" sub-tab
-2. Filter by status/priority
-3. See SLA indicators (🔴 overdue, 🟡 at-risk, 🟢 on-track)
-
-**Manage Ticket**:
-1. Go to "Ticket Details" sub-tab
-2. Enter ticket ID
-3. Click "Load Ticket"
-4. View conversation
-5. Add reply or internal note
-6. Update status/priority/assignment
-
-**SLA Dashboard**:
-1. Go to "SLA Dashboard" sub-tab
-2. View breached tickets (needs immediate attention)
-3. View at-risk tickets (due soon)
-4. Monitor compliance
-
-#### 📚 Knowledge Base Tab - Article Management
-
-**Create Article**:
-1. Go to "Create Article" sub-tab
-2. Fill in:
-   - Title: "How to Reset Password"
-   - Summary: "Step-by-step password reset guide"
-   - Content (Markdown):
-     ```markdown
-     # Password Reset Guide
-
-     ## Steps:
-     1. Go to login page
-     2. Click "Forgot Password"
-     ...
-     ```
-   - Category: Technical
-   - Status: published
-3. Click "Create Article"
-
-**Build Search Index**:
-1. Go to "Index Management" sub-tab
-2. Click "Build Index"
-3. Wait for FAISS index creation (one-time setup)
-
-**Search Articles**:
-1. Go to "Search" sub-tab
-2. Enter query: "reset password"
-3. Select search type: Semantic (recommended)
-4. Click "Search"
-5. View ranked results with relevance scores
-
-**Expected Output**:
-```
-## Search Results for: 'reset password'
-
-Found 2 relevant articles:
-
-### 1. How to Reset Your Password
-**Relevance Score:** 0.92 | **Views:** 150 | **Helpfulness:** 85%
-
-Step-by-step guide to reset your password...
-
-[View Article #2]
-
----
-
-### 2. Account Security Best Practices
-**Relevance Score:** 0.67 | **Views:** 75 | **Helpfulness:** 90%
-
-Learn how to keep your account secure...
-
-[View Article #5]
-```
-
-#### 💬 Live Chat Tab - Customer Conversations
-
-**Test Bot**:
-1. Go to "Test Bot" sub-tab
-2. Enter message: "How do I reset my password?"
-3. Click "Test Bot Response"
-4. View AI response with metadata
-
-**Expected Output**:
-```
-## Bot Response:
-
-Based on our knowledge base, here's what I found:
-
-To reset your password:
-1. Go to the login page
-2. Click "Forgot Password"
-3. Enter your email address
-4. Check your email for reset link
-5. Click link and create new password
-
-For more details, check out: **How to Reset Your Password**
-
----
-
-Metadata:
-{
-  "intent": "question",
-  "sentiment": "neutral",
-  "confidence": 0.85,
-  "should_escalate": false,
-  "suggested_articles": [2]
-}
-```
-
-**Manage Sessions**:
-1. Go to "Active Sessions" tab
-2. View all chat sessions
-3. See bot/human status
-4. Monitor wait times
-
-**View Conversation**:
-1. Go to "Session Details" tab
-2. Enter session ID
-3. See full conversation
-4. Send agent messages
-5. Handoff to human if needed
-
-#### 📊 Analytics Tab - Performance Metrics
-
-**Overview Dashboard**:
-1. Go to "Overview" tab
-2. View key metrics:
-   - Total customers: 1,247
-   - Open tickets: 45
-   - Active chats: 3
-   - Avg resolution time: 2.5 hours
-
-**Ticket Analytics**:
-1. Go to "Ticket Analytics" tab
-2. View distributions:
-   - By status: {open: 45, resolved: 892, closed: 310}
-   - By priority: {urgent: 5, high: 15, medium: 20, low: 5}
-   - By category: {technical: 25, billing: 10, account: 10}
-3. Check SLA performance:
-   - Breached: 2 (4%)
-   - At risk: 5 (11%)
-   - On track: 38 (85%)
-
-**Weekly Trends**:
-1. Go to "Trends" tab
-2. Select weeks: 4
-3. Click "Load Trends"
-4. View trend table
-
-**Custom Report**:
-1. Go to "Reports" tab
-2. Set date range: 2024-01-01 to 2024-01-31
-3. Click "Generate Report"
-4. Download/export data
-
----
-
-## 📥 Input → Output Examples
-
-### Example 1: Pipeline - Single Company
-
-**Input**:
-```
-Company Names: Shopify
-```
-
-**Processing** (2-3 minutes):
-- Hunter finds: shopify.com, E-commerce, 10K employees
-- Enricher gathers: Recent IPO, challenges in merchant retention
-- Contactor finds: 3 decision-makers
-- Scorer calculates: 0.85 fit score
-- Writer generates: personalized summary + email
-- Compliance checks: PASS (domain not suppressed)
-- Sequencer creates: email thread
-- Curator prepares: handoff packet
-
-**Output**:
-- ✅ 1 company processed
-- ✅ 3 contacts discovered
-- ✅ Fit score: 0.85/1.0
-- ✅ Email draft ready
-- ✅ Thread ID: thread_shopify_abc123
-- ✅ Next steps: Review and approve for sending
-
-### Example 2: Pipeline - Multiple Companies
-
-**Input**:
-```
-Company Names: Shopify, Stripe, Zendesk, Slack, Monday.com
-```
-
-**Output** (5-6 minutes):
-- ✅ 5 companies processed
-- ✅ 17 contacts discovered
-- ✅ Average fit score: 0.78
-- ✅ 5 personalized email drafts
-- ✅ 5 email threads created
-- ✅ All handoff packets ready
-
-### Example 3: Ticket Creation
-
-**Input**:
-```
-Customer: [email protected]
-Subject: Cannot access dashboard
-Description: Getting 403 error when trying to access dashboard
-Priority: high
-Category: technical
-```
-
-**Output**:
-```
-✅ Ticket #42 created successfully
-
-Auto-detected:
-- Sentiment: negative (frustration detected)
-- AI Category: technical (95% confidence)
-- SLA Due: 2024-01-15 15:30 (1 hour)
-- Assigned To: tech_support_agent_1
-- Status: open
-```
-
-### Example 4: KB Semantic Search
-
-**Input**:
-```
-Query: "how to change my email address"
-Search Type: Semantic
-Top K: 5
-```
-
-**Output**:
-```
-Found 3 relevant articles:
-
-1. Account Settings Guide (Score: 0.89)
-   - How to update email, password, profile
-
-2. Email Verification Process (Score: 0.72)
-   - Verifying new email address
-
-3. Account Security (Score: 0.65)
-   - Protecting your account information
-```
-
-### Example 5: Chatbot Interaction
-
-**Input**:
-```
-Customer: "I'm really frustrated, I've been charged twice this month!"
-```
-
-**Bot Analysis**:
-```
-Intent: complaint
-Sentiment: negative
-Keywords: charged, twice, frustrated
-Escalation: YES (billing + negative sentiment)
-```
-
-**Output**:
-```
-Bot: "I understand your frustration. Let me connect you
-with our billing specialist who can help resolve this
-immediately. Please hold for just a moment..."
-
-[Handoff to human agent]
-Agent receives: Full context + sentiment analysis + customer history
-```
-
----
-
-## 🔍 Advanced Features
-
-### 1. RAG (Retrieval-Augmented Generation)
-
-**How It Works**:
-1. User asks question
-2. System encodes query → vector embedding
-3. FAISS searches for similar KB articles
-4. Top-K articles retrieved as context
-5. LLM generates response using context
-6. Response includes source citations
-
-**Benefits**:
-- Accurate, grounded responses
-- No hallucination (based on real KB content)
-- Automatic knowledge updates
-
-### 2. AI Sentiment Analysis
-
-**Implementation**:
-- Keyword-based detection (extensible to ML models)
-- Detects: positive, neutral, negative
-- Applied to: tickets, chat messages, emails
-
-**Use Cases**:
-- Auto-escalate negative sentiment tickets
-- Route angry customers to senior agents
-- Prioritize frustrated chat users
-
-### 3. SLA Tracking
-
-**Rules** (configurable in code):
-```python
-sla_config = {
-    'urgent':  {'first_response': 15min,  'resolution': 2hr},
-    'high':    {'first_response': 1hr,    'resolution': 8hr},
-    'medium':  {'first_response': 4hr,    'resolution': 24hr},
-    'low':     {'first_response': 8hr,    'resolution': 48hr}
-}
-```
-
-**Tracking**:
-- SLA due time calculated on ticket creation
-- Real-time breach detection
-- Dashboard shows: breached, at-risk, on-track
-
-### 4. MCP Integration
-
-**What is MCP?**
-Model Context Protocol - standardized way for LLMs to interact with external tools.
-
-**MCP Servers**:
-1. **Search MCP**: Web search via Serper API
-2. **Email MCP**: Email thread management
-3. **Calendar MCP**: Meeting scheduling
-4. **Store MCP**: Prospect data persistence
-
-**Benefits**:
-- Agents autonomously use tools
-- Standardized tool interface
-- Easy to add new tools
-
----
-
-## 🎓 Learning Resources
-
-### Understanding the Pipeline
-
-**Key Concepts**:
-- **Agent**: Autonomous unit that performs specific task
-- **Orchestrator**: Coordinates agents in sequence
-- **MCP Server**: Tool that agents can use
-- **Prospect**: Enriched company/contact data
-- **Handoff Packet**: Complete sales-ready package
-
-### Understanding RAG
-
-**Steps**:
-1. **Indexing**: Convert KB articles to vectors (one-time)
-2. **Query**: Convert user question to vector
-3. **Retrieval**: Find similar vectors in FAISS index
-4. **Augmentation**: Add retrieved content to LLM prompt
-5. **Generation**: LLM generates response with context
-
-### Database Schema
-
-**Core Tables**:
-- `cx_customers`: Customer master records
-- `cx_tickets`: Support tickets
-- `cx_kb_articles`: Knowledge base articles
-- `cx_chat_sessions`: Live chat sessions
-- `cx_analytics_daily`: Daily metrics snapshots
-
-**Relationships**:
-- Customer → has many → Tickets
-- Ticket → has many → Messages
-- KB Category → has many → Articles
-- Chat Session → has many → Messages
-
----
-
-## 🚨 Troubleshooting
-
-### Pipeline Not Processing Companies
-
-**Issue**: "Companies Processed: 0"
-
-**Solutions**:
-1. Check SERPER_API_KEY is set correctly
-2. Verify API quota not exceeded
-3. Check company names are valid
-4. Review logs for errors
-
-### KB Search Not Working
-
-**Issue**: "No results found" for known articles
-
-**Solutions**:
-1. Build search index first (Index Management tab)
-2. Ensure articles are published (not draft)
-3. Check FAISS dependencies installed
-4. Rebuild index if stale
-
-### Database Errors
-
-**Issue**: "no such table: cx_tickets"
-
-**Solutions**:
-1. Delete database file
-2. Restart application (auto-recreates)
-3. Check database path permissions
-4. Verify SQLAlchemy models imported
-
-### Slow Performance
-
-**Optimizations**:
-1. Limit pipeline to 1-2 companies for testing
-2. Use semantic search only when needed
-3. Paginate ticket/chat lists
-4. Archive old data periodically
-
----
-
-## 📊 Performance Metrics
-
-### Pipeline Performance
-
-**Single Company**:
-- Discovery time: 30-45 seconds
-- Enrichment time: 20-30 seconds
-- Content generation: 30-60 seconds
-- **Total**: ~2-3 minutes
-
-**Batch (5 companies)**:
-- Parallel processing: ~5-6 minutes
-- **vs. Manual**: 10-15 hours saved
-
-### Search Performance
-
-**Semantic Search**:
-- Index build (100 articles): ~30 seconds
-- Query time: <500ms
-- Accuracy: 85-92% relevance
-
-**Keyword Search**:
-- Query time: <100ms
-- Accuracy: 60-70% relevance
-
----
-
-## 🔐 Security & Compliance
-
-### Data Privacy
-
-- All data stored locally (SQLite)
-- No external data sharing
-- GDPR-compliant (local storage)
-- Customer data encrypted at rest (configurable)
-
-### Email Compliance
-
-**CAN-SPAM Compliance**:
-- Physical address in footer
-- Unsubscribe link required
-- Suppression list checking
-- Honest subject lines
-
-**Regional Rules**:
-- PECR (UK/EU)
-- CASL (Canada)
-- Auto-enforcement via Compliance Agent
-
----
-
-## 🎯 Best Practices
-
-### For Sales Teams
-
-1. **Start Small**: Test with 2-3 companies first
-2. **Review Outputs**: Always review AI-generated content
-3. **Customize**: Adjust email templates for your brand
-4. **Track Results**: Monitor response rates in analytics
-
-### For Support Teams
-
-1. **Use SLA Dashboard**: Monitor breaches daily
-2. **Tag Tickets**: Use consistent tags for reporting
-3. **Update KB**: Add articles for common issues
-4. **Review Bot Performance**: Check handoff rates weekly
-
-### For Managers
-
-1. **Weekly Reports**: Review analytics every Monday
-2. **Trend Analysis**: Identify patterns in ticket volume
-3. **Agent Training**: Use low-CSAT tickets for coaching
-4. **Process Optimization**: Automate repetitive tasks
-
----
-
-## 📞 Support & Contribution
-
-### Getting Help
-
-- Check this ABOUT.md
-- Review CX_PLATFORM_SUMMARY.md
-- Check GitHub issues
-- Review error logs in console
-
-### Contributing
-
-Contributions welcome! Focus areas:
-- Additional MCP servers
-- ML-based sentiment analysis
-- Advanced analytics visualizations
-- CRM integrations
-
----
-
-## 📈 Roadmap
-
-### Coming Soon
-
-- [ ] Real-time notifications
-- [ ] Advanced workflow automation
-- [ ] Multilingual support
-- [ ] Mobile-responsive UI
-- [ ] API endpoints
-- [ ] Salesforce/HubSpot integration
-- [ ] Advanced reporting (Plotly charts)
-- [ ] Team collaboration features
-
----
-
-## 🏁 Conclusion
-
-**CX AI Agent** is a complete platform that combines:
-- Autonomous AI agents for lead discovery
-- Enterprise CX management tools
-- RAG-powered intelligence
-- Real-time analytics
-
-Whether you're a sales team looking to automate prospecting or a support team managing customer interactions, this platform provides the tools and intelligence you need.
-
-**Start exploring each module and see how AI can transform your customer experience operations!**
-
----
-
-**Version**: 3.0.0-full-platform
-**Last Updated**: 2025-01-15
-**License**: MIT
-**Built With**: ❤️ and AI

AI_REPLY_HANDLER_GUIDE.md

@@ -1,484 +0,0 @@
-# 🤖 AI Reply Handler & Handoff Packet - Complete Guide
-
-## Overview
-
-The AI Reply Handler simulates the complete workflow of an AI assistant handling prospect responses, qualifying leads, and escalating to human sales reps when appropriate.
-
-## 🔄 Complete Workflow
-
-```
-Initial Email Sent
-        ↓
-Prospect Replies
-        ↓
-AI Analyzes Intent & Sentiment
-        ↓
-AI Generates Response
-        ↓
-    ┌───┴───┐
-    │       │
-Escalate?  Continue?
-    │       │
-    ↓       ↓
-Handoff   AI Nurtures
-Packet    Lead Further
-```
-
-## 🎯 Features Implemented
-
-### 1. **Prospect Reply Simulation**
-5 different reply types to test various scenarios:
-
-- **Interested + Pricing Request** → Triggers escalation
-- **Has Questions** → AI continues conversation
-- **Objection** → AI handles objection
-- **Ready to Buy** → Immediate escalation (hot lead!)
-- **Not Interested** → AI politely closes conversation
-
-### 2. **AI Intent Analysis**
-The AI automatically detects:
-- **Intent**: interested, needs_info, ready_to_buy, not_interested, general
-- **Sentiment**: positive, negative, neutral, very_positive
-- **Escalation Triggers**:
-  - Pricing/cost inquiries
-  - Demo/meeting requests
-  - Ready to purchase
-  - Technical questions beyond AI scope
-
-### 3. **AI Response Generation**
-Context-aware responses based on:
-- Prospect's intent
-- Conversation history
-- Client company information
-- Prospect company information
-
-**Response Types:**
-- **Not Interested** → Polite acknowledgment + unsubscribe confirmation
-- **Escalation Needed** → Explains human will follow up + handoff packet being prepared
-- **Interested** → Shares benefits + asks about next steps
-- **General** → Helpful response + prompts for more info
-
-### 4. **Escalation Logic**
-
-**Automatic Escalation Triggers:**
-- Keywords: "pricing", "price", "cost", "how much"
-- Keywords: "demo", "call", "meeting", "speak to someone"
-- Keywords: "buy", "purchase", "contract", "sign up"
-- Keywords: "technical", "integration", "API", "security"
-
-**Escalation Reasons:**
-1. `pricing_inquiry` - Needs custom quote
-2. `demo_request` - Wants to see product
-3. `ready_to_buy` - Strong buying signals
-4. `technical_question` - Complex tech questions
-5. `general_escalation` - Requires human expertise
-
-### 5. **Comprehensive Handoff Packet**
-
-When escalation is triggered, a complete handoff packet is generated with:
-
-#### 🎯 Executive Summary
-- Escalation status and reason
-- Engagement score (0-10)
-- Sentiment analysis
-- Recommended immediate action
-
-#### 👤 Contact Information
-- Full name and title
-- Email and LinkedIn
-- Company name
-- Authority level
-
-#### 💬 Conversation Summary
-- Total messages exchanged
-- Timeline (start → last message)
-- **Pain Points Identified**
-- **Questions Asked**
-- **Buying Signals Detected**
-
-#### 🔥 Escalation Details
-- Specific trigger that caused escalation
-- Detailed explanation of why human is needed
-
-#### 📊 Qualification Assessment
-- **Fit Score** (0-10) based on prospect profile
-- **Need Alignment** - How well solution matches needs
-- **Budget Signals** - Pricing discussion positive/negative
-- **Timeline Urgency** - How soon they want to move
-- **Decision Authority** - Verified decision maker?
-
-#### 💰 BANT Analysis
-- **Budget**: Qualification status
-- **Authority**: Decision maker confirmed?
-- **Need**: Solution fit validated?
-- **Timeline**: Implementation timeline
-
-#### 🎬 Recommended Next Steps
-- **Immediate actions** (within 24 hours)
-- **Short-term actions** (this week)
-- **Follow-up strategy**
-
-#### 📝 Full Conversation Transcript
-- Complete message history
-- Timestamps for each message
-- Clearly labeled (AI vs. Prospect)
-
-#### 🎁 Suggested Resources
-- Case studies to share
-- Demo materials
-- ROI calculators
-- Implementation guides
-
-#### ⚠️ Priority Level
-- 🔴 **HIGH** - Engagement score 8+, ready to buy
-- 🟡 **MEDIUM** - Engagement score 6-7
-- 🟢 **NORMAL** - Standard follow-up
-
-## 📖 How to Use
-
-### Step 1: Run B2B Pipeline
-1. Go to "💼 B2B Sales" tab
-2. Enter client company (e.g., "Shopify")
-3. Generate prospect emails
-4. Note one of the generated emails
-
-### Step 2: Simulate Prospect Reply
-1. Scroll down to "AI Reply Handler & Escalation Simulator"
-2. Select reply type from dropdown:
-   - **"Interested + Asking for Pricing"** (recommended to see escalation)
-   - Other types to see different AI behaviors
-3. (Optional) Customize the JSON context with your data
-4. Click "💬 Simulate Prospect Reply & AI Conversation"
-
-### Step 3: Watch AI in Action
-You'll see:
-1. **Prospect Reply** - Simulated response
-2. **AI Intent Analysis** - How AI understands the message
-3. **AI Response** - What AI replies back
-4. **Escalation (if triggered)** - Handoff packet generation
-
-### Step 4: Review Handoff Packet
-If escalation was triggered, you'll see a comprehensive handoff packet with:
-- All conversation details
-- Qualification scoring
-- Recommended actions
-- Priority level
-- Complete context for the sales rep
-
-## 🎭 Example Scenarios
-
-### Scenario 1: Interested Prospect (Escalates)
-
-**Prospect Reply:**
-```
-Hi,
-
-Thanks for reaching out. I'm interested in learning more about how
-this could help Small Fashion Boutique. Could you share some pricing
-information and maybe schedule a quick call?
-
-Best,
-Sarah Johnson
-```
-
-**AI Analysis:**
-- Intent: `interested`
-- Sentiment: `positive`
-- Escalation: `YES` (pricing inquiry)
-
-**AI Response:**
-```
-Thank you for your interest! Those are great questions.
-
-I'm connecting you with one of our specialists who can provide
-detailed information about pricing inquiry. They'll reach out to
-you within 24 hours...
-
-In the meantime, I've prepared a summary of our conversation for
-them so they'll have full context.
-```
-
-**Result:** ✅ Handoff packet generated with 7.5/10 engagement score
-
-### Scenario 2: Ready to Buy (Escalates)
-
-**Prospect Reply:**
-```
-Hi there,
-
-This is exactly what we need! We'd like to move forward. Can you
-send over pricing and contract details? Also, when can we get started?
-
-Sarah
-```
-
-**AI Analysis:**
-- Intent: `ready_to_buy`
-- Sentiment: `very_positive`
-- Escalation: `YES` (ready to buy)
-
-**AI Response:**
-```
-Thank you for your interest! Those are great questions.
-
-I'm connecting you with one of our specialists who can provide
-detailed information about ready to buy...
-```
-
-**Result:** ✅ 🔥 **HOT LEAD** - Handoff packet with 🔴 HIGH priority
-
-### Scenario 3: Has Questions (Continues)
-
-**Prospect Reply:**
-```
-Hello,
-
-This sounds interesting. I have a few questions:
-1. How does the integration process work?
-2. What kind of timeline are we looking at?
-3. Do you have case studies in our industry?
-
-Thanks,
-Sarah
-```
-
-**AI Analysis:**
-- Intent: `needs_info`
-- Sentiment: `neutral`
-- Escalation: `NO`
-
-**AI Response:**
-```
-Thank you for your message!
-
-I'm here to help answer questions about how Shopify can help
-Small Fashion Boutique.
-
-Is there anything specific you'd like to know about our solution,
-implementation process, or results we've achieved with similar companies?
-```
-
-**Result:** ℹ️ AI continues nurturing - no escalation
-
-### Scenario 4: Not Interested (Closes)
-
-**Prospect Reply:**
-```
-Thanks for the email, but we're not interested at this time.
-
-Sarah
-```
-
-**AI Analysis:**
-- Intent: `not_interested`
-- Sentiment: `negative`
-- Escalation: `NO`
-
-**AI Response:**
-```
-Thank you for your response. I understand you're not interested at this time.
-
-I've noted this in our system and you won't receive further emails from us.
-If your needs change in the future, feel free to reach out.
-```
-
-**Result:** ✅ Lead marked as not interested, removed from nurture
-
-## 📊 Handoff Packet Contents
-
-### Full Example
-
-```markdown
-# 📋 HANDOFF PACKET - Small Fashion Boutique
-
-## 🎯 Executive Summary
-**Status:** ESCALATED - Pricing Inquiry
-**Engagement Score:** 7.5/10
-**Sentiment:** Positive
-**Recommended Action:** Prepare custom pricing based on their needs
-
----
-
-## 👤 Contact Information
-**Name:** Sarah Johnson
-**Title:** CEO
-**Email:** [email protected]
-**Company:** Small Fashion Boutique
-**LinkedIn:** https://linkedin.com/in/sarah-johnson
-
----
-
-## 💬 Conversation Summary
-**Total Messages:** 2
-**Conversation Started:** 2025-11-16 10:30:15
-**Last Message:** 2025-11-16 10:30:17
-
-### Key Points Discussed:
-**Pain Points:**
-- To be discovered in follow-up call
-
-**Questions Asked:**
-- Could you share some pricing information?
-- Maybe schedule a quick call?
-
-**Buying Signals:**
-- Mentioned 'pricing'
-
----
-
-## 🔥 Escalation Details
-**Trigger:** Pricing Inquiry
-**Reason:** Prospect asked about pricing - needs custom quote from sales
-
----
-
-## 📊 Qualification Assessment
-
-### Fit Score: 7.5/10
-- **Need Alignment:** High - Prospect has identified challenges we can solve
-- **Budget Signals:** Positive - Asking about pricing (not objecting)
-- **Timeline Urgency:** Medium urgency - No immediate deadline mentioned
-- **Decision Authority:** CEO (Confirmed)
-
-### BANT Analysis:
-- **Budget:** 💰 To be qualified - Asked about pricing (positive signal)
-- **Authority:** ✅ Yes - Decision maker or influencer
-- **Need:** ✅ Confirmed - Engaged with solution discussion
-- **Timeline:** 📅 To be discovered - Schedule discovery call
-
----
-
-## 🎬 Recommended Next Steps
-
-1. **Immediate (Within 24 hours):**
-   - Send personalized email acknowledging their interest
-
-2. **Short-term (This Week):**
-   - Prepare custom proposal for Small Fashion Boutique
-   - Schedule demo/discovery call
-   - Share relevant case studies
-
-3. **Follow-up Strategy:**
-   - Multi-touch: Email → Call → Demo → Proposal
-
----
-
-## 📝 Full Conversation Transcript
-
-### 👤 Prospect (2025-11-16 10:30:15)
-Hi,
-
-Thanks for reaching out. I'm interested in learning more about how
-this could help Small Fashion Boutique. Could you share some pricing
-information and maybe schedule a quick call?
-
-Best,
-Sarah Johnson
-
-### 🤖 AI Assistant (2025-11-16 10:30:17)
-Thank you for your interest! Those are great questions.
-
-I'm connecting you with one of our specialists who can provide
-detailed information about pricing inquiry. They'll reach out to
-you within 24 hours with answers to your questions and can schedule
-a time that works for you.
-
-In the meantime, I've prepared a summary of our conversation for
-them so they'll have full context.
-
-Best regards,
-Shopify AI Assistant
-
----
-
-## 🎁 Suggested Resources to Share
-- Case study: Similar company in their industry
-- Product demo video (15 min)
-- ROI calculator customized for Small Fashion Boutique
-- Implementation timeline overview
-
----
-
-## ⚠️ Important Notes
-- Prospect has initial response received
-- Standard follow-up cadence recommended
-- AI has handled initial qualification - ready for human engagement
-
----
-
-**Generated by:** Shopify AI Sales Assistant
-**Handoff Time:** 2025-11-16 10:30:18
-**Priority:** 🟡 MEDIUM
-```
-
-## 🛠️ Technical Details
-
-### Class: `AIReplyHandler`
-
-**Key Methods:**
-1. `simulate_prospect_reply()` - Generates realistic prospect responses
-2. `analyze_intent()` - NLP-based intent detection and sentiment analysis
-3. `generate_ai_response()` - Context-aware response generation
-4. `generate_handoff_packet()` - Creates comprehensive handoff document
-5. `_calculate_engagement_score()` - Scores prospect engagement 0-10
-6. `_extract_pain_points()` - Identifies pain points from conversation
-7. `_extract_questions()` - Lists all questions asked
-8. `_extract_buying_signals()` - Detects buying intent keywords
-
-### Function: `simulate_conversation_flow()`
-
-Orchestrates the complete simulation with streaming updates:
-- Step 1: Prospect reply
-- Step 2: Intent analysis
-- Step 3: AI response generation
-- Step 4: Escalation check
-- Step 5: Handoff packet (if escalated)
-
-## 🎓 Best Practices for Real Implementation
-
-1. **Use Real Email Service:**
-   - Integrate with AWS SES, SendGrid, or Mailgun
-   - Implement webhook for actual reply detection
-
-2. **Enhanced Intent Detection:**
-   - Use LLM for better intent analysis
-   - Train on historical conversations
-   - Implement multi-turn context tracking
-
-3. **CRM Integration:**
-   - Store conversations in database
-   - Update lead scores in real-time
-   - Sync with Salesforce/HubSpot
-
-4. **Human Handoff:**
-   - Send Slack notification to sales rep
-   - Create task in CRM automatically
-   - Schedule calendar hold for follow-up
-
-5. **Continuous Learning:**
-   - Track escalation accuracy
-   - Measure time to human response
-   - Optimize AI responses based on outcomes
-
-## 🚀 Future Enhancements
-
-- [ ] Multi-turn conversations (AI handles 2-3 back-and-forth)
-- [ ] Sentiment tracking over time
-- [ ] Auto-scheduling integration (Calendly)
-- [ ] Email webhook integration for real replies
-- [ ] Lead scoring that updates with each message
-- [ ] A/B testing different AI response strategies
-- [ ] Integration with voice/phone systems
-- [ ] Automatic meeting booking when escalated
-- [ ] Post-meeting follow-up automation
-
-## ✅ Summary
-
-The AI Reply Handler provides a **complete simulation** of:
-1. ✅ Prospect replying to initial outreach
-2. ✅ AI analyzing intent and sentiment
-3. ✅ AI generating contextual responses
-4. ✅ AI detecting escalation triggers
-5. ✅ AI creating comprehensive handoff packets
-
-This demonstrates the **full workflow** from initial email → AI conversation → human escalation, exactly as requested!

BUGFIX_SUMMARY.md

@@ -1,136 +0,0 @@
-# Bug Fix Summary - WebSearchService Integration
-
-## 🐛 Issue
-
-```
-❌ Error: WebSearchService.search() got an unexpected keyword argument 'num_results'
-```
-
-## 🔍 Root Cause
-
-The `B2BSalesAgent` class was using incorrect parameter names and missing `await` keywords when calling the asynchronous `WebSearchService.search()` method.
-
-### Problems Identified:
-
-1. **Wrong parameter name**: Used `num_results` instead of `max_results`
-2. **Missing await**: Didn't use `await` for async method calls
-3. **Wrong field names**: Used `'snippet'` and `'link'` instead of `'body'` and `'url'`
-
-## ✅ Fixes Applied
-
-### 1. Parameter Name Corrections (4 instances)
-
-**Before:**
-```python
-results = self.web_search.search(query, num_results=5)
-```
-
-**After:**
-```python
-results = await self.web_search.search(query, max_results=5)
-```
-
-**Files affected:**
-- `app.py` lines 431, 447, 457, 475, 495
-
-### 2. Field Name Corrections
-
-**Before:**
-```python
-client_profile['website'] = result['link']  # ❌ Wrong
-snippet = result.get('snippet', '')         # ❌ Wrong
-```
-
-**After:**
-```python
-client_profile['website'] = result['url']   # ✅ Correct
-body = result.get('body', '')               # ✅ Correct
-```
-
-## 📋 WebSearchService Return Format
-
-The `WebSearchService.search()` method returns results with these keys:
-
-```python
-{
-    'title': 'Result title',
-    'body': 'Result snippet/description',  # NOT 'snippet'
-    'url': 'https://example.com',          # NOT 'link'
-    'source': 'example.com'
-}
-```
-
-## 🔧 Complete Change List
-
-### `app.py` - B2BSalesAgent class
-
-1. **Line 431** - `research_client()`:
-   - ✅ Changed `num_results=5` → `max_results=5`
-   - ✅ Added `await`
-
-2. **Line 443** - `research_client()`:
-   - ✅ Changed `result.get('link')` → `result.get('url')`
-
-3. **Line 447** - `research_client()`:
-   - ✅ Changed `num_results=3` → `max_results=3`
-   - ✅ Added `await`
-
-4. **Line 457** - `find_prospects()`:
-   - ✅ Changed `num_results=num_prospects * 2` → `max_results=num_prospects * 2`
-   - ✅ Added `await`
-
-5. **Lines 463-464** - `find_prospects()`:
-   - ✅ Changed `result.get('link')` → `result.get('url')`
-   - ✅ Changed `result.get('snippet')` → `result.get('body')`
-
-6. **Line 475** - `research_prospect()`:
-   - ✅ Changed `num_results=5` → `max_results=5`
-   - ✅ Added `await`
-
-7. **Line 487** - `research_prospect()`:
-   - ✅ Changed `result.get('snippet')` → `result.get('body')`
-
-8. **Line 495** - `find_contacts()`:
-   - ✅ Changed `num_results=5` → `max_results=5`
-   - ✅ Added `await`
-
-9. **Lines 501, 510** - `find_contacts()`:
-   - ✅ Changed `result.get('snippet')` → `result.get('body')`
-   - ✅ Changed `result.get('link')` → `result.get('url')`
-
-## ✅ Verification
-
-All fixes have been applied and syntax verified:
-
-```bash
-✅ python -m py_compile app.py  # No errors
-```
-
-## 🚀 Status
-
-**RESOLVED** - The B2B Sales Agent now correctly integrates with WebSearchService.
-
-The application should now work without errors when:
-1. Running the B2B Sales pipeline
-2. Researching client companies
-3. Finding prospects
-4. Finding contacts
-5. Generating emails
-
-## 🧪 Testing Checklist
-
-After deploying these fixes, verify:
-
-- [ ] B2B Sales pipeline runs without errors
-- [ ] Client company research completes
-- [ ] Prospects are discovered
-- [ ] Contacts are found at prospect companies
-- [ ] Emails are generated successfully
-- [ ] AI Reply Handler simulation works
-- [ ] No "unexpected keyword argument" errors
-
----
-
-**Fixed by:** Claude Code AI Assistant
-**Date:** 2025-11-16
-**Files Modified:** `app.py` (9 changes)

CRITICAL_SETUP.md

@@ -1,227 +0,0 @@
-# 🚨 CRITICAL: Setup Real Contact Discovery (2 MINUTES)
-
-## The Problem
-
-Your emails look like this:
-```
-Hi Hello,  ← Should be "Hi John,"
-
-I hope this email finds you well. I'm reaching out on behalf of Shopify...
-```
-
-**Root Cause:** `SERPER_API_KEY` is not configured, so the system cannot search for real decision-makers.
-
----
-
-## ✅ Quick Fix (Choose Your Deployment)
-
-### Option 1: Running Locally
-
-**Step 1: Get Free API Key (1 minute)**
-
-1. Go to: **https://serper.dev**
-2. Sign up (free, no credit card)
-3. Copy your API key
-
-**Free Tier:**
-- 2,500 searches/month
-- Perfect for testing
-
-**Step 2: Add to .env File (30 seconds)**
-
-Open `.env` file and replace:
-```
-SERPER_API_KEY=your_serper_api_key_here
-```
-
-With:
-```
-SERPER_API_KEY=YOUR-ACTUAL-API-KEY-HERE
-```
-
-**Step 3: Restart Application**
-
-```bash
-# Stop current app (Ctrl+C)
-python app.py
-```
-
----
-
-### Option 2: Running on HuggingFace Space
-
-**HuggingFace Spaces require secrets to be set in the UI**
-
-**Step 1: Get API Key** (same as above - https://serper.dev)
-
-**Step 2: Add to Space Secrets**
-
-1. Go to your Space settings
-2. Click **"Settings"** → **"Variables and secrets"**
-3. Add new secret:
-   - Name: `SERPER_API_KEY`
-   - Value: Your actual API key
-4. Save and **restart the Space**
-
-**Step 3: Verify in Logs**
-
-After restart, check logs for:
-```
-✅ EnhancedFinder: Found REAL contact: John Smith (CEO) - [email protected]
-```
-
-Instead of:
-```
-❌ No contacts found, using generic contact
-```
-
----
-
-## 🔍 How to Know It's Working
-
-### BEFORE (Current State):
-```
-Logs:
-❌ SERPER_API_KEY not set. Cannot perform search.
-❌ No contacts found for E-Commerce Nation, using generic contact
-
-Email Generated:
-Hi Hello,  ← Generic greeting
-I hope this email finds you well...
-```
-
-### AFTER (With API Key):
-```
-Logs:
-✅ Searching via Serper API for: 'CEO at TheCommerceShop'
-✅ EnhancedFinder: Found REAL contact: Sarah Johnson (CEO) - [email protected]
-✅ Writer: Using contact: Sarah Johnson (CEO) - [email protected]
-
-Email Generated:
-Hi Sarah,  ← Real person's first name
-As CEO of TheCommerceShop, you're likely focused on...
-```
-
----
-
-## 📊 Test After Setup
-
-Run this command to verify:
-
-```bash
-python test_contact_finder.py
-```
-
-**Expected Output:**
-```
-[TEST 1] Enhanced Contact Finder
-Testing: Shopify (shopify.com)
-
-[OK] Found 2 REAL contacts:
-
-  1. Tobi Lütke
-     Title: CEO
-     Email: [email protected]
-```
-
----
-
-## ⚙️ Your Current .env File
-
-I've created `.env` from `.env.example`. You need to update these values:
-
-**REQUIRED for Real Contacts:**
-```
-SERPER_API_KEY=GET-FROM-SERPER-DEV
-```
-
-**Also Required for AI Email Generation:**
-```
-HF_API_TOKEN=YOUR-HUGGINGFACE-TOKEN
-```
-
----
-
-## 🚀 Complete Setup Checklist
-
-- [ ] Go to https://serper.dev and get free API key
-- [ ] Add `SERPER_API_KEY` to `.env` file (local) OR HF Space secrets (cloud)
-- [ ] Restart application
-- [ ] Check logs for "Found REAL contact"
-- [ ] Test email generation - should say "Hi [FirstName],"
-- [ ] Verify email addresses are work emails (not info@)
-
----
-
-## 💡 Why This Matters
-
-**Without SERPER_API_KEY:**
-- ❌ Cannot search LinkedIn for real profiles
-- ❌ Cannot find company team pages
-- ❌ Uses fake names from preset pool
-- ❌ Emails addressed to "Hello" or generic names
-- ❌ Low response rates
-
-**With SERPER_API_KEY:**
-- ✅ Searches LinkedIn for real decision-makers
-- ✅ Scrapes company team pages
-- ✅ Finds actual names, titles, work emails
-- ✅ Emails personalized: "Hi Sarah, As VP of CX at..."
-- ✅ Higher response rates (personalization works)
-
----
-
-## 🆘 Troubleshooting
-
-### "SERPER_API_KEY not found" after setting it
-
-**Local Development:**
-- Restart terminal completely
-- Restart application
-- Verify .env file is in project root
-- Check for typos in .env file
-
-**HuggingFace Space:**
-- Verify secret is named exactly: `SERPER_API_KEY`
-- Restart the Space (not just refresh)
-- Check Space logs for errors
-
-### "EnhancedFinder: Found 0 real contacts"
-
-**Causes:**
-1. API key invalid or expired
-2. Quota exceeded (2,500 searches/month)
-3. Company doesn't have public LinkedIn profiles
-
-**Solutions:**
-1. Verify API key at https://serper.dev/dashboard
-2. Check usage/quota
-3. Try different company (e.g., "Shopify", "Stripe")
-
-### Emails still say "Hi Hello"
-
-**Check Logs For:**
-```
-Writer: Using contact: [Name] ([Title]) - [Email]
-```
-
-If you don't see this, contacts aren't being attached to prospects.
-
-**Debug Steps:**
-1. Check logs for "Found REAL contact"
-2. Verify `prospect.contacts` is not empty
-3. Check writer.py logs
-
----
-
-## 📞 Next Steps
-
-1. **Set SERPER_API_KEY** (highest priority!)
-2. **Restart application**
-3. **Test with real company** (Shopify, Stripe, etc.)
-4. **Check email output** - should say "Hi [FirstName],"
-5. **Verify work emails** - should be [email protected]
-
----
-
-**This is THE critical issue preventing real contact discovery. Everything else works correctly once this key is set!**

DEBUGGING_GUIDE.md

@@ -1,254 +0,0 @@
-# Debugging Guide: Real Contact Discovery
-
-## What to Check in Your HuggingFace Space Logs
-
-When you start your HuggingFace Space, you should now see diagnostic information at the top of the logs.
-
----
-
-## ✅ SUCCESS - What You SHOULD See:
-
-```
-================================================================================
-API KEY DIAGNOSTICS
-================================================================================
-[OK] SERPER_API_KEY is loaded (length: 64 chars)
-     Preview: sk_abc123...
-[OK] HF_API_TOKEN is loaded (length: 40 chars)
-[INFO] Running in HuggingFace Space: your-space-id
-================================================================================
-
-...
-
-================================================================================
-WEB SEARCH SERVICE CHECK
-================================================================================
-[OK] WebSearchService initialized WITH API key
-     Key length: 64 characters
-================================================================================
-```
-
-**If you see this:** ✅ Your API key is configured correctly!
-
----
-
-## ❌ PROBLEM - What You DON'T Want to See:
-
-```
-================================================================================
-API KEY DIAGNOSTICS
-================================================================================
-[CRITICAL] SERPER_API_KEY NOT FOUND!
-           Real contact discovery will NOT work!
-           Set SERPER_API_KEY in:
-           - Local: .env file or environment variable
-           - HF Space: Settings -> Repository secrets
-           Get free key: https://serper.dev
-...
-================================================================================
-
-...
-
-================================================================================
-WEB SEARCH SERVICE CHECK
-================================================================================
-[CRITICAL] WebSearchService initialized WITHOUT API key!
-           Contact discovery will use FALLBACK data only!
-================================================================================
-```
-
-**If you see this:** ❌ Your API key is NOT being loaded!
-
----
-
-## 🔧 Troubleshooting Steps
-
-### If API Key NOT Found in HuggingFace Space:
-
-**Step 1: Verify Secret Name**
-- Go to your Space → Settings → Repository secrets
-- Secret name MUST be **exactly**: `SERPER_API_KEY` (case-sensitive)
-- NOT: `SERPER_KEY`, `SERPER`, or anything else
-
-**Step 2: Verify Secret Value**
-- Make sure the value is your actual API key from serper.dev
-- Should start with something like `sk_...` or similar
-- No extra spaces or quotes
-
-**Step 3: Force Restart**
-- After setting the secret, you MUST restart the Space
-- Go to Space → Settings → Factory Reboot
-- Or click the restart button
-- Wait for full reload (may take 1-2 minutes)
-
-**Step 4: Check Logs Again**
-- After restart, check the logs immediately
-- Look for the "API KEY DIAGNOSTICS" section
-- Should now show `[OK] SERPER_API_KEY is loaded`
-
----
-
-## 🧪 Testing After Fix
-
-Once you see `[OK] SERPER_API_KEY is loaded` in the logs:
-
-**Test 1: Create a Prospect**
-1. Enter client company: "Shopify"
-2. Click "Start Pipeline"
-3. Watch the logs
-
-**What to Look For:**
-```
-✅ GOOD:
-ProspectDiscovery: Using ENHANCED contact finder (LinkedIn + Team pages + AI)
-Searching via Serper API for: 'CEO at TheCommerceShop'
-EnhancedFinder: Found REAL contact: Sarah Johnson (CEO) - sarah.johnson@...
-Writer: Using contact: Sarah Johnson (CEO) - sarah.johnson@...
-
-❌ BAD:
-SERPER_API_KEY not set. Cannot perform search.
-No contacts found, using generic contact
-```
-
-**Test 2: Check Generated Email**
-Email should look like:
-```
-Hi Sarah,  ← Real first name
-
-As CEO of TheCommerceShop, you're likely focused on...
-```
-
-NOT:
-```
-Hi Hello,  ← Generic greeting
-```
-
----
-
-## 📊 Log Interpretation
-
-### Scenario 1: Key Loaded but Still No Contacts
-
-**Logs show:**
-```
-[OK] SERPER_API_KEY is loaded (length: 64 chars)
-[OK] WebSearchService initialized WITH API key
-```
-
-**But later:**
-```
-No contacts found for Company, using generic contact
-```
-
-**Possible Causes:**
-1. **API Quota Exceeded** - Check https://serper.dev/dashboard
-   - Free tier: 2,500 searches/month
-   - Solution: Wait for quota reset or upgrade plan
-
-2. **Invalid API Key** - Key is set but not valid
-   - Test your key at serper.dev dashboard
-   - Regenerate key if needed
-
-3. **Company Has No Public Profiles**
-   - Some companies don't have LinkedIn/team pages
-   - Try a well-known company like "Shopify", "Stripe"
-
----
-
-### Scenario 2: Key Not Loaded in HF Space
-
-**Logs show:**
-```
-[CRITICAL] SERPER_API_KEY NOT FOUND!
-[INFO] Running in HuggingFace Space: your-space-id
-```
-
-**Solutions:**
-1. Double-check secret name is exactly: `SERPER_API_KEY`
-2. Make sure you saved the secret
-3. Restart the Space (Factory Reboot)
-4. Check if there are any deployment errors
-
----
-
-### Scenario 3: Works Locally, Not in HF Space
-
-**Local (works):**
-```
-[OK] SERPER_API_KEY is loaded
-[INFO] Running locally
-```
-
-**HF Space (doesn't work):**
-```
-[CRITICAL] SERPER_API_KEY NOT FOUND!
-[INFO] Running in HuggingFace Space
-```
-
-**Reason:**
-- Local uses `.env` file
-- HF Space uses Repository secrets
-- These are separate configurations
-
-**Solution:**
-- You need to set the secret in HF Space settings
-- .env file is ignored in HF Spaces
-
----
-
-## 🎯 Quick Checklist
-
-Before reporting issues, verify:
-
-- [ ] Logs show: `[OK] SERPER_API_KEY is loaded`
-- [ ] Logs show: `[OK] WebSearchService initialized WITH API key`
-- [ ] HF Space secret name is exactly: `SERPER_API_KEY`
-- [ ] Space has been restarted after adding secret
-- [ ] API key is valid (check serper.dev dashboard)
-- [ ] Quota not exceeded (check usage at serper.dev)
-- [ ] Test with well-known company (Shopify, Stripe)
-
----
-
-## 📝 What to Share If Still Not Working
-
-If you've done all the above and it still doesn't work, share:
-
-1. **Startup Logs:**
-   - Copy the "API KEY DIAGNOSTICS" section
-   - Copy the "WEB SEARCH SERVICE CHECK" section
-
-2. **Pipeline Logs:**
-   - Copy logs when creating a prospect
-   - Look for lines containing "ProspectDiscovery", "EnhancedFinder"
-
-3. **Generated Email:**
-   - What greeting does it use? ("Hi Hello" vs "Hi Sarah")
-
-4. **HF Space Settings:**
-   - Screenshot of Repository secrets (hide the actual key value!)
-   - Confirm secret name is exactly `SERPER_API_KEY`
-
----
-
-## 💡 Expected Behavior
-
-**With SERPER_API_KEY properly configured:**
-
-1. **Startup logs:** `[OK] SERPER_API_KEY is loaded`
-2. **Contact discovery logs:** `Searching via Serper API for...`
-3. **Contact found logs:** `EnhancedFinder: Found REAL contact: [Name]...`
-4. **Email greeting:** `Hi [FirstName],`
-5. **Email recipient:** `[email protected]`
-
-**Without SERPER_API_KEY:**
-
-1. **Startup logs:** `[CRITICAL] SERPER_API_KEY NOT FOUND!`
-2. **Contact discovery logs:** `SERPER_API_KEY not set. Cannot perform search.`
-3. **Contact fallback logs:** `No contacts found, using generic contact`
-4. **Email greeting:** `Hi Hello,` or generic
-5. **Email recipient:** `[email protected]`
-
----
-
-**The diagnostic logs will tell you exactly what's happening. Share them if you need help debugging!**

DEMO_MODE.md

@@ -1,331 +0,0 @@
-# Demo Mode - Skip Web Search
-
-## Problem Solved
-
-DuckDuckGo rate limiting can block web searches, especially in shared environments like HF Spaces. This causes the pipeline to fail.
-
-## Solution: Skip Web Search Mode
-
-The app now supports a **demo mode** that skips web search entirely and uses intelligent fallback data based on company names.
-
----
-
-## How It Works
-
-### With Web Search (Default - May Get Rate Limited):
-```
-User Input: "Shopify"
-↓
-Web Search → Find domain, industry, size
-↓
-Web Search → Find facts and news
-↓
-Web Search → Find decision-makers
-↓
-Generate Content
-```
-
-### With Demo Mode (Recommended for HF Spaces):
-```
-User Input: "Shopify"
-↓
-Intelligent Fallback → Detect industry from name ("shop" → E-commerce)
-↓
-Intelligent Fallback → Use contextual defaults
-↓
-Generate Content (works instantly!)
-```
-
----
-
-## Configuration
-
-### Enable Demo Mode
-
-Set environment variable:
-```bash
-SKIP_WEB_SEARCH=true
-```
-
-In HF Spaces:
-1. Go to Settings → Variables
-2. Add: `SKIP_WEB_SEARCH` = `true`
-3. Restart space
-
-### Disable Demo Mode (Try Web Search)
-
-```bash
-SKIP_WEB_SEARCH=false
-```
-
-**Note:** May encounter rate limiting!
-
----
-
-## Intelligent Fallback Logic
-
-The app detects industry from company name:
-
-### E-Commerce Detection
-**Keywords:** shop, store, retail, commerce
-**Example:** "Shopify" → E-commerce
-
-**Fallback Data:**
-- Industry: E-commerce
-- Size: 500 employees
-- Pain Points:
-  - Managing high transaction volumes during peak seasons
-  - Customer retention and engagement challenges
-  - Providing seamless omnichannel experiences
-  - Scaling customer support operations
-
-### Technology Detection
-**Keywords:** tech, software, cloud, data
-**Example:** "TechCorp" → Technology
-
-**Fallback Data:**
-- Industry: Technology
-- Size: 1,000 employees
-- Pain Points:
-  - Rapid scaling of customer success operations
-  - Technical support complexity
-  - Customer onboarding efficiency
-  - Product adoption and engagement
-
-### FinTech Detection
-**Keywords:** pay, bank, financial, stripe, square
-**Example:** "Stripe" → FinTech
-
-**Fallback Data:**
-- Industry: FinTech
-- Size: 800 employees
-- Pain Points:
-  - Regulatory compliance for customer communications
-  - Building customer trust and security
-  - Multi-channel support consistency
-  - Complex integration support
-
-### Default (Generic)
-**Any other company**
-
-**Fallback Data:**
-- Industry: Technology
-- Size: 500 employees
-- Pain Points:
-  - Customer experience consistency across touchpoints
-  - Scalable support operations
-  - Customer retention and satisfaction
-  - Data-driven customer insights
-
----
-
-## Performance Comparison
-
-| Mode | Time per Company | Success Rate | Use Case |
-|------|------------------|--------------|----------|
-| **Demo Mode** | 15-25s | 100% | HF Spaces, demos, rate-limited |
-| **Web Search** | 30-60s | 70-95% | Local dev, production with stable network |
-
----
-
-## What Still Works in Demo Mode
-
-✅ **All Features Work:**
-- Company discovery (intelligent fallback)
-- Prospect creation
-- Contact generation (plausible contacts)
-- AI-generated emails (using fallback context)
-- Compliance checking
-- Handoff packet creation
-
-❌ **Not Available:**
-- Real-time web search data
-- Actual decision-maker names from LinkedIn
-- Current company news
-- Real employee counts
-
----
-
-## Example Output
-
-### Input
-```
-Company Name: "Shopify"
-```
-
-### Demo Mode Output
-```
-Company: Shopify
-Domain: shopify.com
-Industry: E-commerce
-Size: 500 employees
-
-Pain Points:
-- Managing high transaction volumes during peak seasons
-- Customer retention and engagement challenges
-- Providing seamless omnichannel experiences
-- Scaling customer support operations
-
-Contacts:
-- Olivia Martinez, VP Customer Experience ([email protected])
-- Noah Patel, Director of CX ([email protected])
-- Sophia Lee, Head of Support ([email protected])
-
-Email Generated: ✅
-Compliance: ✅
-Handoff Ready: ✅
-```
-
----
-
-## When to Use Each Mode
-
-### Use Demo Mode When:
-✅ Running on Hugging Face Spaces (free tier)
-✅ Getting rate limit errors
-✅ Need fast, reliable demos
-✅ Network has restrictions
-✅ Want to avoid API dependencies
-
-### Use Web Search Mode When:
-✅ Running locally with stable network
-✅ Need real-time company data
-✅ Researching actual companies
-✅ Production environment with good network
-✅ Can tolerate occasional rate limits
-
----
-
-## Troubleshooting
-
-### Issue: Still Getting Rate Limits
-
-**Solution:** Ensure `SKIP_WEB_SEARCH=true` is set
-
-Check in code:
-```python
-from app.config import SKIP_WEB_SEARCH
-print(f"Skip web search: {SKIP_WEB_SEARCH}")
-```
-
-Should output: `Skip web search: True`
-
-### Issue: Want Better Fallback Data
-
-**Solution:** Edit `services/company_discovery.py`
-
-Customize the `_create_fallback_company()` method:
-```python
-def _create_fallback_company(self, company_name: str):
-    # Add your custom logic here
-    # Can detect more industries
-    # Can set different defaults
-    # Can use external data sources
-```
-
-### Issue: Need Mix of Real and Fallback
-
-**Solution:** Use web search but with higher timeout tolerance
-
-Set longer backoff:
-```python
-# In services/web_search.py
-backoff_time = 10 * (2 ** attempt)  # 10s, 20s, 40s
-```
-
----
-
-## HF Spaces Recommendation
-
-**For Hugging Face Spaces, use Demo Mode:**
-
-```bash
-# In HF Spaces Settings → Variables
-SKIP_WEB_SEARCH=true
-USE_IN_MEMORY_MCP=true
-```
-
-This ensures:
-- ✅ No rate limiting issues
-- ✅ Fast response times
-- ✅ 100% reliability
-- ✅ Great for demos
-- ✅ No external dependencies
-
----
-
-## Testing
-
-### Test Demo Mode
-
-```bash
-# Set environment variable
-export SKIP_WEB_SEARCH=true
-
-# Run app
-python app.py
-
-# Try any company name
-Input: "Shopify"
-Expected: Works instantly without web search!
-```
-
-### Test Web Search Mode
-
-```bash
-# Unset or set to false
-export SKIP_WEB_SEARCH=false
-
-# Run app
-python app.py
-
-# Try a company
-Input: "Shopify"
-Expected: Attempts web search (may get rate limited)
-```
-
----
-
-## Summary
-
-| Feature | Demo Mode | Web Search Mode |
-|---------|-----------|-----------------|
-| **Speed** | Fast (15-25s) | Slow (30-60s) |
-| **Reliability** | 100% | 70-95% |
-| **Data Source** | Intelligent fallback | Real-time web |
-| **Rate Limits** | Never | Possible |
-| **HF Spaces** | ✅ Recommended | ⚠️ May fail |
-| **Local Dev** | ✅ Works | ✅ Works |
-| **Demo** | ✅ Perfect | ⚠️ Risky |
-| **Production** | ⚠️ Limited data | ✅ Best |
-
----
-
-## Recommendation
-
-**For Hugging Face Spaces: Use Demo Mode**
-```bash
-SKIP_WEB_SEARCH=true
-```
-
-**For Production/Local: Try Web Search First, Fall Back to Demo if Needed**
-```bash
-SKIP_WEB_SEARCH=false
-```
-
-The app will automatically fall back to demo data if web search fails!
-
----
-
-## What's Next?
-
-Future enhancements:
-- [ ] Cache web search results for reuse
-- [ ] Support multiple search providers (Brave, SerpAPI)
-- [ ] Hybrid mode (try web search, fall back faster)
-- [ ] User-provided company data option
-- [ ] Integration with CrunchBase/LinkedIn APIs
-
----
-
-**Demo mode makes the app 100% reliable on HF Spaces! 🎉**

DEPENDENCY_FIX.md

@@ -1,117 +0,0 @@
-# Dependency Version Fix
-
-## Issue
-`ImportError: huggingface-hub>=0.19.3,<1.0 is required for a normal functioning of this module, but found huggingface-hub==1.1.4`
-
-## Root Cause
-Version conflict between `transformers` and `huggingface-hub`. The `transformers` 4.x series requires `huggingface-hub<1.0`.
-
-## Solution
-
-### Option 1: Fresh Install (Recommended)
-
-```bash
-# Remove existing packages
-pip uninstall -y huggingface-hub transformers sentence-transformers
-
-# Reinstall with correct versions
-pip install -r requirements_gradio.txt
-```
-
-### Option 2: Force Correct Versions
-
-```bash
-# Install specific compatible versions
-pip install "huggingface-hub>=0.19.3,<1.0" "transformers>=4.36.0,<5.0"
-```
-
-### Option 3: Use Virtual Environment (Best Practice)
-
-```bash
-# Create fresh environment
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-
-# Install all dependencies fresh
-pip install -r requirements_gradio.txt
-```
-
-## Verification
-
-After fixing, verify the installation:
-
-```bash
-python -c "import transformers; import huggingface_hub; print(f'transformers: {transformers.__version__}'); print(f'huggingface-hub: {huggingface_hub.__version__}')"
-```
-
-Expected output:
-```
-transformers: 4.36.x or higher (but <5.0)
-huggingface-hub: 0.19.x - 0.99.x (but <1.0)
-```
-
-## For Hugging Face Spaces
-
-The `requirements_gradio.txt` has been updated with correct version constraints:
-
-```txt
-huggingface-hub>=0.19.3,<1.0
-transformers>=4.36.0,<5.0
-```
-
-When you push to HF Spaces, it will automatically use the correct versions.
-
-## Why This Happened
-
-The original `requirements_gradio.txt` had:
-- `huggingface-hub==0.26.2` (pinned)
-- `transformers==4.45.0` (pinned)
-
-These are compatible, but if pip resolved dependencies differently or if there was a cached version, it might install `huggingface-hub>=1.0`, which breaks `transformers` 4.x.
-
-## Fixed Version Constraints
-
-Now using version ranges for better compatibility:
-- `huggingface-hub>=0.19.3,<1.0` - Compatible with transformers 4.x
-- `transformers>=4.36.0,<5.0` - Modern enough for features, <5.0 for compatibility
-
-## Still Getting Errors?
-
-### Error: "No module named 'transformers'"
-```bash
-pip install transformers
-```
-
-### Error: "No module named 'sentence_transformers'"
-```bash
-pip install sentence-transformers
-```
-
-### Error: Version conflict persists
-```bash
-# Nuclear option - remove all and reinstall
-pip freeze | xargs pip uninstall -y
-pip install -r requirements_gradio.txt
-```
-
-## Testing
-
-After fixing, test the import:
-
-```bash
-python -c "from app.orchestrator import Orchestrator; print('✓ All imports successful')"
-```
-
-If successful, you'll see:
-```
-✓ All imports successful
-```
-
-## Running the App
-
-```bash
-# Start the Gradio app
-python app.py
-```
-
-The app should now start without import errors!

DEPLOYMENT.md

@@ -1,301 +0,0 @@
-# Deployment Guide for CX AI Agent
-
-## Hugging Face Spaces Deployment
-
-### Prerequisites
-1. Hugging Face account
-2. Hugging Face API token with write access
-
-### Step 1: Create a New Space
-
-1. Go to https://huggingface.co/spaces
-2. Click "Create new Space"
-3. Choose:
-   - **Owner**: Your username or organization
-   - **Space name**: `cx-ai-agent`
-   - **License**: MIT
-   - **Space SDK**: Gradio
-   - **Space hardware**: CPU Basic (free) or upgrade for better performance
-
-### Step 2: Upload Files
-
-Upload these essential files to your Space:
-
-**Required Files:**
-```
-app.py                          # Main Gradio app
-requirements_gradio.txt         # Dependencies (rename to requirements.txt)
-README_HF_SPACES.md            # Space README (rename to README.md)
-app/                           # Application code
-├── __init__.py
-├── config.py
-├── main.py
-├── orchestrator.py
-├── schema.py
-└── logging_utils.py
-agents/                        # Agent implementations
-├── __init__.py
-├── hunter.py
-├── enricher.py
-├── contactor.py
-├── scorer.py
-├── writer.py
-├── compliance.py
-├── sequencer.py
-└── curator.py
-mcp/                          # MCP servers
-├── __init__.py
-├── registry.py
-└── servers/
-    ├── __init__.py
-    ├── calendar_server.py
-    ├── email_server.py
-    ├── search_server.py
-    └── store_server.py
-vector/                       # Vector store
-├── __init__.py
-├── embeddings.py
-├── retriever.py
-└── store.py
-data/                         # Data files
-├── companies.json
-├── suppression.json
-└── footer.txt
-scripts/                      # Utility scripts
-├── start_mcp_servers.sh
-└── seed_vectorstore.py
-```
-
-### Step 3: Configure Secrets
-
-In your Space settings, add these secrets:
-
-1. Go to your Space settings
-2. Click on "Repository secrets"
-3. Add:
-   - `HF_API_TOKEN`: Your Hugging Face API token
-
-### Step 4: Update README.md
-
-Rename `README_HF_SPACES.md` to `README.md` and update:
-- Space URL
-- Social media post link
-- Demo video link (after recording)
-
-Make sure the README includes the frontmatter:
-```yaml
----
-title: CX AI Agent - Autonomous Multi-Agent System
-emoji: 🤖
-colorFrom: blue
-colorTo: purple
-sdk: gradio
-sdk_version: 5.5.0
-app_file: app.py
-pinned: false
-tags:
-  - mcp-in-action-track-02
-  - autonomous-agents
-  - mcp
-  - rag
-license: mit
----
-```
-
-### Step 5: Start MCP Servers
-
-For HF Spaces, you have two options:
-
-#### Option A: Background Processes (Recommended for demo)
-The MCP servers will start automatically when the app launches. Make sure `scripts/start_mcp_servers.sh` is executable.
-
-#### Option B: Simplified Integration
-If background processes don't work on HF Spaces, you can integrate the MCP server logic directly into the app by modifying the `mcp/registry.py` to use in-memory implementations instead of separate processes.
-
-### Step 6: Initialize Vector Store
-
-The vector store will be initialized on first run. You can also pre-seed it by running:
-```bash
-python scripts/seed_vectorstore.py
-```
-
-### Step 7: Test the Deployment
-
-1. Visit your Space URL
-2. Check the System tab for health status
-3. Run the pipeline with a test company
-4. Verify MCP server interactions in the workflow log
-
----
-
-## Local Development
-
-### Setup
-
-1. **Clone the repository:**
-```bash
-git clone https://github.com/yourusername/cx_ai_agent
-cd cx_ai_agent
-```
-
-2. **Create virtual environment:**
-```bash
-python3.11 -m venv .venv
-source .venv/bin/activate  # Windows: .venv\Scripts\activate
-```
-
-3. **Install dependencies:**
-```bash
-pip install -r requirements_gradio.txt
-```
-
-4. **Set up environment:**
-```bash
-cp .env.example .env
-# Edit .env and add your HF_API_TOKEN
-```
-
-5. **Start MCP servers:**
-```bash
-bash scripts/start_mcp_servers.sh
-```
-
-6. **Seed vector store:**
-```bash
-python scripts/seed_vectorstore.py
-```
-
-7. **Run the app:**
-```bash
-python app.py
-```
-
-The app will be available at http://localhost:7860
-
----
-
-## Troubleshooting
-
-### MCP Servers Not Starting
-
-**On HF Spaces:**
-If MCP servers fail to start as background processes, you can modify the implementation to use in-memory storage instead. Update `mcp/registry.py` to instantiate servers directly rather than connecting to them via HTTP.
-
-**Locally:**
-```bash
-# Check if ports are already in use
-lsof -i:9001,9002,9003,9004  # Unix
-netstat -ano | findstr "9001 9002 9003 9004"  # Windows
-
-# Kill processes if needed
-pkill -f "mcp/servers"  # Unix
-```
-
-### Vector Store Issues
-
-```bash
-# Rebuild the index
-rm data/faiss.index
-python scripts/seed_vectorstore.py
-```
-
-### HuggingFace API Issues
-
-```bash
-# Verify token
-python -c "from huggingface_hub import InferenceClient; c = InferenceClient(); print('OK')"
-
-# Try fallback model if main model is rate limited
-# Edit app/config.py and change MODEL_NAME to MODEL_NAME_FALLBACK
-```
-
----
-
-## Performance Optimization
-
-### For HF Spaces
-
-1. **Upgrade Space Hardware:**
-   - CPU Basic (free): Good for testing
-   - CPU Upgraded: Better for demos
-   - GPU: Best for production-like performance
-
-2. **Model Selection:**
-   - Default: `Qwen/Qwen2.5-7B-Instruct` (high quality)
-   - Fallback: `mistralai/Mistral-7B-Instruct-v0.2` (faster)
-   - For free tier: Consider smaller models like `HuggingFaceH4/zephyr-7b-beta`
-
-3. **Caching:**
-   - Vector store is cached after first build
-   - Consider pre-building the FAISS index in the repo
-
----
-
-## Monitoring
-
-### Health Checks
-
-The System tab provides:
-- MCP server status
-- Vector store initialization status
-- HF Inference API connectivity
-
-### Logs
-
-Check Space logs for:
-- Agent execution flow
-- MCP server interactions
-- Error messages
-
----
-
-## Security Notes
-
-### Secrets Management
-
-- Never commit `.env` file
-- Always use HF Spaces secrets for `HF_API_TOKEN`
-- Rotate tokens regularly
-
-### Data Privacy
-
-- Sample data is for demonstration only
-- For production, ensure GDPR/CCPA compliance
-- Implement proper suppression list management
-
----
-
-## Next Steps
-
-After successful deployment:
-
-1. **Record Demo Video:**
-   - Show pipeline execution
-   - Highlight MCP interactions
-   - Demonstrate RAG capabilities
-   - Record 1-5 minutes
-
-2. **Create Social Media Post:**
-   - Share on X/LinkedIn
-   - Include Space URL
-   - Use hackathon hashtags
-   - Add demo video or GIF
-
-3. **Submit to Hackathon:**
-   - Verify README includes `mcp-in-action-track-02` tag
-   - Add social media link to README
-   - Add demo video link to README
-
----
-
-## Support
-
-For issues:
-- Check HF Spaces logs
-- Review troubleshooting section
-- Check GitHub issues
-- Contact maintainers
-
----
-
-**Good luck with your submission! 🚀**

DEPLOYMENT_CHECKLIST.md

@@ -1,179 +0,0 @@
-# Deployment Checklist - B2B Sales Automation
-
-## ✅ Completed Changes
-
-### Files Modified:
-1. ✅ `app.py` - Added B2BSalesAgent class and primary tab
-2. ✅ `ABOUT.md` - Added B2B workflow documentation
-3. ✅ `README.md` - Updated with B2B focus
-4. ✅ `IMPLEMENTATION_SUMMARY.md` - Created (NEW)
-5. ✅ `DEPLOYMENT_CHECKLIST.md` - Created (NEW)
-
-### Code Quality:
-- ✅ Python syntax validated (no errors)
-- ✅ All imports present
-- ✅ No syntax errors in modifications
-- ✅ Existing functionality preserved
-
-## 🚀 Ready to Deploy
-
-### Environment Variables Required:
-```
-SERPER_API_KEY=your_serper_api_key_here
-```
-
-**How to set on HuggingFace Spaces:**
-1. Go to your Space settings
-2. Navigate to "Secrets" tab
-3. Add `SERPER_API_KEY` with your Serper API key
-4. Restart the Space
-
-### Expected Behavior After Deployment:
-
-1. **Landing Page:**
-   - Title: "CX AI Agent - B2B Sales Automation Platform"
-   - Subtitle emphasizes B2B sales as core feature
-   - Primary features listed first
-
-2. **First Tab (💼 B2B Sales):**
-   - Clear workflow explanation
-   - Input field for client company
-   - Slider for number of prospects (1-5)
-   - "🚀 Find Prospects & Generate Emails" button
-   - Two output sections:
-     - Pipeline Execution Log
-     - Generated Emails (Full Content)
-
-3. **When Button Clicked:**
-   - Shows real-time progress updates
-   - Displays step-by-step workflow
-   - Final output shows:
-     - Summary (clients, prospects, contacts, emails count)
-     - Full email content for each generated email
-
-4. **Additional Tabs:**
-   - 🔄 Advanced Pipeline (existing 8-agent pipeline)
-   - 🎫 Tickets
-   - 📚 Knowledge Base
-   - 💬 Live Chat
-   - 📊 Analytics
-   - ⚙️ System
-   - ℹ️ About
-
-## 🧪 Testing Steps
-
-### Test 1: Basic B2B Sales Pipeline
-1. Go to "💼 B2B Sales" tab
-2. Enter "Shopify" as client company
-3. Set prospects to 3
-4. Click "🚀 Find Prospects & Generate Emails"
-5. **Expected:**
-   - See "Researching Shopify..." in execution log
-   - See "Found X Prospect Companies"
-   - See "Found X Contacts"
-   - See "Email Generated" for each contact
-   - See full email content in "Generated Emails" section
-   - Emails should be FROM Shopify TO prospects
-
-### Test 2: Different Client
-1. Try "Stripe" as client company
-2. Set prospects to 2
-3. **Expected:**
-   - Different prospects found (payment-related companies)
-   - Emails mention payment processing pain points
-
-### Test 3: Error Handling
-1. Enter invalid company name "asdfghjkl12345"
-2. **Expected:**
-   - Graceful error handling
-   - Error message displayed
-
-## 🔍 Verification Checklist
-
-After deployment, verify:
-
-- [ ] Application loads without errors
-- [ ] "💼 B2B Sales" tab appears first
-- [ ] Can enter client company name
-- [ ] Can run pipeline successfully
-- [ ] Execution log displays progress
-- [ ] Generated emails show full content
-- [ ] Email direction is correct (FROM client TO prospects)
-- [ ] All other tabs still work (Tickets, KB, Chat, Analytics)
-- [ ] No console errors in browser
-- [ ] Database initializes successfully
-- [ ] CX modules still functional
-
-## 📊 Expected Performance
-
-- **Pipeline Execution Time:** 1-3 minutes for 3 prospects
-- **Web Searches:** 5-15 API calls per run
-- **Email Generation:** 3-9 emails per run (1-3 per prospect)
-- **Database:** Auto-initializes on first run
-
-## 🐛 Common Issues & Solutions
-
-### Issue: "No such table: cx_tickets"
-**Solution:** Database initialization order is fixed. Should not occur.
-
-### Issue: "SERPER_API_KEY not found"
-**Solution:** Set in HuggingFace Spaces Secrets
-
-### Issue: "metadata is reserved"
-**Solution:** Already fixed - all `metadata` columns renamed to `meta_data`
-
-### Issue: "Function returned wrong number of outputs"
-**Solution:** Already fixed - all return values match Gradio expectations
-
-### Issue: "Zero companies processed"
-**Solution:** Now displays full email content, not just counts
-
-## 📝 Git Commit Message (Suggested)
-
-```
-feat: Implement B2B sales automation as core functionality
-
-- Add B2BSalesAgent class with CLIENT → PROSPECT workflow
-- Create new primary "B2B Sales" tab in UI
-- Generate personalized emails FROM client TO prospects
-- Display full email content (not just logs)
-- Update documentation (README, ABOUT.md)
-- Fix SQLAlchemy metadata conflicts
-- Improve results visibility
-
-Fixes: Incorrect workflow direction (was TO client, now TO prospects)
-Addresses: User requirement for simplified UI and visible results
-```
-
-## 🎉 Success Criteria
-
-The deployment is successful if:
-
-1. ✅ User can enter "Shopify" and get 3 prospect companies
-2. ✅ Each prospect has 1-3 contacts identified
-3. ✅ Each contact has a full email generated
-4. ✅ Emails are FROM Shopify TO the prospects (not reversed)
-5. ✅ Full email body is visible in the output
-6. ✅ All existing CX features still work
-7. ✅ UI is cleaner and focused on B2B sales
-
-## 🔜 Next Steps (Future)
-
-Based on user's original requirements, future enhancements could include:
-
-1. **Reply Handling:** AI processes prospect responses
-2. **Escalation Logic:** Determines when to hand off to human
-3. **Handoff Packets:** Structured data for sales team
-4. **Separate Functions:** API endpoints for each step
-5. **Email Sending:** Integration with AWS SES
-6. **Advanced Compliance:** CAN-SPAM, PECR, CASL validation
-7. **Better Contact Finding:** LinkedIn/Apollo integration
-8. **Database Storage:** Save prospects and emails to DB
-
----
-
-**Status:** ✅ READY TO DEPLOY
-
-**Last Updated:** 2025-11-16
-
-**Deployed By:** Claude Code AI Assistant

DEPLOYMENT_FIX.md

@@ -1,231 +0,0 @@
-# 🔧 Deployment Fix - BeautifulSoup4 Installation
-
-## ❌ Error
-
-```
-ModuleNotFoundError: No module named 'bs4'
-```
-
-## ✅ Fix Applied
-
-### **1. Updated `requirements.txt`**
-
-Added the missing dependencies:
-
-```txt
-# Web Scraping (REQUIRED for production contact finding)
-beautifulsoup4>=4.12.0
-lxml>=4.9.0
-
-# Gradio Interface (REQUIRED)
-gradio==5.5.0
-```
-
-### **2. HuggingFace Spaces Will Auto-Install**
-
-When you **rebuild** your Space, HuggingFace will automatically install all packages from `requirements.txt`.
-
----
-
-## 🚀 Deployment Steps
-
-### **Option 1: Rebuild Space (Recommended)**
-
-1. Go to your HuggingFace Space
-2. Go to **Settings** → **Factory Reboot**
-3. Click **"Reboot this Space"**
-4. Wait for dependencies to install (~2-3 minutes)
-5. Space will restart with all dependencies
-
-### **Option 2: Push Changes (If using Git)**
-
-If you're pushing via Git:
-
-```bash
-git add requirements.txt
-git commit -m "Add BeautifulSoup4 and lxml for web scraping"
-git push
-```
-
-HuggingFace will auto-detect changes and rebuild.
-
-### **Option 3: Manual Upload**
-
-1. Upload the updated `requirements.txt` via HuggingFace interface
-2. Space will automatically rebuild
-
----
-
-## 📋 Verify Installation
-
-After rebuild, check the **Logs** tab in your Space. You should see:
-
-```
-✅ Collecting beautifulsoup4>=4.12.0
-✅ Collecting lxml>=4.9.0
-✅ Successfully installed beautifulsoup4-4.12.x lxml-4.9.x
-```
-
----
-
-## 🔍 What These Packages Do
-
-### **beautifulsoup4**
-- **Purpose**: HTML/XML parsing for web scraping
-- **Used by**: `services/web_scraper.py`
-- **Features**: Extracts company info, emails, contact details from websites
-- **Size**: ~500 KB
-
-### **lxml**
-- **Purpose**: Fast XML/HTML parser (backend for BeautifulSoup)
-- **Used by**: BeautifulSoup4 internally
-- **Features**: High-performance parsing
-- **Size**: ~5 MB
-
----
-
-## ⚠️ If Error Persists
-
-### **Check 1: requirements.txt Format**
-
-Make sure `requirements.txt` is in the **root directory** of your Space:
-
-```
-/your-space-root/
-  ├── app.py
-  ├── requirements.txt  ← Must be here
-  ├── services/
-  └── ...
-```
-
-### **Check 2: Correct Package Name**
-
-**Install name**: `beautifulsoup4` (in requirements.txt)
-**Import name**: `bs4` (in Python code)
-
-```python
-# In requirements.txt:
-beautifulsoup4>=4.12.0
-
-# In Python code:
-from bs4 import BeautifulSoup  # ✅ Correct
-```
-
-### **Check 3: Space Logs**
-
-Go to **Logs** tab and check for:
-- ❌ `ERROR: Could not find a version that satisfies...`
-- ❌ `ERROR: No matching distribution found...`
-
-If you see these, there may be a dependency conflict.
-
-### **Check 4: Python Version**
-
-Ensure your Space is using Python 3.10+:
-- Go to **Settings** → **Python version**
-- Should be `3.10` or `3.11`
-
----
-
-## 🔄 Alternative: Graceful Degradation (If Needed)
-
-If you want the app to run without web scraping temporarily, you can add this to `app.py`:
-
-```python
-# At the top of app.py
-try:
-    from services.web_scraper import WebScraperService
-    from services.ai_contact_extractor import AIContactExtractor
-    WEB_SCRAPING_ENABLED = True
-except ImportError:
-    WEB_SCRAPING_ENABLED = False
-    print("⚠️ Web scraping not available - install beautifulsoup4 and lxml")
-```
-
-Then in `B2BSalesAgent.__init__`:
-
-```python
-def __init__(self):
-    self.web_search = WebSearchService()
-
-    if WEB_SCRAPING_ENABLED:
-        self.web_scraper = WebScraperService()
-        self.ai_extractor = AIContactExtractor()
-    else:
-        self.web_scraper = None
-        self.ai_extractor = None
-```
-
-**But this is NOT recommended** - just install the packages properly!
-
----
-
-## ✅ Expected Result After Fix
-
-Once dependencies are installed, you should see in logs:
-
-```
-✅ CX Platform database initialized
-✅ System initialized successfully
-Running on local URL:  http://0.0.0.0:7860
-```
-
-No more `ModuleNotFoundError`!
-
----
-
-## 📦 Complete requirements.txt
-
-Your final `requirements.txt` should look like this:
-
-```txt
-# Gradio Interface (REQUIRED)
-gradio==5.5.0
-
-# FastAPI
-fastapi==0.109.0
-uvicorn==0.27.0
-pydantic==2.5.3
-
-# HTTP and Web
-requests>=2.31.0
-aiohttp>=3.9.1
-
-# Web Scraping (REQUIRED for production contact finding)
-beautifulsoup4>=4.12.0
-lxml>=4.9.0
-
-# Data handling
-email-validator==2.1.0
-python-dotenv==1.0.0
-pandas>=2.1.4
-rich>=13.7.0
-sentence-transformers>=2.3.1
-faiss-cpu>=1.7.4
-numpy>=1.24.3,<2.0.0
-scikit-learn>=1.3.2
-
-# Testing (optional)
-pytest>=7.4.4
-pytest-asyncio>=0.21.1
-
-# Enterprise database support
-sqlalchemy>=2.0.0
-alembic>=1.13.0
-
-# HuggingFace dependencies
-huggingface-hub>=0.34.0,<1.0
-transformers>=4.36.0,<5.0
-```
-
----
-
-## 🎯 Summary
-
-**Problem**: BeautifulSoup4 not installed
-**Cause**: Missing from requirements.txt
-**Fix**: Added `beautifulsoup4>=4.12.0` and `lxml>=4.9.0`
-**Action**: Rebuild your HuggingFace Space
-**Result**: Production-ready web scraping enabled! ✅
-
-After rebuild, your B2B Sales Agent will find REAL companies and contacts using web scraping!

DYNAMIC_DISCOVERY_README.md

@@ -1,424 +0,0 @@
-# 🌐 Dynamic Company Discovery - Feature Overview
-
-## What is Dynamic Discovery?
-
-The CX AI Agent now features **Dynamic Company Discovery** - the ability to research and process **ANY company in real-time** using live web search, without requiring predefined data files.
-
-## Key Benefits
-
-### 🚀 Process Any Company
-- No longer limited to 3 predefined companies
-- Enter any company name: "Shopify", "Stripe", "Zendesk", etc.
-- System discovers all necessary information automatically
-
-### 🌐 Live Data
-- Searches the web in real-time for current information
-- Finds actual company news, facts, and developments
-- Discovers real decision-makers and contacts
-
-### 💰 Free & Open
-- Uses **DuckDuckGo Search** (completely free)
-- No API keys required
-- No rate limits to worry about
-- Works in any environment (including HF Spaces)
-
-### 🔄 Fully Compatible
-- Backwards compatible with legacy static mode
-- Graceful fallbacks when data is incomplete
-- Robust error handling
-
----
-
-## How It Works
-
-### 1. Company Discovery (Hunter Agent)
-
-**Input:** Company name (e.g., "Shopify")
-
-**Web Search Queries:**
-- "Shopify official website"
-- "Shopify industry sector business"
-- "Shopify number of employees headcount"
-- "Shopify challenges problems"
-- "Shopify news latest updates"
-
-**Output:** Complete company profile
-```python
-Company(
-    id="shopify_a1b2c3d4",
-    name="Shopify",
-    domain="shopify.com",
-    industry="E-commerce",
-    size=10000,
-    pains=[
-        "Managing high transaction volumes during peak seasons",
-        "Supporting merchants across multiple countries",
-        "Maintaining platform reliability at scale"
-    ],
-    notes=[
-        "Leading e-commerce platform provider",
-        "Recently expanded into enterprise segment",
-        "Strong focus on merchant success"
-    ]
-)
-```
-
-### 2. Fact Enrichment (Enricher Agent)
-
-**Web Search Queries:**
-- "Shopify news latest updates"
-- "Shopify E-commerce customer experience"
-- "Shopify challenges problems"
-- "shopify.com customer support contact"
-
-**Output:** List of relevant facts
-```python
-[
-    Fact(
-        text="Shopify expands AI-powered features for merchants",
-        source="techcrunch.com",
-        confidence=0.8
-    ),
-    Fact(
-        text="E-commerce platform focusing on seamless checkout",
-        source="shopify.com",
-        confidence=0.75
-    ),
-    ...
-]
-```
-
-### 3. Prospect Discovery (Contactor Agent)
-
-**Web Search Queries:**
-- "Chief Customer Officer at Shopify linkedin"
-- "Shopify VP Customer Experience contact"
-- "CCO Shopify email"
-
-**Output:** List of decision-makers
-```python
-[
-    Contact(
-        name="Sarah Johnson",
-        email="[email protected]",
-        title="Chief Customer Officer"
-    ),
-    Contact(
-        name="Michael Chen",
-        email="[email protected]",
-        title="VP Customer Experience"
-    ),
-    ...
-]
-```
-
-### 4. Personalized Content Generation
-
-Uses all discovered data to generate:
-- **Summary**: Company overview with context
-- **Email Draft**: Personalized outreach based on real pain points
-- **Compliance Check**: Regional policy enforcement
-- **Handoff Packet**: Complete dossier for sales team
-
----
-
-## Usage Examples
-
-### Gradio UI
-
-```
-1. Open the app: python app.py
-2. Go to "Pipeline" tab
-3. Enter company name: "Shopify"
-4. Click "Discover & Process"
-5. Watch real-time discovery and content generation!
-```
-
-### FastAPI
-
-```bash
-curl -X POST http://localhost:8000/run \
-  -H "Content-Type: application/json" \
-  -d '{"company_names": ["Shopify", "Stripe"]}'
-```
-
-### Python Code
-
-```python
-import asyncio
-from app.orchestrator import Orchestrator
-
-async def main():
-    orchestrator = Orchestrator()
-
-    # Process any companies
-    async for event in orchestrator.run_pipeline(
-        company_names=["Shopify", "Stripe", "Zendesk"]
-    ):
-        if event['type'] == 'agent_end':
-            print(f"✓ {event['agent']}: {event['message']}")
-
-asyncio.run(main())
-```
-
----
-
-## Supported Company Types
-
-The system works best with:
-
-✅ **Well-Known Companies**
-- Public companies (Shopify, Stripe, etc.)
-- Tech companies with web presence
-- Companies with news coverage
-
-✅ **Mid-Sized Companies**
-- B2B SaaS companies
-- Growing startups
-- Regional leaders
-
-⚠️ **Smaller Companies**
-- May have less web presence
-- System uses intelligent fallbacks
-- Still generates useful profiles
-
----
-
-## Discovery Accuracy
-
-### Company Information
-- **Domain**: 90%+ accurate for established companies
-- **Industry**: 85%+ accurate using keyword matching
-- **Size**: 70%+ accurate when data is available
-- **Pain Points**: Context-based, varies by company visibility
-
-### Contact Discovery
-- **Real Contacts**: Found when publicly listed (LinkedIn, news, etc.)
-- **Plausible Contacts**: Generated when search doesn't find results
-- **Fallback Logic**: Always provides contacts even if search fails
-
-### Fact Quality
-- **News & Updates**: 90%+ accurate for recent events
-- **Company Context**: Depends on web presence and news coverage
-- **Source URLs**: Always provided for verification
-
----
-
-## Technical Details
-
-### Web Search Technology
-- **Provider**: DuckDuckGo (via `duckduckgo-search` library)
-- **License**: Free for any use
-- **Rate Limits**: None (be respectful)
-- **Regions**: Global
-- **Results**: Real-time web search results
-
-### Performance
-- **Company Discovery**: ~2-5 seconds
-- **Fact Enrichment**: ~3-6 seconds (4 queries)
-- **Prospect Discovery**: ~2-4 seconds
-- **Total Pipeline**: ~30-60 seconds per company
-
-### Caching & Optimization
-- Results stored in MCP Store server
-- Deduplicated contacts by domain
-- Intelligent fallbacks for missing data
-- Async operations for concurrent searches
-
----
-
-## Error Handling
-
-### Company Not Found
-```python
-# Graceful fallback
-company = Company(
-    name="Unknown Corp",
-    domain="unknowncorp.com",  # Sanitized from name
-    industry="Technology",      # Default
-    size=100,                   # Estimate
-    pains=["Customer experience improvement needed"],
-    notes=["Limited data available"]
-)
-```
-
-### Search API Errors
-```python
-# Logs error, continues with fallback
-logger.error("Search error: Connection timeout")
-# Uses cached data or generates fallback
-```
-
-### No Prospects Found
-```python
-# Generates plausible contacts based on company size
-contacts = [
-    Contact(
-        name="Sarah Johnson",  # From name pool
-        email="[email protected]",
-        title="VP Customer Experience"
-    )
-]
-```
-
----
-
-## Comparison: Static vs Dynamic
-
-| Feature | Static Mode (Old) | Dynamic Mode (New) |
-|---------|-------------------|-------------------|
-| **Companies** | 3 predefined | Unlimited |
-| **Data Source** | JSON file | Live web search |
-| **Updates** | Manual edit | Automatic |
-| **Facts** | Mock/templated | Real web search |
-| **Contacts** | Generated | Discovered + generated |
-| **Flexibility** | Limited | High |
-| **Setup** | Requires seed file | No setup needed |
-| **API Key** | None | None |
-| **Cost** | Free | Free |
-
----
-
-## Best Practices
-
-### 1. Company Name Formatting
-✅ Good:
-- "Shopify"
-- "Stripe Inc"
-- "Monday.com"
-
-❌ Avoid:
-- "shopify.com" (use name, not domain)
-- "SHOPIFY" (works, but not preferred)
-- "" (empty string)
-
-### 2. Batch Processing
-```python
-# Process multiple companies efficiently
-company_names = ["Shopify", "Stripe", "Zendesk"]
-
-# System handles concurrent searches
-async for event in orchestrator.run_pipeline(company_names=company_names):
-    # Real-time events
-    pass
-```
-
-### 3. Caching Results
-```python
-# Results automatically saved to MCP Store
-# Re-run won't re-discover, uses cached data
-
-# To force fresh discovery, clear store:
-await store.clear_all()
-```
-
-### 4. Monitoring
-```python
-# Watch for discovery events
-if event['type'] == 'mcp_call' and 'web_search' in event['payload']:
-    print(f"Discovering: {event['message']}")
-```
-
----
-
-## Integration Examples
-
-### Example 1: Batch Processing
-```python
-# Process list of companies from CSV
-import pandas as pd
-
-df = pd.read_csv('companies.csv')
-company_names = df['company_name'].tolist()
-
-async for event in orchestrator.run_pipeline(company_names=company_names):
-    # Process events
-    pass
-```
-
-### Example 2: API Endpoint
-```python
-from fastapi import FastAPI
-
-app = FastAPI()
-
-@app.post("/discover")
-async def discover_company(company_name: str):
-    """Discover single company"""
-    async for event in orchestrator.run_pipeline(
-        company_names=[company_name]
-    ):
-        if event['type'] == 'llm_done':
-            return event['payload']
-```
-
-### Example 3: Scheduled Discovery
-```python
-import asyncio
-from apscheduler.schedulers.asyncio import AsyncIOScheduler
-
-scheduler = AsyncIOScheduler()
-
-@scheduler.scheduled_job('cron', hour=9)  # Daily at 9 AM
-async def daily_discovery():
-    """Discover companies daily"""
-    companies = ["Shopify", "Stripe", "Zendesk"]
-    async for event in orchestrator.run_pipeline(company_names=companies):
-        pass
-
-scheduler.start()
-```
-
----
-
-## Troubleshooting
-
-### Slow Performance?
-- Normal for web search (30-60s per company)
-- Consider processing fewer companies at once
-- Use caching for repeat runs
-
-### Inaccurate Data?
-- Depends on web presence
-- Check logs for search queries used
-- Manually verify critical data
-
-### No Results Found?
-- Try different company name variations
-- System will use fallbacks automatically
-- Check internet connection
-
----
-
-## Future Enhancements
-
-Potential improvements:
-- [ ] Multiple search provider support (Brave, SerpAPI, etc.)
-- [ ] Caching layer for faster re-runs
-- [ ] Parallel search optimization
-- [ ] Confidence scoring improvements
-- [ ] Contact email verification
-- [ ] LinkedIn API integration
-- [ ] CrunchBase data enrichment
-
----
-
-## Credits
-
-**Web Search**: DuckDuckGo (via `duckduckgo-search` library)
-**License**: Free for any use, no API key required
-**Documentation**: https://pypi.org/project/duckduckgo-search/
-
----
-
-## Support
-
-Questions or issues? Check:
-1. `UPGRADE_GUIDE.md` - Complete migration guide
-2. Code comments in `services/` directory
-3. Log files for detailed error messages
-4. GitHub issues
-
----
-
-**Happy Discovering! 🚀**

ENHANCED_CONTACT_FINDER.md

@@ -1,321 +0,0 @@
-# Enhanced Contact Finder - Real People, Real Emails
-
-## Overview
-
-The CX AI Agent now finds **real decision-makers** with their **actual names** and **work email addresses**, instead of generic emails like `[email protected]`.
-
-## What Changed?
-
-### Before ❌
-- Used basic regex to extract names from search results (often failed)
-- Generated email addresses based on assumptions (`first.last@domain`)
-- Fell back to **fake names** from a predefined pool when search failed
-- Emails addressed to generic "Dear team" instead of real people
-
-### After ✅
-- **Multi-strategy approach** to find real contacts:
-  1. LinkedIn profile search
-  2. Company team page scraping
-  3. AI-powered contact extraction
-  4. Email pattern detection
-- **Real names** extracted from multiple sources
-- **Multiple email formats** tried (first.last, firstlast, first_last, etc.)
-- **Emails personalized** with real contact names and titles
-
----
-
-## How It Works
-
-### Step 1: LinkedIn Profile Search
-```
-Query: "site:linkedin.com/in VP Customer Experience at Shopify"
-```
-- Searches specifically for LinkedIn profiles
-- Extracts real names and titles from profiles
-- Validates that the person works at the target company
-
-### Step 2: Company Team Page Scraping
-```
-URLs checked:
-- https://company.com/team
-- https://company.com/about-us
-- https://company.com/leadership
-- https://company.com/our-team
-```
-- Scrapes company websites for team/about pages
-- Extracts names, titles, and emails directly from page content
-- Matches decision-maker titles (CEO, VP, Director, etc.)
-
-### Step 3: AI-Powered Contact Extraction
-- Uses regex patterns to extract contact information from text
-- Validates that names are real (not company names or generic terms)
-- Cross-references with target titles
-
-### Step 4: Email Pattern Detection
-```
-Formats tried (in order):
-1. [email protected]
-2. [email protected]
-3. [email protected]
-4. [email protected]
-5. [email protected]
-6. [email protected]
-```
-- Tries multiple common email formats
-- Validates email format
-- Filters out generic addresses (info@, contact@, support@)
-
----
-
-## Contact Discovery Flow
-
-```
-┌─────────────────────────────────────────────────────────┐
-│  Input: Company Name + Domain + Target Titles           │
-└─────────────────────────────────────────────────────────┘
-                        ↓
-        ┌───────────────────────────────┐
-        │  Strategy 1: LinkedIn Search   │
-        │  Find: 2-3 decision-makers     │
-        └───────────────────────────────┘
-                        ↓
-        ┌───────────────────────────────┐
-        │  Strategy 2: Team Page Scrape  │
-        │  Extract: Names + Emails       │
-        └───────────────────────────────┘
-                        ↓
-        ┌───────────────────────────────┐
-        │  Strategy 3: Web Search        │
-        │  General contact discovery     │
-        └───────────────────────────────┘
-                        ↓
-        ┌───────────────────────────────┐
-        │  Validation + Deduplication    │
-        │  Remove duplicates & generics  │
-        └───────────────────────────────┘
-                        ↓
-┌─────────────────────────────────────────────────────────┐
-│  Output: List[Contact] with real names + verified emails│
-└─────────────────────────────────────────────────────────┘
-```
-
----
-
-## Email Personalization
-
-### Before
-```
-Subject: Improve YourCompany's Customer Experience
-
-Dear YourCompany team,
-
-We'd like to discuss...
-```
-
-### After
-```
-Subject: Transform Shopify's E-commerce Customer Experience
-
-Hi Sarah,
-
-As VP of Customer Experience at Shopify, you're likely focused on...
-```
-
-**Key Improvements:**
-- Addresses contact by **first name** (e.g., "Hi Sarah,")
-- References their **title** (e.g., "As VP of Customer Experience")
-- Sends to their **real work email** (e.g., `[email protected]`)
-- No more generic greetings
-
----
-
-## Real-World Example
-
-**Input:**
-```
-Client: Shopify
-Prospect: Small online retailer (50 employees)
-Target Title: CEO
-```
-
-**Enhanced Contact Finder Process:**
-
-**1. LinkedIn Search**
-```
-Query: "site:linkedin.com/in CEO at OnlineRetailer"
-Result: Found "John Smith - CEO at OnlineRetailer"
-```
-
-**2. Extract Information**
-```
-Name: John Smith
-Title: CEO
-Company: OnlineRetailer
-```
-
-**3. Generate Email**
-```
-Tried formats:
-- [email protected] ✓ (Valid format, not generic)
-```
-
-**4. Generate Personalized Email**
-```
-To: [email protected]
-Subject: Transform OnlineRetailer's E-commerce Customer Experience
-
-Hi John,
-
-As CEO of OnlineRetailer, you're likely focused on scaling your
-e-commerce operations while maintaining exceptional customer service...
-
-[Personalized content based on their industry and challenges]
-
-Best regards,
-The CX Team
-```
-
----
-
-## Key Features
-
-### ✅ Real Contact Discovery
-- Searches LinkedIn, company websites, and web results
-- Extracts actual names from multiple sources
-- Validates that names are real people (not companies or generic terms)
-
-### ✅ Email Verification
-- Tries multiple email formats
-- Validates email syntax
-- Filters out generic emails (info@, contact@, support@)
-- Deduplicates contacts
-
-### ✅ Personalization
-- Emails address contacts by first name
-- References their title and role
-- Connects their challenges to solutions
-- Professional and friendly tone
-
-### ✅ Fallback Handling
-- If enhanced finder fails, uses basic search
-- If search yields no results, generates plausible fallback
-- Logs warnings when using fallbacks
-- Always indicates which contacts are real vs. generated
-
----
-
-## Files Modified/Created
-
-### New Files
-1. **`services/enhanced_contact_finder.py`** - Core enhanced contact discovery logic
-   - LinkedIn profile search
-   - Team page scraping
-   - AI-powered extraction
-   - Email pattern detection
-
-### Modified Files
-1. **`services/prospect_discovery.py`** - Updated to use enhanced finder
-   - Integrated enhanced finder as primary method
-   - Basic search as fallback
-   - Better logging for contact discovery
-
-2. **`services/web_scraper.py`** - Added generic page scraper
-   - New `scrape_page()` method for team page scraping
-   - Cleans HTML and extracts clean text
-
-3. **`agents/writer.py`** - Enhanced email personalization
-   - Uses real contact names in greetings
-   - Includes title and role context
-   - All fallbacks use contact names
-
----
-
-## Configuration
-
-No additional configuration needed! The enhanced finder works with existing API keys:
-
-- **SERPER_API_KEY** - For Google search results (already configured)
-- **HF_API_TOKEN** - For AI-powered extraction (optional, already configured)
-
----
-
-## Testing
-
-To test the enhanced contact finder, run the application and create a prospect:
-
-```bash
-python app.py
-```
-
-Then in the UI:
-1. Enter a client company (e.g., "Shopify")
-2. The system will find prospects
-3. For each prospect, it will discover **real decision-makers**
-4. Emails will be addressed to real people by name
-
-**Check the logs** to see:
-- `ProspectDiscovery: Found REAL contact: [Name] ([Title]) - [Email]`
-- Indicates which contacts were found vs. generated
-
----
-
-## Benefits
-
-### For Sales Teams
-✅ **Higher response rates** - Personalized emails to real people perform better
-✅ **Better deliverability** - Real emails less likely to bounce
-✅ **Professional image** - Shows you did your research
-
-### For Decision-Makers
-✅ **Relevant outreach** - Email addressed to the right person
-✅ **Clear value proposition** - Understands their role and challenges
-✅ **Respectful approach** - Not a mass blast to info@
-
----
-
-## Next Steps
-
-### Optional Enhancements
-If you want even more accurate contact data, consider:
-
-1. **Professional APIs** (paid but very accurate):
-   - Hunter.io - Email finder + verification ($49/mo)
-   - Apollo.io - B2B contact database ($49-99/mo)
-   - RocketReach - Contact finder ($39-119/mo)
-
-2. **Email Verification** (confirm emails exist):
-   - NeverBounce - Email verification service
-   - ZeroBounce - Email validation
-   - Hunter.io Email Verifier
-
-3. **Phone Numbers** (for multi-channel outreach):
-   - Apollo.io includes phone numbers
-   - Lusha - Contact enrichment
-
----
-
-## Summary
-
-The enhanced contact finder transforms your B2B sales automation from:
-
-**Generic Mass Emails**
-```
-To: [email protected]
-Subject: Improve Your Customer Experience
-
-Dear Company team,
-We can help...
-```
-
-**To Personalized Outreach**
-```
-To: [email protected]
-Subject: Transform Company's E-commerce CX
-
-Hi Sarah,
-
-As VP of Customer Experience at Company, you're likely
-focused on scaling while maintaining service quality...
-```
-
-This results in **higher response rates**, **better deliverability**, and a more **professional image** for your sales outreach.

ENTERPRISE_DEPLOYMENT.md

@@ -1,452 +0,0 @@
-# CX AI Agent - Enterprise Edition Deployment Guide
-
-## 🎉 What's New in Enterprise Edition
-
-The enterprise edition transforms the simple pipeline demo into a **full-featured CX automation platform** with:
-
-### ✅ Core Features Implemented
-
-1. **Campaign Management**
-   - Create and manage multiple campaigns
-   - Track campaign progress through all stages
-   - Real-time metrics and analytics
-   - Campaign status tracking (Draft, Active, Paused, Completed)
-
-2. **Contact Database**
-   - SQLite database with full CRUD operations
-   - Advanced contact scoring (fit, engagement, intent, overall)
-   - Contact lifecycle management (Lead → MQL → SQL → Opportunity → Customer)
-   - Company relationship tracking
-
-3. **Email Sequences**
-   - Pre-built sequence templates (Cold Outreach 3-touch)
-   - Multi-step email automation
-   - Variable substitution ({{company_name}}, {{first_name}}, etc.)
-   - Email activity tracking (sent, opened, clicked, replied)
-
-4. **Enterprise UI/UX**
-   - Professional multi-tab navigation (Dashboard, Campaigns, Contacts, Sequences, Analytics)
-   - Real-time metric cards
-   - Activity feed with live updates
-   - Sortable, filterable data tables
-   - Status badges and progress bars
-   - Empty states with call-to-actions
-
-5. **Analytics & Tracking**
-   - Dashboard with key metrics
-   - Campaign performance tracking
-   - Contact engagement scoring
-   - Activity timeline
-   - Meeting scheduling and tracking
-
-6. **Database Schema**
-   - 12 comprehensive tables
-   - Companies, Contacts, Campaigns
-   - Email Sequences, Activities
-   - Meetings, A/B Tests
-   - Analytics Snapshots
-   - Settings and Templates
-
----
-
-## 🚀 Quick Start
-
-### 1. Install Dependencies
-
-```bash
-pip install -r requirements_gradio.txt
-```
-
-New dependencies added:
-- `sqlalchemy>=2.0.0` - ORM and database management
-- `alembic>=1.13.0` - Database migrations (future use)
-
-### 2. Set Up Environment
-
-```bash
-# Copy example environment file
-cp .env.example .env
-
-# Edit .env and add required keys:
-# - HF_API_TOKEN (Hugging Face for LLM)
-# - SERPER_API_KEY (for web search)
-```
-
-### 3. Run Enterprise Edition
-
-```bash
-# Run the new enterprise application
-python app_enterprise.py
-
-# Or run the original simple pipeline
-python app.py
-```
-
-The enterprise edition will:
-- Automatically create `./data/cx_agent.db` (SQLite database)
-- Initialize database schema on first run
-- Load default settings and sequence templates
-- Start on `http://0.0.0.0:7860`
-
----
-
-## 📊 Using the Enterprise Edition
-
-### Dashboard View
-
-The **Dashboard** shows:
-- **Metric Cards**: Total campaigns, active campaigns, contacts, upcoming meetings
-- **Activity Feed**: Real-time updates of all agent activities
-- **Quick Stats**: At-a-glance performance metrics
-
-### Campaigns View
-
-**Create a Campaign:**
-1. Click "+ New Campaign"
-2. Enter campaign name (e.g., "Q1 SaaS Outreach")
-3. Add description
-4. Enter target companies (comma-separated: "Shopify, Stripe, Zendesk")
-5. Click "Create & Launch Campaign"
-
-**What Happens:**
-- Creates campaign in database
-- Runs the 8-agent pipeline (Hunter → Enricher → Contactor → Scorer → Writer → Compliance → Sequencer → Curator)
-- Discovers company info via Serper API
-- Enriches contacts with web data
-- Stores all contacts in database
-- Links contacts to campaign
-- Updates campaign metrics in real-time
-
-**Campaign Table Shows:**
-- Campaign name and description
-- Status badge (Active, Draft, Paused, Completed)
-- Contacts discovered
-- Contacted count vs. goal
-- Response count
-- Meetings booked
-- Progress bar
-- Creation date
-
-### Contacts View
-
-**Features:**
-- **Search**: Find contacts by name, email, or company
-- **Filter**: By status (New, Contacted, Responded, Meeting Scheduled)
-- **Sortable Table**: Name, Company, Title, Status, Score, Date Added
-- **Scoring**: Visual score indicator (0.0 - 1.0)
-  - Green (0.7+): High fit
-  - Yellow (0.4-0.7): Medium fit
-  - Red (<0.4): Low fit
-
-**Contact Statuses:**
-- `new` - Just discovered
-- `contacted` - Email sent
-- `responded` - Reply received
-- `meeting_scheduled` - Meeting booked
-- `qualified` - Passed qualification
-- `lost` - Not interested/no response
-- `customer` - Converted to customer
-
-### Sequences View
-
-Currently shows "Coming Soon" placeholder. Full email sequence builder will include:
-- Drag-and-drop sequence editor
-- Email templates with variables
-- A/B testing
-- Send time optimization
-- Performance tracking
-
-### Analytics View
-
-Currently shows "Coming Soon" placeholder. Full analytics dashboard will include:
-- Charts and graphs (Plotly integration)
-- Campaign ROI tracking
-- Cohort analysis
-- Funnel visualization
-- Export to CSV/PDF
-
----
-
-## 🗄️ Database Structure
-
-### Key Tables
-
-**Companies** (id, name, domain, industry, size, location, pain_points)
-- Stores all target companies
-- Linked to contacts
-
-**Contacts** (id, company_id, first_name, last_name, email, job_title, scores, status)
-- All discovered prospects
-- Scoring: fit_score, engagement_score, intent_score, overall_score
-- Lifecycle tracking
-
-**Campaigns** (id, name, description, status, goals, metrics)
-- Campaign definitions and tracking
-- Progress metrics (discovered, enriched, contacted, responded, meetings)
-
-**CampaignContacts** (id, campaign_id, contact_id, stage)
-- Many-to-many relationship
-- Tracks which contacts are in which campaigns
-- Stage tracking (discovery → enrichment → scoring → outreach → responded → meeting → closed)
-
-**Sequences** (id, name, category, is_template)
-- Email sequence definitions
-- Pre-built templates
-
-**SequenceEmails** (id, sequence_id, step_number, wait_days, subject, body)
-- Individual emails in a sequence
-- Automated sending logic
-
-**EmailActivities** (id, contact_id, campaign_id, type, occurred_at)
-- Track all email interactions
-- Types: sent, delivered, opened, clicked, replied, bounced, unsubscribed
-
-**Meetings** (id, contact_id, campaign_id, scheduled_at, status, outcome)
-- Meeting scheduling and tracking
-- Outcomes: interested, not_interested, needs_follow_up, closed_won
-
-**Activities** (id, contact_id, campaign_id, type, description, occurred_at)
-- General activity log
-- Agent actions and system events
-
-**Settings** (key, value, description)
-- Application configuration
-- Company details for email footers
-- Email sending limits
-- Feature flags
-
----
-
-## 🔧 Configuration
-
-### Database Path
-
-Default: `./data/cx_agent.db`
-
-Change via environment variable:
-```bash
-export DATABASE_PATH=/custom/path/to/database.db
-```
-
-### Default Settings
-
-Automatically created on first run:
-- `company_name`: "Your Company"
-- `company_address`: "123 Main St, City, State 12345"
-- `sender_name`: "Sales Team"
-- `sender_email`: "[email protected]"
-- `daily_email_limit`: 1000
-- `enable_tracking`: True
-
-Modify in database:
-```python
-from database.manager import get_db_manager
-from models.database import Setting
-
-db = get_db_manager()
-with db.get_session() as session:
-    setting = session.query(Setting).filter_by(key='company_name').first()
-    setting.value = 'My Company Inc.'
-    session.commit()
-```
-
----
-
-## 📈 Roadmap: What's Next
-
-### Phase 2 (Next Sprint)
-- [ ] Complete Email Sequence Builder UI
-- [ ] Add A/B testing functionality
-- [ ] Implement meeting scheduling integration
-- [ ] Real-time notifications
-
-### Phase 3
-- [ ] Analytics Dashboard with charts
-- [ ] Export campaigns to CSV/Excel
-- [ ] Email report scheduling
-- [ ] Custom report builder
-
-### Phase 4
-- [ ] Sentiment analysis on replies
-- [ ] Smart reply suggestions
-- [ ] Conversation intelligence
-- [ ] Automated workflows (triggers)
-
-### Phase 5
-- [ ] CRM integrations (Salesforce, HubSpot)
-- [ ] Webhook/API for custom integrations
-- [ ] Team collaboration features
-- [ ] Advanced permission system
-
----
-
-## 🐛 Troubleshooting
-
-### Database Issues
-
-**Error: "Unable to open database file"**
-```bash
-# Create data directory
-mkdir -p ./data
-chmod 755 ./data
-```
-
-**Reset Database:**
-```bash
-# Delete existing database
-rm ./data/cx_agent.db
-
-# Restart application - will recreate with fresh schema
-python app_enterprise.py
-```
-
-### Application Not Loading
-
-**Check Dependencies:**
-```bash
-pip install -r requirements_gradio.txt
-```
-
-**Check Ports:**
-```bash
-# Default port 7860
-# If in use, application will show error
-# Kill process using port:
-lsof -ti:7860 | xargs kill -9
-```
-
-### Serper API Errors
-
-**401 Unauthorized:**
-- Check `SERPER_API_KEY` in `.env`
-- Verify key at https://serper.dev/
-
-**429 Rate Limit:**
-- Free tier: 2,500 searches/month
-- Check usage at https://serper.dev/dashboard
-- Upgrade plan or set `SKIP_WEB_SEARCH=true`
-
----
-
-## 💡 Tips & Best Practices
-
-### Campaign Management
-
-1. **Start Small**: Test with 2-3 companies first
-2. **Set Realistic Goals**: Estimate 5-10 contacts per company
-3. **Monitor Progress**: Check dashboard daily
-4. **Iterate**: Pause, adjust, and relaunch campaigns
-
-### Contact Quality
-
-1. **Review Scores**: Focus on contacts with score > 0.7
-2. **Update Manually**: Add notes and tags
-3. **Track Engagement**: Monitor email opens and clicks
-4. **Follow Up**: Schedule meetings for hot leads
-
-### Email Sequences
-
-1. **Use Templates**: Start with "Cold Outreach - 3 Touch"
-2. **Personalize**: Use variables ({{company_name}}, {{first_name}})
-3. **A/B Test**: Try different subject lines
-4. **Optimize Timing**: Test send times for best open rates
-
----
-
-## 📚 API Reference
-
-### Database Manager
-
-```python
-from database.manager import get_db_manager
-
-db = get_db_manager()
-
-# Get session
-with db.get_session() as session:
-    contacts = session.query(Contact).all()
-    # Session auto-commits on success
-    # Auto-rollback on exception
-```
-
-### Models
-
-```python
-from models.database import Contact, Campaign, Company
-
-# Create contact
-contact = Contact(
-    first_name="John",
-    last_name="Doe",
-    email="[email protected]",
-    job_title="VP of Sales",
-    fit_score=0.85
-)
-
-# Query
-high_score_contacts = session.query(Contact).filter(
-    Contact.overall_score > 0.7
-).all()
-```
-
----
-
-## 🎯 Success Metrics
-
-Track these KPIs in your enterprise deployment:
-
-- **Discovery Rate**: Contacts discovered per campaign
-- **Enrichment Rate**: % of contacts successfully enriched
-- **Response Rate**: % of emails that get replies
-- **Meeting Rate**: % of contacts that book meetings
-- **Conversion Rate**: % of meetings that convert to opportunities
-- **Pipeline Value**: Total value of opportunities generated
-
-Target Benchmarks:
-- Discovery: 5-10 contacts/company
-- Enrichment: >90%
-- Response Rate: 10-20%
-- Meeting Rate: 5-10%
-- Conversion Rate: 20-30%
-
----
-
-## 🔐 Security & Compliance
-
-### Data Privacy
-
-- All data stored locally in SQLite
-- No external data sharing
-- Contact suppression support
-- GDPR-friendly (local storage)
-
-### Email Compliance
-
-- CAN-SPAM footer included
-- Unsubscribe link required
-- Physical address in footer
-- Suppression list checking
-
-### Best Practices
-
-- Never store sensitive PII without encryption
-- Regular database backups
-- Secure API keys in environment variables
-- Monitor for data breaches
-
----
-
-## 📞 Support
-
-For issues or questions:
-- Check this deployment guide
-- Review `ENTERPRISE_UPGRADE_PLAN.md`
-- Check application logs
-- Open GitHub issue
-
----
-
-**Built with ❤️ for Enterprise CX Teams**
-
-**Version**: 2.0.0-enterprise
-**Last Updated**: 2025-01-15

ENTERPRISE_EXPANSION_PROPOSAL.md

@@ -1,930 +0,0 @@
-# CX AI Agent - Enterprise Expansion Proposal
-
-## Executive Summary
-
-This document outlines how CX AI Agent can evolve from a B2B sales automation tool into a comprehensive **Enterprise Revenue & Customer Intelligence Platform**. The focus is entirely on business value, use cases, and operational impact—not technical implementation.
-
----
-
-## Current State Assessment
-
-### What We Have Today
-| Module | Capability | Business Value |
-|--------|-----------|----------------|
-| **8-Agent Sales Pipeline** | Automated prospect discovery → email generation | 10-15x faster lead research |
-| **MCP Search** | Web & news search | Real-time company intelligence |
-| **MCP Store** | Prospects, companies, contacts, facts | Centralized prospect database |
-| **MCP Email** | Thread management | Conversation tracking |
-| **MCP Calendar** | Meeting slot suggestions | Scheduling automation |
-| **Autonomous Agent** | AI-driven task execution | Natural language operations |
-
-### Current Limitations
-- Single-channel focus (email only)
-- No revenue tracking or deal management
-- Limited analytics and reporting
-- No team collaboration features
-- No customer lifecycle management post-sale
-
----
-
-# PART 1: SALES & REVENUE OPERATIONS EXPANSION
-
-## 1.1 Multi-Channel Outreach Engine
-
-### Current State
-- Email-only outreach
-
-### Enterprise Expansion
-
-#### **LinkedIn Integration**
-| Feature | Business Value |
-|---------|---------------|
-| Connection request generation | Personalized invites based on prospect research |
-| InMail drafting | AI-crafted messages using company facts |
-| Profile visit tracking | Know when prospects view your profile |
-| Content engagement suggestions | Comment/like recommendations on prospect posts |
-
-#### **Phone/Call Intelligence**
-| Feature | Business Value |
-|---------|---------------|
-| Call script generation | Personalized talking points per prospect |
-| Voicemail drop scripts | Pre-written voicemails using pain points |
-| Best time to call prediction | Based on industry/role patterns |
-| Post-call summary templates | Quick note capture with AI suggestions |
-
-#### **Multi-Touch Sequence Builder**
-```
-Day 1:  LinkedIn Connection Request
-Day 3:  Personalized Email #1 (Introduction)
-Day 5:  LinkedIn Profile View
-Day 7:  Email #2 (Value Proposition)
-Day 10: Phone Call Attempt
-Day 12: LinkedIn InMail
-Day 14: Email #3 (Case Study)
-Day 17: Final Email (Break-up)
-```
-
-**Business Impact:**
-- 3-5x higher response rates through multi-channel
-- Coordinated messaging across touchpoints
-- Reduced prospect fatigue from single-channel spam
-
----
-
-## 1.2 Deal Pipeline & Revenue Management
-
-### New Module: Deal Tracker
-
-#### **Deal Stages with AI Recommendations**
-| Stage | AI Capabilities |
-|-------|----------------|
-| **Discovery** | Auto-populate deal from prospect data |
-| **Qualification** | BANT/MEDDIC scoring automation |
-| **Demo Scheduled** | Meeting prep brief generation |
-| **Proposal Sent** | Proposal content suggestions |
-| **Negotiation** | Competitive intelligence alerts |
-| **Closed Won/Lost** | Win/loss pattern analysis |
-
-#### **Revenue Forecasting**
-- **AI-Predicted Close Dates**: Based on engagement patterns
-- **Deal Health Scores**: Real-time risk indicators
-- **Pipeline Coverage Analysis**: Gap identification
-- **Quota Attainment Projections**: Individual & team forecasts
-
-#### **Competitive Intelligence**
-| Feature | Business Value |
-|---------|---------------|
-| Competitor mention alerts | Know when prospects evaluate competitors |
-| Battle card generation | AI-created competitive positioning |
-| Win/loss analysis | Pattern recognition across deals |
-| Pricing intelligence | Market rate benchmarking |
-
-**Business Impact:**
-- 20-30% improvement in forecast accuracy
-- Earlier identification of at-risk deals
-- Data-driven pricing decisions
-
----
-
-## 1.3 Account-Based Marketing (ABM) Module
-
-### Target Account Intelligence
-
-#### **Account Scoring & Tiering**
-| Tier | Criteria | Treatment |
-|------|----------|-----------|
-| **Tier 1** | Fortune 500, >$1B revenue, perfect ICP fit | White-glove, executive outreach |
-| **Tier 2** | Mid-market, strong fit, active buying signals | Multi-threaded, personalized |
-| **Tier 3** | SMB, moderate fit | Automated sequences |
-
-#### **Buying Committee Mapping**
-- **Champion Identification**: Who's your internal advocate?
-- **Economic Buyer**: Who controls budget?
-- **Technical Evaluator**: Who assesses solution fit?
-- **Blocker Detection**: Who might oppose the purchase?
-- **Relationship Strength Scoring**: Per-contact engagement levels
-
-#### **Account Penetration Dashboard**
-```
-ACME Corporation (Tier 1 Account)
-├── Contacts Identified: 12
-├── Contacts Engaged: 7
-├── Active Opportunities: 2
-├── Total Pipeline Value: $450,000
-├── Buying Committee Coverage: 75%
-└── Next Best Action: "Engage CFO - economic buyer not yet contacted"
-```
-
-**Business Impact:**
-- Focus resources on highest-value accounts
-- Multi-thread deals to reduce single-point-of-failure
-- Increase average deal size through strategic engagement
-
----
-
-## 1.4 Sales Intelligence & Signals
-
-### Buying Intent Detection
-
-#### **Signal Categories**
-| Signal Type | Examples | Action Triggered |
-|-------------|----------|------------------|
-| **Hiring Signals** | "Hiring VP of Customer Success" | Outreach with CX solution pitch |
-| **Funding Signals** | "Series B announced" | Congratulations + growth pitch |
-| **Tech Stack Changes** | "Migrating from Salesforce" | Competitive displacement outreach |
-| **Leadership Changes** | "New CTO appointed" | Executive introduction campaign |
-| **Expansion Signals** | "Opening new office in Austin" | Regional expansion pitch |
-| **Pain Signals** | "Glassdoor reviews mention poor tools" | Solution-focused outreach |
-
-#### **News & Event Monitoring**
-- Earnings call summaries with key quotes
-- Press release analysis
-- Industry event attendance tracking
-- Social media sentiment shifts
-
-#### **Website Visitor Intelligence**
-- Anonymous company identification
-- Page visit patterns (pricing page = high intent)
-- Return visitor alerts
-- Content consumption analysis
-
-**Business Impact:**
-- Reach prospects at the right moment
-- Relevant, timely outreach increases conversion 2-3x
-- Proactive vs. reactive selling
-
----
-
-# PART 2: CUSTOMER SUCCESS & RETENTION
-
-## 2.1 Customer Health Scoring
-
-### Predictive Churn Prevention
-
-#### **Health Score Components**
-| Factor | Weight | Signals |
-|--------|--------|---------|
-| **Product Usage** | 30% | Login frequency, feature adoption, API calls |
-| **Engagement** | 25% | Email opens, meeting attendance, support tickets |
-| **Relationship** | 20% | NPS scores, executive sponsor activity |
-| **Financial** | 15% | Payment history, expansion purchases |
-| **External** | 10% | News sentiment, Glassdoor, funding status |
-
-#### **Risk Categorization**
-| Risk Level | Health Score | Action |
-|------------|--------------|--------|
-| **Healthy** | 80-100 | Expansion opportunity identification |
-| **Stable** | 60-79 | Maintain engagement cadence |
-| **At Risk** | 40-59 | CSM intervention required |
-| **Critical** | 0-39 | Executive escalation, save plan |
-
-#### **AI-Generated Intervention Plans**
-```
-Customer: TechCorp Inc.
-Health Score: 42 (Critical)
-Risk Factors:
-  - Login frequency down 60% (last 30 days)
-  - Support tickets up 3x
-  - Champion left company 2 weeks ago
-
-Recommended Actions:
-1. Schedule executive business review within 5 days
-2. Identify and engage new champion
-3. Offer dedicated onboarding for new users
-4. Provide ROI analysis showing value delivered
-```
-
-**Business Impact:**
-- Reduce churn by 15-25%
-- Earlier intervention = higher save rates
-- Systematic approach to retention
-
----
-
-## 2.2 Customer 360 View
-
-### Unified Customer Intelligence
-
-#### **Single Pane of Glass**
-| Data Category | Information |
-|--------------|-------------|
-| **Company Profile** | Industry, size, tech stack, news |
-| **Relationship History** | All interactions across sales & CS |
-| **Product Usage** | Feature adoption, usage trends |
-| **Financial** | ARR, expansion history, payment status |
-| **Sentiment** | NPS, CSAT, support satisfaction |
-| **Contacts** | All stakeholders with engagement history |
-| **Documents** | Contracts, proposals, meeting notes |
-
-#### **Timeline View**
-```
-TechCorp Inc. - Customer Since: Jan 2023
-
-Mar 2024  │ ★ Expanded to Enterprise plan (+$50K ARR)
-Feb 2024  │ ● NPS Score: 9 (Promoter)
-Jan 2024  │ ○ QBR completed - discussed API integration
-Dec 2023  │ ! Support escalation - resolved in 2 hours
-Nov 2023  │ ● New champion identified: Sarah Chen (VP Ops)
-Oct 2023  │ ★ Renewed for 2 years
-...
-```
-
-#### **Relationship Mapping**
-- Org chart visualization
-- Stakeholder influence mapping
-- Communication frequency heatmap
-- Decision-maker identification
-
-**Business Impact:**
-- Eliminate "tribal knowledge" dependency
-- Faster onboarding for new CSMs
-- Informed conversations at every touchpoint
-
----
-
-## 2.3 Expansion & Upsell Intelligence
-
-### Revenue Growth from Existing Customers
-
-#### **Expansion Opportunity Detection**
-| Signal | Opportunity |
-|--------|------------|
-| Heavy feature usage near plan limits | Upgrade to higher tier |
-| New department using product | Cross-sell additional seats |
-| Feature requests for premium features | Upsell add-ons |
-| Successful ROI demonstrated | Multi-year commitment |
-| New budget cycle approaching | Expansion conversation |
-
-#### **AI-Generated Expansion Plays**
-```
-Customer: DataFlow Systems
-Current ARR: $36,000 (Growth Plan, 50 seats)
-Expansion Score: 87/100
-
-Opportunities Identified:
-1. Seat Expansion: 23 new users added organically
-   → Potential: +$16,500 ARR
-
-2. Feature Upsell: API usage at 90% of limit
-   → Potential: +$12,000 ARR (Enterprise API add-on)
-
-3. New Department: Marketing team requesting access
-   → Potential: +$24,000 ARR (30 additional seats)
-
-Total Expansion Potential: $52,500 (146% growth)
-
-Recommended Talk Track:
-"I noticed your team has grown significantly and you're
-approaching some usage limits. Let's discuss how we can
-better support your scaling needs..."
-```
-
-#### **Renewal Management**
-- 120/90/60/30 day renewal alerts
-- Renewal risk assessment
-- Pricing recommendation engine
-- Auto-generated renewal proposals
-
-**Business Impact:**
-- Increase Net Revenue Retention to 120%+
-- Systematic expansion pipeline
-- Reduce missed renewal opportunities
-
----
-
-# PART 3: MARKETING INTELLIGENCE
-
-## 3.1 Ideal Customer Profile (ICP) Refinement
-
-### Data-Driven ICP Evolution
-
-#### **Win/Loss Pattern Analysis**
-| Attribute | Won Deals | Lost Deals | Insight |
-|-----------|-----------|------------|---------|
-| Company Size | 200-2000 employees | <50 or >5000 | Sweet spot identified |
-| Industry | SaaS, FinTech | Manufacturing | Focus verticals |
-| Tech Stack | Modern (AWS, React) | Legacy (On-prem) | Technical fit matters |
-| Buying Process | <90 days | >180 days | Long cycles = poor fit |
-| Champion Title | VP/Director level | Individual contributor | Seniority matters |
-
-#### **ICP Scoring Model**
-```
-Company: Acme Software
-ICP Score: 92/100
-
-Matching Criteria:
-✓ Industry: SaaS (perfect match)
-✓ Size: 450 employees (sweet spot)
-✓ Tech Stack: AWS, React, PostgreSQL (modern)
-✓ Funding: Series C (growth stage)
-✓ Location: US (primary market)
-? Growth Rate: Unknown (data gap)
-✗ Competitor: Uses competitor product (displacement needed)
-```
-
-#### **Lookalike Account Discovery**
-- Find companies similar to best customers
-- Expand TAM with data-backed targeting
-- Prioritize outreach based on similarity scores
-
-**Business Impact:**
-- Focus on prospects most likely to convert
-- Shorter sales cycles
-- Higher win rates
-
----
-
-## 3.2 Content Intelligence
-
-### Content Performance & Recommendations
-
-#### **Content Effectiveness Tracking**
-| Content Asset | Views | Engagement | Influenced Pipeline |
-|--------------|-------|------------|---------------------|
-| ROI Calculator | 1,200 | 45% | $2.3M |
-| Case Study: FinTech | 800 | 38% | $1.8M |
-| Product Demo Video | 2,100 | 22% | $1.2M |
-| Pricing Page | 3,400 | 12% | $980K |
-
-#### **AI Content Recommendations**
-- Which content to send based on prospect stage
-- Personalized content suggestions per industry
-- Gap analysis (missing content for key objections)
-- A/B test recommendations
-
-#### **Competitive Content Analysis**
-- Competitor messaging tracking
-- Differentiation opportunity identification
-- Battle card content suggestions
-
-**Business Impact:**
-- Higher content ROI
-- More relevant prospect engagement
-- Data-driven content strategy
-
----
-
-## 3.3 Campaign Intelligence
-
-### Marketing Campaign Optimization
-
-#### **Campaign Performance Dashboard**
-```
-Q4 Outbound Campaign: "FinTech CX Leaders"
-
-Metrics:
-├── Prospects Targeted: 500
-├── Emails Sent: 2,340
-├── Open Rate: 42% (benchmark: 25%)
-├── Reply Rate: 8.5% (benchmark: 3%)
-├── Meetings Booked: 34
-├── Pipeline Generated: $1.2M
-├── Closed Revenue: $340K
-└── ROI: 12.4x
-
-Top Performing Segments:
-1. Series B-C FinTech (52% open rate)
-2. VP/Director titles (11% reply rate)
-3. Companies using Stripe (highest conversion)
-```
-
-#### **AI Campaign Optimization**
-- Subject line A/B test recommendations
-- Best send time by segment
-- Personalization variable effectiveness
-- Sequence length optimization
-
-**Business Impact:**
-- Continuous campaign improvement
-- Higher marketing ROI
-- Sales-marketing alignment
-
----
-
-# PART 4: OPERATIONS & PRODUCTIVITY
-
-## 4.1 Meeting Intelligence
-
-### Before, During & After Meeting Automation
-
-#### **Pre-Meeting Briefings**
-```
-Meeting: Discovery Call with DataFlow Systems
-Date: Tomorrow, 2:00 PM EST
-Duration: 30 minutes
-Attendees: John Smith (VP Engineering), Sarah Lee (Director Ops)
-
-Company Brief:
-- 450 employees, Series C, $40M raised
-- Industry: Data Analytics SaaS
-- Recent News: Launched enterprise product last month
-
-Attendee Insights:
-- John Smith: 8 years at company, promoted twice
-  LinkedIn: Active, posts about engineering culture
-  Talking points: Scaling challenges, team growth
-
-- Sarah Lee: Joined 6 months ago from Competitor X
-  Likely evaluating tools, change agent
-  Talking points: Process improvement, efficiency
-
-Suggested Agenda:
-1. Current challenges (5 min)
-2. Solution overview (10 min)
-3. Q&A and fit assessment (10 min)
-4. Next steps (5 min)
-
-Competitive Intel:
-- Currently using Competitor Y (based on job postings)
-- Pain points: "Integration difficulties" mentioned in G2 review
-```
-
-#### **Post-Meeting Automation**
-- AI-generated meeting summary
-- Action item extraction
-- Follow-up email drafting
-- CRM update suggestions
-- Next meeting scheduling
-
-**Business Impact:**
-- 30 minutes saved per meeting in prep
-- More informed, productive conversations
-- Consistent follow-up execution
-
----
-
-## 4.2 Email Intelligence
-
-### Advanced Email Capabilities
-
-#### **Smart Inbox Management**
-| Feature | Capability |
-|---------|-----------|
-| **Priority Scoring** | AI ranks emails by importance and urgency |
-| **Response Suggestions** | Pre-drafted replies based on context |
-| **Follow-up Reminders** | "No response in 3 days" alerts |
-| **Sentiment Detection** | Flag frustrated/happy customer emails |
-| **Thread Summarization** | TL;DR for long email threads |
-
-#### **Email Analytics**
-- Best performing subject lines
-- Optimal email length
-- Response time impact on conversion
-- Personalization effectiveness
-
-#### **Template Intelligence**
-```
-Template: "Post-Demo Follow-up"
-Performance:
-├── Times Used: 234
-├── Open Rate: 67%
-├── Reply Rate: 23%
-├── Meetings Booked: 41
-└── Suggested Improvements:
-    - Shorten paragraph 2 (too long)
-    - Add specific pain point from demo
-    - Include social proof (case study)
-```
-
-**Business Impact:**
-- Faster email response times
-- Higher email effectiveness
-- Reduced inbox overwhelm
-
----
-
-## 4.3 Task & Workflow Automation
-
-### Intelligent Task Management
-
-#### **AI Task Prioritization**
-```
-Today's Priorities (AI-Ranked):
-
-🔴 HIGH PRIORITY
-1. Follow up with TechCorp (deal closing this week)
-2. Respond to DataFlow support escalation
-3. Send proposal to NewCo (requested yesterday)
-
-🟡 MEDIUM PRIORITY
-4. Schedule QBR with existing customer
-5. Research 3 new prospects for ABM campaign
-6. Update CRM notes from yesterday's calls
-
-🟢 LOW PRIORITY
-7. Review marketing content for feedback
-8. Clean up prospect list
-```
-
-#### **Automated Workflows**
-| Trigger | Automated Action |
-|---------|------------------|
-| New lead assigned | Send welcome sequence, create tasks |
-| Deal stage changed | Notify team, update forecasts |
-| Customer health drops | Alert CSM, create intervention task |
-| Contract expiring (90 days) | Start renewal workflow |
-| Support ticket escalated | Notify account team |
-
-#### **Natural Language Task Creation**
-```
-User: "Remind me to follow up with John at TechCorp next Tuesday about the proposal"
-
-System Creates:
-- Task: Follow up with John at TechCorp about proposal
-- Due: Tuesday, [date]
-- Related Contact: John Smith (TechCorp)
-- Related Deal: TechCorp Enterprise Deal
-- Context: Proposal sent on [date]
-```
-
-**Business Impact:**
-- Zero tasks falling through cracks
-- Proactive vs. reactive work
-- Consistent process execution
-
----
-
-# PART 5: ANALYTICS & INSIGHTS
-
-## 5.1 Revenue Analytics
-
-### Comprehensive Revenue Intelligence
-
-#### **Pipeline Analytics**
-| Metric | Current | Target | Trend |
-|--------|---------|--------|-------|
-| Total Pipeline | $4.2M | $5M | ↑ 12% |
-| Qualified Pipeline | $2.8M | $3M | ↑ 8% |
-| Pipeline Coverage | 3.2x | 3x | ✓ |
-| Avg Deal Size | $45K | $50K | ↑ 5% |
-| Win Rate | 28% | 30% | ↓ 2% |
-| Sales Cycle | 62 days | 55 days | ↑ 7 days |
-
-#### **Cohort Analysis**
-- Revenue by customer acquisition month
-- Expansion patterns over time
-- Churn timing analysis
-- Payback period tracking
-
-#### **Revenue Attribution**
-```
-Q4 Closed Revenue: $1.2M
-
-Attribution:
-├── Outbound Sales: 45% ($540K)
-│   ├── Cold Email: $320K
-│   ├── LinkedIn: $150K
-│   └── Phone: $70K
-├── Inbound Marketing: 35% ($420K)
-│   ├── Content: $200K
-│   ├── Events: $120K
-│   └── Referrals: $100K
-└── Expansion: 20% ($240K)
-    ├── Upsells: $160K
-    └── Cross-sells: $80K
-```
-
-**Business Impact:**
-- Data-driven resource allocation
-- Clear ROI by channel
-- Optimized go-to-market strategy
-
----
-
-## 5.2 Team Performance Analytics
-
-### Individual & Team Insights
-
-#### **Rep Performance Dashboard**
-```
-Rep: Sarah Johnson
-Role: Account Executive
-Territory: Mid-Market West
-
-Performance (Q4):
-├── Quota: $400K | Attainment: 112% ($448K)
-├── Pipeline Generated: $1.8M
-├── Win Rate: 34% (team avg: 28%)
-├── Avg Deal Size: $52K (team avg: $45K)
-├── Sales Cycle: 48 days (team avg: 62 days)
-└── Activity Metrics:
-    ├── Emails Sent: 1,240 (response rate: 12%)
-    ├── Calls Made: 320 (connect rate: 18%)
-    └── Meetings Held: 67
-
-Strengths:
-- Exceptional discovery calls (highest conversion to demo)
-- Strong relationship building (multi-threaded deals)
-
-Development Areas:
-- Proposal customization (below team benchmark)
-- Follow-up consistency (gaps in sequence completion)
-```
-
-#### **Team Comparison & Benchmarking**
-- Activity benchmarks
-- Conversion rate comparisons
-- Best practice identification
-- Coaching opportunity detection
-
-#### **Quota & Territory Planning**
-- Historical attainment analysis
-- Territory balance assessment
-- Quota recommendation engine
-- Capacity planning
-
-**Business Impact:**
-- Identify top performers and replicate success
-- Targeted coaching for improvement areas
-- Fair, data-driven quota setting
-
----
-
-## 5.3 Predictive Analytics
-
-### AI-Powered Forecasting
-
-#### **Deal Outcome Prediction**
-```
-Deal: TechCorp Enterprise
-Stage: Proposal Sent
-Amount: $120,000
-
-AI Prediction:
-├── Win Probability: 72%
-├── Predicted Close Date: Dec 15 (±7 days)
-├── Confidence: High (based on 847 similar deals)
-└── Risk Factors:
-    - No executive sponsor engaged (reduces prob by 15%)
-    - Competitor mentioned in calls (reduces prob by 8%)
-
-Recommendation:
-"Engage VP-level sponsor before final decision.
-Similar deals with executive engagement close at 85%."
-```
-
-#### **Pipeline Forecast**
-| Category | Amount | Probability | Weighted |
-|----------|--------|-------------|----------|
-| Commit | $800K | 90% | $720K |
-| Best Case | $1.2M | 60% | $720K |
-| Pipeline | $2.4M | 30% | $720K |
-| **Total Forecast** | | | **$2.16M** |
-
-#### **Trend Predictions**
-- Churn risk forecasting
-- Expansion timing prediction
-- Market demand signals
-- Seasonal pattern analysis
-
-**Business Impact:**
-- More accurate forecasting
-- Proactive deal management
-- Better resource planning
-
----
-
-# PART 6: INDUSTRY-SPECIFIC SOLUTIONS
-
-## 6.1 Vertical Customizations
-
-### SaaS/Technology
-| Feature | Business Value |
-|---------|---------------|
-| Tech stack detection | Know what tools prospects use |
-| Integration opportunity mapping | "They use Salesforce, we integrate!" |
-| Developer community monitoring | Track GitHub, Stack Overflow mentions |
-| Product-led growth signals | Freemium conversion opportunities |
-
-### Financial Services
-| Feature | Business Value |
-|---------|---------------|
-| Regulatory compliance tracking | Know their compliance requirements |
-| M&A activity monitoring | Acquisition = new decision makers |
-| AUM/Revenue correlation | Size-appropriate solutions |
-| Board/executive changes | Timing for executive outreach |
-
-### Healthcare
-| Feature | Business Value |
-|---------|---------------|
-| HIPAA compliance indicators | Pre-qualify for healthcare |
-| Health system hierarchy mapping | Navigate complex org structures |
-| Grant/funding tracking | Budget timing intelligence |
-| Clinical trial monitoring | R&D activity = growth signals |
-
-### E-Commerce/Retail
-| Feature | Business Value |
-|---------|---------------|
-| Platform detection (Shopify, Magento) | Technical fit assessment |
-| Seasonal planning cycles | Time outreach to budget planning |
-| Store count tracking | Expansion signals |
-| Customer review sentiment | Pain point identification |
-
----
-
-## 6.2 Use Case Templates
-
-### By Business Function
-
-#### **For Sales Development (SDR/BDR)**
-- Prospect research automation
-- Multi-channel sequence building
-- Meeting booking optimization
-- Activity tracking and coaching
-
-#### **For Account Executives**
-- Deal management and forecasting
-- Competitive intelligence
-- Proposal generation
-- Meeting preparation
-
-#### **For Customer Success**
-- Health score monitoring
-- Renewal management
-- Expansion identification
-- Risk mitigation workflows
-
-#### **For Marketing**
-- ABM campaign management
-- Content performance tracking
-- Lead scoring refinement
-- Campaign ROI analysis
-
-#### **For Revenue Operations**
-- Pipeline analytics
-- Forecast accuracy
-- Territory planning
-- Process optimization
-
-#### **For Executives**
-- Revenue dashboards
-- Team performance
-- Strategic insights
-- Board reporting
-
----
-
-# PART 7: BUSINESS IMPACT SUMMARY
-
-## Quantified Value Delivery
-
-### Sales Efficiency Gains
-| Metric | Before | After | Improvement |
-|--------|--------|-------|-------------|
-| Prospect Research Time | 45 min/prospect | 5 min/prospect | 90% reduction |
-| Email Personalization | 15 min/email | 2 min/email | 87% reduction |
-| Meeting Prep Time | 30 min/meeting | 5 min/meeting | 83% reduction |
-| CRM Data Entry | 20 min/day | 5 min/day | 75% reduction |
-
-### Revenue Impact
-| Metric | Improvement | Annual Value (100-person sales team) |
-|--------|-------------|--------------------------------------|
-| Win Rate | +5% | +$2.5M revenue |
-| Sales Cycle | -15 days | +$1.8M (faster closes) |
-| Pipeline Coverage | +20% | +$3.2M pipeline |
-| Rep Productivity | +25% | +$4.0M capacity |
-
-### Customer Success Impact
-| Metric | Improvement | Annual Value |
-|--------|-------------|--------------|
-| Churn Reduction | -20% | +$800K retained ARR |
-| Expansion Revenue | +30% | +$1.2M expansion |
-| CSM Efficiency | +40% | Support 50% more accounts |
-
-### Total Enterprise Value
-```
-Conservative Annual Impact (Mid-Market Company):
-
-Sales Efficiency:        $500K - $1M saved
-Revenue Acceleration:    $2M - $4M additional revenue
-Customer Retention:      $500K - $1M retained
-Expansion Revenue:       $800K - $1.5M growth
-
-TOTAL ANNUAL VALUE:      $3.8M - $7.5M
-```
-
----
-
-# PART 8: IMPLEMENTATION ROADMAP
-
-## Phased Delivery (Business Milestones)
-
-### Phase 1: Foundation (Immediate Value)
-**Focus: Enhanced Sales Automation**
-- Multi-channel outreach (Email + LinkedIn)
-- Advanced contact discovery
-- Improved prospect scoring
-- Basic deal tracking
-
-**Business Outcome:** 50% reduction in prospect research time
-
-### Phase 2: Intelligence Layer
-**Focus: Buying Signals & Insights**
-- Intent signal detection
-- News & event monitoring
-- Competitive intelligence
-- Meeting preparation automation
-
-**Business Outcome:** 20% improvement in response rates
-
-### Phase 3: Customer Success
-**Focus: Retention & Growth**
-- Customer health scoring
-- Churn prediction
-- Expansion opportunity detection
-- Renewal management
-
-**Business Outcome:** 15% reduction in churn
-
-### Phase 4: Revenue Operations
-**Focus: Analytics & Optimization**
-- Pipeline analytics
-- Forecasting
-- Team performance
-- Revenue attribution
-
-**Business Outcome:** 25% improvement in forecast accuracy
-
-### Phase 5: Enterprise Platform
-**Focus: Advanced Capabilities**
-- AI-powered recommendations
-- Workflow automation
-- Industry-specific features
-- Executive dashboards
-
-**Business Outcome:** Fully integrated revenue platform
-
----
-
-# PART 9: COMPETITIVE DIFFERENTIATION
-
-## How CX AI Agent Stands Apart
-
-### vs. Traditional CRM (Salesforce, HubSpot)
-| Aspect | Traditional CRM | CX AI Agent |
-|--------|-----------------|-------------|
-| Data Entry | Manual | AI-automated |
-| Intelligence | Passive storage | Active insights |
-| Personalization | Template-based | AI-generated |
-| Workflow | Rigid rules | Autonomous AI |
-
-### vs. Sales Engagement (Outreach, Salesloft)
-| Aspect | Sales Engagement | CX AI Agent |
-|--------|------------------|-------------|
-| Research | Separate tools | Built-in AI research |
-| Content | Templates | Dynamic generation |
-| Intelligence | Basic analytics | Predictive AI |
-| Scope | Outbound only | Full revenue cycle |
-
-### vs. Revenue Intelligence (Gong, Chorus)
-| Aspect | Revenue Intelligence | CX AI Agent |
-|--------|---------------------|-------------|
-| Focus | Call analysis | Full journey |
-| Automation | Insights only | Insights + action |
-| Scope | Post-meeting | End-to-end |
-
-### Unique Value Proposition
-1. **True AI Autonomy** - Agent decides actions, not just follows rules
-2. **Full-Cycle Coverage** - Prospect → Customer → Expansion
-3. **Real-Time Intelligence** - Live web research, not stale data
-4. **Unified Platform** - One tool for entire revenue team
-
----
-
-# CONCLUSION
-
-CX AI Agent has the foundation to become a comprehensive **Enterprise Revenue Intelligence Platform** that:
-
-1. **Automates** repetitive sales and success tasks
-2. **Intelligently** surfaces insights and recommendations
-3. **Predicts** outcomes and risks before they happen
-4. **Unifies** the entire revenue team on one platform
-5. **Scales** from SMB to enterprise with industry-specific solutions
-
-The expansion from a B2B sales automation tool to a full revenue platform addresses a $50B+ market opportunity and positions CX AI Agent as a category-defining solution.
-
----
-
-*Document Version: 1.0*
-*Created: November 2024*
-*Classification: Strategic Planning*

ENTERPRISE_UPGRADE_PLAN.md

@@ -1,752 +0,0 @@
-# Enterprise CX AI Agent - Upgrade Plan
-
-## Overview
-
-Transform the current pipeline-based demo into a **full-fledged enterprise-level CX (Customer Experience) AI Agent** application with production-ready features, enterprise UI/UX, and real-world scenario support.
-
-**Focus Areas:**
-- ✅ Core CX Agent Functionalities (not authentication/multi-tenancy)
-- ✅ Enterprise-level UI/UX
-- ✅ Real-world scenario support
-- ✅ MCP-powered automation
-- ✅ SQLite database (simple start, can migrate later)
-
----
-
-## Phase 1: Enterprise UI/UX Foundation (Week 1-2)
-
-### 1.1 Modern Dashboard Layout
-
-**Replace simple Gradio interface with enterprise-grade UI:**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  🤖 CX AI Agent          [Search]  [Settings]  [Help]       │
-├─────────────────────────────────────────────────────────────┤
-│ 📊 Dashboard  📋 Campaigns  👥 Contacts  📧 Sequences  📈   │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
-│  │   Active    │  │  Contacts   │  │   Email     │        │
-│  │  Campaigns  │  │  Discovered │  │   Sent      │        │
-│  │      12     │  │     1,247   │  │    3,891    │        │
-│  └─────────────┘  └─────────────┘  └─────────────┘        │
-│                                                              │
-│  Recent Activity                                            │
-│  ┌──────────────────────────────────────────────────────┐  │
-│  │ ✅ Campaign "Q1 SaaS" completed - 47 prospects       │  │
-│  │ 🔄 Discovery running for "Enterprise Tech"          │  │
-│  │ 📧 Sequence "Follow-up" - 23 emails sent            │  │
-│  └──────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Components:**
-- Multi-tab navigation (Dashboard, Campaigns, Contacts, Sequences, Analytics)
-- Real-time metric cards
-- Activity feed with live updates
-- Quick action buttons
-- Filter and search across all sections
-
-### 1.2 Enhanced Gradio Components
-
-**Upgrade from basic Gradio to advanced components:**
-
-```python
-# Current: Simple tabs
-with gr.Tabs():
-    with gr.Tab("Pipeline"):
-        # Basic pipeline
-
-# Enterprise: Multi-level navigation with state
-with gr.Blocks(theme=custom_enterprise_theme()) as demo:
-    # Header with branding
-    gr.HTML(enterprise_header())
-
-    # Navigation bar
-    with gr.Row():
-        nav_dashboard = gr.Button("📊 Dashboard", variant="primary")
-        nav_campaigns = gr.Button("📋 Campaigns")
-        nav_contacts = gr.Button("👥 Contacts")
-        nav_sequences = gr.Button("📧 Sequences")
-        nav_analytics = gr.Button("📈 Analytics")
-
-    # Dynamic content area
-    content = gr.Column()
-
-    # Route between views
-    nav_dashboard.click(show_dashboard, outputs=[content])
-    nav_campaigns.click(show_campaigns, outputs=[content])
-```
-
-**Custom Theme:**
-- Professional color scheme
-- Consistent spacing and typography
-- Icons and visual hierarchy
-- Responsive design
-
----
-
-## Phase 2: Campaign Management System (Week 2-3)
-
-### 2.1 Campaign Builder
-
-**Create campaigns with:**
-- Campaign name and description
-- Target industry/company size filters
-- Geographic targeting
-- Budget and timeline
-- Success metrics (response rate, meetings booked, etc.)
-
-**Campaign Stages:**
-```
-Discovery → Enrichment → Scoring → Outreach → Follow-up → Closed Won/Lost
-```
-
-**UI:**
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Create New Campaign                                         │
-├─────────────────────────────────────────────────────────────┤
-��  Campaign Name: [Q1 Enterprise SaaS Outreach____________]   │
-│  Description:   [___________________________________]        │
-│                                                              │
-│  🎯 Targeting                                               │
-│  Industries:     [☑ SaaS  ☑ Fintech  ☐ Healthcare]         │
-│  Company Size:   [○ 1-50  ● 51-200  ○ 201-1000  ○ 1000+]   │
-│  Geography:      [North America ▼]                          │
-│                                                              │
-│  📧 Outreach Settings                                       │
-│  Email Sequence: [Cold Outreach - Enterprise ▼]            │
-│  Follow-up Days: [3, 7, 14_____]                           │
-│                                                              │
-│  📊 Goals                                                   │
-│  Target Contacts: [500_]                                    │
-│  Response Rate:   [15%_]                                    │
-│  Meetings Booked: [50__]                                    │
-│                                                              │
-│  [Cancel]  [Save Draft]  [Launch Campaign →]               │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 2.2 Campaign Dashboard
-
-**Track campaigns in real-time:**
-- Active campaigns list
-- Campaign status (Draft, Active, Paused, Completed)
-- Progress bars for each stage
-- Real-time metrics
-- Quick actions (Pause, Edit, Clone, Archive)
-
-**Campaign Detail View:**
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Campaign: Q1 Enterprise SaaS Outreach                      │
-│  Status: ● Active   Started: Jan 15, 2025   Progress: 68%  │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  Pipeline Funnel                                            │
-│  ┌────────────────────────────────────────────────────────┐│
-│  │ Discovery      ████████████████ 500 companies          ││
-│  │ Enrichment     ████████████ 420 enriched               ││
-│  │ Scoring        ██████████ 380 scored                   ││
-│  │ Outreach       ████████ 340 contacted                  ││
-│  │ Responded      ███ 51 responses (15%)                  ││
-│  │ Meeting Booked █ 12 meetings                           ││
-│  └────────────────────────────────────────────────────────┘│
-│                                                              │
-│  Recent Activity                                            │
-│  • 10:45 AM - 12 new prospects discovered                  │
-│  • 10:30 AM - Email sent to John Doe (TechCorp)           │
-│  • 10:15 AM - Response from Sarah Smith (DataInc)         │
-│                                                              │
-│  [⏸ Pause]  [⚙️ Settings]  [📊 Full Report]  [📤 Export]  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 2.3 A/B Testing
-
-**Test different variations:**
-- Email subject lines
-- Email body content
-- Sending times
-- Follow-up cadence
-
-**Track performance:**
-- Open rates
-- Click rates
-- Response rates
-- Meeting booking rates
-
----
-
-## Phase 3: Contact & Lead Management (Week 3-4)
-
-### 3.1 Contact Database
-
-**Comprehensive contact management:**
-
-```sql
-CREATE TABLE contacts (
-    id INTEGER PRIMARY KEY,
-    -- Basic Info
-    first_name TEXT,
-    last_name TEXT,
-    email TEXT UNIQUE,
-    phone TEXT,
-    job_title TEXT,
-
-    -- Company Info
-    company_id INTEGER,
-    company_name TEXT,
-    company_domain TEXT,
-    company_size TEXT,
-    company_industry TEXT,
-
-    -- Enrichment Data
-    linkedin_url TEXT,
-    twitter_url TEXT,
-    location TEXT,
-    timezone TEXT,
-
-    -- Scoring
-    fit_score REAL,
-    engagement_score REAL,
-
-    -- Status
-    status TEXT, -- new, contacted, responded, meeting_scheduled, qualified, lost
-    lifecycle_stage TEXT, -- lead, mql, sql, opportunity, customer
-
-    -- Tracking
-    source TEXT, -- discovery_agent, manual_import, api
-    first_contacted_at TIMESTAMP,
-    last_contacted_at TIMESTAMP,
-    last_activity_at TIMESTAMP,
-
-    -- Metadata
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    tags TEXT, -- JSON array of tags
-    notes TEXT,
-
-    FOREIGN KEY (company_id) REFERENCES companies(id)
-);
-```
-
-### 3.2 Contact List View
-
-**Sortable, filterable contact table:**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  👥 Contacts (1,247)                                        │
-│  [🔍 Search contacts...]  [Filter ▼]  [+ New Contact]      │
-├─────────────────────────────────────────────────────────────┤
-│  Filters: ☑ Active  ☐ Responded  ☐ Meeting Scheduled       │
-├─────────────────────────────────────────────────────────────┤
-│ Name ↓          | Company    | Status      | Score | Last │
-│─────────────────────────────────────────────────────────────│
-│ 👤 Sarah Johnson│ TechCorp   │ ✅ Responded│ 0.89  │ 2h  ││
-│ 👤 Mike Chen    │ DataInc    │ 📧 Contacted│ 0.85  │ 1d  ││
-│ 👤 Emma Wilson  │ CloudSys   │ 🆕 New      │ 0.92  │ 3h  ││
-│ 👤 James Brown  │ AILabs     │ 📅 Meeting  │ 0.78  │ 4h  ││
-│                                                              │
-│  [←]  Page 1 of 25  [→]         Showing 1-50 of 1,247      │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 3.3 Contact Detail View
-
-**Rich contact profile:**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  👤 Sarah Johnson                         [Edit]  [Archive] │
-│  VP of Customer Experience @ TechCorp                       │
-│  📧 [email protected]  📱 +1-555-0123                   │
-│  📍 San Francisco, CA  🔗 linkedin.com/in/sarahj           │
-├─────────────────────────────────────────────────────────────┤
-│  Score: ⭐⭐⭐⭐⭐ 0.89 (High fit)  Status: ✅ Responded    │
-│  Tags: [enterprise] [decision-maker] [warm-lead]           │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  🏢 Company Info                                            │
-│  TechCorp - SaaS, 250 employees, $50M ARR                  │
-│  Pain points: Manual support processes, data fragmentation │
-│                                                              │
-│  📊 Engagement History                                      │
-│  ┌──────────────────────────────────────────────────────┐  │
-│  │ Jan 15, 10:30 AM  📧 Email sent: "Transform CX..."   │  │
-│  │ Jan 15, 2:45 PM   ✉️ Opened email                    │  │
-│  │ Jan 16, 9:15 AM   💬 Replied: "Interested, let's..."│  │
-│  │ Jan 16, 10:00 AM  📅 Meeting scheduled               │  │
-│  └──────────────────────────────────────────────────────┘  │
-│                                                              │
-│  📝 Notes                                                   │
-│  [Add note about this contact...]                          │
-│                                                              │
-│  [📧 Send Email]  [📅 Schedule Meeting]  [📞 Log Call]     │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Phase 4: Email Sequence Builder (Week 4-5)
-
-### 4.1 Sequence Templates
-
-**Pre-built sequence library:**
-- Cold Outreach (3-touch)
-- Cold Outreach (5-touch)
-- Warm Introduction
-- Event Follow-up
-- Demo Request Follow-up
-- Re-engagement
-- Custom templates
-
-### 4.2 Sequence Builder UI
-
-**Drag-and-drop sequence editor:**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Create Email Sequence: Cold Outreach - Enterprise          │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  Sequence Flow:                                             │
-│  ┌──────────┐   wait    ┌──────────┐   wait   ┌─────────┐ │
-│  │ Email 1  │ ─────3d──→│ Email 2  │ ────7d──→│ Email 3 │ │
-│  │ Initial  │           │ Value    │          │Follow-up│ │
-│  │ Contact  │           │ Prop     │          │  Call   │ │
-│  └──────────┘           └──────────┘          └─────────┘ │
-│       ↓                      ↓                      ↓      │
-│   [Edit Email]          [Edit Email]          [Edit Email]│
-│                                                              │
-│  Email 1: Initial Contact                                  │
-│  ┌──────────────────────────────────────────────────────┐  │
-│  │ Subject: {{company_name}} + CX Automation           │  │
-│  │                                                       │  │
-│  │ Hi {{first_name}},                                   │  │
-│  │                                                       │  │
-│  │ I noticed {{company_name}} is in the {{industry}}   │  │
-│  │ space with {{company_size}} employees. Companies    │  │
-│  │ like yours often face {{pain_points}}.              │  │
-│  │                                                       │  │
-│  │ Our AI-powered platform has helped similar          │  │
-│  │ companies reduce support costs by 35%.              │  │
-│  │                                                       │  │
-│  │ Would you be open to a 15-minute call?              │  │
-│  │                                                       │  │
-│  │ Best,                                                 │  │
-│  │ {{sender_name}}                                      │  │
-│  └──────────────────────────────────────────────────────┘  │
-│                                                              │
-│  Variables: {{first_name}}, {{company_name}}, {{industry}} │
-│  [+ Add Variable]  [Preview]  [Test Send]                  │
-│                                                              │
-│  [Save Draft]  [Activate Sequence]                         │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 4.3 Sequence Performance Tracking
-
-**Monitor sequence effectiveness:**
-- Sent vs. Delivered
-- Open rates per email
-- Click rates
-- Response rates
-- Meeting booking rates
-- Unsubscribe rates
-
-**Optimize based on data:**
-- Best performing subject lines
-- Optimal send times
-- Effective follow-up cadence
-
----
-
-## Phase 5: Analytics & Reporting (Week 5-6)
-
-### 5.1 Real-time Dashboard
-
-**Key Metrics:**
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  📈 Analytics Dashboard                                     │
-│  Date Range: [Last 30 Days ▼]                              │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│  Overview Metrics                                           │
-│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐     │
-│  │ Contacts │ │  Emails  │ │ Response │ │ Meetings │     │
-│  │ Enriched │ │   Sent   │ │   Rate   │ │  Booked  │     │
-│  │  1,247   │ │  3,891   │ │   18.5%  │ │    47    │     │
-│  │  ↑ 23%   │ │  ↑ 45%   │ │  ↑ 3.2%  │ │  ↑ 12    │     │
-│  └──────────┘ └─────────���┘ └──────────┘ └──────────┘     │
-│                                                              │
-│  Email Performance Trend                                    │
-│  ┌──────────────────────────────────────────────────────┐  │
-│  │   %                                                   │  │
-│  │ 100│                                                  │  │
-│  │  80│                     ╱──────╲                    │  │
-│  │  60│           ╱────────╱        ╲                   │  │
-│  │  40│  ╱───────╱                   ╲─────             │  │
-│  │  20│╱                                   ╲            │  │
-│  │   0└──────────────────────────────────────────────  │  │
-│  │     Week 1  Week 2  Week 3  Week 4                   │  │
-│  │     ─── Open Rate  ─── Response Rate                 │  │
-│  └──────────────────────────────────────────────────────┘  │
-│                                                              │
-│  Top Performing Campaigns                                  │
-│  1. Q1 SaaS Outreach      - 24% response, 15 meetings     │
-│  2. Enterprise Tech       - 19% response, 12 meetings     │
-│  3. Fintech Expansion     - 17% response, 8 meetings      │
-│                                                              │
-│  [📊 Full Report]  [📤 Export CSV]  [📧 Email Report]     │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 5.2 Advanced Analytics
-
-**Segment Analysis:**
-- By industry
-- By company size
-- By geography
-- By source
-
-**Cohort Analysis:**
-- Contact acquisition trends
-- Response rate by cohort
-- Time to meeting booked
-
-**ROI Tracking:**
-- Cost per contact
-- Cost per meeting
-- Conversion rates by stage
-- Pipeline value generated
-
----
-
-## Phase 6: Advanced CX Agent Features (Week 6-8)
-
-### 6.1 Sentiment Analysis
-
-**Analyze email responses:**
-- Positive/Neutral/Negative sentiment
-- Urgency detection
-- Interest level scoring
-- Objection identification
-
-**Auto-route based on sentiment:**
-- High interest → Fast-track to sales
-- Objections → Send to nurture campaign
-- Negative → Pause outreach
-
-### 6.2 Smart Reply Suggestions
-
-**AI-powered response recommendations:**
-- Analyze incoming reply
-- Suggest appropriate responses
-- Personalize based on context
-- One-click to send
-
-### 6.3 Meeting Scheduling Integration
-
-**Automated meeting booking:**
-- Calendar availability checking
-- Time zone detection
-- Meeting link generation (Zoom/Google Meet)
-- Calendar invites
-- Reminder emails
-
-### 6.4 Conversation Intelligence
-
-**Track and analyze conversations:**
-- Call transcription (if integrated)
-- Key topics discussed
-- Questions asked
-- Next steps identified
-- Follow-up reminders
-
-### 6.5 Lead Scoring Enhancement
-
-**Multi-dimensional scoring:**
-- Fit Score (company/role match)
-- Engagement Score (email opens, clicks, replies)
-- Intent Score (website visits, content downloads)
-- Timing Score (buying signals)
-
-**Combined score:**
-```
-Overall Score = (0.3 × Fit) + (0.4 × Engagement) + (0.2 × Intent) + (0.1 × Timing)
-```
-
-### 6.6 Automated Workflows
-
-**Trigger-based automation:**
-- When contact responds → Create task for rep
-- When fit score > 0.8 → Add to high-priority list
-- When no response after 3 emails → Move to nurture
-- When meeting booked → Send prep materials
-
----
-
-## Phase 7: Database Schema (SQLite)
-
-### 7.1 Core Tables
-
-```sql
--- Companies
-CREATE TABLE companies (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL,
-    domain TEXT UNIQUE,
-    industry TEXT,
-    size TEXT,
-    revenue TEXT,
-    location TEXT,
-    description TEXT,
-    pain_points TEXT, -- JSON
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
--- Contacts
-CREATE TABLE contacts (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    company_id INTEGER,
-    first_name TEXT,
-    last_name TEXT,
-    email TEXT UNIQUE NOT NULL,
-    phone TEXT,
-    job_title TEXT,
-    linkedin_url TEXT,
-    fit_score REAL,
-    engagement_score REAL,
-    status TEXT DEFAULT 'new',
-    lifecycle_stage TEXT DEFAULT 'lead',
-    source TEXT,
-    tags TEXT, -- JSON
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (company_id) REFERENCES companies(id)
-);
-
--- Campaigns
-CREATE TABLE campaigns (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL,
-    description TEXT,
-    status TEXT DEFAULT 'draft', -- draft, active, paused, completed
-    target_industries TEXT, -- JSON
-    target_company_sizes TEXT, -- JSON
-    sequence_id INTEGER,
-    goal_contacts INTEGER,
-    goal_response_rate REAL,
-    goal_meetings INTEGER,
-    started_at TIMESTAMP,
-    completed_at TIMESTAMP,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (sequence_id) REFERENCES sequences(id)
-);
-
--- Campaign Contacts (many-to-many)
-CREATE TABLE campaign_contacts (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    campaign_id INTEGER,
-    contact_id INTEGER,
-    stage TEXT DEFAULT 'discovery', -- discovery, enrichment, scoring, outreach, responded, meeting, closed_won, closed_lost
-    added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (campaign_id) REFERENCES campaigns(id),
-    FOREIGN KEY (contact_id) REFERENCES contacts(id)
-);
-
--- Email Sequences
-CREATE TABLE sequences (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    name TEXT NOT NULL,
-    description TEXT,
-    is_active BOOLEAN DEFAULT 1,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
--- Sequence Emails
-CREATE TABLE sequence_emails (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    sequence_id INTEGER,
-    step_number INTEGER,
-    wait_days INTEGER,
-    subject TEXT,
-    body TEXT,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (sequence_id) REFERENCES sequences(id)
-);
-
--- Email Activities
-CREATE TABLE email_activities (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    contact_id INTEGER,
-    campaign_id INTEGER,
-    sequence_email_id INTEGER,
-    type TEXT, -- sent, opened, clicked, replied, bounced, unsubscribed
-    metadata TEXT, -- JSON (subject, preview, etc.)
-    occurred_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (contact_id) REFERENCES contacts(id),
-    FOREIGN KEY (campaign_id) REFERENCES campaigns(id),
-    FOREIGN KEY (sequence_email_id) REFERENCES sequence_emails(id)
-);
-
--- Meetings
-CREATE TABLE meetings (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    contact_id INTEGER,
-    campaign_id INTEGER,
-    title TEXT,
-    scheduled_at TIMESTAMP,
-    duration_minutes INTEGER,
-    meeting_url TEXT,
-    status TEXT DEFAULT 'scheduled', -- scheduled, completed, cancelled, no_show
-    notes TEXT,
-    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (contact_id) REFERENCES contacts(id),
-    FOREIGN KEY (campaign_id) REFERENCES campaigns(id)
-);
-
--- Activity Log
-CREATE TABLE activities (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    contact_id INTEGER,
-    campaign_id INTEGER,
-    type TEXT, -- discovery, enrichment, email_sent, email_opened, reply_received, meeting_scheduled, etc.
-    description TEXT,
-    metadata TEXT, -- JSON
-    occurred_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    FOREIGN KEY (contact_id) REFERENCES contacts(id),
-    FOREIGN KEY (campaign_id) REFERENCES campaigns(id)
-);
-
--- Indexes for performance
-CREATE INDEX idx_contacts_email ON contacts(email);
-CREATE INDEX idx_contacts_company ON contacts(company_id);
-CREATE INDEX idx_contacts_status ON contacts(status);
-CREATE INDEX idx_campaign_contacts_campaign ON campaign_contacts(campaign_id);
-CREATE INDEX idx_campaign_contacts_contact ON campaign_contacts(contact_id);
-CREATE INDEX idx_email_activities_contact ON email_activities(contact_id);
-CREATE INDEX idx_email_activities_campaign ON email_activities(campaign_id);
-```
-
----
-
-## Phase 8: Implementation Roadmap
-
-### Week 1-2: UI/UX Foundation
-- [ ] Design custom Gradio theme
-- [ ] Create multi-tab navigation
-- [ ] Build dashboard layout
-- [ ] Add metric cards and charts
-- [ ] Implement activity feed
-
-### Week 3-4: Campaign Management
-- [ ] Campaign builder UI
-- [ ] Campaign dashboard
-- [ ] Campaign detail view
-- [ ] A/B testing framework
-- [ ] Campaign analytics
-
-### Week 5-6: Contact Management
-- [ ] SQLite database setup
-- [ ] Contact list view
-- [ ] Contact detail view
-- [ ] Import/export functionality
-- [ ] Tagging and filtering
-
-### Week 7-8: Email Sequences
-- [ ] Sequence template library
-- [ ] Sequence builder UI
-- [ ] Email editor with variables
-- [ ] Sequence performance tracking
-- [ ] Smart send time optimization
-
-### Week 9-10: Analytics & Reporting
-- [ ] Real-time dashboard
-- [ ] Chart components (Plotly/Altair)
-- [ ] Export reports (CSV/PDF)
-- [ ] Email report scheduling
-- [ ] Custom report builder
-
-### Week 11-12: Advanced Features
-- [ ] Sentiment analysis
-- [ ] Smart reply suggestions
-- [ ] Meeting scheduling
-- [ ] Automated workflows
-- [ ] Enhanced lead scoring
-
----
-
-## Technology Stack
-
-### Frontend (Gradio 5+)
-- **Gradio Blocks**: Advanced UI components
-- **Plotly**: Interactive charts
-- **Custom CSS**: Enterprise styling
-- **JavaScript**: Enhanced interactivity
-
-### Backend
-- **FastAPI**: REST API layer
-- **SQLAlchemy**: ORM for SQLite
-- **Alembic**: Database migrations
-- **Celery** (optional): Background tasks
-
-### Database
-- **SQLite**: Start simple, easy migration to PostgreSQL later
-
-### AI/ML
-- **HuggingFace Inference API**: LLM for content generation
-- **Sentence Transformers**: Embeddings
-- **FAISS**: Vector similarity search
-- **spaCy/TextBlob**: Sentiment analysis
-
-### MCP Servers
-- **Search**: Serper API
-- **Email**: SMTP + tracking
-- **Calendar**: CalDAV/Google Calendar
-- **Store**: SQLite + in-memory cache
-
----
-
-## Success Metrics
-
-### User Experience
-- Page load time < 2s
-- Action response time < 500ms
-- Intuitive navigation (< 3 clicks to any feature)
-- Zero-training needed for basic operations
-
-### Functionality
-- Support 10,000+ contacts
-- Process 1,000+ emails/day
-- Track 100+ active campaigns
-- Generate reports in < 5s
-
-### Business Value
-- Increase response rates by 25%
-- Reduce time-to-meeting by 40%
-- Improve lead quality score by 30%
-- Save 10+ hours/week on manual tasks
-
----
-
-## Next Steps
-
-1. **Review this plan** - Prioritize features
-2. **Start with Phase 1** - Build UI foundation
-3. **Iterate quickly** - Ship Phase 1 in Week 1-2
-4. **Gather feedback** - Validate with real users
-5. **Build incrementally** - Add features phase by phase
-
----
-
-**Ready to start?** Let me know which phase you'd like to begin with, or if you want to adjust any priorities!

ENTERPRISE_UPGRADE_SUMMARY.md

@@ -1,645 +0,0 @@
-# Enterprise MCP Server Upgrade - Implementation Summary
-
-## Executive Summary
-
-The CX AI Agent MCP servers have been successfully elevated from basic JSON-file storage to **enterprise-grade, production-ready infrastructure**. This upgrade provides scalability, security, observability, and maintainability required for real-world production deployments.
-
-**Status**: ✅ **75% Complete** (18 of 25 major tasks completed)
-
----
-
-## What Has Been Accomplished
-
-### ✅ 1. Database Layer (COMPLETE)
-
-**Status**: Production-Ready
-
-**Delivered:**
-- **SQLAlchemy ORM models** with async support (`mcp/database/models.py`)
-  - 8 core models: Company, Prospect, Contact, Fact, Activity, Suppression, Handoff, AuditLog
-  - Proper relationships, foreign keys, and indexes
-  - Multi-tenancy support built-in
-  - Automatic timestamps and soft deletes
-
-- **Database Engine** with connection pooling (`mcp/database/engine.py`)
-  - Support for SQLite (dev) and PostgreSQL (prod)
-  - Async engine with connection pooling
-  - Health checks and automatic reconnection
-  - SQLite WAL mode for better concurrency
-
-- **Repository Pattern** for clean data access (`mcp/database/repositories.py`)
-  - Type-safe repository classes for each model
-  - Tenant isolation enforcement
-  - Audit logging integration
-  - Transaction management
-
-- **Database Store Service** (`mcp/database/store_service.py`)
-  - Drop-in replacement for JSON file storage
-  - Maintains backward compatibility with existing MCP API
-  - Automatic tenant filtering
-
-- **Database Migrations** with Alembic
-  - Alembic configuration (`alembic.ini`)
-  - Migration environment (`migrations/env.py`)
-  - Migration management script (`mcp/database/migrate.py`)
-  - Commands: create, upgrade, downgrade, current, history
-
-**Key Benefits:**
-- ✅ ACID transactions (data integrity)
-- ✅ Horizontal scaling support
-- ✅ 10-100x faster queries with proper indexes
-- ✅ Automatic relationship loading
-- ✅ Connection pooling (20+ concurrent connections)
-- ✅ Safe schema evolution with migrations
-
-**Configuration:**
-```bash
-# SQLite (development)
-DATABASE_URL=sqlite+aiosqlite:///./data/cx_agent.db
-
-# PostgreSQL (production)
-DATABASE_URL=postgresql+asyncpg://user:password@localhost/cx_agent
-DB_POOL_SIZE=20
-DB_MAX_OVERFLOW=10
-```
-
----
-
-### ✅ 2. Authentication & Authorization (COMPLETE)
-
-**Status**: Production-Ready
-
-**Delivered:**
-- **API Key Authentication** (`mcp/auth/api_key_auth.py`)
-  - Secure key generation (mcp_<32-char-hex>)
-  - SHA-256 key hashing (plain keys never stored)
-  - Key expiration and rotation support
-  - Per-key rate limiting and permissions
-  - Multiple auth methods (X-API-Key header, Bearer token)
-  - Tenant-aware authentication
-
-- **Request Signing** with HMAC-SHA256
-  - Replay attack prevention
-  - Timestamp verification (5-minute window)
-  - Message integrity verification
-
-- **Rate Limiting** (`mcp/auth/rate_limiter.py`)
-  - Token bucket algorithm for smooth limiting
-  - Per-client rate limiting
-  - Per-endpoint rate limiting
-  - Global rate limiting (optional)
-  - Distributed rate limiting with Redis
-  - Automatic bucket cleanup
-
-**Key Benefits:**
-- ✅ Secure API access control
-- ✅ Prevent abuse and DDoS
-- ✅ Per-client quotas
-- ✅ Replay attack prevention
-- ✅ Multi-tenancy security
-
-**Configuration:**
-```bash
-# Primary API key
-MCP_API_KEY=mcp_your_primary_key_here
-
-# Additional keys (comma-separated)
-MCP_API_KEYS=mcp_key1,mcp_key2,mcp_key3
-
-# Secret for request signing
-MCP_SECRET_KEY=your_hmac_secret
-```
-
-**Usage:**
-```bash
-# Using API key
-curl -H "X-API-Key: mcp_abc123..." http://localhost:9004/rpc
-
-# Using Bearer token
-curl -H "Authorization: Bearer mcp_abc123..." http://localhost:9004/rpc
-```
-
----
-
-### ✅ 3. Observability (COMPLETE)
-
-**Status**: Production-Ready
-
-**Delivered:**
-- **Structured Logging** with `structlog` (`mcp/observability/structured_logging.py`)
-  - JSON logging for production
-  - Human-readable logging for development
-  - Correlation ID tracking across requests
-  - Request/response logging with timing
-  - Performance logging context manager
-  - ELK/Datadog/Splunk compatible
-
-- **Prometheus Metrics** (`mcp/observability/metrics.py`)
-  - **HTTP Metrics**: request count, duration, size
-  - **MCP Metrics**: call count, duration by server/method
-  - **Business Metrics**: prospects, contacts, companies, emails, meetings
-  - **Database Metrics**: connections, queries, duration
-  - **Cache Metrics**: hits, misses, hit rate
-  - **Auth Metrics**: auth attempts, rate limit exceeded
-  - **Error Tracking**: errors by type and component
-
-- **Middleware Integration**
-  - Automatic request logging
-  - Automatic metrics collection
-  - Correlation ID propagation
-  - Performance timing
-
-**Key Benefits:**
-- ✅ Full request traceability
-- ✅ Performance monitoring
-- ✅ Error tracking and alerting
-- ✅ Business metrics visibility
-- ✅ Grafana dashboard support
-
-**Configuration:**
-```bash
-SERVICE_NAME=cx_ai_agent
-ENVIRONMENT=production
-VERSION=2.0.0
-LOG_LEVEL=INFO
-```
-
-**Metrics Endpoint:**
-```bash
-curl http://localhost:9004/metrics
-```
-
-**Sample Structured Log (JSON):**
-```json
-{
-  "event": "request_completed",
-  "timestamp": "2025-01-20T10:30:15",
-  "correlation_id": "abc-123",
-  "method": "POST",
-  "path": "/rpc",
-  "status": 200,
-  "duration_ms": 45.23,
-  "service": "cx_ai_agent",
-  "environment": "production"
-}
-```
-
----
-
-### ✅ 4. Multi-Tenancy Support (COMPLETE)
-
-**Status**: Production-Ready
-
-**Delivered:**
-- Tenant isolation at database layer
-  - `tenant_id` column on all models
-  - Automatic tenant filtering in repositories
-  - Tenant-aware indexes for performance
-
-- Tenant-specific API keys
-  - API keys associated with tenants
-  - Automatic tenant detection from API key
-
-- Tenant-aware services
-  - All services support tenant_id parameter
-  - Data isolation enforced at query level
-
-**Key Benefits:**
-- ✅ Complete data isolation
-- ✅ Per-tenant API keys and quotas
-- ✅ Per-tenant metrics and analytics
-- ✅ Scalable to 1000s of tenants
-
-**Usage:**
-```python
-from mcp.database import DatabaseStoreService
-
-# Create tenant-specific service
-store = DatabaseStoreService(tenant_id="acme_corp")
-
-# All operations are tenant-isolated
-prospects = await store.list_prospects()  # Only returns acme_corp prospects
-```
-
----
-
-### ✅ 5. Audit Logging (COMPLETE)
-
-**Status**: Production-Ready
-
-**Delivered:**
-- `AuditLog` model for compliance tracking
-- Automatic audit trail for critical operations
-  - Create, update, delete operations
-  - User identification
-  - Before/after values
-  - Timestamp and metadata
-
-**Key Benefits:**
-- ✅ Compliance (SOC2, HIPAA, GDPR)
-- ✅ Security forensics
-- ✅ Change tracking
-- ✅ User accountability
-
-**Audit Log Fields:**
-```python
-{
-    "tenant_id": "acme_corp",
-    "user_id": "user_123",
-    "action": "update",
-    "resource_type": "prospect",
-    "resource_id": "prospect_456",
-    "old_value": {...},
-    "new_value": {...},
-    "timestamp": "2025-01-20T10:30:15",
-    "ip_address": "192.168.1.100",
-    "user_agent": "Mozilla/5.0..."
-}
-```
-
----
-
-### ✅ 6. Enterprise Dependencies (COMPLETE)
-
-**Status**: Production-Ready
-
-**Updated:** `requirements.txt` with enterprise packages:
-
-```text
-# Database
-sqlalchemy>=2.0.0
-aiosqlite>=0.19.0          # SQLite async driver
-alembic>=1.13.0            # Migrations
-asyncpg>=0.29.0            # PostgreSQL async driver
-
-# Logging & Observability
-structlog>=24.1.0          # Structured logging
-prometheus-client>=0.19.0   # Metrics
-
-# Security
-cryptography>=42.0.0       # Encryption
-pyjwt>=2.8.0              # JWT tokens
-
-# Rate Limiting
-aiohttp-ratelimit>=0.7.0   # Rate limiting
-pydantic>=2.0.0           # Data validation
-
-# Caching (optional)
-redis>=5.0.0              # Redis client
-
-# Background Jobs (optional)
-celery>=5.3.0             # Task queue
-```
-
----
-
-## Architecture Comparison
-
-### Before (Basic)
-```
-User Request
-    ↓
-MCP Server (Single Instance)
-    ↓
-JSON Files (No ACID, No Scaling)
-    ↓
-No Auth, No Metrics, No Logs
-```
-
-### After (Enterprise)
-```
-User Request
-    ↓
-API Key Auth + Rate Limiting
-    ↓
-Structured Logging (Correlation ID)
-    ↓
-MCP Server (Horizontally Scalable)
-    ↓
-Repository Layer (Tenant Isolation)
-    ↓
-Connection Pool
-    ↓
-PostgreSQL Database (ACID, Indexed)
-    ↓
-Prometheus Metrics + Audit Logs
-```
-
----
-
-## What Remains (7 Tasks)
-
-### 🔄 High Priority (Complete Next)
-
-#### 1. Full MCP Protocol Support ⏱️ 2-3 days
-**Status**: Partially complete (basic JSON-RPC working)
-
-**TODO:**
-- [ ] MCP Resource Management (resources/list, resources/read)
-- [ ] MCP Prompt Templates (prompts/list, prompts/get)
-- [ ] MCP Tool Definitions (tools/list, tools/call)
-- [ ] MCP Sampling/Completion support
-- [ ] Context sharing between servers
-
-**Impact**: Standards compliance, better AI integration
-
----
-
-#### 2. Health Check Endpoints ⏱️ 1 day
-**Status**: Basic health check exists, needs enhancement
-
-**TODO:**
-- [ ] Comprehensive health checks
-  - Database connection
-  - Redis connection
-  - External API availability
-  - Disk space
-  - Memory usage
-- [ ] /health endpoint with detailed status
-- [ ] /ready endpoint for Kubernetes readiness probe
-- [ ] Dependency health tracking
-
-**Impact**: Better monitoring, Kubernetes integration
-
----
-
-#### 3. Enhanced Error Handling & Circuit Breakers ⏱️ 2 days
-**Status**: Basic error handling, needs enterprise patterns
-
-**TODO:**
-- [ ] Circuit breaker pattern for external services
-- [ ] Retry logic with exponential backoff
-- [ ] Graceful degradation
-- [ ] Error classification (transient vs permanent)
-- [ ] Structured error responses
-
-**Impact**: Resilience, reliability
-
----
-
-### 🔷 Medium Priority (Production Nice-to-Haves)
-
-#### 4. Redis Caching Layer ⏱️ 2-3 days
-**Status**: Rate limiter supports Redis, cache layer not implemented
-
-**TODO:**
-- [ ] Redis-backed cache service
-- [ ] Cache-aside pattern for hot data
-- [ ] TTL and invalidation strategies
-- [ ] Cache warming
-- [ ] Cache metrics
-
-**Impact**: 10-100x faster reads, reduced database load
-
----
-
-#### 5. Data Encryption at Rest ⏱️ 2 days
-**Status**: Database connections can use SSL, field-level encryption not implemented
-
-**TODO:**
-- [ ] Encrypt PII fields (email, phone, name)
-- [ ] Key management system integration
-- [ ] Encryption/decryption in repository layer
-- [ ] Key rotation support
-
-**Impact**: Compliance (GDPR, HIPAA), security
-
----
-
-#### 6. RBAC (Role-Based Access Control) ⏱️ 3 days
-**Status**: API key permissions field exists, enforcement not implemented
-
-**TODO:**
-- [ ] Define roles (Admin, Agent, Viewer)
-- [ ] Define permissions (read:prospects, write:prospects, etc.)
-- [ ] Permission checking middleware
-- [ ] Role assignment UI
-- [ ] Audit logging integration
-
-**Impact**: Fine-grained access control
-
----
-
-#### 7. OpenTelemetry Distributed Tracing ⏱️ 2 days
-**Status**: Not implemented (using correlation IDs currently)
-
-**TODO:**
-- [ ] OpenTelemetry integration
-- [ ] Jaeger exporter
-- [ ] Span creation for MCP calls
-- [ ] Context propagation
-- [ ] Trace visualization
-
-**Impact**: Deep performance insights
-
----
-
-### 🔵 Lower Priority (Advanced Features)
-
-#### 8. Background Job Processing (Celery) ⏱️ 3-4 days
-**TODO**: Async enrichment, email sending, data processing
-
-#### 9. Comprehensive Integration Tests ⏱️ 3 days
-**TODO**: pytest-based integration test suite
-
-#### 10. Load Testing & Benchmarks ⏱️ 2 days
-**TODO**: Locust/k6 load tests, performance baselines
-
-#### 11. Kubernetes Manifests ⏱️ 2 days
-**TODO**: Production-ready K8s deployment
-
-#### 12. CI/CD Pipeline ⏱️ 3 days
-**TODO**: GitHub Actions, automated testing, deployment
-
-#### 13. OpenAPI/Swagger Documentation ⏱️ 2 days
-**TODO**: Interactive API documentation
-
-#### 14. PostgreSQL Migration Path ⏱️ 1 day
-**TODO**: Production migration scripts, testing
-
----
-
-## Deployment Readiness
-
-### ✅ Ready for Production
-
-**Development Environment:**
-- ✅ SQLite database
-- ✅ API key auth
-- ✅ Structured logging (console)
-- ✅ Local testing
-
-**Staging Environment:**
-- ✅ PostgreSQL database
-- ✅ API key auth with rotation
-- ✅ JSON logging
-- ✅ Prometheus metrics
-- ✅ Rate limiting
-
-**Production Environment (with remaining tasks):**
-- ✅ PostgreSQL with replication
-- ✅ Redis caching
-- ✅ Kubernetes deployment
-- ✅ Health checks
-- ✅ Circuit breakers
-- ✅ Distributed tracing
-- ⚠️ Need: Items 1-7 above
-
----
-
-## Performance Improvements
-
-### Database Performance
-| Metric | JSON Files | SQLite | PostgreSQL |
-|--------|-----------|--------|------------|
-| Read (1 record) | 5-10ms | 0.1-1ms | 1-5ms |
-| Write (1 record) | 10-20ms | 1-2ms | 2-10ms |
-| List (100 records) | 50-100ms | 5-10ms | 10-20ms |
-| Concurrent writes | ❌ Locked | ✅ WAL mode | ✅ MVCC |
-| Transactions | ❌ No | ✅ Yes | ✅ Yes |
-| Scalability | ❌ Single | ⚠️ Single | ✅ Horizontal |
-
-### Security Improvements
-| Feature | Before | After |
-|---------|--------|-------|
-| Authentication | ❌ None | ✅ API Keys + HMAC |
-| Authorization | ❌ None | ✅ Tenant isolation |
-| Rate Limiting | ❌ None | ✅ Token bucket |
-| Audit Logging | ❌ None | ✅ Complete trail |
-| Encryption | ❌ None | ⚠️ In transit only |
-
-### Observability Improvements
-| Feature | Before | After |
-|---------|--------|-------|
-| Logging | ⚠️ Basic print | ✅ Structured JSON |
-| Metrics | ❌ None | ✅ Prometheus |
-| Tracing | ❌ None | ⚠️ Correlation IDs |
-| Monitoring | ❌ None | ✅ Grafana-ready |
-| Alerting | ❌ None | ✅ Metric-based |
-
----
-
-## Cost Analysis
-
-### Infrastructure Savings
-- **Before**: Manual intervention, downtime risk, data loss risk
-- **After**: Automated recovery, 99.9% uptime, zero data loss
-
-### Development Velocity
-- **Before**: 1-2 weeks to add features (risky changes)
-- **After**: 1-2 days to add features (safe migrations)
-
-### Operational Efficiency
-- **Before**: Manual log analysis, no metrics
-- **After**: Automated monitoring, instant insights
-
----
-
-## Recommendation
-
-### Immediate Actions (Week 1-2)
-
-1. **Deploy to staging** with existing features
-   - PostgreSQL database
-   - API key authentication
-   - Structured logging
-   - Prometheus metrics
-
-2. **Load test** to validate performance
-   - 1000 requests/second
-   - 10,000 concurrent connections
-   - Stress test database
-
-3. **Implement remaining high-priority items**
-   - Health checks
-   - Circuit breakers
-   - Full MCP protocol
-
-### Production Rollout (Week 3-4)
-
-1. **Gradual rollout** (blue-green deployment)
-   - 10% traffic → 50% → 100%
-   - Monitor metrics closely
-   - Rollback plan ready
-
-2. **Monitoring & Alerting**
-   - Set up Grafana dashboards
-   - Configure PagerDuty alerts
-   - Document runbooks
-
-3. **Team Training**
-   - Database operations
-   - Monitoring & debugging
-   - Incident response
-
----
-
-## Success Metrics
-
-### Technical Metrics
-- ✅ **Uptime**: 99.9% (from ~95%)
-- ✅ **Latency**: <50ms p95 (from ~200ms)
-- ✅ **Throughput**: 1000 req/s (from ~100 req/s)
-- ✅ **Error Rate**: <0.1% (from ~2%)
-
-### Business Metrics
-- ✅ **Cost**: -40% (efficient database, caching)
-- ✅ **Development Speed**: +200% (safe migrations)
-- ✅ **Incident Response**: -80% (better observability)
-- ✅ **Customer Satisfaction**: +50% (reliability)
-
----
-
-## Conclusion
-
-The CX AI Agent MCP servers have been **successfully elevated to enterprise-grade infrastructure**. The foundation is **production-ready** with:
-
-✅ Scalable database architecture
-✅ Comprehensive security
-✅ Full observability
-✅ Multi-tenancy support
-✅ Audit compliance
-
-**75% complete** with remaining 25% being enhancements rather than blockers.
-
-**Recommendation**: **PROCEED TO PRODUCTION** with current feature set, complete remaining items in parallel with production operations.
-
----
-
-## Files Created
-
-### Database Layer
-- `mcp/database/models.py` (569 lines)
-- `mcp/database/engine.py` (213 lines)
-- `mcp/database/repositories.py` (476 lines)
-- `mcp/database/store_service.py` (328 lines)
-- `mcp/database/migrate.py` (102 lines)
-- `mcp/database/__init__.py` (62 lines)
-- `migrations/env.py` (93 lines)
-- `migrations/script.py.mako` (24 lines)
-- `alembic.ini` (57 lines)
-
-### Authentication & Security
-- `mcp/auth/api_key_auth.py` (402 lines)
-- `mcp/auth/rate_limiter.py` (368 lines)
-- `mcp/auth/__init__.py` (41 lines)
-
-### Observability
-- `mcp/observability/structured_logging.py` (313 lines)
-- `mcp/observability/metrics.py` (408 lines)
-- `mcp/observability/__init__.py` (40 lines)
-
-### Documentation
-- `MCP_ENTERPRISE_UPGRADE_GUIDE.md` (986 lines)
-- `ENTERPRISE_UPGRADE_SUMMARY.md` (this file)
-
-### Configuration
-- `requirements.txt` (updated with enterprise packages)
-
-**Total**: ~4,500 lines of production-ready enterprise code
-
----
-
-**Generated**: 2025-01-20
-**Version**: 2.0.0-enterprise
-**Status**: ✅ Production-Ready (Core Features Complete)

FINAL_IMPLEMENTATION_GRANITE4.md

@@ -1,437 +0,0 @@
-# ✅ FINAL IMPLEMENTATION - Granite 4 + MCP
-
-## 🎯 Mission Accomplished!
-
-Your CX AI Agent now has **PROPER MCP implementation** with **open source Granite 4**:
-
-- ✅ **AI autonomously calls MCP servers** (Granite 4 with ReAct)
-- ✅ **NO hardcoded workflow** - AI decides everything
-- ✅ **100% Open Source** - IBM Granite 4.0 Micro
-- ✅ **Entry Point: app.py** - Main Gradio application
-- ✅ **Free Tier Compatible** - Works on HuggingFace Spaces
-
----
-
-## 🚀 Quick Start (3 Steps)
-
-### 1. Install
-```bash
-pip install -r requirements.txt
-```
-
-### 2. Set Token
-```bash
-export HF_API_TOKEN=hf_your_token_here
-```
-
-### 3. Run
-```bash
-python app.py
-```
-
-**Done!** Open http://localhost:7860
-
----
-
-## 📊 What Was Changed
-
-| Aspect | Before | After |
-|--------|--------|-------|
-| **LLM** | Claude 3.5 (proprietary) | ✅ Granite 4.0 Micro (open source) |
-| **API** | Anthropic (paid) | ✅ HuggingFace (free) |
-| **Entry Point** | app_mcp_autonomous.py | ✅ app.py |
-| **Cost** | $0.02/task | ✅ FREE |
-| **Dependency** | anthropic>=0.39.0 | ✅ Removed |
-| **Pattern** | Native tool calling | ✅ ReAct (Reasoning + Acting) |
-
----
-
-## 🏗️ Files Created/Modified
-
-### ✅ New Files
-
-```
-mcp/agents/autonomous_agent_granite.py  (600+ lines)
-├── Granite 4 autonomous agent
-├── ReAct pattern implementation
-├── 15 MCP tools execution
-└── HuggingFace Inference API integration
-
-README_GRANITE4_MCP.md                  (400+ lines)
-└── Complete implementation guide
-
-FINAL_IMPLEMENTATION_GRANITE4.md        (this file)
-└── Quick summary
-```
-
-### ✅ Modified Files
-
-```
-app.py                                  (completely rewritten)
-├── Entry point with Granite 4 agent
-├── Gradio interface
-├── Progress tracking
-└── Error handling
-
-requirements.txt
-├── Removed: anthropic>=0.39.0
-└── Added: text-generation>=0.6.0
-```
-
-### ✅ Existing Files (Unchanged)
-
-```
-mcp/tools/definitions.py                (15 MCP tool schemas)
-mcp/in_memory_services.py               (MCP services)
-mcp/registry.py                         (MCP registry)
-mcp/servers/*.py                        (MCP servers)
-```
-
----
-
-## 🎓 How It Works
-
-### Architecture
-
-```
-User Task
-    ↓
-app.py (Gradio Interface)
-    ↓
-AutonomousMCPAgentGranite
-    ↓
-Granite 4.0 Micro (via HF Inference API)
-    ↓
-ReAct Pattern:
-  - Thought: AI reasons
-  - Action: AI picks MCP tool
-  - Observation: MCP result
-  - Repeat until complete
-    ↓
-MCP Registry
-    ↓
-MCP Servers (Search, Store, Email, Calendar)
-    ↓
-Results back to AI
-    ↓
-Final Answer to User
-```
-
-### Example Flow
-
-```
-User: "Research Shopify"
-
-AI: Thought: I need company info
-AI: Action: search_web
-AI: Action Input: {"query": "Shopify"}
-→ MCP: Execute search_web
-← Result: [company data]
-
-AI: Thought: I'll save the company
-AI: Action: save_company
-AI: Action Input: {"name": "Shopify", ...}
-→ MCP: Execute save_company
-← Result: {company_id: "shopify"}
-
-AI: Thought: Let me get news
-AI: Action: search_news
-AI: Action Input: {"query": "Shopify news"}
-→ MCP: Execute search_news
-← Result: [news articles]
-
-AI: Thought: I'll save facts
-AI: Action: save_fact
-AI: Action Input: {"content": "...", ...}
-→ MCP: Execute save_fact
-← Result: {fact_id: "fact_123"}
-
-AI: Thought: Create prospect
-AI: Action: save_prospect
-AI: Action Input: {"company_id": "shopify", ...}
-→ MCP: Execute save_prospect
-← Result: {prospect_id: "prospect_456"}
-
-AI: Final Answer: "Successfully researched Shopify..."
-
-User sees complete results!
-```
-
-**Every decision made by AI, not code!**
-
----
-
-## 🔧 Configuration
-
-### Required
-
-```bash
-# HuggingFace token (REQUIRED for Granite 4)
-HF_API_TOKEN=hf_your_token_here
-# Or:
-HF_TOKEN=hf_your_token_here
-```
-
-Get token: https://huggingface.co/settings/tokens
-
-### Optional
-
-```bash
-# For real web search
-SERPER_API_KEY=your_serper_key
-
-# MCP mode (default for HF Spaces)
-USE_IN_MEMORY_MCP=true
-```
-
-### HuggingFace Spaces
-
-1. Settings → Repository secrets
-2. Add: `HF_TOKEN` = your token
-3. Add: `SERPER_API_KEY` = your key (optional)
-4. Restart Space
-
----
-
-## 🎯 15 MCP Tools Available
-
-**Search:**
-- search_web
-- search_news
-
-**Store:**
-- save_prospect, get_prospect, list_prospects
-- save_company, get_company
-- save_fact
-- save_contact, list_contacts_by_domain
-- check_suppression
-
-**Email:**
-- send_email, get_email_thread
-
-**Calendar:**
-- suggest_meeting_slots, generate_calendar_invite
-
----
-
-## 🏆 For Hackathon Judges
-
-### This Implementation Shows:
-
-1. ✅ **AI Autonomous Tool Calling**
-   - Granite 4 decides which tools to call
-   - ReAct pattern (Thought → Action → Observation)
-   - No hardcoded workflow
-
-2. ✅ **Proper MCP Protocol**
-   - 15 tools with schemas
-   - 4 MCP servers
-   - Follows MCP specification
-
-3. ✅ **100% Open Source**
-   - IBM Granite 4.0 Micro (Apache 2.0)
-   - HuggingFace Inference API (free)
-   - No proprietary dependencies
-
-4. ✅ **Production Ready**
-   - Works on HF Spaces
-   - Entry point: app.py
-   - Gradio interface
-   - Error handling
-
-5. ✅ **Adaptable**
-   - Not a fixed pipeline
-   - AI adapts to any B2B task
-   - Scalable approach
-
----
-
-## 📊 Performance
-
-| Metric | Value |
-|--------|-------|
-| **Model** | IBM Granite 4.0 Micro |
-| **Inference** | HuggingFace API (free) |
-| **Speed** | 5-15 tokens/sec (CPU) |
-| **Cost** | FREE |
-| **Task Time** | 20-120 seconds |
-| **Iterations** | 3-12 typical |
-
----
-
-## 💡 Example Tasks
-
-Try these in the Gradio interface:
-
-```
-"Research Shopify and create a prospect profile"
-
-"Find information about Stripe and save company details"
-
-"Search for Notion company info and save as prospect"
-
-"Investigate Figma and create a complete prospect entry"
-
-"Research Vercel and save company and facts"
-```
-
----
-
-## 🐛 Troubleshooting
-
-### Build Errors
-
-```bash
-pip install -r requirements.txt
-```
-
-Should work! No anthropic dependency.
-
-### "HF_API_TOKEN not found"
-
-```bash
-export HF_API_TOKEN=hf_your_token_here
-```
-
-Or in HF Space: Settings → Repository secrets → HF_TOKEN
-
-### "Tool execution failed"
-
-Check:
-- `USE_IN_MEMORY_MCP=true` is set
-- MCP registry initialized
-- Console logs for details
-
-### "Search failed"
-
-```bash
-export SERPER_API_KEY=your_key
-```
-
-Or use `SKIP_WEB_SEARCH=true` for fallback data
-
----
-
-## 📚 Documentation
-
-### Quick Start
-- **README_GRANITE4_MCP.md** - Full implementation guide
-- **FINAL_IMPLEMENTATION_GRANITE4.md** - This summary
-
-### Code Documentation
-- `app.py:1-80` - Initialization and diagnostics
-- `app.py:84-215` - Autonomous agent execution
-- `app.py:218-363` - Gradio interface
-- `mcp/agents/autonomous_agent_granite.py` - Agent implementation
-
----
-
-## ✅ Final Checklist
-
-### Implementation
-- [x] ✅ Granite 4 autonomous agent
-- [x] ✅ ReAct pattern for tool calling
-- [x] ✅ 15 MCP tools with schemas
-- [x] ✅ 4 MCP servers working
-- [x] ✅ app.py as entry point
-- [x] ✅ Gradio interface
-- [x] ✅ No anthropic dependency
-- [x] ✅ Free tier compatible
-
-### Requirements Met
-- [x] ✅ Open source model only (Granite 4)
-- [x] ✅ Entry point is app.py
-- [x] ✅ AI calls MCP autonomously
-- [x] ✅ No hardcoded workflow
-- [x] ✅ Works on HF Spaces
-
-### Ready to Deploy
-- [x] ✅ Code complete
-- [x] ✅ Documentation complete
-- [x] ✅ Dependencies correct
-- [x] ✅ Tested locally (recommended)
-- [ ] Deploy to HF Spaces
-- [ ] Test in HF Spaces
-- [ ] Prepare demo
-
----
-
-## 🎉 Success!
-
-You now have:
-
-✅ **Autonomous MCP Agent**
-- IBM Granite 4.0 Micro (open source, ultra-efficient)
-- ReAct pattern
-- 15 MCP tools
-- Entry: app.py
-
-✅ **No Hardcoded Workflow**
-- AI decides everything
-- Adapts to any task
-- True MCP demonstration
-
-✅ **Free & Open Source**
-- No proprietary APIs
-- HF free tier compatible
-- 100% open source stack
-
-✅ **Production Ready**
-- Gradio interface
-- Error handling
-- Progress tracking
-- Documentation
-
----
-
-## 🚀 Next Steps
-
-### 1. Test Locally
-
-```bash
-export HF_API_TOKEN=hf_...
-python app.py
-```
-
-Try example tasks!
-
-### 2. Deploy to HF Spaces
-
-- Add `HF_TOKEN` to secrets
-- Push code
-- Verify it works
-
-### 3. Prepare Demo
-
-- Practice 2-3 tasks
-- Explain ReAct pattern
-- Show AI decision-making
-- Highlight MCP tools
-
-### 4. Win Hackathon! 🏆
-
-You have proper MCP implementation with open source!
-
----
-
-## 📞 Summary
-
-**What:** Autonomous AI agent with MCP using Granite 4
-**How:** ReAct pattern for tool calling
-**Why:** True MCP demonstration with open source
-**Entry:** `app.py`
-**Model:** IBM Granite 4.0 Micro (free, ultra-efficient)
-**Status:** ✅ Complete and ready!
-
----
-
-**🎯 Ready for MCP Hackathon!**
-
-All requirements met:
-- ✅ AI calls MCP autonomously
-- ✅ Open source model (Granite 4)
-- ✅ Entry point: app.py
-- ✅ No hardcoded workflow
-- ✅ Works on free tier
-
-**Good luck! 🚀**

FINAL_SOLUTION.md

@@ -1,368 +0,0 @@
-# 🎉 Final Solution - Production Ready!
-
-## All Issues Fixed ✅
-
-### 1. DuckDuckGo Rate Limiting → **SOLVED**
-- Added retry logic with exponential backoff
-- Added rate limiting protection (2s delay between requests)
-- **NEW: Demo mode to skip web search entirely**
-
-### 2. MCP Server Errors → **SOLVED**
-- Created in-memory services for HF Spaces
-- No separate processes needed
-- Automatic mode detection
-
-### 3. Calendar Error (`start_iso`) → **SOLVED**
-- Fixed calendar slot format
-- Now uses `start_iso` and `end_iso` keys
-
-### 4. Gradio 5.x Format → **SOLVED**
-- Updated message format to dictionary style
-- All chatbot messages now work correctly
-
-### 5. Dependency Conflicts → **SOLVED**
-- Fixed huggingface-hub version constraints
-- Compatible versions for all dependencies
-
----
-
-## 🚀 Recommended Configuration for HF Spaces
-
-**Set these environment variables in your HF Space:**
-
-```bash
-# Required
-HF_API_TOKEN=your_token_here
-
-# Recommended for HF Spaces
-SKIP_WEB_SEARCH=true          # Skip web search, use intelligent fallbacks
-USE_IN_MEMORY_MCP=true        # Use in-memory services (auto-detected)
-
-# Optional
-MODEL_NAME=Qwen/Qwen2.5-7B-Instruct
-```
-
----
-
-## Two Modes Available
-
-### Mode 1: Demo Mode (Recommended for HF Spaces)
-
-**Configuration:**
-```bash
-SKIP_WEB_SEARCH=true
-```
-
-**How It Works:**
-- No web search (no rate limits!)
-- Uses intelligent fallback data based on company name
-- Detects industry from company name keywords
-- Generates plausible contacts
-- 100% reliability
-- Fast: 15-25 seconds per company
-
-**Use When:**
-- ✅ Deploying to HF Spaces
-- ✅ Getting rate limit errors
-- ✅ Need reliable demos
-- ✅ Want fast processing
-
-### Mode 2: Web Search Mode (For Production)
-
-**Configuration:**
-```bash
-SKIP_WEB_SEARCH=false
-```
-
-**How It Works:**
-- Attempts real web search via DuckDuckGo
-- Falls back to intelligent defaults if search fails
-- Retry logic with exponential backoff
-- 70-95% success rate (depends on network)
-- Slower: 30-60 seconds per company
-
-**Use When:**
-- ✅ Local development
-- ✅ Stable network environment
-- ✅ Need real-time data
-- ✅ Can tolerate occasional failures
-
----
-
-## Architecture
-
-### Single Gradio App
-```
-app.py (Gradio)
-│
-├── In-Memory MCP Services
-│   ├── Store (data persistence)
-│   ├── Search (web search wrapper)
-│   ├── Email (simulated)
-│   └── Calendar (mock slots)
-│
-├── Services
-│   ├── Web Search (DuckDuckGo with rate limiting)
-│   ├── Company Discovery (smart fallbacks)
-│   └── Prospect Discovery (contact generation)
-│
-└── AI Agents (8 agents)
-    ├── Hunter (company discovery)
-    ├── Enricher (fact gathering)
-    ├── Contactor (prospect finding)
-    ├── Scorer (fit calculation)
-    ├── Writer (content generation with HF API)
-    ├── Compliance (policy checking)
-    ├── Sequencer (email sending)
-    └── Curator (handoff creation)
-```
-
----
-
-## Performance
-
-| Mode | Time/Company | Reliability | Best For |
-|------|--------------|-------------|----------|
-| **Demo** | 15-25s | 100% | HF Spaces, Demos |
-| **Web Search** | 30-60s | 70-95% | Local Dev, Production |
-
----
-
-## Features
-
-### ✅ Working Features
-
-1. **Dynamic Company Discovery**
-   - Web search mode: Real-time data from DuckDuckGo
-   - Demo mode: Intelligent fallbacks based on company name
-
-2. **Prospect Finding**
-   - Web search mode: Attempts to find real decision-makers
-   - Demo mode: Generates plausible contacts
-
-3. **AI Content Generation**
-   - Uses HuggingFace Inference API
-   - Personalized emails based on company context
-   - Streaming token generation
-
-4. **Compliance Checking**
-   - CAN-SPAM, PECR, CASL compliance
-   - Email/domain suppression checking
-   - Policy enforcement
-
-5. **Handoff Packet Creation**
-   - Complete prospect dossier
-   - Email thread (simulated)
-   - Calendar slots (mock)
-   - Compliance documentation
-
----
-
-## Files Created/Updated
-
-### New Files:
-1. `services/web_search.py` - DuckDuckGo integration with rate limiting
-2. `services/company_discovery.py` - Dynamic company discovery
-3. `services/prospect_discovery.py` - Contact finding (now with skip_search parameter)
-4. `mcp/in_memory_services.py` - In-memory MCP services
-5. `mcp/in_memory_clients.py` - Client wrappers
-6. `DEMO_MODE.md` - Demo mode documentation
-7. `HF_SPACES_DEPLOYMENT.md` - Deployment guide
-8. `RATE_LIMIT_FIX.md` - Technical details
-9. `SKIP_WEB_SEARCH_FIX.md` - **CRITICAL FIX for rate limiting**
-10. `FINAL_SOLUTION.md` - This document
-
-### Updated Files:
-1. `app.py` - Fixed Gradio 5.x message format
-2. `app/config.py` - Added SKIP_WEB_SEARCH configuration
-3. `agents/hunter.py` - Dynamic discovery support with SKIP_WEB_SEARCH
-4. `agents/enricher.py` - **FIXED: Now respects SKIP_WEB_SEARCH flag** (critical)
-5. `agents/contactor.py` - **FIXED: Now passes SKIP_WEB_SEARCH to discovery** (critical)
-6. `agents/sequencer.py` - **FIXED: Email send error handling**
-7. `mcp/registry.py` - Dual mode support
-8. `.env.example` - New configuration options (SKIP_WEB_SEARCH=true by default)
-9. `requirements.txt` - Fixed dependency versions
-10. `requirements_gradio.txt` - Compatible versions
-
----
-
-## Quick Start
-
-### 1. Set Environment Variable
-
-For HF Spaces, add in Settings → Variables:
-```
-SKIP_WEB_SEARCH = true
-```
-
-### 2. Upload Files
-
-Upload entire project to your HF Space.
-
-### 3. Test
-
-```
-Company Name: "Shopify"
-Click: "Discover & Process"
-```
-
-Expected: Works instantly with fallback data!
-
----
-
-## Example Output (Demo Mode)
-
-```
-Input: "Shopify"
-
-Discovered Company:
-- Name: Shopify
-- Domain: shopify.com
-- Industry: E-commerce (detected from "shop")
-- Size: 500 employees
-- Pain Points:
-  • Managing high transaction volumes during peak seasons
-  • Customer retention and engagement challenges
-  • Providing seamless omnichannel experiences
-  • Scaling customer support operations
-
-Generated Contacts:
-- Olivia Martinez, VP Customer Experience
-- Noah Patel, Director of CX
-- Sophia Lee, Head of Support
-
-Generated Email: ✅
-Subject: Transform Shopify's Customer Experience with AI-Powered Solutions
-
-Compliance Checks: ✅
-Handoff Packet: ✅
-
-Status: ready_for_handoff
-Time: ~20 seconds
-```
-
----
-
-## Deployment Checklist
-
-### For Hugging Face Spaces:
-
-- [ ] Create new Space (Gradio SDK, Python 3.10)
-- [ ] Upload all files
-- [ ] Set `HF_API_TOKEN` in Space secrets
-- [ ] Set `SKIP_WEB_SEARCH=true` in Space variables
-- [ ] Verify `requirements_gradio.txt` has correct versions
-- [ ] Test with a company name
-- [ ] Confirm no rate limit errors
-- [ ] Verify content generation works
-
-### Expected Result:
-✅ App runs smoothly
-✅ No rate limiting
-✅ No MCP server errors
-✅ Content generates successfully
-✅ ~20 seconds per company
-
----
-
-## Troubleshooting
-
-### Rate Limit Errors (Even with Demo Mode)?
-
-Check configuration:
-```python
-from app.config import SKIP_WEB_SEARCH
-print(SKIP_WEB_SEARCH)  # Should be True
-```
-
-If False, set environment variable:
-```bash
-export SKIP_WEB_SEARCH=true
-```
-
-### Calendar Errors?
-
-Ensure in-memory calendar returns correct format (fixed in latest version).
-
-### Slow Performance?
-
-Demo mode should be fast (15-25s). If slow:
-- Check HF API token is valid
-- Verify model name is correct
-- Try smaller model for faster generation
-
----
-
-## Documentation
-
-Complete documentation available:
-
-1. **QUICK_START.md** - Get started fast
-2. **DEMO_MODE.md** - Demo mode explained
-3. **HF_SPACES_DEPLOYMENT.md** - Complete deployment guide
-4. **RATE_LIMIT_FIX.md** - Technical details
-5. **UPGRADE_GUIDE.md** - Migration from static to dynamic
-6. **DYNAMIC_DISCOVERY_README.md** - Feature overview
-
----
-
-## Success Criteria
-
-✅ **All Met:**
-
-1. ✅ Works on HF Spaces without errors
-2. ✅ No rate limiting issues (demo mode)
-3. ✅ No MCP server connection errors
-4. ✅ Processes any company name
-5. ✅ Generates personalized content
-6. ✅ Fast and reliable
-7. ✅ Single Gradio app (no separate processes)
-8. ✅ Free to run (no API keys for search)
-
----
-
-## Summary
-
-### Problem
-- DuckDuckGo rate limiting
-- MCP servers don't work on HF Spaces
-- Calendar errors
-- Gradio 5.x incompatibility
-
-### Solution
-- ✅ Demo mode to skip web search
-- ✅ In-memory MCP services
-- ✅ Fixed calendar format
-- ✅ Updated Gradio message format
-- ✅ Intelligent fallback data
-
-### Result
-**Production-ready app for Hugging Face Spaces!**
-
-- Works 100% reliably
-- No external dependencies (except HF API)
-- Fast processing
-- Great for demos
-- Scalable architecture
-
----
-
-## Next Steps
-
-1. **Deploy to HF Spaces** with demo mode
-2. **Test with various company names**
-3. **Customize fallback data** if needed
-4. **Add more industry detection** keywords
-5. **Integrate real APIs** when ready (optional)
-
----
-
-**Your CX AI Agent is now ready for production deployment! 🚀🎉**
-
-For best results on HF Spaces, use:
-```bash
-SKIP_WEB_SEARCH=true
-USE_IN_MEMORY_MCP=true
-```
-
-This ensures 100% reliability with zero rate limiting issues!

FIXES_SUMMARY.md

@@ -1,246 +0,0 @@
-# Summary of Critical Fixes
-
-## 🎯 Issues Fixed
-
-### 1. ✅ Enhanced Contact Finder Now Active in Gradio UI
-
-**Problem:**
-- SERPER_API_KEY was loaded successfully
-- But contact discovery was still failing
-- Messages showed: "No contacts found, using generic contact"
-
-**Root Cause:**
-- The Gradio UI was using the **OLD contact discovery method** (AI extractor)
-- The **NEW enhanced contact finder** (with SERPER_API_KEY) was never called
-- Two separate systems existed but only the old one was being used
-
-**Fix:**
-- Updated `app.py` `find_contacts()` method to use enhanced contact finder
-- Falls back to old method only if enhanced finder fails
-- Added detailed logging to track which system is being used
-
-**Result:**
-- LinkedIn profile searches now work
-- Team page scraping is active
-- Real decision-makers with actual names and emails are found
-
----
-
-### 2. ✅ SQLAlchemy Session Error Fixed
-
-**Problem:**
-```
-Instance <CXKBArticle> is not bound to a Session
-attribute refresh operation cannot proceed
-```
-
-**Root Cause:**
-- SQLAlchemy was expiring objects after commit
-- Objects became detached from session
-- `session.refresh()` calls failed
-
-**Fix:**
-- Added `expire_on_commit=False` to sessionmaker in `database/manager.py`
-- Objects remain accessible after commit
-- No more session binding errors
-
-**Result:**
-- Knowledge base operations work smoothly
-- No more "not bound to Session" errors
-
----
-
-### 3. ✅ System Health Display Fixed
-
-**Problem:**
-```
-❌ Search: healthy (in-memory)
-❌ Email: healthy (in-memory)
-❌ Calendar: healthy (in-memory)
-❌ Store: healthy (in-memory)
-```
-All showing ❌ even though they were healthy!
-
-**Root Cause:**
-- Health check returned "healthy (in-memory)"
-- Code checked for exact match: `status == "healthy"`
-- Didn't match, so showed ❌
-
-**Fix:**
-- Changed to: `if "healthy" in status.lower()`
-- Now matches both "healthy" and "healthy (in-memory)"
-
-**Result:**
-```
-✅ Search: healthy (in-memory)
-✅ Email: healthy (in-memory)
-✅ Calendar: healthy (in-memory)
-✅ Store: healthy (in-memory)
-```
-
----
-
-### 4. ✅ Duplicate Prevention Added
-
-**Problem:**
-- Same prospect could be created multiple times
-- Same contact could be saved multiple times
-- Data duplication in database
-
-**Fix:**
-
-**Prospects (`mcp/in_memory_services.py`):**
-- Check for duplicate by domain before creating
-- If domain exists, update existing prospect instead
-- Prevents multiple prospects for same company
-
-**Contacts (`mcp/in_memory_services.py`):**
-- Check for duplicate by email before creating
-- If email exists, skip creation
-- Prevents multiple contacts with same email
-
-**Result:**
-- No duplicate prospects in database
-- No duplicate contacts in database
-- Cleaner data integrity
-
----
-
-## 📊 What Changed
-
-### Files Modified:
-
-1. **`app.py`**
-   - Updated `find_contacts()` to use enhanced contact finder
-   - Fixed health check icon logic
-   - Added detailed logging
-
-2. **`database/manager.py`**
-   - Added `expire_on_commit=False` to sessionmaker
-   - Fixed SQLAlchemy session issues
-
-3. **`mcp/in_memory_services.py`**
-   - Added duplicate checking for prospects (by domain)
-   - Added duplicate checking for contacts (by email)
-
-4. **`services/enhanced_contact_finder.py`**
-   - Added detailed `[CONTACT FINDER]` logging
-   - Shows search progress and results
-
----
-
-## 🔍 New Diagnostic Logs
-
-When you create a prospect, you'll now see:
-
-```
-[APP] Finding contacts for Shopify (shopify.com)
-[APP] Using ENHANCED contact finder...
-
-[CONTACT FINDER] Starting search for Shopify
-[CONTACT FINDER] Domain: shopify.com
-[CONTACT FINDER] Target titles: ['CEO', 'Founder', 'Head of Customer Success']
-[CONTACT FINDER] Max contacts: 3
-[CONTACT FINDER] Strategy 1: Searching LinkedIn profiles...
-[CONTACT FINDER]   Searching for: CEO
-[CONTACT FINDER]     Query: 'site:linkedin.com/in CEO at Shopify'
-[CONTACT FINDER]     Results: 5 found
-[CONTACT FINDER]   ✓ FOUND: Tobi Lütke (CEO) - [email protected]
-
-[CONTACT FINDER] === FINAL RESULT ===
-[CONTACT FINDER] Total contacts found: 1
-[CONTACT FINDER]   1. Tobi Lütke (CEO) - [email protected]
-[CONTACT FINDER] ====================
-
-[APP] Found 1 REAL contacts via enhanced finder
-```
-
----
-
-## 🧪 Testing Checklist
-
-After pushing these changes:
-
-- [ ] System health shows ✅ for all MCP servers
-- [ ] Knowledge base works without session errors
-- [ ] Creating same prospect twice updates instead of duplicates
-- [ ] Creating contact with same email skips duplicate
-- [ ] Contact discovery uses enhanced finder
-- [ ] Logs show `[CONTACT FINDER]` messages
-- [ ] Real names found in LinkedIn searches
-- [ ] Emails addressed to real people: "Hi Sarah," not "Hi Hello,"
-
----
-
-### 5. ✅ Client Profile Database & Caching
-
-**Problem:**
-- Client company research was performed every time
-- No reuse of client data across multiple prospect campaigns
-- Wasted API calls for repeated client lookups
-
-**Root Cause:**
-- Client research results were returned but not stored
-- No database model for CLIENT company profiles
-- Had to re-research client for each prospect
-
-**Fix:**
-- Added `ClientProfile` model to `models/database.py`
-- Stores client company data: offerings, value props, target customers, use cases
-- Implements 7-day cache in `app.py` `research_client()` method
-- Checks DB first, returns cached if < 7 days old
-- Performs fresh research only if stale or missing
-- Automatically updates database after research
-
-**Fields Stored:**
-- `name`, `website`, `domain`, `description`, `industry`
-- `offerings` (JSON list of products/services)
-- `value_propositions` (JSON list of benefits)
-- `target_customers` (JSON list of who they serve)
-- `use_cases` (JSON list of examples)
-- `differentiators` (JSON list of unique features)
-- `last_researched_at` (timestamp for cache invalidation)
-
-**Result:**
-- Client profiles cached for 7 days
-- Reduced API calls for repeat campaigns
-- Faster prospect processing after initial research
-- Consistent client data across all prospects
-
----
-
-## 🚀 Next Steps
-
-1. **Push changes**: `git push origin main`
-2. **Test in HF Space** with SERPER_API_KEY set
-3. **Create a prospect** (try "Shopify" or "Stripe")
-4. **Verify logs** show enhanced contact finder activity
-5. **Check emails** use real names
-6. **Verify client caching** - research same client twice, second should use cache
-
----
-
-## 📝 Summary
-
-**All critical issues resolved:**
-- ✅ Enhanced contact finder integrated into UI
-- ✅ SERPER_API_KEY now being used
-- ✅ SQLAlchemy session errors fixed
-- ✅ System health display corrected
-- ✅ Duplicate prevention implemented
-- ✅ Detailed logging added for debugging
-- ✅ Client profile database & caching implemented
-- ✅ Personalized email generation with client research
-
-**Expected outcome:**
-- Real decision-makers found via LinkedIn
-- Emails personalized with actual names (Hi Sarah, not Hi Hello)
-- Emails customized based on CLIENT offerings + PROSPECT needs
-- Client profiles cached for 7 days to reduce API calls
-- No database errors
-- Clean data without duplicates
-- Clear logs showing what's happening
-
----
-
-**All changes are ready to push to HuggingFace Space!**

GRADIO_5_FIX.md

@@ -1,152 +0,0 @@
-# Gradio 5.x Message Format Fix
-
-## Issue
-```
-gradio.exceptions.Error: "Data incompatible with messages format. Each message should be a dictionary with 'role' and 'content' keys or a ChatMessage object."
-```
-
-## Root Cause
-Gradio 5.x changed the chatbot message format from tuples to dictionaries.
-
-### Old Format (Gradio 4.x):
-```python
-chat_history.append((None, "Assistant message"))
-chat_history.append(("User message", "Assistant response"))
-```
-
-### New Format (Gradio 5.x):
-```python
-chat_history.append({"role": "assistant", "content": "Assistant message"})
-chat_history.append({"role": "user", "content": "User message"})
-chat_history.append({"role": "assistant", "content": "Assistant response"})
-```
-
-## Fixed Files
-- `app.py` - Updated all message additions to use dictionary format
-
-## Changes Made
-
-### 1. Initial Message
-**Before:**
-```python
-chat_history.append((None, "Starting pipeline..."))
-```
-
-**After:**
-```python
-chat_history.append({
-    "role": "assistant",
-    "content": "Starting pipeline..."
-})
-```
-
-### 2. Company Processing Messages
-**Before:**
-```python
-chat_history.append((
-    f"Process {company}",
-    f"Processing: {company}"
-))
-```
-
-**After:**
-```python
-chat_history.append({
-    "role": "assistant",
-    "content": f"Processing: {company}",
-    "metadata": {"company": company}  # For tracking updates
-})
-```
-
-### 3. Updating Streaming Messages
-**Before:**
-```python
-if chat_history and chat_history[-1][0] == f"Process {company}":
-    chat_history[-1] = (f"Process {company}", updated_content)
-```
-
-**After:**
-```python
-if chat_history and chat_history[-1].get("metadata", {}).get("company") == company:
-    chat_history[-1]["content"] = updated_content
-```
-
-### 4. Error/Status Messages
-**Before:**
-```python
-chat_history.append((None, "Error occurred"))
-```
-
-**After:**
-```python
-chat_history.append({
-    "role": "assistant",
-    "content": "Error occurred"
-})
-```
-
-## Message Roles
-
-Gradio 5.x supports these roles:
-- `"user"` - User messages
-- `"assistant"` - Assistant/bot messages
-- `"system"` - System messages (optional)
-
-For this application, all messages are from the assistant role since it's a pipeline monitoring interface.
-
-## Testing
-
-After the fix, test with:
-```bash
-python app.py
-# Enter a company name and run the pipeline
-```
-
-Expected: Messages should display properly without format errors.
-
-## Chatbot Configuration
-
-The chatbot component is configured as:
-```python
-gr.Chatbot(
-    label="Agent Output & Generated Content",
-    height=600,
-    type="messages"  # This enables the new format
-)
-```
-
-## Additional Notes
-
-### Metadata Field
-We added a `metadata` field to track which company each message belongs to:
-```python
-{
-    "role": "assistant",
-    "content": "...",
-    "metadata": {"company": "Shopify"}
-}
-```
-
-This allows us to update the correct message when streaming tokens for a specific company.
-
-### Streaming Updates
-For real-time token streaming, we update the message in place:
-```python
-# Find the message for this company
-if chat_history[-1].get("metadata", {}).get("company") == company:
-    # Update its content
-    chat_history[-1]["content"] = new_content
-```
-
-## Migration Checklist
-
-If you have other Gradio interfaces, check for:
-- [ ] All `chat_history.append()` use dictionary format
-- [ ] Chatbot component has `type="messages"`
-- [ ] Message updates modify the `"content"` key, not tuple indices
-- [ ] All roles are valid: "user", "assistant", or "system"
-
-## Resources
-
-- [Gradio 5.0 Migration Guide](https://www.gradio.app/guides/migration-guide-5)
-- [Chatbot Component Docs](https://www.gradio.app/docs/chatbot)

HF_SPACES_DEPLOYMENT.md

@@ -1,412 +0,0 @@
-# Hugging Face Spaces Deployment Guide
-
-## Overview
-
-This CX AI Agent is designed to run as a single Gradio app on Hugging Face Spaces without requiring separate server processes.
-
-## Architecture for HF Spaces
-
-### In-Memory Mode
-The app automatically uses in-memory services instead of HTTP MCP servers:
-
-```
-Gradio App
-├── Web Search Service (DuckDuckGo)
-├── In-Memory MCP Services
-│   ├── Store Service (in-memory)
-│   ├── Search Service (web search wrapper)
-│   ├── Email Service (simulated)
-│   └── Calendar Service (simulated)
-└── AI Agents (Hunter, Enricher, etc.)
-```
-
-### Key Features for HF Spaces
-
-1. **No Separate Processes** - Everything runs in a single Gradio app
-2. **No Port Management** - All services are in-memory
-3. **Free Web Search** - Uses DuckDuckGo (no API key)
-4. **Rate Limiting Protection** - Built-in delays and retry logic
-5. **Error Handling** - Graceful fallbacks when search fails
-
----
-
-## Deployment Steps
-
-### 1. Create HF Space
-
-1. Go to https://huggingface.co/spaces
-2. Click "Create new Space"
-3. Choose:
-   - **SDK**: Gradio
-   - **Python version**: 3.10
-   - **Space hardware**: CPU Basic (free tier)
-
-### 2. Upload Files
-
-Upload these files to your Space:
-
-**Required Files:**
-- `app.py` - Main Gradio app
-- `requirements_gradio.txt` - Dependencies
-- `README.md` - Space description
-
-**Application Code:**
-- `app/` - Main application logic
-- `agents/` - AI agents
-- `mcp/` - MCP services (in-memory)
-- `services/` - Web search and discovery
-- `vector/` - Vector store and embeddings
-- `data/` - Data files
-
-### 3. Set Environment Variables
-
-In your Space settings, add:
-
-```bash
-# Required
-HF_API_TOKEN=your_hf_token_here
-
-# Optional (with defaults)
-MODEL_NAME=Qwen/Qwen2.5-7B-Instruct
-USE_IN_MEMORY_MCP=true  # Always true for HF Spaces
-```
-
-### 4. Configure Space
-
-**app.py** should be at the root level:
-```
-your-space/
-├── app.py                 # Main Gradio app
-├── requirements_gradio.txt
-├── README.md
-├── app/
-├── agents/
-├── mcp/
-├── services/
-├── vector/
-└── data/
-```
-
-### 5. Dependencies
-
-**requirements_gradio.txt** should include:
-
-```txt
-gradio==5.5.0
-huggingface-hub>=0.19.3,<1.0
-transformers>=4.36.0,<5.0
-fastapi==0.109.0
-pydantic==2.5.3
-aiohttp==3.9.1
-sentence-transformers==2.3.1
-faiss-cpu==1.7.4
-duckduckgo-search==4.1.1
-email-validator==2.1.0
-python-dotenv==1.0.0
-pandas==2.1.4
-```
-
----
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `HF_API_TOKEN` | Yes | - | HuggingFace API token for inference |
-| `USE_IN_MEMORY_MCP` | No | `true` | Use in-memory services (always true for HF Spaces) |
-| `MODEL_NAME` | No | `Qwen/Qwen2.5-7B-Instruct` | LLM model for content generation |
-
-### Automatic Mode Detection
-
-The app automatically detects HF Spaces environment and uses in-memory mode:
-
-```python
-# In mcp/registry.py
-USE_IN_MEMORY_MODE = os.getenv("USE_IN_MEMORY_MCP", "true").lower() == "true"
-```
-
----
-
-## Rate Limiting
-
-### DuckDuckGo Rate Limits
-
-The web search service includes protection against rate limiting:
-
-**Built-in Protection:**
-- 2-second delay between requests
-- Exponential backoff on rate limit errors (5s, 10s, 20s)
-- Maximum 3 retry attempts per query
-- Fresh DDGS instance for each request
-
-**Configuration:**
-```python
-# In services/web_search.py
-WebSearchService(
-    max_results=10,
-    rate_limit_delay=2.0  # Seconds between requests
-)
-```
-
-### Handling Rate Limits
-
-If you encounter rate limits:
-
-1. **Reduce Company Count** - Process fewer companies at once
-2. **Increase Delay** - Modify `rate_limit_delay` in `web_search.py`
-3. **Use Fallbacks** - System automatically uses fallback data
-
----
-
-## Performance
-
-### Expected Times (Per Company)
-
-| Phase | Time | Notes |
-|-------|------|-------|
-| Discovery | 5-10s | Web search for company info |
-| Enrichment | 5-10s | Web search for facts/news |
-| Contact Finding | 3-5s | Web search for prospects |
-| Content Generation | 10-20s | LLM generation with HF API |
-| **Total** | **25-45s** | Per company |
-
-### Optimization Tips
-
-1. **Single Company** - Start with one company to test
-2. **Batch Processing** - Process multiple companies sequentially
-3. **Caching** - Results are cached in in-memory store
-4. **Error Handling** - Fallbacks keep pipeline moving
-
----
-
-## Troubleshooting
-
-### Issue: Rate Limit Errors
-
-**Symptoms:**
-```
-DuckDuckGoSearchException: Ratelimit
-```
-
-**Solutions:**
-1. Wait 1-2 minutes and try again
-2. Process fewer companies
-3. System will automatically retry with backoff
-
-### Issue: Slow Performance
-
-**Symptoms:** Pipeline takes >60s per company
-
-**Solutions:**
-1. Normal for web search (30-60s expected)
-2. Use CPU Basic tier (free)
-3. Consider upgrading to CPU Upgrade ($9/month) for faster processing
-
-### Issue: Memory Errors
-
-**Symptoms:**
-```
-MemoryError or Out of Memory
-```
-
-**Solutions:**
-1. Process companies one at a time
-2. Clear store between runs: `store.clear_all()`
-3. Upgrade to higher tier Space
-
-### Issue: HF API Errors
-
-**Symptoms:**
-```
-HuggingFaceAPIError or 503 errors
-```
-
-**Solutions:**
-1. Check HF_API_TOKEN is valid
-2. Verify model name is correct
-3. Check HF API status
-4. Wait and retry (HF API rate limits)
-
----
-
-## Space Configuration
-
-### Recommended Settings
-
-**Hardware:**
-- Free tier: CPU Basic (sufficient for demo)
-- Production: CPU Upgrade (faster, $9/month)
-
-**Visibility:**
-- Public: Anyone can use
-- Private: Only you can access
-
-**Sleep Mode:**
-- Disabled: Always on (requires paid plan)
-- Enabled: Sleeps after inactivity (free tier)
-
-### README.md
-
-Include in your Space's README:
-
-```markdown
----
-title: CX AI Agent - Dynamic Discovery
-emoji: 🤖
-colorFrom: blue
-colorTo: green
-sdk: gradio
-sdk_version: 5.5.0
-app_file: app.py
-pinned: false
----
-
-# CX AI Agent - Dynamic Discovery Edition
-
-Autonomous multi-agent system for customer experience research and outreach.
-
-## Features
-
-- 🔍 Dynamic company discovery via web search
-- 🌐 Live data from DuckDuckGo (no API key needed)
-- 👥 Real prospect finding
-- ✍️ AI-generated personalized outreach
-- ✅ Compliance checking
-
-## Usage
-
-1. Enter a company name (e.g., "Shopify")
-2. Click "Discover & Process"
-3. Watch real-time discovery and content generation!
-
-## Performance
-
-- ~30-60 seconds per company
-- Uses free DuckDuckGo search
-- HuggingFace Inference API for LLM
-
-## Limitations
-
-- Free tier may have rate limits
-- Web search can be slow
-- Demo mode for email/calendar services
-```
-
----
-
-## Advanced Configuration
-
-### Custom Model
-
-Change the LLM model in Space secrets:
-
-```bash
-MODEL_NAME=meta-llama/Llama-2-7b-chat-hf
-# or
-MODEL_NAME=mistralai/Mistral-7B-Instruct-v0.2
-```
-
-### Adjust Rate Limiting
-
-Edit `services/web_search.py`:
-
-```python
-def __init__(self, max_results: int = 10, rate_limit_delay: float = 3.0):
-    # Increase delay to 3 seconds
-```
-
-### Reduce Search Queries
-
-Edit `services/company_discovery.py` to reduce queries:
-
-```python
-# Reduce from 4 queries to 2
-queries = [
-    f"{company_name} official website",
-    f"{company_name} industry business"
-]
-```
-
----
-
-## Cost Estimation
-
-### Free Tier
-
-- **Compute**: Free (CPU Basic)
-- **Storage**: Free (up to 50GB)
-- **DuckDuckGo**: Free (no limits)
-- **HF Inference API**: Free tier (limited)
-
-**Limitations:**
-- May sleep after inactivity
-- Rate limits on HF API
-- Slower performance
-
-### Paid Tier
-
-**CPU Upgrade ($9/month):**
-- Always on
-- Faster processing
-- Higher priority
-
-**Resources:**
-- 2 vCPU cores
-- 16GB RAM
-- 50GB storage
-
----
-
-## Monitoring
-
-### View Logs
-
-Check Space logs for:
-- Web search requests
-- Rate limit warnings
-- Error messages
-- Performance metrics
-
-### Health Check
-
-Use the System tab in the UI:
-- MCP services status
-- Vector store status
-- Model configuration
-
----
-
-## Security
-
-### API Tokens
-
-**Never commit tokens to Git!**
-
-Use Space secrets:
-1. Go to Space → Settings → Secrets
-2. Add `HF_API_TOKEN`
-3. Reference in code: `os.getenv("HF_API_TOKEN")`
-
-### Data Privacy
-
-- No data is stored permanently (in-memory only)
-- Web searches are anonymous (DuckDuckGo)
-- HF API calls are private to your account
-
----
-
-## Support
-
-For issues:
-1. Check logs in Space console
-2. Review error messages
-3. See `TROUBLESHOOTING.md`
-4. Open GitHub issue
-
----
-
-## License
-
-Same as main project - see LICENSE file.

IMPLEMENTATION_COMPLETE.md

@@ -1,508 +0,0 @@
-# ✅ MCP Autonomous Implementation - COMPLETE
-
-## 🎯 Mission Accomplished
-
-Your CX AI Agent now has **TRUE MCP implementation** where:
-- ✅ **AI autonomously calls MCP servers** (Claude 3.5 Sonnet)
-- ✅ **NO hardcoded workflow** - AI decides everything
-- ✅ **15+ MCP tools** exposed to AI with proper schemas
-- ✅ **All services use MCP** - No bypassing
-- ✅ **Proper Model Context Protocol** - Following spec
-
----
-
-## 🚀 What Was Built
-
-### 1. MCP Tool Definitions
-**File:** `mcp/tools/definitions.py` (400+ lines)
-
-**15 MCP Tools:**
-- `search_web` - Web search
-- `search_news` - News search
-- `save_prospect` - Save prospect
-- `get_prospect` - Get prospect
-- `list_prospects` - List all prospects
-- `save_company` - Save company
-- `get_company` - Get company
-- `save_fact` - Save enrichment facts
-- `save_contact` - Save contacts
-- `list_contacts_by_domain` - Get company contacts
-- `check_suppression` - Check opt-outs
-- `send_email` - Send email
-- `get_email_thread` - Get email thread
-- `suggest_meeting_slots` - Get meeting times
-- `generate_calendar_invite` - Create .ics file
-
-**Each tool has:**
-- ✅ Proper JSON schema
-- ✅ Clear description for AI
-- ✅ Required/optional parameters
-- ✅ Type safety
-
-### 2. Autonomous AI Agent
-**File:** `mcp/agents/autonomous_agent.py` (500+ lines)
-
-**Features:**
-- Uses Claude 3.5 Sonnet (best tool calling)
-- AI-driven decision making
-- Autonomous MCP tool execution
-- Real-time progress streaming
-- Error handling and recovery
-- Max iteration safety
-
-**How it works:**
-```python
-agent = AutonomousMCPAgent(mcp_registry, api_key)
-
-# AI autonomously completes task
-async for event in agent.run("Research Shopify"):
-    # AI decides:
-    # 1. search_web("Shopify")
-    # 2. save_company(...)
-    # 3. search_news("Shopify")
-    # 4. save_fact(...)
-    # 5. save_prospect(...)
-    print(event)
-```
-
-### 3. Gradio Demo App
-**File:** `app_mcp_autonomous.py` (200+ lines)
-
-**Features:**
-- User-friendly interface
-- Real-time progress display
-- Example tasks
-- API key input (secure)
-- Full event logging
-
-### 4. Documentation
-**Files:**
-- `MCP_PROPER_IMPLEMENTATION.md` - Complete guide (800+ lines)
-- `IMPLEMENTATION_COMPLETE.md` - This file
-
----
-
-## 🔄 Architecture Transformation
-
-### Before (Hardcoded ❌)
-
-```python
-# Fixed pipeline - NO AI decision making
-orchestrator = Orchestrator(mcp_registry)
-
-for company in companies:
-    # Hardcoded workflow:
-    prospect = await hunter.run(company)      # Step 1
-    prospect = await enricher.run(prospect)   # Step 2
-    prospect = await contactor.run(prospect)  # Step 3
-    prospect = await writer.run(prospect)     # Step 4
-    # ... always the same order
-```
-
-**Problems:**
-- ❌ AI doesn't decide anything
-- ❌ Fixed order of operations
-- ❌ Can't adapt to different tasks
-- ❌ Not true MCP usage
-
-### After (Autonomous ✅)
-
-```python
-# AI-driven - FULL autonomy
-agent = AutonomousMCPAgent(mcp_registry, api_key)
-
-# AI decides everything:
-async for event in agent.run("Research Shopify and create prospect"):
-    # AI autonomously:
-    # - Decides which tools to call
-    # - Decides when to call them
-    # - Decides what data to pass
-    # - Adapts based on results
-    # - Continues until task complete
-    print(event)
-```
-
-**Benefits:**
-- ✅ AI makes all decisions
-- ✅ Adapts to any task
-- ✅ No hardcoded logic
-- ✅ True MCP demonstration
-- ✅ Works for ANY B2B sales task
-
----
-
-## 📊 AI Decision Flow Example
-
-### Task: "Research Shopify and create a prospect profile"
-
-```
-User: "Research Shopify and create a prospect profile"
-    ↓
-┌─────────────────────────────────────────────────┐
-│ AI: "I need to search for Shopify information"  │
-│ Decision: Call search_web()                     │
-└────────────────┬────────────────────────────────┘
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ MCP Tool: search_web("Shopify company info")    │
-│ Result: [company info, website, description]    │
-└────────────────┬────────────────────────────────┘
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ AI: "Good, now I'll save the company data"      │
-│ Decision: Call save_company()                   │
-└────────────────┬────────────────────────────────┘
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ MCP Tool: save_company(name="Shopify", ...)     │
-│ Result: {status: "saved", company_id: "..."}    │
-└────────────────┬────────────────────────────────┘
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ AI: "Need recent news for context"              │
-│ Decision: Call search_news()                    │
-└────────────────┬────────────────────────────────┘
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ MCP Tool: search_news("Shopify recent news")    │
-│ Result: [news articles about Shopify]           │
-└────────────────┬────────────────────────────────┘
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ AI: "Found interesting facts, let me save them" │
-│ Decision: Call save_fact() multiple times       │
-└────────────────┬────────────────────────────────┘
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ MCP Tool: save_fact("Shopify launched X", ...)  │
-│ MCP Tool: save_fact("Shopify has Y users", ...) │
-│ Result: {status: "saved"}                       │
-└────────────────┬────────────────────────────────┘
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ AI: "Now I can create the prospect profile"     │
-│ Decision: Call save_prospect()                  │
-└────────────────┬────────────────────────────────┘
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ MCP Tool: save_prospect(company_id, score, ...) │
-│ Result: {status: "saved", prospect_id: "..."}   │
-└────────────────┬────────────────────────────────┘
-                 ↓
-┌─────────────────────────────────────────────────┐
-│ AI: "Task complete! Here's the summary..."      │
-│ Decision: No more tools needed                  │
-└─────────────────────────────────────────────────┘
-```
-
-**Key Point:** Every decision made by AI, not code!
-
----
-
-## 🎯 How to Use
-
-### 1. Set Environment Variables
-
-```bash
-# REQUIRED: Claude API key (get from console.anthropic.com)
-export ANTHROPIC_API_KEY=sk-ant-api03-...
-
-# REQUIRED: Serper API key for web search
-export SERPER_API_KEY=your_serper_key
-
-# OPTIONAL: Use in-memory MCP (recommended for HF Spaces)
-export USE_IN_MEMORY_MCP=true
-```
-
-### 2. Install Dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-**New package:** `anthropic>=0.39.0` for Claude 3.5 Sonnet
-
-### 3. Run the Demo
-
-```bash
-python app_mcp_autonomous.py
-```
-
-Opens Gradio interface at `http://localhost:7860`
-
-### 4. Try It Out
-
-**Enter your Anthropic API key** (in the interface)
-
-**Try these tasks:**
-- "Research Shopify and create a prospect profile"
-- "Find 3 e-commerce SaaS companies and save as prospects"
-- "Search for recent AI startup news and save as facts"
-- "Create a prospect for Notion with company research"
-
-**Watch the AI:**
-- Decide which tools to call
-- Execute MCP tools autonomously
-- Adapt based on results
-- Complete the task
-
----
-
-## 🏆 Why This is Proper MCP
-
-### ✅ Follows MCP Specification
-
-1. **MCP Servers** - 4 servers (Search, Store, Email, Calendar)
-2. **MCP Tools** - 15 tools with proper schemas
-3. **MCP Resources** - Databases exposed as resources
-4. **MCP Prompts** - Pre-defined prompt templates
-5. **Tool Calling** - Native AI function calling
-6. **Autonomous Execution** - AI decides tool usage
-
-### ✅ Demonstrates Key Concepts
-
-- **No Hardcoded Workflow** - AI makes all decisions
-- **Dynamic Tool Selection** - AI picks tools based on task
-- **Context Awareness** - AI remembers previous tool results
-- **Error Recovery** - AI handles tool failures gracefully
-- **Task Adaptation** - Works for any B2B sales task
-
-### ✅ Real-World Benefits
-
-- Can handle tasks not programmed for
-- Adapts to new scenarios
-- Scales to complex multi-step workflows
-- Reduces code maintenance
-- True AI agency
-
----
-
-## 📈 Performance & Cost
-
-### Speed
-
-| Metric | Value |
-|--------|-------|
-| **Time to first tool call** | 1-3 seconds |
-| **Tool execution** | 0.1-2 seconds each |
-| **Typical iterations** | 5-10 tools |
-| **Total task time** | 10-30 seconds |
-
-### Cost (Claude 3.5 Sonnet)
-
-| Task Complexity | Tokens | Cost |
-|----------------|--------|------|
-| Simple (1-2 tools) | ~1K | $0.005 |
-| Medium (5-7 tools) | ~3K | $0.015 |
-| Complex (10-15 tools) | ~6K | $0.030 |
-
-**Very affordable for demonstrations!**
-
----
-
-## 🔧 Files Structure
-
-```
-cx_ai_agent/
-├── mcp/
-│   ├── tools/
-│   │   ├── definitions.py     ✅ NEW: MCP tool schemas
-│   │   └── __init__.py        ✅ NEW
-│   ├── agents/
-│   │   └── autonomous_agent.py ✅ NEW: AI agent
-│   ├── servers/               ✅ EXISTING: MCP servers
-│   ├── in_memory_services.py  ✅ EXISTING: In-memory mode
-│   └── registry.py            ✅ EXISTING: MCP registry
-├── app_mcp_autonomous.py      ✅ NEW: Autonomous demo
-├── MCP_PROPER_IMPLEMENTATION.md ✅ NEW: Full docs
-├── IMPLEMENTATION_COMPLETE.md  ✅ NEW: This file
-└── requirements.txt           ✅ UPDATED: Added anthropic
-
-OLD (ignore these):
-├── app.py                     ❌ OLD: Hardcoded workflow
-├── app/orchestrator.py        ❌ OLD: Hardcoded orchestrator
-└── agents/*.py                ❌ OLD: Hardcoded agents
-```
-
----
-
-## 🎥 Demo Script for Hackathon
-
-### 1. Show the Problem (30 seconds)
-
-"Traditional AI pipelines are hardcoded:
-- Fixed workflow
-- No adaptation
-- Can't handle new tasks
-- Not true AI agency"
-
-### 2. Introduce MCP Solution (30 seconds)
-
-"With Model Context Protocol:
-- AI decides which tools to use
-- Autonomous decision-making
-- Adapts to any task
-- True AI agency"
-
-### 3. Live Demo (2 minutes)
-
-**Task 1:** "Research Shopify and create prospect"
-- Show AI searching
-- Show AI saving data
-- Show AI creating prospect
-- Show final result
-
-**Task 2:** "Find 3 AI startups"
-- Different task, same AI
-- Show adaptation
-- Show autonomous decisions
-
-### 4. Show the Code (1 minute)
-
-```python
-# This is ALL the code needed:
-agent = AutonomousMCPAgent(mcp_registry, api_key)
-async for event in agent.run(user_task):
-    print(event)
-```
-
-"No hardcoded logic! AI does everything!"
-
-### 5. Explain Value (30 seconds)
-
-"This enables:
-- Any B2B sales task
-- Research, enrichment, outreach
-- Scales automatically
-- Production-ready"
-
-**Total: 4-5 minutes**
-
----
-
-## ✅ Checklist for Hackathon
-
-### Before Demo
-- [ ] Set ANTHROPIC_API_KEY
-- [ ] Set SERPER_API_KEY
-- [ ] Test app locally
-- [ ] Prepare 2-3 example tasks
-- [ ] Have backup (in case API fails)
-
-### During Demo
-- [ ] Explain the problem (hardcoded)
-- [ ] Show autonomous solution
-- [ ] Run live demo
-- [ ] Show 2 different tasks
-- [ ] Explain MCP value
-
-### After Demo
-- [ ] Answer questions
-- [ ] Share code/docs
-- [ ] Discuss production use cases
-
----
-
-## 🐛 Troubleshooting
-
-### "ANTHROPIC_API_KEY not found"
-```bash
-export ANTHROPIC_API_KEY=sk-ant-api03-...
-```
-
-Or enter in Gradio interface.
-
-### "Tool execution failed"
-- Check MCP servers are running
-- Or use `USE_IN_MEMORY_MCP=true`
-
-### "Search failed"
-```bash
-export SERPER_API_KEY=your_key
-```
-
-Or use `SKIP_WEB_SEARCH=true` for mock data.
-
-### "Max iterations reached"
-- Task too complex
-- Break into smaller tasks
-- Or increase `max_iterations` in code
-
----
-
-## 🎓 Learning Resources
-
-### MCP Protocol
-- Official docs: https://modelcontextprotocol.io/
-- Anthropic: https://docs.anthropic.com/en/docs/agents
-
-### Claude Tool Calling
-- https://docs.anthropic.com/en/docs/build-with-claude/tool-use
-
-### Your Implementation
-- Read: `MCP_PROPER_IMPLEMENTATION.md`
-- Code: `mcp/agents/autonomous_agent.py`
-- Demo: `app_mcp_autonomous.py`
-
----
-
-## 🎉 Conclusion
-
-You now have:
-
-✅ **TRUE MCP Implementation**
-- AI autonomously calls MCP servers
-- No hardcoded workflow
-- Claude 3.5 Sonnet with tool calling
-
-✅ **15 MCP Tools**
-- Search, Store, Email, Calendar
-- Proper schemas and definitions
-
-✅ **Autonomous Agent**
-- Makes own decisions
-- Adapts to any task
-- Production-ready
-
-✅ **Ready for Hackathon**
-- Clear demonstration
-- Live demo app
-- Comprehensive docs
-
-**This is what Model Context Protocol is meant for!** 🚀
-
----
-
-## 📞 Next Steps
-
-1. **Test locally:**
-   ```bash
-   python app_mcp_autonomous.py
-   ```
-
-2. **Deploy to HF Spaces:**
-   - Add ANTHROPIC_API_KEY to secrets
-   - Add SERPER_API_KEY to secrets
-   - Set USE_IN_MEMORY_MCP=true
-   - Push to HF
-
-3. **Prepare demo:**
-   - Practice 2-3 tasks
-   - Prepare explanation
-   - Have backup ready
-
-4. **Win hackathon!** 🏆
-
----
-
-**Implementation Complete!** ✅
-
-All requirements met:
-- ✅ AI calls MCP servers (not manual)
-- ✅ No hardcoded workflow
-- ✅ No service bypassing
-- ✅ Proper MCP demonstration
-- ✅ Tool calling implemented
-- ✅ Production-ready
-
-**Ready to demonstrate at MCP hackathon!** 🎯

IMPLEMENTATION_SUMMARY.md

@@ -1,202 +0,0 @@
-# B2B Sales Automation - Implementation Summary
-
-## 🎯 What Was Done
-
-Successfully integrated the correct B2B Sales workflow into the main application, addressing the user's core requirements.
-
-## ✅ Changes Made
-
-### 1. **app.py** - Main Application File
-
-#### Added B2B Sales Agent Class (Lines 418-621)
-- **B2BSalesAgent** class with 5 core methods:
-  - `research_client()` - Researches the CLIENT company
-  - `find_prospects()` - Finds PROSPECT companies who need client's services
-  - `research_prospect()` - Analyzes prospect pain points
-  - `find_contacts()` - Finds decision-makers at prospect companies
-  - `generate_email()` - Creates personalized emails FROM client TO prospects
-  - `run_full_pipeline()` - Orchestrates complete workflow with streaming
-
-#### Added UI Handler (Lines 628-709)
-- `run_b2b_pipeline_ui()` - Handles Gradio interface interaction
-  - Streams progress updates in real-time
-  - Displays execution log
-  - Shows full email content (not just logs)
-  - Error handling with user-friendly messages
-
-#### Added Primary Tab (Lines 743-789)
-- **New "💼 B2B Sales" tab** as FIRST tab (primary feature)
-- Clear workflow explanation with examples
-- Input: Client company name + number of prospects
-- Output: Execution log + Full email content
-- Emphasizes: "The company you're selling FOR (not TO)"
-
-#### Updated Main Header (Lines 722-743)
-- Changed title to "B2B Sales Automation Platform"
-- Emphasized core B2B functionality
-- Listed B2B features first, CX features second
-- Clear workflow: CLIENT → PROSPECT → EMAIL
-
-#### Renamed Existing Pipeline Tab (Line 792)
-- Changed from "🚀 Pipeline" to "🔄 Advanced Pipeline"
-- Positions it as advanced feature, not primary
-
-### 2. **ABOUT.md** - Documentation
-
-#### Added Core Workflow Section (Lines 12-95)
-- **New Section: "B2B Sales Automation - Core Workflow"**
-- Explains the problem being solved
-- Step-by-step process breakdown
-- Real-world example with Shopify → Fashion Boutique
-- Full email example showing expected output
-- Key features list
-
-#### Updated Introduction (Lines 5-8)
-- Changed primary purpose to "B2B Sales Automation (CORE)"
-- De-emphasized 8-agent pipeline as secondary feature
-
-### 3. **app_simplified.py** - Reference Implementation (Already Created)
-- Complete standalone implementation of correct workflow
-- Serves as reference for the integrated version
-- Can be used for testing or as alternative entry point
-
-## 🔄 Correct Workflow Now Implemented
-
-### ❌ OLD (Incorrect):
-```
-Input: Shopify
-↓
-Find contacts AT Shopify
-↓
-Generate emails TO Shopify
-```
-
-### ✅ NEW (Correct):
-```
-Input: Shopify (CLIENT)
-↓
-Research Shopify's offerings
-↓
-Find prospects who need Shopify (e.g., small e-commerce stores)
-↓
-Research each prospect's pain points
-↓
-Find decision-makers at PROSPECTS
-↓
-Generate emails FROM Shopify TO prospects
-```
-
-## 📊 Key Features Implemented
-
-1. ✅ **Correct Email Direction**: FROM client TO prospects
-2. ✅ **Live Web Search**: Real-time company research via Serper API
-3. ✅ **Personalization**: Emails reference prospect-specific pain points
-4. ✅ **Full Results Display**: Shows complete email content, not just logs
-5. ✅ **Streaming UI**: Real-time progress updates
-6. ✅ **Scalable**: Process 1-5 prospects per run
-7. ✅ **Professional**: Clean, focused UI as requested
-
-## 🎨 UI/UX Improvements
-
-### Simplified Interface:
-- **Primary Tab**: B2B Sales (core functionality)
-- **Secondary Tabs**: Advanced Pipeline, Tickets, KB, Chat, Analytics, System, About
-- Clear workflow explanation
-- Helpful placeholder text
-- Real-time feedback
-- Separate sections for logs vs. results
-
-### Results Display:
-- **Execution Log**: Shows progress and status
-- **Generated Emails**: Full email content with:
-  - To/From addresses
-  - Prospect company name
-  - Contact name and title
-  - Subject line
-  - Complete email body
-  - Formatted for easy reading
-
-## 🔌 Integration with Existing System
-
-The B2B Sales Agent integrates seamlessly with existing components:
-- **WebSearchService**: Used for all company research
-- **Database Manager**: Available for storing results
-- **Gradio Interface**: Added as first tab
-- **MCP Registry**: Available for advanced features
-- **CX Modules**: Remain intact for complete platform
-
-## 📝 Documentation Updates
-
-1. **ABOUT.md**: Added B2B workflow section at the beginning
-2. **Main Header**: Updated to emphasize B2B sales
-3. **Tab Descriptions**: Clear explanation of workflow
-4. **Examples**: Shopify → Fashion Boutique use case
-
-## 🚀 How to Use
-
-1. Open the application
-2. Go to "💼 B2B Sales" tab (first tab)
-3. Enter CLIENT company name (e.g., "Shopify")
-4. Select number of prospects (1-5)
-5. Click "🚀 Find Prospects & Generate Emails"
-6. Watch real-time progress in execution log
-7. View full email content in "Generated Emails" section
-
-## 🎯 User Requirements Addressed
-
-| Requirement | Status | Implementation |
-|-------------|--------|----------------|
-| CLIENT → PROSPECT workflow | ✅ | B2BSalesAgent class with correct flow |
-| Research client company | ✅ | `research_client()` method |
-| Find prospects | ✅ | `find_prospects()` with web search |
-| Research prospect pain points | ✅ | `research_prospect()` method |
-| Find decision-makers | ✅ | `find_contacts()` method |
-| Generate personalized emails | ✅ | `generate_email()` method |
-| Email FROM client TO prospects | ✅ | Correct email direction in all outputs |
-| Compliance rules | ✅ | Unsubscribe language + AI disclosure |
-| See results, not just logs | ✅ | Separate "Generated Emails" output |
-| Reduce UI complexity | ✅ | B2B tab as primary, clear layout |
-| Professional CX software | ✅ | Integration with existing CX modules |
-| AI agents + MCP | ✅ | Uses WebSearchService, ready for MCP |
-
-## 📦 Files Modified
-
-1. `app.py` (4 major changes)
-2. `ABOUT.md` (2 sections updated)
-3. `app_simplified.py` (reference implementation)
-4. `IMPLEMENTATION_SUMMARY.md` (this file - NEW)
-
-## 🧪 Testing Recommendations
-
-1. Test with different client companies:
-   - Shopify (e-commerce platform)
-   - Stripe (payment processing)
-   - HubSpot (CRM/marketing)
-   - Slack (team communication)
-
-2. Verify output:
-   - Execution log shows all steps
-   - Emails display with full content
-   - Email direction is correct (FROM client TO prospects)
-   - Personalization includes prospect pain points
-
-3. Check edge cases:
-   - No prospects found
-   - No contacts found
-   - Web search errors
-   - Invalid company names
-
-## 🔜 Future Enhancements
-
-Based on user's original requirements not yet fully implemented:
-
-1. **Reply Handling**: AI handles prospect responses until escalation
-2. **Handoff Packets**: Structured data for human executives
-3. **Separate Functions**: Break pipeline into individual callable functions
-4. **Email Service Integration**: AWS SES for actual sending (when available)
-5. **Advanced Compliance**: CAN-SPAM, PECR, CASL rule checking
-6. **Contact Enrichment**: Better contact finding with LinkedIn/Apollo integration
-
-## ✨ Summary
-
-The application now correctly implements the B2B sales automation workflow as specified by the user. The core functionality (CLIENT → PROSPECTS → EMAILS) is working, prominently displayed, and delivers the actual results (full email content) rather than just execution logs.

MCP_ANALYSIS_AND_FIXES.md

@@ -1,416 +0,0 @@
-# MCP Analysis & Fixes for CX AI Agent
-
-## Executive Summary
-
-After deep analysis of your codebase, here are the findings and fixes:
-
-### 🔍 Key Findings
-
-1. **NOT all modules use MCP** - Services bypass MCP and call APIs directly
-2. **MCP is NOT called by AI** - All invocations are hardcoded workflow logic
-3. **LLM is too large for CPU** - 7B model → upgraded to 3B for 2.3x speed
-
----
-
-## Issue 1: Services Bypass MCP Servers
-
-### Problem
-
-**These services make DIRECT API calls instead of using MCP:**
-
-```
-services/web_search.py         → Direct Serper.dev API
-services/company_discovery.py  → Direct Serper.dev API
-services/prospect_discovery.py → Direct Serper.dev API
-services/client_researcher.py  → Direct Serper.dev + scraping
-services/llm_service.py        → Direct Anthropic API
-```
-
-**Why this matters:**
-- ❌ Inconsistent architecture (some use MCP, some don't)
-- ❌ Can't centrally monitor/control API usage
-- ❌ Harder to mock/test
-- ❌ Can't benefit from MCP features (caching, rate limiting, etc.)
-
-### Current Architecture
-
-```
-┌─────────────────────────────────────────┐
-│          Orchestrator                   │
-└───────────┬─────────────────────────────┘
-            │
-    ┌───────┴───────┐
-    │               │
-┌───▼────┐    ┌────▼─────┐
-│ Agents │    │ Services │
-│        │    │          │
-│ Use    │    │ BYPASS   │
-│ MCP ✅  │    │ MCP ❌    │
-└───┬────┘    └────┬─────┘
-    │               │
-┌───▼────────┐  ┌──▼──────┐
-│ MCP Servers│  │ Direct  │
-│            │  │ API     │
-│ - Store    │  │ Calls   │
-│ - Search   │  │         │
-│ - Email    │  │ Serper  │
-│ - Calendar │  │ HF      │
-└────────────┘  └─────────┘
-```
-
-### Solution: Make Services Use MCP
-
-**Option A: Keep Current (Acceptable for Hackathon)**
-- Services can bypass MCP for performance
-- MCP is used by agents for coordination
-- **Recommendation: This is fine for now**
-
-**Option B: Force Everything Through MCP**
-- Refactor services to use `mcp_registry.search`
-- Centralize all external API calls
-- **More work, not needed for hackathon**
-
-### Verdict: ✅ Current Architecture is OK
-
-For a hackathon, having services make direct API calls is **acceptable**. The MCP servers are mainly for:
-1. Agent coordination
-2. Data persistence (Store)
-3. Email/Calendar simulation
-
----
-
-## Issue 2: MCP is Called by Workflow, NOT by AI
-
-### Problem
-
-**The AI/LLM is NOT autonomously calling MCP tools.**
-
-All MCP invocations are **hardcoded in workflow logic**:
-
-```python
-# From orchestrator.py - This is HARDCODED, not AI decision
-store = self.mcp.get_store_client()
-suppressed = await store.check_suppression("domain", domain)
-
-# From enricher.py - This is HARDCODED workflow
-search_results = await self.mcp_search.query(f"{company_name} news")
-await self.mcp_store.save_fact(fact)
-```
-
-**Current Flow:**
-```
-User Input
-    ↓
-Orchestrator (hardcoded workflow)
-    ↓
-Agent 1 → Call MCP (hardcoded)
-    ↓
-Agent 2 → Call MCP (hardcoded)
-    ↓
-Agent 3 → Call MCP (hardcoded)
-    ↓
-LLM (only for content generation)
-    ↓
-Result
-```
-
-**What's Missing:**
-```
-User Input
-    ↓
-AI Agent (autonomous decision-making)
-    ↓
-AI decides to call MCP tool A
-    ↓
-AI sees result, decides to call MCP tool B
-    ↓
-AI generates final response
-    ↓
-Result
-```
-
-### Solution Options
-
-#### Option A: Keep Current Workflow (Recommended for Hackathon)
-**Pros:**
-- ✅ Works reliably
-- ✅ Predictable behavior
-- ✅ Easier to debug
-- ✅ No complex agent framework needed
-
-**Cons:**
-- ❌ Not "true AI agents"
-- ❌ Can't adapt to new scenarios
-- ❌ Fixed pipeline logic
-
-#### Option B: Add AI Tool Calling (Advanced)
-**Requires:**
-1. Upgrade LLM to tool-calling model (Claude 3.5, GPT-4, Gemini 1.5)
-2. Expose MCP servers as OpenAI function schemas
-3. Implement agent loop with tool calling
-4. Add ReAct or similar reasoning framework
-
-**Example Implementation:**
-```python
-# Pseudo-code for AI-driven MCP calling
-async def ai_agent_loop(task: str, mcp_registry):
-    messages = [{"role": "user", "content": task}]
-
-    # Define MCP tools for AI
-    tools = [
-        {
-            "name": "search_company",
-            "description": "Search for company information",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "company_name": {"type": "string"}
-                }
-            }
-        },
-        {
-            "name": "save_prospect",
-            "description": "Save prospect data",
-            "parameters": {
-                "type": "object",
-                "properties": {
-                    "prospect_data": {"type": "object"}
-                }
-            }
-        },
-        # ... more tools
-    ]
-
-    while True:
-        # AI decides what to do next
-        response = await llm_client.chat_completion(
-            messages=messages,
-            tools=tools
-        )
-
-        # If AI wants to call a tool
-        if response.tool_calls:
-            for tool_call in response.tool_calls:
-                # Execute MCP call
-                if tool_call.name == "search_company":
-                    result = await mcp_registry.search.query(
-                        tool_call.args["company_name"]
-                    )
-                elif tool_call.name == "save_prospect":
-                    result = await mcp_registry.store.save_prospect(
-                        tool_call.args["prospect_data"]
-                    )
-
-                # Give result back to AI
-                messages.append({
-                    "role": "tool",
-                    "tool_call_id": tool_call.id,
-                    "content": str(result)
-                })
-        else:
-            # AI is done, return final answer
-            return response.content
-```
-
-### Verdict: ✅ Keep Current for Hackathon, Add AI Tool Calling Later
-
-**For hackathon:**
-- Current workflow is **good enough**
-- Shows MCP server capabilities
-- Reliable and debuggable
-
-**For production/future:**
-- Add AI tool calling with Claude 3.5 or GPT-4
-- Make agents truly autonomous
-
----
-
-## Issue 3: LLM Too Large for Free HF CPU
-
-### Problem
-
-**Current:** `Qwen/Qwen2.5-7B-Instruct` (7B parameters)
-- **Size:** 14GB memory (FP16)
-- **CPU Inference:** ~10-30 tokens/sec (slow)
-- **Cost:** Works on free tier but slow
-
-### Solution: Upgrade to Efficient CPU Models
-
-#### ✅ **Recommended: Qwen2.5-3B-Instruct** (NOW CONFIGURED)
-
-**Specs:**
-- **Size:** 3 billion parameters
-- **Memory:** ~6GB (FP16)
-- **Speed:** 2.3x faster than 7B
-- **Quality:** 90-95% of 7B quality
-- **CPU Friendly:** Optimized for efficiency
-
-**Benchmarks:**
-- MMLU: 74.0% (vs 75.1% for 7B)
-- HumanEval: 63.4% (vs 65.9% for 7B)
-- GSM8K: 82.9% (vs 85.3% for 7B)
-
-**Why this is better:**
-- ✅ 2.3x faster inference on CPU
-- ✅ Lower memory usage (fits better in HF free tier)
-- ✅ Still maintains good quality
-- ✅ Better user experience (faster responses)
-
-#### Alternative Options (if you want even faster)
-
-**Option B: Microsoft Phi-3-mini** (3.8B params)
-```python
-MODEL_NAME = "microsoft/Phi-3-mini-4k-instruct"
-```
-- **Pros:** Ultra-efficient, great for reasoning
-- **Cons:** Smaller context (4k tokens)
-
-**Option C: SmolLM2-1.7B** (1.7B params)
-```python
-MODEL_NAME = "HuggingFaceTB/SmolLM2-1.7B-Instruct"
-```
-- **Pros:** Fastest inference (5-10x faster than 7B)
-- **Cons:** Lower quality output
-
-### Performance Comparison
-
-| Model | Params | Speed (CPU) | Memory | Quality | Best For |
-|-------|--------|-------------|--------|---------|----------|
-| **Qwen2.5-3B** ⭐ | 3B | 23-70 tok/s | 6GB | 90% | **Balanced (Recommended)** |
-| Phi-3-mini | 3.8B | 20-60 tok/s | 7GB | 85% | Reasoning tasks |
-| SmolLM2-1.7B | 1.7B | 50-150 tok/s | 3GB | 75% | Ultra-fast responses |
-| Qwen2.5-7B (old) | 7B | 10-30 tok/s | 14GB | 100% | Slow on CPU |
-
-### What Changed
-
-**File:** `app/config.py`
-
-**Before:**
-```python
-MODEL_NAME = "Qwen/Qwen2.5-7B-Instruct"  # Too large
-MODEL_NAME_FALLBACK = "mistralai/Mistral-7B-Instruct-v0.2"  # Also too large
-```
-
-**After:**
-```python
-MODEL_NAME = "Qwen/Qwen2.5-3B-Instruct"  # 2.3x faster! ⚡
-MODEL_NAME_FALLBACK = "microsoft/Phi-3-mini-4k-instruct"  # Efficient backup
-```
-
----
-
-## Summary of Fixes
-
-### ✅ Fix 1: LLM Upgraded (DONE)
-- **Changed:** `Qwen2.5-7B` → `Qwen2.5-3B`
-- **Result:** 2.3x faster inference on free HF CPU
-- **Impact:** Better user experience, faster responses
-
-### ℹ️ Fix 2: Services Bypass MCP (OK for Hackathon)
-- **Status:** Acceptable - services can make direct API calls
-- **Why:** Performance and simplicity
-- **Future:** Could refactor to use MCP if needed
-
-### ℹ️ Fix 3: No AI Tool Calling (OK for Hackathon)
-- **Status:** Current workflow is deterministic
-- **Why:** Reliable, predictable, easier to debug
-- **Future:** Add AI tool calling with Claude 3.5 / GPT-4
-
----
-
-## Testing the Upgrade
-
-### Test the New LLM
-
-```python
-# Test locally
-from huggingface_hub import InferenceClient
-
-client = InferenceClient(token="your_hf_token")
-
-prompt = "Write a professional email introducing our B2B SaaS product."
-
-# Test new model
-for token in client.text_generation(
-    prompt,
-    model="Qwen/Qwen2.5-3B-Instruct",
-    max_new_tokens=200,
-    stream=True
-):
-    print(token, end="", flush=True)
-```
-
-### Expected Improvements
-
-**Speed:**
-- **Before:** 10-30 tokens/sec on CPU
-- **After:** 23-70 tokens/sec on CPU (2.3x faster)
-
-**Quality:**
-- **Before:** Excellent (100% baseline)
-- **After:** Great (90-95% of baseline)
-- **Acceptable:** Yes, for email/summary generation
-
-**User Experience:**
-- **Before:** Slow streaming, users wait
-- **After:** Fast streaming, better UX
-
----
-
-## Configuration Options
-
-You can experiment with different models using environment variables:
-
-```bash
-# Option 1: Qwen2.5-3B (recommended, default)
-MODEL_NAME=Qwen/Qwen2.5-3B-Instruct
-
-# Option 2: Phi-3-mini (ultra efficient)
-MODEL_NAME=microsoft/Phi-3-mini-4k-instruct
-
-# Option 3: SmolLM2 (fastest)
-MODEL_NAME=HuggingFaceTB/SmolLM2-1.7B-Instruct
-
-# Option 4: Keep 7B if you have GPU
-MODEL_NAME=Qwen/Qwen2.5-7B-Instruct
-```
-
----
-
-## Recommendations
-
-### For Your Hackathon
-
-✅ **Use the upgraded LLM (Qwen2.5-3B)** - Much faster on free CPU
-✅ **Keep current MCP workflow** - Works great, reliable
-✅ **Services can bypass MCP** - Direct API calls are fine
-✅ **Focus on functionality** - Make MCP servers useful for AI
-
-### For Future Production
-
-🔮 **Add AI tool calling** - Make agents autonomous
-🔮 **Centralize through MCP** - All external calls through MCP
-🔮 **Add caching** - Cache search results, embeddings
-🔮 **Use GPU** - For faster inference if available
-
----
-
-## Key Takeaways
-
-1. **Your MCP servers are good!** They work well for agent coordination
-2. **Not everything needs MCP** - Direct API calls are fine for services
-3. **LLM is now optimized** - 2.3x faster on free HF CPU
-4. **Workflow vs AI agents** - Current workflow is deterministic (OK!)
-5. **Focus on hackathon** - Don't over-engineer, ship it!
-
----
-
-## Next Steps
-
-1. ✅ **Test the new LLM** - Verify it works on HF Spaces
-2. ✅ **Deploy to HF Spaces** - Should build successfully now
-3. ✅ **Monitor performance** - Check if CPU usage is acceptable
-4. 📝 **Document MCP capabilities** - Show what AI can do with your MCP servers
-5. 🎯 **Demo the pipeline** - Show end-to-end AI agent workflow
-
-Good luck with the hackathon! 🚀

MCP_ENTERPRISE_UPGRADE_GUIDE.md

@@ -1,928 +0,0 @@
-# MCP Enterprise Upgrade Guide
-
-## Overview
-
-This guide documents the comprehensive enterprise-grade upgrades to the CX AI Agent MCP (Model Context Protocol) servers. The upgrades transform the basic MCP implementation into production-ready, scalable, and secure enterprise infrastructure.
-
----
-
-## Table of Contents
-
-1. [Architecture Overview](#architecture-overview)
-2. [Database Layer](#database-layer)
-3. [Authentication & Authorization](#authentication--authorization)
-4. [Observability](#observability)
-5. [Deployment](#deployment)
-6. [Configuration](#configuration)
-7. [Migration Guide](#migration-guide)
-8. [API Reference](#api-reference)
-
----
-
-## Architecture Overview
-
-### Before: Basic JSON Storage
-```
-┌─────────────────────┐
-│   MCP Server        │
-│   (HTTP/JSON-RPC)   │
-│                     │
-│   ┌─────────────┐   │
-│   │ JSON Files  │   │
-│   └─────────────┘   │
-└─────────────────────┘
-```
-
-### After: Enterprise Architecture
-```
-┌──────────────────────────────────────────┐
-│       Load Balancer / API Gateway        │
-└──────────────┬───────────────────────────┘
-               │
-    ┌──────────┼──────────┐
-    │          │          │
-┌───▼───┐  ┌──▼────┐  ┌──▼────┐
-│ MCP   │  │ MCP   │  │ MCP   │
-│Server │  │Server │  │Server │
-│  #1   │  │  #2   │  │  #3   │
-└───┬───┘  └──┬────┘  └──┬────┘
-    │         │          │
-    └─────────┼──────────┘
-              │
-    ┌─────────▼──────────┐
-    │                    │
-    │   ┌────────────┐   │
-    │   │PostgreSQL  │   │
-    │   │  +ACID     │   │
-    │   └────────────┘   │
-    │                    │
-    │   ┌────────────┐   │
-    │   │   Redis    │   │
-    │   │  (Cache)   │   │
-    │   └────────────┘   │
-    │                    │
-    │   ┌────────────┐   │
-    │   │Prometheus  │   │
-    │   │(Metrics)   │   │
-    │   └────────────┘   │
-    └────────────────────┘
-```
-
----
-
-## Database Layer
-
-### Features
-
-✅ **SQLAlchemy ORM with Async Support**
-- Async database operations with `asyncio` and `asyncpg`
-- Type-safe models with SQLAlchemy 2.0
-- Automatic relationship loading
-
-✅ **Multi-Database Support**
-- SQLite (development/single-instance)
-- PostgreSQL (production/multi-instance)
-- MySQL (optional)
-
-✅ **Enterprise Schema Design**
-- Proper foreign keys and relationships
-- Comprehensive indexes for performance
-- Audit trail with `AuditLog` table
-- Multi-tenancy support built-in
-
-✅ **Connection Pooling**
-- Configurable pool size
-- Pool pre-ping for connection health
-- Automatic connection recycling
-
-✅ **Database Migrations**
-- Alembic integration for schema versioning
-- Automatic migration generation
-- Rollback support
-
-### Database Models
-
-#### Core Models
-- `Company` - Company/account information
-- `Prospect` - Sales prospects with scoring
-- `Contact` - Decision-maker contacts
-- `Fact` - Enrichment data and insights
-- `Activity` - All prospect interactions (emails, calls, meetings)
-- `Suppression` - Compliance (opt-outs, bounces)
-- `Handoff` - AI-to-human transitions
-- `AuditLog` - Compliance and security audit trail
-
-#### Key Features
-```python
-# Multi-tenancy
-tenant_id: Optional[str]  # On all tenant-aware models
-
-# Automatic timestamps
-created_at: datetime
-updated_at: datetime
-
-# Soft deletes
-is_active: bool
-
-# Rich relationships
-company.prospects  # All prospects for a company
-prospect.activities  # All activities for a prospect
-```
-
-### Usage
-
-#### Initialize Database
-```python
-from mcp.database import init_database
-
-# Create tables
-await init_database()
-```
-
-#### Using Repositories
-```python
-from mcp.database import get_db_manager, CompanyRepository
-
-# Get database session
-db_manager = get_db_manager()
-async with db_manager.get_session() as session:
-    repo = CompanyRepository(session, tenant_id="acme_corp")
-
-    # Create company
-    company = await repo.create({
-        "id": "shopify",
-        "name": "Shopify",
-        "domain": "shopify.com",
-        "industry": "E-commerce",
-        "employee_count": 10000
-    })
-
-    # Get company
-    company = await repo.get_by_domain("shopify.com")
-
-    # List companies
-    companies = await repo.list(industry="E-commerce", limit=100)
-```
-
-#### Using Database Store Service
-```python
-from mcp.database import DatabaseStoreService
-
-# Create service instance
-store = DatabaseStoreService(tenant_id="acme_corp")
-
-# Save prospect
-await store.save_prospect({
-    "id": "prospect_123",
-    "company_id": "shopify",
-    "fit_score": 85.0,
-    "status": "new"
-})
-
-# Get prospect
-prospect = await store.get_prospect("prospect_123")
-
-# List prospects
-prospects = await store.list_prospects()
-```
-
-### Migrations
-
-#### Create Migration
-```bash
-python -m mcp.database.migrate create "add_new_field"
-```
-
-#### Apply Migrations
-```bash
-# Upgrade to latest
-python -m mcp.database.migrate upgrade
-
-# Upgrade to specific revision
-python -m mcp.database.migrate upgrade abc123
-```
-
-#### Rollback
-```bash
-python -m mcp.database.migrate downgrade <revision>
-```
-
-### Configuration
-
-```bash
-# Database URL (SQLite)
-DATABASE_URL=sqlite+aiosqlite:///./data/cx_agent.db
-
-# Database URL (PostgreSQL)
-DATABASE_URL=postgresql+asyncpg://user:password@localhost/cx_agent
-
-# Connection pool settings
-DB_POOL_SIZE=20
-DB_MAX_OVERFLOW=10
-DB_POOL_TIMEOUT=30
-DB_POOL_RECYCLE=3600
-DB_POOL_PRE_PING=true
-
-# SQLite WAL mode (better concurrency)
-SQLITE_WAL=true
-
-# Echo SQL (debugging)
-DB_ECHO=false
-```
-
----
-
-## Authentication & Authorization
-
-### Features
-
-✅ **API Key Authentication**
-- Secure key generation (`mcp_<32-char-hex>`)
-- SHA-256 key hashing (never store plain keys)
-- Key expiration support
-- Per-key rate limiting
-- Multiple authentication methods (header, bearer token)
-
-✅ **Request Signing (HMAC)**
-- HMAC-SHA256 request signing
-- Timestamp verification (5-minute window)
-- Replay attack prevention
-
-✅ **Rate Limiting**
-- Token bucket algorithm
-- Per-client rate limiting
-- Per-endpoint rate limiting
-- Global rate limiting (optional)
-- Redis-based distributed rate limiting
-
-✅ **Multi-Tenancy**
-- Tenant isolation at data layer
-- Tenant-specific API keys
-- Tenant-aware rate limits
-
-### API Key Authentication
-
-#### Generate API Key
-```python
-from mcp.auth import get_key_manager
-
-manager = get_key_manager()
-
-# Generate new key
-plain_key, api_key_obj = manager.create_key(
-    name="Production API Key",
-    tenant_id="acme_corp",
-    expires_in_days=365,
-    rate_limit=1000  # requests per minute
-)
-
-# Save plain_key securely! It's shown only once
-print(f"API Key: {plain_key}")
-```
-
-#### Validate API Key
-```python
-api_key = manager.validate_key(plain_key)
-if api_key and api_key.is_valid():
-    print(f"Valid key: {api_key.name}")
-```
-
-#### Revoke API Key
-```python
-manager.revoke_key(key_hash)
-```
-
-### Using API Keys
-
-#### HTTP Header
-```bash
-curl -H "X-API-Key: mcp_abc123..." http://localhost:9004/rpc
-```
-
-#### Bearer Token
-```bash
-curl -H "Authorization: Bearer mcp_abc123..." http://localhost:9004/rpc
-```
-
-### Request Signing
-
-```python
-from mcp.auth import RequestSigningAuth
-import time
-import json
-
-signer = RequestSigningAuth(secret_key="your_secret_key")
-
-# Sign request
-method = "POST"
-path = "/rpc"
-body = json.dumps({"method": "store.get_prospect", "params": {"id": "123"}})
-timestamp = datetime.utcnow().isoformat() + "Z"
-
-signature = signer.sign_request(method, path, body, timestamp)
-
-# Send request with signature
-headers = {
-    "X-Signature": signature,
-    "X-Timestamp": timestamp,
-    "Content-Type": "application/json"
-}
-```
-
-### Rate Limiting
-
-#### Configure Limits
-```python
-from mcp.auth import get_rate_limiter
-
-limiter = get_rate_limiter()
-
-# Set endpoint-specific limits
-limiter.endpoint_limits["/rpc"] = {
-    "capacity": 100,  # Max 100 requests
-    "refill_rate": 10.0  # Refill 10 per second
-}
-```
-
-#### Check Rate Limit
-```python
-allowed, retry_after = await limiter.check_rate_limit(request)
-if not allowed:
-    print(f"Rate limited! Retry after {retry_after} seconds")
-```
-
-### Configuration
-
-```bash
-# Primary API key
-MCP_API_KEY=mcp_your_primary_key_here
-
-# Additional API keys (comma-separated)
-MCP_API_KEYS=mcp_key1,mcp_key2,mcp_key3
-
-# Secret key for request signing
-MCP_SECRET_KEY=your_hmac_secret_key_here
-```
-
----
-
-## Observability
-
-### Features
-
-✅ **Structured Logging**
-- JSON logging for production
-- Correlation ID tracking
-- Request/response logging
-- Performance timing
-- ELK/Datadog/Splunk compatible
-
-✅ **Prometheus Metrics**
-- HTTP request metrics (count, duration, size)
-- MCP-specific metrics
-- Business metrics (prospects, contacts, emails)
-- Database metrics
-- Cache metrics
-- Authentication metrics
-- Error tracking
-
-✅ **Performance Tracking**
-- Automatic request timing
-- MCP call duration tracking
-- Database query performance
-- Context managers for custom tracking
-
-### Structured Logging
-
-#### Configuration
-```python
-from mcp.observability import configure_logging
-
-# Development (human-readable)
-configure_logging(level="DEBUG", json_output=False)
-
-# Production (JSON)
-configure_logging(level="INFO", json_output=True)
-```
-
-#### Usage
-```python
-from mcp.observability import get_logger, set_correlation_id
-
-logger = get_logger(__name__)
-
-# Set correlation ID
-set_correlation_id("request-abc-123")
-
-# Log messages
-logger.info("Processing request", user_id="user123", action="create_prospect")
-logger.warning("Rate limit approaching", remaining=10)
-logger.error("Database error", exc_info=True)
-```
-
-#### Log Output (Development)
-```
-2025-01-20 10:30:15 [info     ] Processing request [cx_ai_agent] correlation_id=request-abc-123 user_id=user123 action=create_prospect
-```
-
-#### Log Output (Production JSON)
-```json
-{
-  "event": "Processing request",
-  "timestamp": "2025-01-20T10:30:15",
-  "level": "info",
-  "correlation_id": "request-abc-123",
-  "service": "cx_ai_agent",
-  "environment": "production",
-  "user_id": "user123",
-  "action": "create_prospect"
-}
-```
-
-### Prometheus Metrics
-
-#### Available Metrics
-
-**HTTP Metrics:**
-- `mcp_http_requests_total` - Total requests by method, path, status
-- `mcp_http_request_duration_seconds` - Request duration histogram
-- `mcp_http_request_size_bytes` - Request size
-- `mcp_http_response_size_bytes` - Response size
-
-**MCP Metrics:**
-- `mcp_calls_total` - Total MCP calls by server, method, status
-- `mcp_call_duration_seconds` - MCP call duration histogram
-
-**Business Metrics:**
-- `mcp_prospects_total` - Total prospects by status, tenant
-- `mcp_contacts_total` - Total contacts by tenant
-- `mcp_companies_total` - Total companies by tenant
-- `mcp_emails_sent_total` - Total emails sent
-- `mcp_meetings_booked_total` - Total meetings booked
-
-**Database Metrics:**
-- `mcp_db_connections` - Active database connections
-- `mcp_db_queries_total` - Total queries by operation, table
-- `mcp_db_query_duration_seconds` - Query duration histogram
-
-**Cache Metrics:**
-- `mcp_cache_hits_total` - Total cache hits
-- `mcp_cache_misses_total` - Total cache misses
-
-**Auth Metrics:**
-- `mcp_auth_attempts_total` - Auth attempts by result
-- `mcp_rate_limit_exceeded_total` - Rate limit exceeded events
-
-#### Usage
-```python
-from mcp.observability import get_metrics
-
-metrics = get_metrics()
-
-# Record HTTP request
-metrics.record_http_request(
-    method="POST",
-    path="/rpc",
-    status=200,
-    duration=0.05
-)
-
-# Record MCP call
-metrics.record_mcp_call(
-    server="search",
-    method="search.query",
-    duration=0.1,
-    success=True
-)
-
-# Update business metrics
-metrics.prospects_total.labels(status="qualified", tenant_id="acme").set(150)
-```
-
-#### Metrics Endpoint
-```bash
-curl http://localhost:9004/metrics
-```
-
-#### Grafana Dashboard
-
-Example Prometheus queries:
-```promql
-# Request rate
-rate(mcp_http_requests_total[5m])
-
-# P95 latency
-histogram_quantile(0.95, rate(mcp_http_request_duration_seconds_bucket[5m]))
-
-# Error rate
-rate(mcp_http_requests_total{status=~"5.."}[5m])
-
-# MCP call success rate
-rate(mcp_calls_total{status="success"}[5m]) / rate(mcp_calls_total[5m])
-```
-
-### Configuration
-
-```bash
-# Service name (for logging and metrics)
-SERVICE_NAME=cx_ai_agent
-
-# Environment
-ENVIRONMENT=production
-
-# Version
-VERSION=2.0.0
-
-# Log level
-LOG_LEVEL=INFO
-```
-
----
-
-## Deployment
-
-### Development (Local)
-
-#### 1. Install Dependencies
-```bash
-pip install -r requirements.txt
-```
-
-#### 2. Set Environment Variables
-```bash
-export DATABASE_URL=sqlite+aiosqlite:///./data/cx_agent.db
-export MCP_API_KEY=mcp_dev_key_for_testing_only
-export LOG_LEVEL=DEBUG
-```
-
-#### 3. Initialize Database
-```python
-python -c "
-import asyncio
-from mcp.database import init_database
-asyncio.run(init_database())
-"
-```
-
-#### 4. Start MCP Server
-```bash
-python mcp/servers/store_server_enterprise.py
-```
-
-### Production (Docker)
-
-#### Dockerfile
-```dockerfile
-FROM python:3.11-slim
-
-WORKDIR /app
-
-# Install dependencies
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Copy application
-COPY . .
-
-# Initialize database
-RUN python -c "import asyncio; from mcp.database import init_database; asyncio.run(init_database())"
-
-# Expose port
-EXPOSE 9004
-
-# Health check
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-  CMD curl -f http://localhost:9004/health || exit 1
-
-# Run server
-CMD ["python", "mcp/servers/store_server_enterprise.py"]
-```
-
-#### docker-compose.yml
-```yaml
-version: '3.8'
-
-services:
-  postgres:
-    image: postgres:15-alpine
-    environment:
-      POSTGRES_DB: cx_agent
-      POSTGRES_USER: cx_user
-      POSTGRES_PASSWORD: ${DB_PASSWORD}
-    volumes:
-      - postgres_data:/var/lib/postgresql/data
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U cx_user"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-
-  redis:
-    image: redis:7-alpine
-    healthcheck:
-      test: ["CMD", "redis-cli", "ping"]
-      interval: 10s
-      timeout: 3s
-      retries: 3
-
-  mcp-store:
-    build: .
-    ports:
-      - "9004:9004"
-    environment:
-      DATABASE_URL: postgresql+asyncpg://cx_user:${DB_PASSWORD}@postgres/cx_agent
-      REDIS_URL: redis://redis:6379/0
-      MCP_API_KEY: ${MCP_API_KEY}
-      MCP_SECRET_KEY: ${MCP_SECRET_KEY}
-      SERVICE_NAME: mcp-store
-      ENVIRONMENT: production
-      LOG_LEVEL: INFO
-    depends_on:
-      postgres:
-        condition: service_healthy
-      redis:
-        condition: service_healthy
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://localhost:9004/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 3
-
-  prometheus:
-    image: prom/prometheus:latest
-    volumes:
-      - ./prometheus.yml:/etc/prometheus/prometheus.yml
-      - prometheus_data:/prometheus
-    ports:
-      - "9090:9090"
-    command:
-      - '--config.file=/etc/prometheus/prometheus.yml'
-
-  grafana:
-    image: grafana/grafana:latest
-    ports:
-      - "3000:3000"
-    environment:
-      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD}
-    volumes:
-      - grafana_data:/var/lib/grafana
-
-volumes:
-  postgres_data:
-  prometheus_data:
-  grafana_data:
-```
-
-### Kubernetes Deployment
-
-#### deployment.yaml
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: mcp-store
-  labels:
-    app: mcp-store
-spec:
-  replicas: 3
-  selector:
-    matchLabels:
-      app: mcp-store
-  template:
-    metadata:
-      labels:
-        app: mcp-store
-    spec:
-      containers:
-      - name: mcp-store
-        image: cx-agent/mcp-store:latest
-        ports:
-        - containerPort: 9004
-        env:
-        - name: DATABASE_URL
-          valueFrom:
-            secretKeyRef:
-              name: db-credentials
-              key: url
-        - name: MCP_API_KEY
-          valueFrom:
-            secretKeyRef:
-              name: mcp-credentials
-              key: api_key
-        - name: REDIS_URL
-          value: redis://redis-service:6379/0
-        resources:
-          requests:
-            memory: "256Mi"
-            cpu: "250m"
-          limits:
-            memory: "512Mi"
-            cpu: "500m"
-        livenessProbe:
-          httpGet:
-            path: /health
-            port: 9004
-          initialDelaySeconds: 30
-          periodSeconds: 10
-        readinessProbe:
-          httpGet:
-            path: /health
-            port: 9004
-          initialDelaySeconds: 5
-          periodSeconds: 5
----
-apiVersion: v1
-kind: Service
-metadata:
-  name: mcp-store-service
-spec:
-  selector:
-    app: mcp-store
-  ports:
-  - port: 9004
-    targetPort: 9004
-  type: LoadBalancer
-```
-
----
-
-## Configuration
-
-### Environment Variables
-
-#### Database
-```bash
-DATABASE_URL=postgresql+asyncpg://user:pass@localhost/cx_agent
-DB_POOL_SIZE=20
-DB_MAX_OVERFLOW=10
-DB_POOL_TIMEOUT=30
-DB_POOL_RECYCLE=3600
-DB_POOL_PRE_PING=true
-SQLITE_WAL=true
-DB_ECHO=false
-```
-
-#### Authentication
-```bash
-MCP_API_KEY=mcp_primary_key_here
-MCP_API_KEYS=mcp_key1,mcp_key2,mcp_key3
-MCP_SECRET_KEY=hmac_secret_key_here
-```
-
-#### Observability
-```bash
-SERVICE_NAME=cx_ai_agent
-ENVIRONMENT=production
-VERSION=2.0.0
-LOG_LEVEL=INFO
-```
-
-#### Redis (Optional)
-```bash
-REDIS_URL=redis://localhost:6379/0
-```
-
----
-
-## Migration Guide
-
-### From JSON to Database
-
-#### 1. Backup JSON Files
-```bash
-cp data/prospects.json data/prospects.json.backup
-cp data/companies_store.json data/companies_store.json.backup
-cp data/contacts.json data/contacts.json.backup
-```
-
-#### 2. Initialize Database
-```bash
-python -m mcp.database.migrate upgrade
-```
-
-#### 3. Migrate Data
-```python
-import json
-import asyncio
-from pathlib import Path
-from mcp.database import DatabaseStoreService
-
-async def migrate():
-    store = DatabaseStoreService()
-
-    # Migrate prospects
-    with open("data/prospects.json") as f:
-        prospects = json.load(f)
-        for prospect in prospects:
-            await store.save_prospect(prospect)
-
-    # Migrate companies
-    with open("data/companies_store.json") as f:
-        companies = json.load(f)
-        for company in companies:
-            await store.save_company(company)
-
-    # Migrate contacts
-    with open("data/contacts.json") as f:
-        contacts = json.load(f)
-        for contact in contacts:
-            await store.save_contact(contact)
-
-    print("Migration completed!")
-
-asyncio.run(migrate())
-```
-
-#### 4. Test
-```bash
-# Test database access
-python -c "
-import asyncio
-from mcp.database import DatabaseStoreService
-
-async def test():
-    store = DatabaseStoreService()
-    prospects = await store.list_prospects()
-    print(f'Migrated {len(prospects)} prospects')
-
-asyncio.run(test())
-"
-```
-
-#### 5. Switch to Database Backend
-```bash
-# Update environment
-export USE_IN_MEMORY_MCP=false
-export DATABASE_URL=sqlite+aiosqlite:///./data/cx_agent.db
-```
-
----
-
-## API Reference
-
-### MCP Store Methods
-
-#### `store.save_prospect(prospect: Dict) -> str`
-Save or update a prospect.
-
-#### `store.get_prospect(id: str) -> Optional[Dict]`
-Get a prospect by ID.
-
-#### `store.list_prospects() -> List[Dict]`
-List all prospects (tenant-filtered).
-
-#### `store.save_company(company: Dict) -> str`
-Save or update a company.
-
-#### `store.get_company(id: str) -> Optional[Dict]`
-Get a company by ID.
-
-#### `store.save_contact(contact: Dict) -> str`
-Save a contact.
-
-#### `store.list_contacts_by_domain(domain: str) -> List[Dict]`
-List contacts by email domain.
-
-#### `store.check_suppression(type: str, value: str) -> bool`
-Check if email/domain is suppressed.
-
-#### `store.save_handoff(packet: Dict) -> str`
-Save a handoff packet.
-
-#### `store.clear_all() -> str`
-Clear all data (use with caution!).
-
----
-
-## Next Steps
-
-1. **Review Performance**: Monitor metrics in Grafana
-2. **Scale Up**: Add more replicas in Kubernetes
-3. **Add More Features**:
-   - Real email sending (AWS SES)
-   - Real calendar integration (Google/Outlook)
-   - Advanced analytics
-   - Machine learning scoring
-4. **Security Hardening**:
-   - TLS/SSL certificates
-   - WAF (Web Application Firewall)
-   - DDoS protection
-5. **Compliance**:
-   - GDPR compliance features
-   - Data retention policies
-   - Privacy controls
-
----
-
-## Support
-
-For issues or questions:
-1. Check logs: `docker logs mcp-store`
-2. Check metrics: `http://localhost:9004/metrics`
-3. Check health: `http://localhost:9004/health`
-
----
-
-## License
-
-Enterprise License - All Rights Reserved

MCP_HACKATHON_GUIDE.md

@@ -1,376 +0,0 @@
-# MCP Servers for Hugging Face Spaces - Hackathon Guide
-
-## What You Actually Need
-
-This is a **Hugging Face Space** for an **MCP hackathon**. The MCP servers should:
-
-1. ✅ **Work with AI agents** (primary goal)
-2. ✅ **Be simple and deployable** on HF Spaces
-3. ✅ **Provide useful functionality** to AI
-4. ❌ **NOT be over-engineered** with enterprise features
-
----
-
-## What's Currently Working
-
-### ✅ 4 MCP Servers (In-Memory Mode)
-
-Your existing MCP servers are **already functional** and work great for HF Spaces:
-
-1. **Search Server** (port 9001) - Web search via Serper API
-2. **Email Server** (port 9002) - Email thread management
-3. **Calendar Server** (port 9003) - Meeting scheduling
-4. **Store Server** (port 9004) - Data persistence
-
-**Location:** `mcp/servers/` and `mcp/in_memory_services.py`
-
-### ✅ In-Memory Mode (Perfect for HF Spaces)
-
-The `USE_IN_MEMORY_MCP=true` setting (default) means:
-- ✅ No separate server processes needed
-- ✅ Everything runs in single Gradio app
-- ✅ No port binding issues
-- ✅ Works perfectly in HF Spaces sandbox
-
----
-
-## What I Added (That You Can Use)
-
-### 1. SQLite Database (Optional Upgrade)
-
-**If you want better data persistence:**
-
-```python
-# Instead of JSON files, use SQLite
-from mcp.database import init_database, DatabaseStoreService
-
-# Initialize once
-await init_database()
-
-# Use in your code
-store = DatabaseStoreService()
-await store.save_prospect(prospect_data)
-prospects = await store.list_prospects()
-```
-
-**Benefits:**
-- ✅ Faster queries (10-100x)
-- ✅ Proper relationships
-- ✅ No file corruption
-- ✅ Still works in HF Spaces (SQLite is file-based)
-
-**Config:**
-```bash
-DATABASE_URL=sqlite+aiosqlite:///./data/cx_agent.db
-```
-
-### 2. Simple Authentication (Optional)
-
-**If you want to protect your MCP endpoints:**
-
-```python
-from mcp.auth import APIKeyManager
-
-# Generate an API key
-manager = APIKeyManager()
-key, _ = manager.create_key("My App")
-print(f"API Key: {key}")
-
-# Validate requests
-api_key = manager.validate_key(request_key)
-if not api_key:
-    return {"error": "Unauthorized"}
-```
-
-**Config:**
-```bash
-MCP_API_KEY=mcp_your_key_here
-```
-
----
-
-## What You Should IGNORE
-
-### ❌ Don't Use These (Over-engineered)
-
-1. **PostgreSQL** - You don't need it in HF Spaces
-2. **Redis** - Overkill for a hackathon
-3. **Celery** - Not needed
-4. **Prometheus/Grafana** - HF has monitoring
-5. **Alembic migrations** - Just use SQLite directly
-6. **Rate limiting** - Not needed for hackathon
-7. **RBAC/Audit logs** - Over-engineered
-
-### Just Use What You Have
-
-Your **current in-memory MCP servers are perfect** for the hackathon!
-
----
-
-## Recommended Setup for HF Spaces
-
-### Keep It Simple
-
-```python
-# app.py (your existing Gradio app)
-import os
-os.environ["USE_IN_MEMORY_MCP"] = "true"  # Use in-memory mode
-
-from mcp.registry import get_mcp_registry
-from app.orchestrator import Orchestrator
-
-# Create MCP registry (in-memory mode)
-registry = get_mcp_registry()
-
-# Create orchestrator
-orchestrator = Orchestrator(registry)
-
-# Your Gradio interface
-def run_pipeline(company_name, num_prospects):
-    async for event in orchestrator.run_pipeline(company_name, num_prospects):
-        yield event
-
-# Gradio UI
-import gradio as gr
-demo = gr.Interface(fn=run_pipeline, ...)
-demo.launch()
-```
-
-### Required Environment Variables
-
-```bash
-# API Keys
-HF_API_TOKEN=your_huggingface_token
-SERPER_API_KEY=your_serper_key
-
-# MCP Mode (in-memory)
-USE_IN_MEMORY_MCP=true
-```
-
----
-
-## How AI Agents Use Your MCP Servers
-
-The AI agents call your MCP servers through the registry:
-
-```python
-# In your agent code
-class Enricher:
-    def __init__(self, mcp_registry):
-        self.search = mcp_registry.search  # Search MCP
-        self.store = mcp_registry.store    # Store MCP
-
-    async def run(self, prospect):
-        # Use MCP search
-        results = await self.search.query(f"{prospect.company_name} news")
-
-        # Store facts
-        for result in results:
-            await self.store.save_fact({
-                "id": f"fact_{uuid.uuid4()}",
-                "company_id": prospect.company_id,
-                "fact_type": "news",
-                "content": result["text"],
-                "source_url": result.get("url")
-            })
-```
-
----
-
-## Quick Fixes for Your Build
-
-### 1. Use Simplified requirements.txt
-
-```txt
-# Gradio Interface (REQUIRED)
-gradio==5.5.0
-
-# HTTP and Web
-requests>=2.31.0
-aiohttp>=3.9.1
-
-# Web Scraping (REQUIRED)
-beautifulsoup4>=4.12.0
-lxml>=4.9.0
-
-# Data handling
-python-dotenv>=1.0.0
-pandas>=2.1.4
-email-validator>=2.1.0
-
-# Vector Store and Embeddings
-sentence-transformers>=2.3.1
-faiss-cpu>=1.7.4
-numpy>=1.24.3,<2.0.0
-
-# Database (Optional - only if you want SQLite upgrade)
-sqlalchemy>=2.0.0
-aiosqlite>=0.19.0
-
-# HuggingFace dependencies
-huggingface-hub>=0.34.0,<1.0
-```
-
-### 2. Remove Enterprise Features
-
-You can **delete** or **ignore** these files if you don't need them:
-
-```bash
-# Optional - only if you want SQLite
-mcp/database/models.py
-mcp/database/engine.py
-mcp/database/repositories.py
-mcp/database/store_service.py
-
-# Not needed for HF Spaces
-mcp/auth/
-mcp/observability/
-alembic.ini
-migrations/
-```
-
-### 3. Just Use What Works
-
-Your existing code in:
-- `mcp/in_memory_services.py` ✅ **Keep this!**
-- `mcp/registry.py` ✅ **Keep this!**
-- `mcp/servers/*.py` ✅ **Keep this!**
-
-These are **perfect for HF Spaces** and work great with AI agents.
-
----
-
-## What Makes Good MCP Servers for AI
-
-Focus on making your MCP servers **useful for AI agents**:
-
-### ✅ Good MCP Features
-
-1. **Search** - Let AI find information
-   ```python
-   results = await mcp.search.query("company news")
-   ```
-
-2. **Store** - Let AI persist data
-   ```python
-   await mcp.store.save_prospect(prospect)
-   prospects = await mcp.store.list_prospects()
-   ```
-
-3. **Email** - Let AI track conversations
-   ```python
-   thread_id = await mcp.email.send(to, subject, body)
-   thread = await mcp.email.get_thread(prospect_id)
-   ```
-
-4. **Calendar** - Let AI schedule meetings
-   ```python
-   slots = await mcp.calendar.suggest_slots()
-   ics = await mcp.calendar.generate_ics(slot)
-   ```
-
-### ❌ Don't Overcomplicate
-
-- ❌ Don't add authentication if it's just for demo
-- ❌ Don't use PostgreSQL for a hackathon
-- ❌ Don't add complex rate limiting
-- ❌ Don't over-engineer with enterprise patterns
-
----
-
-## Deployment to HF Spaces
-
-### Current Setup (Works Great!)
-
-```yaml
-# Your space.yaml or config
-title: CX AI Agent
-emoji: 🤖
-colorFrom: blue
-colorTo: green
-sdk: gradio
-sdk_version: 5.5.0
-app_file: app.py
-pinned: false
-```
-
-### Environment Variables in HF Spaces
-
-Go to Settings → Variables:
-
-```bash
-HF_API_TOKEN=your_token
-SERPER_API_KEY=your_serper_key
-USE_IN_MEMORY_MCP=true
-```
-
----
-
-## Testing Your MCP Servers
-
-### Test In-Memory Mode
-
-```python
-import asyncio
-from mcp.registry import get_mcp_registry
-
-async def test():
-    registry = get_mcp_registry()
-
-    # Test search
-    results = await registry.search.query("Shopify news")
-    print(f"Found {len(results)} results")
-
-    # Test store
-    await registry.store.save_prospect({
-        "id": "test_123",
-        "company_id": "shopify",
-        "status": "new"
-    })
-    prospects = await registry.store.list_prospects()
-    print(f"Stored {len(prospects)} prospects")
-
-asyncio.run(test())
-```
-
----
-
-## Summary
-
-### ✅ What to Keep
-
-1. **In-memory MCP servers** - Perfect for HF Spaces
-2. **Simple requirements.txt** - No over-engineered dependencies
-3. **Existing agent pipeline** - Works great with MCP
-
-### ❌ What to Remove/Ignore
-
-1. Enterprise database features (unless you want SQLite)
-2. Authentication (unless you need it)
-3. Observability/metrics (HF has this)
-4. Complex deployment configs
-
-### 🎯 Focus On
-
-Making your MCP servers **useful for AI agents**:
-- Good search results
-- Reliable data storage
-- Clear email tracking
-- Simple calendar management
-
-That's it! Keep it simple, keep it functional, and focus on the **AI agent capabilities**.
-
----
-
-## Need Help?
-
-If you have issues:
-
-1. **Check logs** in HF Spaces console
-2. **Test locally** first: `gradio app.py`
-3. **Use in-memory mode**: `USE_IN_MEMORY_MCP=true`
-4. **Keep requirements simple**: Only what you need
-
-Your **current implementation is already good** for the hackathon! The enterprise upgrades are optional enhancements, not requirements.
-
-Good luck with the hackathon! 🚀

MCP_PROPER_IMPLEMENTATION.md

@@ -1,523 +0,0 @@
-## ✅ PROPER MCP Implementation - AI Autonomous Tool Calling
-
-This is the **correct** MCP implementation for the hackathon where:
-- ✅ **AI calls MCP servers autonomously**
-- ✅ **No hardcoded workflow**
-- ✅ **Claude 3.5 Sonnet with tool calling**
-- ✅ **Proper Model Context Protocol**
-
----
-
-## 🎯 What Changed
-
-### ❌ Before (Hardcoded Workflow)
-
-```python
-# BAD: Orchestrator decides everything
-prospects = await hunter.run()
-for prospect in prospects:
-    await enricher.run(prospect)  # Hardcoded call
-    await contactor.run(prospect)  # Hardcoded call
-    await writer.run(prospect)    # Hardcoded call
-```
-
-**Problems:**
-- Fixed pipeline
-- No AI decision-making
-- Can't adapt to different scenarios
-- Not true MCP usage
-
-### ✅ After (AI Autonomous)
-
-```python
-# GOOD: AI decides what to do
-agent = AutonomousMCPAgent(mcp_registry, api_key)
-
-async for event in agent.run("Research Shopify and create prospect"):
-    # AI autonomously:
-    # 1. Searches for Shopify info
-    # 2. Saves company data
-    # 3. Saves facts
-    # 4. Creates prospect
-    # All decided by AI, not hardcoded!
-    print(event)
-```
-
-**Benefits:**
-- ✅ AI makes decisions
-- ✅ Adapts to task
-- ✅ True MCP demonstration
-- ✅ Can handle any task
-
----
-
-## 🏗️ Architecture
-
-### MCP Tool Definitions
-
-**File:** `mcp/tools/definitions.py`
-
-Defines all MCP servers as tools the AI can call:
-
-```python
-MCP_TOOLS = [
-    {
-        "name": "search_web",
-        "description": "Search the web for information",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "query": {"type": "string"}
-            },
-            "required": ["query"]
-        }
-    },
-    {
-        "name": "save_prospect",
-        "description": "Save a prospect to database",
-        "input_schema": {
-            "type": "object",
-            "properties": {
-                "prospect_id": {"type": "string"},
-                "company_name": {"type": "string"},
-                ...
-            }
-        }
-    },
-    # ... 15 more tools
-]
-```
-
-**Tools Available:**
-- 🔍 **Search**: `search_web`, `search_news`
-- 💾 **Store**: `save_prospect`, `get_prospect`, `list_prospects`, `save_company`, `get_company`, `save_fact`, `save_contact`, `list_contacts_by_domain`, `check_suppression`
-- 📧 **Email**: `send_email`, `get_email_thread`
-- 📅 **Calendar**: `suggest_meeting_slots`, `generate_calendar_invite`
-
-### Autonomous Agent
-
-**File:** `mcp/agents/autonomous_agent.py`
-
-AI agent that uses Claude 3.5 Sonnet to:
-1. Understand the task
-2. Decide which MCP tools to call
-3. Execute tools autonomously
-4. Continue until complete
-
-```python
-class AutonomousMCPAgent:
-    def __init__(self, mcp_registry, api_key):
-        self.client = AsyncAnthropic(api_key=api_key)
-        self.model = "claude-3-5-sonnet-20241022"
-        self.mcp_registry = mcp_registry
-
-    async def run(self, task: str):
-        """AI autonomously completes the task"""
-        messages = [{"role": "user", "content": task}]
-
-        while not_done:
-            # AI decides what to do next
-            response = await self.client.messages.create(
-                model=self.model,
-                messages=messages,
-                tools=MCP_TOOLS  # AI knows about all tools
-            )
-
-            # AI wants to call a tool?
-            if response.tool_calls:
-                for tool in response.tool_calls:
-                    # Execute MCP tool
-                    result = await self._execute_mcp_tool(
-                        tool.name,
-                        tool.input
-                    )
-
-                    # Give result back to AI
-                    messages.append({
-                        "role": "tool",
-                        "content": result
-                    })
-            else:
-                # AI is done!
-                return response.content
-```
-
-### Gradio App
-
-**File:** `app_mcp_autonomous.py`
-
-New Gradio interface for autonomous agent:
-
-```python
-def run_autonomous_agent(task: str, api_key: str):
-    agent = AutonomousMCPAgent(mcp_registry, api_key)
-
-    async for event in agent.run(task):
-        # Show progress
-        yield f"{event['message']}\n{event.get('tool', '')}"
-```
-
----
-
-## 🚀 How to Use
-
-### 1. Set Environment Variables
-
-```bash
-# Required for Claude API
-export ANTHROPIC_API_KEY=sk-ant-...
-
-# Required for web search
-export SERPER_API_KEY=your_serper_key
-
-# Optional: Use in-memory MCP (recommended for HF Spaces)
-export USE_IN_MEMORY_MCP=true
-```
-
-### 2. Install Dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-**New requirement:** `anthropic>=0.39.0` for Claude API
-
-### 3. Run the Autonomous Agent
-
-```bash
-python app_mcp_autonomous.py
-```
-
-### 4. Try Example Tasks
-
-**Example 1: Company Research**
-```
-Task: "Research Shopify and determine if they're a good B2B prospect"
-
-AI will autonomously:
-1. search_web("Shopify company info")
-2. search_news("Shopify recent news")
-3. save_company(name="Shopify", domain="shopify.com", ...)
-4. save_fact(content="Shopify is a leading e-commerce platform", ...)
-5. save_prospect(company_id="shopify", fit_score=85, ...)
-6. Return analysis
-```
-
-**Example 2: Multi-Prospect Research**
-```
-Task: "Find 3 e-commerce SaaS companies and save them as prospects"
-
-AI will autonomously:
-1. search_web("top e-commerce SaaS companies")
-2. For each company:
-   - save_company(...)
-   - search_news("Company X news")
-   - save_fact(...)
-   - save_prospect(...)
-3. list_prospects(status="new")
-4. Return summary
-```
-
-**Example 3: Outreach Campaign**
-```
-Task: "Create a personalized outreach campaign for Stripe"
-
-AI will autonomously:
-1. search_web("Stripe company info")
-2. search_news("Stripe recent developments")
-3. save_company(name="Stripe", ...)
-4. save_fact(content="Stripe launched new payment features", ...)
-5. list_contacts_by_domain("stripe.com")
-6. check_suppression(type="domain", value="stripe.com")
-7. Generate email content
-8. suggest_meeting_slots()
-9. Return campaign plan
-```
-
----
-
-## 🎯 Key Differences
-
-| Aspect | Old (Hardcoded) | New (Autonomous) |
-|--------|----------------|------------------|
-| **Decision Making** | Orchestrator | AI (Claude) |
-| **Tool Calling** | Hardcoded in agents | AI decides autonomously |
-| **Flexibility** | Fixed pipeline | Adapts to any task |
-| **MCP Usage** | Indirect | Direct and proper |
-| **Workflow** | Hunter→Enricher→Writer | AI decides dynamically |
-| **LLM Role** | Content generation only | Full orchestration + tools |
-| **Demonstration** | Not true MCP | ✅ Proper MCP protocol |
-
----
-
-## 📊 AI Decision-Making Examples
-
-### Example: AI Researching a Company
-
-```
-User: "Research Notion and create a prospect profile"
-
-AI Thought Process (autonomous):
-┌─────────────────────────────────────────┐
-│ 1. I need company information           │
-│    → Tool: search_web("Notion company") │
-└─────────────────────────────────────────┘
-           ↓
-┌─────────────────────────────────────────┐
-│ 2. Got company info, save it            │
-│    → Tool: save_company(...)            │
-└─────────────────────────────────────────┘
-           ↓
-┌─────────────────────────────────────────┐
-│ 3. Need recent news for context         │
-│    → Tool: search_news("Notion")        │
-└─────────────────────────────────────────┘
-           ↓
-┌─────────────────────────────────────────┐
-│ 4. Found interesting facts, save them   │
-│    → Tool: save_fact(...)               │
-│    → Tool: save_fact(...)               │
-└─────────────────────────────────────────┘
-           ↓
-┌─────────────────────────────────────────┐
-│ 5. Create prospect with all info        │
-│    → Tool: save_prospect(...)           │
-└─────────────────────────────────────────┘
-           ↓
-┌─────────────────────────────────────────┐
-│ 6. Task complete, return summary        │
-│    → No more tools needed               │
-└─────────────────────────────────────────┘
-```
-
-**Key Point:** AI decided all of this! No hardcoded workflow!
-
----
-
-## 🏆 Why This is Proper MCP
-
-### ✅ Follows MCP Principles
-
-1. **Protocol-Based** - Tools defined with proper schemas
-2. **AI-Driven** - LLM makes autonomous decisions
-3. **Tool Calling** - Native function calling support
-4. **Flexible** - Can handle any task, not fixed pipeline
-5. **Composable** - AI can combine tools creatively
-
-### ✅ Demonstrates MCP Concepts
-
-- **MCP Servers** - Search, Store, Email, Calendar
-- **MCP Tools** - 15+ tools exposed to AI
-- **MCP Resources** - Prospects, Companies, Contacts databases
-- **MCP Prompts** - Pre-defined prompt templates (optional)
-- **Tool Execution** - AI autonomously calls tools
-- **Result Handling** - AI processes results and decides next steps
-
-### ✅ Real-World Applicable
-
-This pattern works for:
-- Customer research
-- Data enrichment
-- Outreach automation
-- Lead qualification
-- Pipeline management
-- Any task involving multiple data sources and actions
-
----
-
-## 🔧 Configuration
-
-### Claude API (Required)
-
-Get API key from: https://console.anthropic.com/
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-api03-...
-```
-
-**Cost:** ~$3 per million input tokens, $15 per million output tokens
-**Model:** claude-3-5-sonnet-20241022 (best tool calling)
-
-### Alternative: Use Other Tool-Calling LLMs
-
-You can modify `autonomous_agent.py` to use:
-
-**OpenAI GPT-4:**
-```python
-from openai import AsyncOpenAI
-
-client = AsyncOpenAI(api_key=api_key)
-response = await client.chat.completions.create(
-    model="gpt-4-turbo-preview",
-    messages=messages,
-    tools=MCP_TOOLS
-)
-```
-
-**Google Gemini:**
-```python
-from google import genai
-
-client = genai.Client(api_key=api_key)
-response = client.models.generate_content(
-    model="gemini-1.5-pro",
-    contents=messages,
-    tools=MCP_TOOLS
-)
-```
-
----
-
-## 📈 Performance
-
-### Tool Calling Speed
-
-| Metric | Claude 3.5 Sonnet |
-|--------|-------------------|
-| **Time to First Tool Call** | 1-3 seconds |
-| **Tool Execution** | 0.1-2 seconds (depends on MCP server) |
-| **Iterations** | 3-10 typical, 15 max |
-| **Total Task Time** | 10-30 seconds |
-
-### Cost Estimate
-
-**Example Task:** "Research 3 companies and create prospects"
-
-- Input: ~2,000 tokens
-- Output: ~1,000 tokens
-- Tool calls: 10-15
-- **Cost: ~$0.02 per task**
-
-Very affordable for demonstration!
-
----
-
-## 🎥 Demo Script
-
-### For Hackathon Presentation
-
-1. **Show the old way** (hardcoded):
-   ```python
-   # Bad: Fixed pipeline
-   orchestrator.run()  # Always does the same thing
-   ```
-
-2. **Show the new way** (autonomous):
-   ```python
-   # Good: AI decides
-   agent.run("Any task here")  # AI figures it out!
-   ```
-
-3. **Run live demo:**
-   - Task: "Research Stripe and create a prospect profile"
-   - Show AI thinking and tool calls
-   - Show final result
-
-4. **Try different task:**
-   - Task: "Find 3 AI startups and save them"
-   - Show AI adapting to new task
-   - Different tools, different order
-
-5. **Explain MCP value:**
-   - No hardcoded workflow needed
-   - AI uses tools intelligently
-   - Scales to any task
-   - True Model Context Protocol
-
----
-
-## 🐛 Troubleshooting
-
-### "No API key"
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-```
-
-### "Tool execution failed"
-- Check MCP servers are running (or use in-memory mode)
-- Check `USE_IN_MEMORY_MCP=true` for HF Spaces
-
-### "Max iterations reached"
-- Task too complex - break into smaller tasks
-- Or increase `max_iterations=15` to `max_iterations=25`
-
-### "Search failed"
-- Check `SERPER_API_KEY` is set
-- Or set `SKIP_WEB_SEARCH=true` for mock data
-
----
-
-## 📚 Files Created
-
-### New Files
-- `mcp/tools/definitions.py` - MCP tool schemas
-- `mcp/tools/__init__.py` - Module init
-- `mcp/agents/autonomous_agent.py` - AI agent with tool calling
-- `app_mcp_autonomous.py` - Gradio app for autonomous agent
-- This documentation file
-
-### Modified Files
-- `requirements.txt` - Added `anthropic>=0.39.0`
-- `app/config.py` - Updated model to Qwen2.5-3B (backup)
-
-### Files to Ignore (Old Hardcoded Workflow)
-- `app/orchestrator.py` - Old hardcoded orchestrator
-- `agents/*.py` - Old hardcoded agents
-- `app.py` - Old Gradio app with hardcoded pipeline
-
----
-
-## 🎯 Summary
-
-### What You Have Now
-
-✅ **True MCP Implementation**
-- AI autonomously calls MCP servers
-- No hardcoded workflow
-- Proper tool calling with Claude 3.5
-
-✅ **15+ MCP Tools**
-- Search, Store, Email, Calendar servers
-- All exposed to AI with proper schemas
-
-✅ **Autonomous Agent**
-- Decides which tools to use
-- Adapts to any task
-- Demonstrates MCP concepts properly
-
-✅ **Ready for Hackathon**
-- Works on HF Spaces (with API key)
-- Clear demonstration of MCP
-- Real-world applicable
-
-### Quick Start
-
-```bash
-# 1. Install
-pip install -r requirements.txt
-
-# 2. Set API keys
-export ANTHROPIC_API_KEY=sk-ant-...
-export SERPER_API_KEY=your_key
-
-# 3. Run
-python app_mcp_autonomous.py
-
-# 4. Try task
-"Research Shopify and create a prospect profile"
-```
-
-**That's it! You now have proper MCP implementation!** 🎉
-
----
-
-**For MCP Hackathon Judges:**
-
-This implementation demonstrates:
-1. ✅ AI autonomous tool calling (not hardcoded)
-2. ✅ Proper MCP protocol (tools, resources, prompts)
-3. ✅ Multiple MCP servers (Search, Store, Email, Calendar)
-4. ✅ Real-world applicable (B2B sales automation)
-5. ✅ Scalable and flexible (works for any task)
-
-**This is what MCP is meant for!** 🚀

MIGRATION.md

@@ -1,262 +0,0 @@
-# Migration Guide: DuckDuckGo to Serper API
-
-## Overview
-
-This document describes the migration from DuckDuckGo search to Serper API (serper.dev).
-
-## Why the Change?
-
-The previous implementation used `duckduckgo-search` package which experienced:
-- **Rate limiting issues**: Frequent `DuckDuckGoSearchException: Ratelimit` errors
-- **Unreliable service**: Multiple retry attempts often failing
-- **No workaround**: DuckDuckGo doesn't offer a paid API tier to bypass rate limits
-
-The new implementation uses Serper API which provides:
-- **Reliable service**: Professional Google Search API with proper rate limiting
-- **Better results**: High-quality search results directly from Google
-- **Generous free tier**: 2,500 free searches/month
-- **Scalability**: Option to upgrade for higher volumes
-- **Simple integration**: Direct REST API, no complex dependencies
-
-## Changes Made
-
-### 1. Dependencies (`requirements.txt`)
-
-**Removed:**
-```python
-duckduckgo-search==4.1.1
-smolagents[toolkit]>=0.1.0  # Was briefly considered
-```
-
-**No new dependencies needed!**
-- Serper API uses only `requests` which we already have
-- Cleaner dependency tree
-- No version conflicts
-
-### 2. Web Search Service (`services/web_search.py`)
-
-**Before:**
-- Used `duckduckgo_search.DDGS` directly
-- Frequent rate limiting failures
-- No API key required but unreliable
-
-**After:**
-- Uses Serper API (serper.dev) via direct REST calls
-- Reliable API-based Google searching
-- Requires `SERPER_API_KEY` environment variable
-- Better error handling and retry logic
-- Supports Google Answer Box and Knowledge Graph results
-
-### 3. Search Server (`mcp/servers/search_server.py`)
-
-**Updated:**
-- Server description changed to reflect Serper API usage
-- No functional changes to the MCP interface
-
-### 4. Environment Configuration (`.env.example`)
-
-**Updated:**
-```bash
-# Web Search Configuration
-# Uses Serper API (serper.dev) - Low-cost Google Search API
-# Get your free API key from: https://serper.dev/ (2,500 free searches/month)
-SERPER_API_KEY=your_serper_api_key_here
-
-# SKIP_WEB_SEARCH: Set to "true" to skip web search and use intelligent fallback data
-# Recommended for: Demo environments, or when SERPER_API_KEY is not available
-SKIP_WEB_SEARCH=false
-```
-
-### 5. Application UI (`app.py`)
-
-**Updated:**
-- UI description now mentions Serper API (Google Search) instead of other providers
-
-## Migration Steps
-
-### For Existing Installations:
-
-1. **Update dependencies:**
-   ```bash
-   pip install -r requirements.txt
-   ```
-   (No changes needed - we removed packages but added none)
-
-2. **Get a Serper API key:**
-   - Visit https://serper.dev/
-   - Sign up for a free account (Google sign-in available)
-   - Get your API key from the dashboard
-   - Free tier includes 2,500 searches/month
-
-3. **Update your `.env` file:**
-   ```bash
-   # Remove old keys (if present):
-   # BRAVE_API_KEY=...
-
-   # Add this line to your .env file:
-   SERPER_API_KEY=your_actual_serper_api_key_here
-   ```
-
-4. **Test the migration:**
-   ```bash
-   python app.py
-   ```
-
-### For New Installations:
-
-1. **Clone the repository:**
-   ```bash
-   git clone <repository-url>
-   cd cx_ai_agent
-   ```
-
-2. **Install dependencies:**
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-3. **Configure environment:**
-   ```bash
-   cp .env.example .env
-   # Edit .env and add your SERPER_API_KEY
-   ```
-
-4. **Run the application:**
-   ```bash
-   python app.py
-   ```
-
-## API Compatibility
-
-The `WebSearchService` interface remains **100% compatible**:
-
-```python
-# This code works exactly the same as before
-from services.web_search import get_search_service
-
-search_service = get_search_service()
-results = await search_service.search("company name", max_results=5)
-```
-
-**Return format unchanged:**
-```python
-[
-    {
-        'title': 'Search result title',
-        'body': 'Search result description/snippet',
-        'url': 'https://example.com',
-        'source': 'example.com'
-    },
-    ...
-]
-```
-
-## Serper API Features
-
-### Enhanced Results
-Serper provides richer results than basic search:
-- **Organic results**: Standard Google search results
-- **Answer Box**: Direct answers when available
-- **Knowledge Graph**: Entity information panels
-- **News results**: Dedicated news search endpoint
-
-### Example Response
-```python
-# Regular search
-results = await search_service.search("Python programming")
-
-# News search
-news = await search_service.search_news("AI technology")
-
-# Instant answers (from Answer Box/Knowledge Graph)
-answer = await search_service.instant_answer("what is the capital of France")
-```
-
-## Fallback Behavior
-
-If `SERPER_API_KEY` is not set:
-- The service will log a warning
-- Web search will fail gracefully
-- The system can use fallback data if `SKIP_WEB_SEARCH=true`
-
-## Troubleshooting
-
-### Error: "SERPER_API_KEY environment variable is required"
-
-**Solution:**
-1. Get a free API key from https://serper.dev/
-2. Add it to your `.env` file
-3. Restart the application
-
-### Error: HTTP 401 Unauthorized
-
-**Solution:**
-- Check that your API key is correct
-- Ensure there are no extra spaces in the `.env` file
-- Verify your account is active at serper.dev
-
-### Rate Limiting
-
-**Free tier limits:**
-- 2,500 searches/month
-- Built-in rate limiting (0.5s delay between requests)
-
-**If you exceed the free tier:**
-- Upgrade to a paid plan at https://serper.dev/pricing
-- Or set `SKIP_WEB_SEARCH=true` to use fallback data
-
-### HTTP 429 Too Many Requests
-
-**Solution:**
-- The service has built-in retry logic with exponential backoff
-- If persistent, consider upgrading your plan
-- Or reduce search frequency
-
-## Benefits of Serper API
-
-1. **Reliability**: 99.9% uptime SLA
-2. **Quality**: Real Google Search results
-3. **Features**: Answer Box, Knowledge Graph, News search
-4. **Cost-Effective**: 2,500 free searches/month is generous
-5. **Simple**: No complex dependencies, just REST API
-6. **Fast**: Low latency responses
-7. **Scalable**: Easy to upgrade as usage grows
-
-## Comparison with Alternatives
-
-| Feature | DuckDuckGo | Brave | Serper |
-|---------|-----------|-------|--------|
-| Free Tier | Unlimited but rate-limited | 2,000/month | 2,500/month |
-| Reliability | ❌ Poor | ✅ Good | ✅ Excellent |
-| Results Quality | ⚠️ Moderate | ✅ Good | ✅ Google Quality |
-| Dependencies | duckduckgo-search | smolagents | None (uses requests) |
-| Rate Limits | Severe | Moderate | Generous |
-| Answer Box | ❌ No | ❌ No | ✅ Yes |
-| Knowledge Graph | ❌ No | ❌ No | ✅ Yes |
-
-## Rollback (if needed)
-
-If you need to rollback to DuckDuckGo:
-
-1. Restore the old `services/web_search.py` from git history
-2. Update `requirements.txt`:
-   ```bash
-   # Add:
-   duckduckgo-search==4.1.1
-   ```
-3. Remove `SERPER_API_KEY` from `.env`
-
-**Note:** We don't recommend this due to the original rate limiting issues.
-
-## Support
-
-For issues or questions:
-- **Serper API**: Check the [Serper Documentation](https://serper.dev/docs)
-- **Application Issues**: Open an issue on GitHub
-- **API Status**: Check https://status.serper.dev/
-
----
-
-**Last Updated:** 2025-01-15
-**Migration Author:** Claude Code
-**Version:** 2.0.0

MIGRATION_SUMMARY.md

@@ -1,307 +0,0 @@
-# Migration Summary: Streamlit → Gradio + HF Spaces
-
-## ✅ Completed Migrations
-
-### 1. Frontend Framework
-- **Before**: Streamlit UI (`ui/streamlit_app.py`)
-- **After**: Gradio interface (`app.py`)
-- **Changes**:
-  - Migrated to Gradio 5.5 with modern UI components
-  - Implemented tabbed interface (Pipeline, System, About)
-  - Real-time streaming with Gradio Chatbot component
-  - Workflow log display with markdown tables
-
-### 2. LLM Integration
-- **Before**: Ollama with qwen3:0.6b model
-- **After**: Hugging Face Inference API with Qwen/Qwen2.5-7B-Instruct
-- **Changes**:
-  - Updated `app/config.py` to use HF_API_TOKEN and MODEL_NAME
-  - Modified `agents/writer.py` to use `AsyncInferenceClient`
-  - Implemented streaming with `text_generation()` method
-  - Added fallback model configuration
-
-### 3. Configuration
-- **Before**: `OLLAMA_BASE_URL`, `MODEL_NAME=qwen3:0.6b`
-- **After**: `HF_API_TOKEN`, `MODEL_NAME=Qwen/Qwen2.5-7B-Instruct`
-- **Files Updated**:
-  - `app/config.py`: Added HF configurations
-  - `.env.example`: Updated with HF credentials
-  - `pyproject.toml`: Updated project metadata
-
-### 4. Dependencies
-- **Before**: `requirements.txt` with Streamlit and Ollama
-- **After**: `requirements_gradio.txt` with Gradio and HF dependencies
-- **New Dependencies**:
-  - `gradio==5.5.0`
-  - `huggingface-hub==0.26.2`
-  - `transformers==4.45.0`
-- **Removed Dependencies**:
-  - `streamlit==1.29.0`
-  - No more Ollama dependency
-
-### 5. Project Branding
-- **Before**: "Lucidya MCP Prototype" (company-specific)
-- **After**: "CX AI Agent" (generalized)
-- **Changes**:
-  - Updated all references from Lucidya to CX AI Agent
-  - Modified prompts to be platform-agnostic
-  - Updated email signatures from "Lucidya Team" to "The CX Team"
-
-### 6. Documentation
-- **Created**:
-  - `README_HF_SPACES.md`: Comprehensive HF Spaces README with frontmatter
-  - `DEPLOYMENT.md`: Step-by-step deployment guide
-  - `requirements_gradio.txt`: Gradio-specific dependencies
-  - `MIGRATION_SUMMARY.md`: This document
-
-- **Updated**:
-  - `README.md`: New instructions for Gradio + HF Spaces
-  - `.env.example`: HF API configuration
-  - `pyproject.toml`: Project metadata and URLs
-
-## 🎯 Track 2 Requirements (MCP in Action)
-
-### ✅ All Requirements Met
-
-1. **Autonomous Agent Behavior** ✅
-   - 8-agent orchestration pipeline
-   - Planning: Hunter discovers, Scorer evaluates
-   - Reasoning: Writer uses RAG for context
-   - Execution: Sequencer sends emails, Curator prepares handoff
-
-2. **MCP Servers as Tools** ✅
-   - Search Server: Used by Enricher for research
-   - Email Server: Used by Sequencer for outreach
-   - Calendar Server: Used by Sequencer for scheduling
-   - Store Server: Used throughout for persistence
-
-3. **Gradio App** ✅
-   - Clean, modern Gradio 5.5 interface
-   - Real-time streaming display
-   - Workflow monitoring
-   - System health checks
-
-4. **Advanced Features** ✅
-   - **RAG**: FAISS vector store with sentence-transformers
-   - **Context Engineering**: Comprehensive prompts with company context
-   - **Streaming**: Real-time LLM token streaming
-   - **Compliance**: Regional policy enforcement
-
-5. **Real-World Value** ✅
-   - Automated CX research and outreach
-   - Production-ready architecture
-   - Scalable design patterns
-
-## 📋 File Structure
-
-```
-cx_ai_agent/
-├── app.py                          # ✨ NEW: Main Gradio app
-├── requirements_gradio.txt         # ✨ NEW: Gradio dependencies
-├── README_HF_SPACES.md            # ✨ NEW: HF Spaces README
-├── DEPLOYMENT.md                   # ✨ NEW: Deployment guide
-├── MIGRATION_SUMMARY.md           # ✨ NEW: This file
-├── README.md                       # ✏️ UPDATED: New instructions
-├── .env.example                    # ✏️ UPDATED: HF configuration
-├── pyproject.toml                  # ✏️ UPDATED: Project metadata
-├── app/
-│   ├── config.py                   # ✏️ UPDATED: HF API config
-│   ├── main.py                     # ✏️ UPDATED: FastAPI health check
-│   ├── orchestrator.py             # ✏️ UPDATED: HF Inference mentions
-│   ├── schema.py                   # ✓ No changes needed
-│   └── logging_utils.py            # ✓ No changes needed
-├── agents/
-│   ├── writer.py                   # ✏️ UPDATED: HF Inference API
-│   ├── hunter.py                   # ✓ No changes needed
-│   ├── enricher.py                 # ✓ No changes needed
-│   ├── contactor.py                # ✓ No changes needed
-│   ├── scorer.py                   # ✓ No changes needed
-│   ├── compliance.py               # ✓ No changes needed
-│   ├── sequencer.py                # ✓ No changes needed
-│   └── curator.py                  # ✓ No changes needed
-├── mcp/                            # ✓ No changes needed
-├── vector/                         # ✓ No changes needed
-├── data/                           # ✓ No changes needed
-├── scripts/                        # ✓ No changes needed
-└── tests/                          # ✓ No changes needed
-```
-
-## 🚀 Next Steps for Deployment
-
-### 1. Prepare for HF Spaces
-
-```bash
-# Rename files for HF Spaces
-cp requirements_gradio.txt requirements.txt
-cp README_HF_SPACES.md README.md  # For the Space (keep original README.md in repo as README_REPO.md)
-```
-
-### 2. Test Locally
-
-```bash
-# Set up environment
-cp .env.example .env
-# Add your HF_API_TOKEN to .env
-
-# Install dependencies
-pip install -r requirements_gradio.txt
-
-# Start MCP servers
-bash scripts/start_mcp_servers.sh
-
-# Seed vector store
-python scripts/seed_vectorstore.py
-
-# Run Gradio app
-python app.py
-```
-
-### 3. Deploy to HF Spaces
-
-1. Create a new Space on Hugging Face
-2. Upload all files
-3. Add `HF_API_TOKEN` as a repository secret
-4. The app will automatically deploy
-
-See `DEPLOYMENT.md` for detailed instructions.
-
-### 4. Record Demo Video
-
-Record a 1-5 minute video showing:
-- Starting the pipeline
-- Real-time agent execution
-- MCP server interactions
-- Generated content (summaries and emails)
-- Workflow monitoring
-
-### 5. Create Social Media Post
-
-Share on X/LinkedIn with:
-- Link to your HF Space
-- Brief description
-- Hackathon hashtags
-- Demo video or GIF
-
-### 6. Submit to Hackathon
-
-Update README.md with:
-- ✅ `mcp-in-action-track-02` tag (already added)
-- 🔗 Link to social media post
-- 🎥 Link to demo video
-- 🌐 Link to HF Space
-
-## 🔧 Technical Improvements
-
-### Performance
-- Upgraded from qwen3:0.6b (0.6B params) to Qwen2.5-7B-Instruct (7B params)
-- Better quality content generation
-- More coherent reasoning
-
-### User Experience
-- Cleaner Gradio interface vs. Streamlit
-- Better real-time streaming visualization
-- Tabbed navigation for better organization
-- Workflow monitoring in dedicated panel
-
-### Deployment
-- Single-file app (`app.py`) vs. separate FastAPI + Streamlit
-- Native HF Spaces integration
-- Easier to deploy and share
-- No need for separate services
-
-## ⚠️ Important Notes
-
-### MCP Servers on HF Spaces
-
-The MCP servers are currently designed to run as separate processes. For HF Spaces:
-
-**Option 1** (Current): Background processes
-- MCP servers start via `scripts/start_mcp_servers.sh`
-- May have limitations on HF Spaces free tier
-
-**Option 2** (Alternative): Integrated implementation
-- Modify `mcp/registry.py` to instantiate servers directly
-- Better compatibility with HF Spaces
-- Simpler deployment
-
-If you encounter issues with background processes on HF Spaces, implement Option 2.
-
-### API Rate Limits
-
-Hugging Face Inference API has rate limits:
-- Free tier: Limited requests per hour
-- PRO tier: Higher limits
-
-For demos:
-- Process 1-3 companies at a time
-- Consider using smaller models if hitting limits
-- Implement request throttling if needed
-
-### Vector Store
-
-The FAISS index is built locally and can be:
-1. Pre-built and committed to the repo
-2. Built on first run (current implementation)
-
-For HF Spaces, consider pre-building the index to reduce startup time.
-
-## ✨ What's New
-
-### Gradio 5.5 Features Used
-- `gr.Chatbot` with messages type for agent output
-- `gr.Markdown` for dynamic workflow logs
-- `gr.Tabs` for organized interface
-- Streaming updates with generators
-- Theme customization
-
-### Autonomous Agent Features
-- Real-time planning and execution visualization
-- MCP tool usage tracking
-- Context engineering with RAG
-- Compliance automation
-- Multi-stage reasoning
-
-### Production Patterns
-- Async/await throughout
-- Event-driven architecture
-- Streaming for UX
-- Modular agent design
-- Clean separation of concerns
-
-## 📊 Comparison: Before vs. After
-
-| Aspect | Before (Streamlit + Ollama) | After (Gradio + HF) |
-|--------|----------------------------|---------------------|
-| Frontend | Streamlit 1.29 | Gradio 5.5 |
-| LLM | Ollama (local) | HF Inference API (cloud) |
-| Model | qwen3:0.6b | Qwen2.5-7B-Instruct |
-| Deployment | Requires local Ollama | HF Spaces ready |
-| Branding | Lucidya-specific | Generalized CX AI |
-| Interface | Multi-tab Streamlit | Tabbed Gradio |
-| Streaming | NDJSON → Streamlit | NDJSON → Gradio Chatbot |
-| Dependencies | 16 packages | 15 packages |
-| Setup Complexity | Medium (Ollama required) | Low (API token only) |
-
-## 🎉 Success Criteria
-
-All Track 2 requirements met:
-- ✅ Demonstrates autonomous agent behavior
-- ✅ Uses MCP servers as tools
-- ✅ Gradio app on HF Spaces
-- ✅ Advanced features (RAG, Context Engineering)
-- ✅ Real-world application
-- ✅ Polished UI/UX
-- ✅ Comprehensive documentation
-
-## 🙏 Credits
-
-Migration completed for the Hugging Face + Anthropic Hackathon (November 2024)
-
-**Original Architecture**: Multi-agent CX platform with Streamlit + Ollama
-**Migrated Architecture**: Autonomous agents with Gradio + HF Inference API
-
----
-
-**Ready for deployment! 🚀**
-
-See `DEPLOYMENT.md` for step-by-step instructions.

PRODUCTION_READY_IMPLEMENTATION.md

@@ -1,370 +0,0 @@
-# 🏭 Production-Ready B2B Sales Automation - Implementation Guide
-
-## ✅ What's Now REAL (Enterprise-Level)
-
-### **1. Prospect Discovery** ✅ PRODUCTION-READY
-- ✅ **Finds ACTUAL company websites** (not article titles)
-- ✅ **AI-powered validation** to filter out blogs, articles, directories
-- ✅ **Web scraping** to extract real company information
-- ✅ **Contact page discovery** automatically finds /contact, /about pages
-- ✅ **Domain extraction** for email generation
-
-### **2. Contact Finding** ✅ PRODUCTION-READY
-- ✅ **Multi-strategy approach**:
-  1. Scrape contact pages for emails and names
-  2. Search Google/LinkedIn for decision makers
-  3. Use AI to extract names and titles from search results
-  4. Generate email addresses using common patterns
-  5. Infer emails based on company email patterns
-- ✅ **Real names** extracted from websites
-- ✅ **Real or inferred email addresses** using patterns
-- ✅ **Confidence scoring** for each contact
-- ✅ **Source tracking** (AI, Web Scraping, Pattern-based)
-
-### **3. AI-Powered Intelligence** ✅ PRODUCTION-READY
-- ✅ **Company validation** - AI determines if search result is a real company
-- ✅ **Decision maker extraction** - LLM extracts names, titles from text
-- ✅ **Email pattern detection** - Learns company email format
-- ✅ **Contact detail inference** - Generates likely emails based on patterns
-
-### **4. Web Scraping** ✅ PRODUCTION-READY
-- ✅ **BeautifulSoup4 + lxml** - Robust HTML parsing
-- ✅ **Email regex extraction** - Finds emails in page source
-- ✅ **Name extraction** - Finds person names from team sections
-- ✅ **Contact page discovery** - Auto-finds contact/about pages
-- ✅ **Meta tag parsing** - Extracts company description
-- ✅ **Phone number extraction** - Finds phone numbers (bonus)
-
-## 🎭 What's Still SIMULATED (By Design)
-
-### **Email Sending** - SIMULATION
-- ❌ No actual email sending (no AWS SES/SendGrid)
-- ✅ Emails are **fully generated** with real content
-- ✅ Ready to integrate with any email service
-
-### **Reply Handling** - SIMULATION
-- ❌ No real email inbox monitoring
-- ✅ Simulates prospect responses (5 types)
-- ✅ AI conversation logic is REAL
-- ✅ Handoff packet generation is REAL
-
-## 🔧 New Services Created
-
-### **1. WebScraperService** (`services/web_scraper.py`)
-
-**Purpose**: Enterprise-grade web scraping for company and contact information
-
-**Key Methods**:
-- `extract_company_info(url)` - Extracts company name, description, domain, contact page
-- `scrape_contact_page(url)` - Finds emails, phones, names from contact pages
-- `generate_email_patterns(name, domain)` - Generates likely email formats
-- `validate_email_format(email)` - Validates email syntax
-
-**Features**:
-- User-Agent spoofing to avoid blocking
-- Timeout and retry logic
-- Multiple extraction strategies
-- Fallback mechanisms
-
-### **2. AIContactExtractor** (`services/ai_contact_extractor.py`)
-
-**Purpose**: AI-powered contact extraction and validation
-
-**Key Methods**:
-- `extract_decision_makers(company_info, page_content, titles)` - Uses LLM to extract contacts
-- `validate_company_match(title, snippet)` - AI determines if result is a real company
-- `infer_contact_details(domain, name, title, known_emails)` - Smart email inference
-- `_detect_email_pattern(emails)` - Learns company email format
-
-**Features**:
-- Hugging Face LLM integration (Llama-3.2-3B-Instruct)
-- JSON parsing from LLM responses
-- Fallback to heuristics if AI unavailable
-- Confidence scoring
-
-## 🔄 Updated B2BSalesAgent Methods
-
-### **`find_prospects()` - PRODUCTION VERSION**
-
-**Before** (Fake):
-```python
-# Just grabbed search result titles
-prospects = [{
-    "name": result.get('title'),  # Article title, not company!
-    "domain": result.get('url')    # Blog URL, not company!
-}]
-```
-
-**After** (Real):
-```python
-# 1. Search for actual company websites
-query = f"{industry_terms} official website contact"
-
-# 2. AI validates each result
-validation = await ai_extractor.validate_company_match(title, snippet)
-
-# 3. Only include if AI confirms it's a real company
-if validation['is_company'] and validation['confidence'] > 0.5:
-    # 4. Scrape the actual website
-    company_info = await web_scraper.extract_company_info(url)
-
-    # 5. Extract real company data
-    prospect = {
-        "name": company_info['name'],     # ✅ REAL company name
-        "domain": company_info['domain'], # ✅ REAL domain
-        "website": url,                   # ✅ REAL website
-        "contact_page": company_info['contact_page'], # ✅ REAL contact page
-        "validation_confidence": validation['confidence']
-    }
-```
-
-### **`find_contacts()` - PRODUCTION VERSION**
-
-**Before** (Fake):
-```python
-contact = {
-    "name": "Contact Name (from search)",  # ❌ HARDCODED
-    "email": f"contact@{domain}"           # ❌ GENERIC
-}
-```
-
-**After** (Real):
-```python
-# 1. Scrape contact page
-scraped_data = await web_scraper.scrape_contact_page(contact_page)
-# Returns: {'emails': [...], 'names': [...], 'phones': [...]}
-
-# 2. Search for decision makers
-search_results = await web_search.search(f"{company} CEO founder president")
-
-# 3. Use AI to extract contacts from search results
-ai_contacts = await ai_extractor.extract_decision_makers(
-    company_info,
-    search_content,
-    ["CEO", "CTO", "CFO", "VP", "Director", ...]
-)
-# Returns: [{"name": "John Doe", "title": "CEO", "email": "[email protected]", "confidence": 0.9}]
-
-# 4. If no email from AI, infer using patterns
-if not email:
-    inferred = await ai_extractor.infer_contact_details(
-        domain, name, title, scraped_emails
-    )
-    # Learns pattern from known emails, generates likely address
-
-# 5. Final contact with real data
-contact = {
-    "name": "John Doe",                    # ✅ REAL or EXTRACTED
-    "title": "CEO",                        # ✅ REAL or EXTRACTED
-    "email": "[email protected]",       # ✅ REAL or PATTERN-BASED
-    "linkedin": "linkedin.com/in/johndoe", # ✅ REAL if found
-    "confidence": 0.85,                    # ✅ CONFIDENCE SCORE
-    "source": "AI + Web Scraping"          # ✅ SOURCE TRACKING
-}
-```
-
-## 📊 Data Quality Levels
-
-### **Level 1: High Confidence (0.8-1.0)** 🟢
-- Email found directly on website
-- Name extracted by AI from official bio
-- LinkedIn profile linked
-- **Example**: [email protected] (found on /team page)
-
-### **Level 2: Medium Confidence (0.6-0.8)** 🟡
-- Email generated using detected pattern
-- Name found via web scraping
-- Title inferred from context
-- **Example**: [email protected] (pattern: first.last)
-
-### **Level 3: Low Confidence (0.4-0.6)** 🟠
-- Name scraped without clear title
-- Email generated using common pattern
-- **Example**: [email protected] (generic contact)
-
-### **Level 4: Fallback (0.3-0.4)** 🔴
-- Generic contact info
-- No specific person identified
-- **Example**: [email protected]
-
-## 🚀 How the Production System Works
-
-### **Step 1: Client Research** (Same as before)
-```
-Input: "Shopify"
-↓
-Web Search: "Shopify company what they offer products services"
-↓
-Output: Real info about Shopify
-```
-
-### **Step 2: Prospect Discovery** (NOW REAL!)
-```
-Input: Client = Shopify
-↓
-Search: "e-commerce stores online retailers official website contact"
-↓
-For each result:
-  ├─ AI validates: Is this a real company? (not an article)
-  ├─ If yes (confidence > 0.5):
-  │   ├─ Scrape website
-  │   ├─ Extract: name, domain, description, contact page
-  │   └─ Add to prospects
-  └─ If no: Skip
-↓
-Output: [
-  {
-    "name": "Fashion Boutique Co",
-    "domain": "fashionboutique.com",
-    "website": "https://fashionboutique.com",
-    "contact_page": "https://fashionboutique.com/contact",
-    "confidence": 0.85
-  }
-]
-```
-
-### **Step 3: Contact Finding** (NOW REAL!)
-```
-Input: Prospect = Fashion Boutique Co
-↓
-Step 3.1: Scrape contact page
-  ├─ Found emails: ["[email protected]", "[email protected]"]
-  ├─ Found names: ["Sarah Johnson", "Mike Chen"]
-  └─ Detected pattern: [email protected]
-↓
-Step 3.2: Search Google/LinkedIn
-  ├─ Search: "Fashion Boutique Co CEO founder president"
-  └─ Results: "Sarah Johnson, CEO at Fashion Boutique..."
-↓
-Step 3.3: AI extracts decision makers
-  ├─ Input: Search results text
-  ├─ LLM extracts: [{"name": "Sarah Johnson", "title": "CEO", ...}]
-  └─ Confidence: 0.9
-↓
-Step 3.4: Match email to person
-  ├─ Name: "Sarah Johnson"
-  ├─ Found email: [email protected] ✅
-  └─ Or generate: [email protected] (pattern-based)
-↓
-Output: [
-  {
-    "name": "Sarah Johnson",
-    "title": "CEO",
-    "email": "[email protected]",
-    "linkedin": "linkedin.com/in/sarah-johnson-xyz",
-    "confidence": 0.9,
-    "source": "AI + Web Scraping"
-  }
-]
-```
-
-### **Step 4: Email Generation** (Already Real!)
-```
-Uses real contact data to generate personalized emails ✅
-```
-
-## 🔧 Integration Points for Enterprise
-
-### **To Make 100% Production-Ready**:
-
-1. **Email Verification API** (Optional)
-   - Integrate Hunter.io, ZeroBounce, or NeverBounce
-   - Verify email exists before adding to list
-   - Reduce bounce rate
-
-2. **LinkedIn Sales Navigator API** (Optional)
-   - Get verified decision maker profiles
-   - More accurate job titles
-   - Direct LinkedIn URLs
-
-3. **Company Enrichment API** (Optional)
-   - Clearbit, Apollo.io for company data
-   - Employee count, revenue, tech stack
-   - Better qualification
-
-4. **Email Sending Service** (Required for actual sending)
-   - AWS SES, SendGrid, Mailgun
-   - Already ready to integrate
-   - Just add SMTP credentials
-
-5. **CRM Integration** (Recommended)
-   - Salesforce, HubSpot, Pipedrive
-   - Store prospects and contacts
-   - Track email opens/replies
-
-## 📈 Expected Results
-
-### **Example Run: "Shopify" → 3 Prospects**
-
-**Input**:
-```
-Client: Shopify
-Number of Prospects: 3
-```
-
-**Output**:
-```
-Prospect 1: Small Fashion Boutique LLC
-  ├─ Website: https://smallfashionboutique.com
-  ├─ Contact Page: https://smallfashionboutique.com/contact-us
-  ├─ Contacts:
-  │   ├─ Sarah Johnson <[email protected]> (CEO) [Confidence: 0.9]
-  │   └─ Mike Chen <[email protected]> (CTO) [Confidence: 0.7]
-  └─ Emails Generated: 2
-
-Prospect 2: Artisan Coffee Roasters
-  ├─ Website: https://artisancoffee.com
-  ├─ Contact Page: https://artisancoffee.com/about
-  ├─ Contacts:
-  │   └─ [email protected] (Business Development) [Confidence: 0.5]
-  └─ Emails Generated: 1
-
-Prospect 3: Handmade Jewelry Co
-  ├─ Website: https://handmadejewelry.shop
-  ├─ Contact Page: https://handmadejewelry.shop/team
-  ├─ Contacts:
-  │   ├─ [email protected] (Founder) [Confidence: 0.8]
-  │   └─ [email protected] (Contact) [Confidence: 0.4]
-  └─ Emails Generated: 2
-
-Total: 3 prospects, 5 contacts, 5 emails generated
-```
-
-## ⚡ Performance Considerations
-
-- **Speed**: ~30-60 seconds for 3 prospects (includes web scraping)
-- **API Calls**: ~15-25 search requests per run
-- **Success Rate**: 60-80% find real companies with contacts
-- **Email Accuracy**: 70-90% (depends on website quality)
-
-## 🔒 Compliance & Ethics
-
-✅ **Compliant**:
-- Only public information
-- Respects robots.txt
-- No aggressive scraping
-- Proper User-Agent
-- Rate limiting included
-
-✅ **Ethical**:
-- Unsubscribe language in emails
-- AI disclosure
-- No spam (qualified prospects only)
-- Respects opt-outs
-
-## 🎯 Summary
-
-**What YOU Asked For**: ✅ DELIVERED
-- ✅ Find REAL prospect companies (not articles)
-- ✅ Find REAL contact details (names, emails)
-- ✅ Use web scraping from company pages
-- ✅ AI-led discovery and extraction
-- ✅ Enterprise-level, production-ready
-- ✅ Can integrate into any enterprise application
-
-**What's Still Simulated**: Only what you specified
-- ✅ Email sending (no AWS SES) - BY DESIGN
-- ✅ Reply handling (demo purposes) - BY DESIGN
-
-**Ready for**: ✅ PRODUCTION USE
-Just add AWS SES or SendGrid for actual email sending!

QUICK_ANSWERS.md

@@ -1,185 +0,0 @@
-# Quick Answers to Your Questions
-
-## Question 1: Are all modules MCP-leveraged?
-
-### ❌ NO - It's Hybrid
-
-**MCP-Leveraged (✅ 8 Agents):**
-```
-✅ Hunter       → Uses MCP Store
-✅ Enricher     → Uses MCP Search + Store
-✅ Contactor    → Uses MCP Store
-✅ Scorer       → Uses MCP Store
-✅ Writer       → Uses MCP Store
-✅ Compliance   → Uses MCP Store
-✅ Sequencer    → Uses MCP Email + Calendar + Store
-✅ Curator      → Uses MCP Email + Calendar + Store
-```
-
-**NOT MCP (❌ 5 Services):**
-```
-❌ WebSearchService         → Direct Serper.dev API
-❌ CompanyDiscoveryService  → Direct Serper.dev API
-❌ ProspectDiscoveryService → Direct Serper.dev API
-❌ ClientResearcher         → Direct Serper.dev + scraping
-❌ LLMService               → Direct Anthropic API
-```
-
-**Verdict:** Services bypass MCP for performance. This is **OK for a hackathon**!
-
----
-
-## Question 2: Are MCP servers called by AI or manually?
-
-### ⚠️ MANUALLY by Workflow Code (NOT by AI!)
-
-**Current Reality:**
-
-```python
-# This is HARDCODED workflow, NOT AI autonomous decision
-store = self.mcp.get_store_client()
-suppressed = await store.check_suppression("domain", domain)
-```
-
-**What the LLM is used for:**
-- ✅ Generating email content
-- ✅ Generating summaries
-- ❌ NOT for deciding which tools to call
-- ❌ NOT for autonomous agent behavior
-
-**Architecture:**
-```
-Orchestrator (hardcoded logic)
-    ↓
-Agent 1 → Call MCP method A (hardcoded)
-    ↓
-Agent 2 → Call MCP method B (hardcoded)
-    ↓
-Agent 3 → Call LLM for content (hardcoded)
-    ↓
-Result
-```
-
-**This is workflow automation with AI content generation, NOT autonomous AI agents.**
-
-**Verdict:** This is **perfectly fine for a hackathon**! It's reliable and predictable.
-
----
-
-## Question 3: Can we use a more efficient LLM for free HF CPU?
-
-### ✅ YES - Upgraded to Qwen2.5-3B!
-
-**Before:**
-```python
-MODEL_NAME = "Qwen/Qwen2.5-7B-Instruct"  # 7B params, slow on CPU
-```
-
-**After:**
-```python
-MODEL_NAME = "Qwen/Qwen2.5-3B-Instruct"  # 3B params, 2.3x faster! ⚡
-```
-
-**Performance Comparison:**
-
-| Model | Size | CPU Speed | Memory | Quality | Best For |
-|-------|------|-----------|--------|---------|----------|
-| **Qwen2.5-3B** ⭐ | 3B | **23-70 tok/s** | 6GB | 90% | **Recommended** |
-| Qwen2.5-7B (old) | 7B | 10-30 tok/s | 14GB | 100% | Too slow |
-
-**Benefits:**
-- ✅ **2.3x faster** inference on free HF CPU
-- ✅ **Lower memory** usage (6GB vs 14GB)
-- ✅ **Better UX** - faster streaming responses
-- ✅ **Still good quality** - 90% of 7B performance
-
-**Alternative Options:**
-
-```bash
-# Ultra-efficient (if you want even faster)
-MODEL_NAME=microsoft/Phi-3-mini-4k-instruct  # 3.8B params
-
-# Ultra-fast (if speed > quality)
-MODEL_NAME=HuggingFaceTB/SmolLM2-1.7B-Instruct  # 1.7B params
-```
-
----
-
-## Summary
-
-| Question | Answer | Status |
-|----------|--------|--------|
-| **All modules use MCP?** | ❌ No - Hybrid (Agents use MCP, Services bypass) | ✅ OK for hackathon |
-| **AI calls MCP?** | ❌ No - Hardcoded workflow calls MCP | ✅ OK for hackathon |
-| **Better LLM for CPU?** | ✅ Yes - Upgraded to Qwen2.5-3B (2.3x faster!) | ✅ **FIXED!** |
-
----
-
-## What to Do Next
-
-### 1. Test the Build
-
-Your build should now work with:
-- ✅ Fixed `requirements.txt` (no bad packages)
-- ✅ Optimized LLM (Qwen2.5-3B)
-
-```bash
-# Should work now!
-pip install -r requirements.txt
-```
-
-### 2. Test the New LLM Locally
-
-```python
-from huggingface_hub import InferenceClient
-
-client = InferenceClient(token="your_hf_token")
-
-for token in client.text_generation(
-    "Write a B2B sales email",
-    model="Qwen/Qwen2.5-3B-Instruct",
-    max_new_tokens=200,
-    stream=True
-):
-    print(token, end="", flush=True)
-```
-
-### 3. Deploy to HF Spaces
-
-Your deployment should now:
-- ✅ Build successfully (no requirement errors)
-- ✅ Run faster (2.3x faster LLM)
-- ✅ Use less memory (6GB vs 14GB)
-
-### 4. Focus on Hackathon
-
-Don't worry about:
-- ❌ Making everything use MCP (current hybrid is fine)
-- ❌ Adding AI tool calling (current workflow is fine)
-- ❌ Over-engineering (keep it simple!)
-
-Do focus on:
-- ✅ Making MCP servers useful for AI agents
-- ✅ Showing the pipeline works end-to-end
-- ✅ Good demo and documentation
-- ✅ Shipping it!
-
----
-
-## Files to Read
-
-1. **MCP_ANALYSIS_AND_FIXES.md** - Deep dive into all issues and solutions
-2. **MCP_HACKATHON_GUIDE.md** - Simplified guide for HF Spaces
-3. **This file** - Quick answers to your 3 questions
-
----
-
-## TL;DR
-
-1. **Services bypass MCP** → OK for hackathon
-2. **Workflow is hardcoded** → OK for hackathon, reliable
-3. **LLM upgraded to 3B** → 2.3x faster on free CPU! 🚀
-
-**Your app should now build and run faster on HF Spaces!**
-
-Good luck! 🎉

QUICK_FIX_SUMMARY.md

@@ -1,68 +0,0 @@
-# ⚡ Quick Fix Summary
-
-## ❌ **Error You Saw**
-```
-ModuleNotFoundError: No module named 'bs4'
-```
-
-## ✅ **What I Fixed**
-
-Updated `requirements.txt` to include the missing packages:
-
-```txt
-# Web Scraping (REQUIRED for production contact finding)
-beautifulsoup4>=4.12.0
-lxml>=4.9.0
-
-# Gradio Interface
-gradio==5.5.0
-```
-
-## 🚀 **What You Need to Do**
-
-### **On HuggingFace Spaces:**
-
-**Simply restart your Space:**
-1. Go to your Space settings
-2. Click **"Factory Reboot"** or just push the updated `requirements.txt`
-3. Wait 2-3 minutes for packages to install
-4. ✅ Done!
-
-HuggingFace will automatically install:
-- `beautifulsoup4` (for web scraping)
-- `lxml` (HTML parser)
-- All other dependencies
-
-## ✅ **After Restart**
-
-Your B2B Sales Agent will have **REAL production capabilities**:
-
-✅ Scrapes actual company websites
-✅ Finds real contact information
-✅ Extracts decision maker names
-✅ Generates pattern-based emails
-✅ AI-powered validation
-
-## 📋 **Verify It Worked**
-
-Check your Space logs for:
-```
-✅ Successfully installed beautifulsoup4-4.12.x lxml-4.9.x
-✅ CX Platform database initialized
-✅ System initialized successfully
-```
-
-**No more errors!** 🎉
-
-## 📁 **Files Updated**
-
-- ✅ `requirements.txt` - Added beautifulsoup4 and lxml
-- ✅ All Python files verified - No syntax errors
-
-## 🎯 **Bottom Line**
-
-**Just restart your HuggingFace Space** and the production-ready web scraping will work!
-
----
-
-See `DEPLOYMENT_FIX.md` for detailed troubleshooting if needed.

QUICK_START.md

@@ -1,196 +0,0 @@
-# 🚀 Quick Start - Dynamic Discovery Mode
-
-## 5-Minute Setup
-
-### 1. Install Dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-**Key dependency**: `duckduckgo-search` (free, no API key needed)
-
-### 2. Set Environment Variables
-
-```bash
-# Copy example
-cp .env.example .env
-
-# Edit .env and add your HuggingFace token
-HF_API_TOKEN=your_token_here
-```
-
-**Note**: No web search API key needed!
-
-### 3. Start MCP Servers
-
-```bash
-bash scripts/start_mcp_servers.sh
-```
-
-### 4. Run the Application
-
-```bash
-# Gradio UI (recommended)
-python app.py
-
-# Or FastAPI
-python app/main.py
-```
-
-### 5. Try It!
-
-**Gradio UI:**
-1. Open browser to http://localhost:7860
-2. Enter company name: `Shopify`
-3. Click "Discover & Process"
-4. Watch real-time discovery!
-
-**FastAPI:**
-```bash
-curl -X POST http://localhost:8000/run \
-  -H "Content-Type: application/json" \
-  -d '{"company_names": ["Shopify"]}'
-```
-
----
-
-## Usage Examples
-
-### Single Company
-
-```python
-from app.orchestrator import Orchestrator
-import asyncio
-
-async def main():
-    orch = Orchestrator()
-    async for event in orch.run_pipeline(company_names=["Shopify"]):
-        print(event)
-
-asyncio.run(main())
-```
-
-### Multiple Companies
-
-```python
-companies = ["Shopify", "Stripe", "Zendesk"]
-async for event in orch.run_pipeline(company_names=companies):
-    print(event)
-```
-
-### API Request
-
-```bash
-# Dynamic mode (NEW)
-curl -X POST http://localhost:8000/run \
-  -d '{"company_names": ["Shopify", "Stripe"]}'
-
-# Legacy mode (backwards compatible)
-curl -X POST http://localhost:8000/run \
-  -d '{"company_ids": ["acme"], "use_seed_file": true}'
-```
-
----
-
-## What Gets Discovered?
-
-For each company, the system finds:
-
-- ✅ **Company Info**: Domain, industry, size
-- ✅ **Pain Points**: Current challenges from web search
-- ✅ **Recent News**: Latest updates and developments
-- ✅ **Facts**: Industry insights and context
-- ✅ **Decision-Makers**: CXOs, VPs, Directors
-- ✅ **Personalized Email**: AI-generated outreach
-- ✅ **Handoff Packet**: Complete dossier for sales
-
----
-
-## Example Companies to Try
-
-### E-Commerce
-- Shopify
-- Etsy
-- BigCommerce
-
-### SaaS
-- Stripe
-- Slack
-- Monday.com
-- Zendesk
-- Notion
-
-### FinTech
-- Square
-- Plaid
-- Braintree
-
-### Tech
-- Atlassian
-- Asana
-- Airtable
-
----
-
-## Typical Output
-
-```
-🔍 Discovering company: Shopify
-✓ Found domain: shopify.com
-✓ Industry: E-commerce
-✓ Size: ~10,000 employees
-✓ Found 12 facts from web search
-✓ Discovered 3 decision-makers
-✓ Generated personalized email
-✓ Compliance checks passed
-✓ Handoff packet ready!
-```
-
----
-
-## Performance
-
-- **Single Company**: ~30-60 seconds
-- **Discovery**: ~5 seconds
-- **Enrichment**: ~5 seconds
-- **Content Generation**: ~10-20 seconds
-- **Total Pipeline**: ~40-60 seconds
-
----
-
-## Troubleshooting
-
-### Issue: Module not found
-```bash
-pip install -r requirements.txt
-```
-
-### Issue: Company not found
-- Try different name variations
-- System uses fallbacks automatically
-
-### Issue: Slow performance
-- Normal for web search
-- Consider fewer companies at once
-
----
-
-## Next Steps
-
-1. **Read Full Guide**: See `UPGRADE_GUIDE.md`
-2. **Explore Features**: Check `DYNAMIC_DISCOVERY_README.md`
-3. **Customize**: Edit `services/company_discovery.py`
-4. **Deploy**: Works on HF Spaces, self-hosted, or cloud
-
----
-
-## Support
-
-Questions? Check:
-- `UPGRADE_GUIDE.md` - Complete documentation
-- `DYNAMIC_DISCOVERY_README.md` - Feature details
-- Code comments in `services/` directory
-- GitHub issues
-
-**Happy Discovering! 🚀**

QUICK_START_MCP.md

@@ -1,168 +0,0 @@
-# 🚀 Quick Start - MCP Autonomous Agent
-
-## TL;DR
-
-Your app now has **PROPER MCP** where AI (Claude 3.5 Sonnet) autonomously calls MCP tools. No hardcoded workflow!
-
----
-
-## ⚡ Quick Start (3 Steps)
-
-### 1. Install
-
-```bash
-pip install -r requirements.txt
-```
-
-### 2. Set API Keys
-
-```bash
-export ANTHROPIC_API_KEY=sk-ant-api03-...
-export SERPER_API_KEY=your_serper_key
-```
-
-### 3. Run
-
-```bash
-python app_mcp_autonomous.py
-```
-
-**Done!** Open `http://localhost:7860`
-
----
-
-## 🎯 What Changed
-
-### ❌ Before (Wrong)
-```python
-# Hardcoded workflow
-orchestrator.run()  # Fixed pipeline, no AI decisions
-```
-
-### ✅ After (Correct)
-```python
-# AI-driven
-agent.run("Any task")  # AI decides everything!
-```
-
----
-
-## 🛠️ Files Created
-
-| File | Purpose |
-|------|---------|
-| `mcp/tools/definitions.py` | 15 MCP tools for AI |
-| `mcp/agents/autonomous_agent.py` | AI agent (Claude 3.5) |
-| `app_mcp_autonomous.py` | Gradio demo |
-| `MCP_PROPER_IMPLEMENTATION.md` | Full docs |
-| `IMPLEMENTATION_COMPLETE.md` | Summary |
-
----
-
-## 💡 Try These Tasks
-
-```
-"Research Shopify and create a prospect profile"
-
-"Find 3 e-commerce SaaS companies and save as prospects"
-
-"Search for AI startup news and save as facts"
-
-"Create outreach campaign for Stripe"
-```
-
----
-
-## 🔑 API Keys
-
-### Anthropic (Required)
-Get from: https://console.anthropic.com/
-```bash
-export ANTHROPIC_API_KEY=sk-ant-api03-...
-```
-
-### Serper (Required for search)
-Get from: https://serper.dev/
-```bash
-export SERPER_API_KEY=your_key
-```
-
----
-
-## 🎭 How It Works
-
-```
-User Task → AI Agent → Decide Tools → Call MCP → Get Results → Repeat until Done
-```
-
-**Key:** AI decides everything autonomously!
-
----
-
-## 📊 Example Run
-
-```
-Task: "Research Shopify"
-
-AI decides:
-1. search_web("Shopify company info")     ← AI chose this
-2. save_company(name="Shopify", ...)      ← AI chose this
-3. search_news("Shopify recent news")     ← AI chose this
-4. save_fact("Shopify launched X", ...)   ← AI chose this
-5. save_prospect(company_id, score, ...)  ← AI chose this
-Done!
-```
-
-**No hardcoded workflow!**
-
----
-
-## 🏆 For Hackathon Judges
-
-This demonstrates:
-1. ✅ AI autonomous tool calling
-2. ✅ Proper MCP protocol
-3. ✅ 15 MCP tools
-4. ✅ 4 MCP servers
-5. ✅ No hardcoded workflow
-
----
-
-## 📚 Read More
-
-- **Full Guide:** `MCP_PROPER_IMPLEMENTATION.md`
-- **Summary:** `IMPLEMENTATION_COMPLETE.md`
-- **This File:** Quick reference
-
----
-
-## 🐛 Troubleshooting
-
-**"No API key"**
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-```
-
-**"Tool failed"**
-```bash
-export USE_IN_MEMORY_MCP=true
-```
-
-**"Search failed"**
-```bash
-export SERPER_API_KEY=your_key
-```
-
----
-
-## ✅ Ready to Demo!
-
-1. Set API keys ✓
-2. Run app ✓
-3. Try a task ✓
-4. Show AI deciding ✓
-5. Win hackathon! 🏆
-
----
-
-**That's it! You're ready!** 🎉

RATE_LIMIT_FIX.md

@@ -1,319 +0,0 @@
-# Rate Limiting and HF Spaces Fix
-
-## Issues Fixed
-
-### 1. DuckDuckGo Rate Limiting
-
-**Problem:**
-```
-DuckDuckGoSearchException: Ratelimit
-```
-
-**Root Cause:**
-Too many requests to DuckDuckGo in quick succession triggered rate limiting.
-
-**Solution:**
-Added comprehensive rate limiting protection:
-
-#### Features Added:
-1. **Request Throttling** - 2-second delay between requests
-2. **Retry Logic** - Up to 3 retry attempts with exponential backoff
-3. **Fresh Instances** - New DDGS instance for each request
-4. **Backoff Strategy** - 5s, 10s, 20s delays on rate limit errors
-
-#### Code Changes:
-
-**services/web_search.py:**
-```python
-class WebSearchService:
-    def __init__(self, max_results: int = 10, rate_limit_delay: float = 2.0):
-        self.rate_limit_delay = rate_limit_delay
-        self.last_request_time = 0
-        self._request_lock = asyncio.Lock()
-
-    async def _rate_limit(self):
-        """Enforce rate limiting between requests"""
-        async with self._request_lock:
-            current_time = time.time()
-            time_since_last_request = current_time - self.last_request_time
-
-            if time_since_last_request < self.rate_limit_delay:
-                sleep_time = self.rate_limit_delay - time_since_last_request
-                await asyncio.sleep(sleep_time)
-
-            self.last_request_time = time.time()
-
-    async def search(self, query: str, max_retries: int = 3):
-        for attempt in range(max_retries):
-            try:
-                await self._rate_limit()  # Throttle requests
-
-                # Create fresh DDGS instance
-                results = await loop.run_in_executor(
-                    None,
-                    lambda: list(DDGS().text(query, max_results=num_results))
-                )
-
-                return formatted_results
-
-            except Exception as e:
-                if "ratelimit" in str(e).lower():
-                    backoff_time = 5 * (2 ** attempt)  # 5s, 10s, 20s
-                    await asyncio.sleep(backoff_time)
-                    continue
-
-        return []  # Fallback to empty
-```
-
----
-
-### 2. MCP Servers for HF Spaces
-
-**Problem:**
-```
-Cannot connect to host localhost:9004 ssl:default [Connect call failed ('127.0.0.1', 9004)]
-```
-
-**Root Cause:**
-HF Spaces doesn't allow separate server processes. The app tried to connect to MCP servers running on different ports, which don't exist in HF Spaces.
-
-**Solution:**
-Created in-memory services that run within the same process.
-
-#### Architecture Change:
-
-**Before (Local Development):**
-```
-Gradio App → HTTP → MCP Server (Port 9001) → Search
-           → HTTP → MCP Server (Port 9002) → Email
-           → HTTP → MCP Server (Port 9003) → Calendar
-           → HTTP → MCP Server (Port 9004) → Store
-```
-
-**After (HF Spaces):**
-```
-Gradio App → In-Memory → Search Service
-           → In-Memory → Email Service
-           → In-Memory → Calendar Service
-           → In-Memory → Store Service
-```
-
-#### New Files Created:
-
-1. **mcp/in_memory_services.py** - In-memory service implementations
-2. **mcp/in_memory_clients.py** - Client wrappers for in-memory services
-3. **mcp/registry.py** - Updated to support both HTTP and in-memory modes
-
-#### Automatic Mode Detection:
-
-```python
-# In mcp/registry.py
-USE_IN_MEMORY_MODE = os.getenv("USE_IN_MEMORY_MCP", "true").lower() == "true"
-
-class MCPRegistry:
-    def __init__(self, use_in_memory: bool = None):
-        self.use_in_memory = use_in_memory if use_in_memory is not None else USE_IN_MEMORY_MODE
-
-        if self.use_in_memory:
-            # HF Spaces mode
-            self.search = InMemorySearchClient()
-            self.email = InMemoryEmailClient()
-            self.calendar = InMemoryCalendarClient()
-            self.store = InMemoryStoreClient()
-        else:
-            # Local development mode
-            self.search = SearchClient(f"http://localhost:{MCP_SEARCH_PORT}")
-            # ...etc
-```
-
----
-
-## Usage
-
-### For HF Spaces Deployment
-
-**No configuration needed!** The app automatically uses in-memory mode.
-
-Environment variable (optional):
-```bash
-USE_IN_MEMORY_MCP=true  # Default: true
-```
-
-### For Local Development
-
-To use separate MCP servers (optional):
-
-```bash
-# In .env
-USE_IN_MEMORY_MCP=false
-
-# Start MCP servers
-bash scripts/start_mcp_servers.sh
-
-# Run app
-python app.py
-```
-
----
-
-## Rate Limiting Best Practices
-
-### Recommended Settings
-
-| Setting | Value | Purpose |
-|---------|-------|---------|
-| `rate_limit_delay` | 2.0s | Delay between requests |
-| `max_results` | 5-10 | Results per query |
-| `max_retries` | 3 | Retry attempts |
-
-### If Still Encountering Rate Limits
-
-1. **Increase Delay:**
-   ```python
-   # In services/web_search.py
-   WebSearchService(rate_limit_delay=3.0)  # 3 seconds
-   ```
-
-2. **Reduce Queries:**
-   ```python
-   # In services/company_discovery.py
-   queries = queries[:2]  # Only use first 2 queries
-   ```
-
-3. **Process Fewer Companies:**
-   ```python
-   # Process one at a time
-   company_names = ["Shopify"]
-   ```
-
-4. **Wait Between Runs:**
-   Wait 1-2 minutes between pipeline runs
-
----
-
-## Performance Impact
-
-### Before (No Rate Limiting)
-
-- Fast but fails with rate limit errors
-- Unreliable for multiple companies
-- No retry logic
-
-### After (With Rate Limiting)
-
-- **Single Company**: ~30-60 seconds (reliable)
-- **Multiple Companies**: ~40-70 seconds each (sequential)
-- **Reliability**: High (3 retries with backoff)
-- **Success Rate**: >95% (with retries)
-
-### Time Breakdown (Per Company)
-
-| Phase | Time | Queries |
-|-------|------|---------|
-| Discovery | 5-15s | 4 queries |
-| Enrichment | 5-15s | 4 queries |
-| Contact Finding | 3-8s | 2-4 queries |
-| Content Generation | 10-20s | 0 queries |
-| **Total** | **25-60s** | **10-12 queries** |
-
----
-
-## Testing
-
-### Test Rate Limiting
-
-```python
-import asyncio
-from services.web_search import get_search_service
-
-async def test():
-    search = get_search_service()
-
-    # Should complete without errors
-    for i in range(5):
-        results = await search.search(f"test query {i}")
-        print(f"Query {i}: {len(results)} results")
-
-asyncio.run(test())
-```
-
-Expected: All queries complete successfully with 2s delays between them.
-
-### Test In-Memory Services
-
-```python
-from mcp.registry import MCPRegistry
-
-async def test():
-    mcp = MCPRegistry(use_in_memory=True)
-    await mcp.connect()
-
-    health = await mcp.health_check()
-    print(health)  # Should show all services as healthy
-
-asyncio.run(test())
-```
-
-Expected:
-```
-{
-    "search": "healthy (in-memory)",
-    "email": "healthy (in-memory)",
-    "calendar": "healthy (in-memory)",
-    "store": "healthy (in-memory)"
-}
-```
-
----
-
-## Troubleshooting
-
-### Still Getting Rate Limits?
-
-1. **Check Delay:** Verify rate_limit_delay is >= 2.0
-2. **Check Retries:** max_retries should be 3
-3. **Wait:** If persistent, wait 5-10 minutes
-4. **Reduce Load:** Process one company at a time
-
-### MCP Services Not Working?
-
-1. **Check Mode:** Verify USE_IN_MEMORY_MCP=true
-2. **Check Imports:** Ensure in_memory_services.py exists
-3. **Check Logs:** Look for "Using in-memory services" message
-
-### Performance Issues?
-
-1. **Normal:** 30-60s per company is expected
-2. **Too Slow:** Consider reducing max_results
-3. **Timeout:** Increase delay between retries
-
----
-
-## Summary
-
-### ✅ Fixed Issues
-
-1. ✅ DuckDuckGo rate limiting
-2. ✅ MCP server connection errors
-3. ✅ HF Spaces deployment compatibility
-4. ✅ Gradio 5.x message format
-5. ✅ Dependency version conflicts
-
-### 🚀 Ready for Deployment
-
-- Works on HF Spaces out of the box
-- No separate server processes needed
-- Built-in rate limiting protection
-- Graceful error handling
-- Automatic fallbacks
-
-### 📚 Documentation Created
-
-- `HF_SPACES_DEPLOYMENT.md` - Complete deployment guide
-- `RATE_LIMIT_FIX.md` - This document
-- Updated `.env.example` - Configuration reference
-- Updated `README.md` - Project overview
-
----
-
-**The app is now production-ready for Hugging Face Spaces! 🎉**

README.md

@@ -1,139 +1,163 @@
 ---
-title: CX AI Agent - B2B Sales Automation
-emoji: 💼
+title: CX AI Agent - B2B Sales Intelligence
+emoji: 🤖
 colorFrom: blue
 colorTo: purple
 sdk: gradio
-sdk_version: 5.49.1
+sdk_version: 5.33.0
 app_file: app.py
 pinned: false
+license: mit
+short_description: AI-powered B2B sales automation with MCP tools
+tags:
+- mcp-in-action-track-enterprise
+- mcp
+- autonomous-agent
+- b2b-sales
+- prospect-discovery
+- email-automation
+- gradio
+- huggingface
+- qwen
+- sales-intelligence
 ---
 
-# 💼 CX AI Agent - B2B Sales Automation Platform
+# 🤖 CX AI Agent - B2B Sales Intelligence Platform
 
-**Automated Prospect Discovery & Personalized Email Generation for B2B Sales**
+[![Enterprise Application](https://img.shields.io/badge/MCP-Enterprise%20Track-blue)](https://github.com)
+[![Powered by AI](https://img.shields.io/badge/Powered%20by-HuggingFace-yellow)](https://huggingface.co)
+[![Gradio](https://img.shields.io/badge/Built%20with-Gradio-orange)](https://gradio.app)
 
-## 🎯 What Does This Do?
+> **🏆 MCP in Action Track - Enterprise Applications**
+>
+> Tag: `mcp-in-action-track-enterprise`
 
-This application automates B2B sales outreach by:
+## 📹 Overview
 
-1. **Researching your CLIENT company** (e.g., "Shopify")
-2. **Finding PROSPECT companies** who would benefit from your client's services
-3. **Discovering decision-makers** at each prospect company
-4. **Generating personalized sales emails** FROM your client TO prospects
+An AI-powered B2B sales automation platform that helps sales teams discover prospects, find decision-makers, and draft personalized outreach emails—all powered by autonomous AI agents using the **Model Context Protocol (MCP)**.
 
-**Input:** CLIENT company name → **Output:** Ready-to-send sales emails
+## 🎯 Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **🔍 AI Discovery** | Automatically find and research prospect companies matching your ideal customer profile |
+| **👥 Contact Finder** | Locate decision-makers (CEOs, VPs, Founders) with verified email addresses |
+| **✉️ Email Drafting** | Generate personalized cold outreach emails based on company research |
+| **💬 AI Chat** | Interactive assistant for pipeline management and real-time research |
+| **👤 Prospect Chat** | Demo of prospect-facing AI with handoff & escalation capabilities |
+| **📊 Dashboard** | Real-time pipeline metrics and progress tracking |
 
 ## 🚀 Quick Start
 
-1. Go to the **"💼 B2B Sales"** tab
-2. Enter your client company name (e.g., "Shopify", "Stripe", "HubSpot")
-3. Choose number of prospects to find (1-5)
-4. Click "🚀 Find Prospects & Generate Emails"
-5. View real-time progress and generated emails
+1. **Setup**: Enter your HuggingFace token and company name
+2. **Discover**: Let AI find prospects matching your profile
+3. **Review**: Check discovered companies and contacts
+4. **Engage**: Use AI-drafted emails for outreach
 
-## 📧 Example
+## 🏗️ Architecture
 
-**Input:**
-- Client: Shopify
-- Prospects: 3
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      CX AI Agent                            │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │   Gradio    │  │  Autonomous │  │    MCP      │         │
+│  │     UI      │──│    Agent    │──│   Servers   │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+│         │                │                │                 │
+│         ▼                ▼                ▼                 │
+│  ┌─────────────────────────────────────────────────┐       │
+│  │              MCP Tool Definitions               │       │
+│  │  • Search (Web, News)                          │       │
+│  │  • Store (Prospects, Contacts, Facts)          │       │
+│  │  • Email (Send, Thread Management)             │       │
+│  │  • Calendar (Meeting Slots, Invites)           │       │
+│  └─────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────┘
+```
 
-**Output:**
-- 3 prospect companies identified
-- 3-9 decision-maker contacts found
-- 3-9 personalized emails generated
+## 🔧 MCP Tools Available
 
-Each email includes:
-- Prospect's pain points
-- Client's value proposition
-- Specific benefits
-- Call to action
+### Search MCP Server
+- `search_web` - Search the web for company information
+- `search_news` - Find recent news about companies
 
-## 🔑 Environment Variables
+### Store MCP Server
+- `save_prospect` / `get_prospect` / `list_prospects` - Manage prospects
+- `save_company` / `get_company` - Store company data
+- `save_contact` / `list_contacts_by_domain` - Manage contacts
+- `discover_prospects_with_contacts` - Full discovery pipeline
+- `find_verified_contacts` - Find decision-makers
 
-Set these in your Space Secrets:
+### Email MCP Server
+- `send_email` - Send outreach emails
+- `get_email_thread` - Retrieve conversation history
 
-```
-SERPER_API_KEY=your_serper_api_key_here
-```
+### Calendar MCP Server
+- `suggest_meeting_slots` - Generate available times
+- `generate_calendar_invite` - Create .ics files
 
-Get your Serper API key at: https://serper.dev
+## 🎭 Prospect Chat Demo
 
-## 🏗️ Features
+The **Prospect Chat Demo** showcases how prospects can interact with your company's AI:
 
-### Core B2B Sales Automation
-- ✅ Live web search for company research
-- ✅ Automated prospect discovery
-- ✅ Contact finding at prospect companies
-- ✅ Personalized email generation
-- ✅ Real-time streaming progress
-- ✅ Full email content display
+- **Lead Qualification**: AI asks qualifying questions to understand prospect needs
+- **Handoff Packets**: Generate comprehensive summaries for human sales reps
+- **Escalation Flows**: Automatically escalate complex inquiries to humans
+- **Meeting Scheduling**: Integrate with calendar for instant booking
 
-### Additional CX Platform
-- 🎫 Ticket Management System
-- 📚 Knowledge Base with RAG
-- 💬 Live Chat with AI Bot
-- 📊 Analytics Dashboard
-- 🔄 8-Agent Orchestration Pipeline
+## 📊 Technology Stack
 
-## 📖 Documentation
+| Component | Technology |
+|-----------|------------|
+| **Frontend** | Gradio 5.x |
+| **AI Model** | Qwen2.5-72B / Qwen3-32B via HuggingFace |
+| **Protocol** | Model Context Protocol (MCP) |
+| **Search** | Serper API |
+| **Language** | Python 3.8+ |
 
-See [ABOUT.md](./ABOUT.md) for complete documentation including:
-- Detailed workflow explanation
-- Real-world examples
-- Architecture overview
-- Usage guide
+## 🔑 Environment Variables
 
-## 🛠️ Technology Stack
+Set these in your Space Secrets:
 
-- **Frontend:** Gradio 5.x
-- **Backend:** Python 3.10+
-- **Search:** Serper API (Google Search)
-- **Database:** SQLite with SQLAlchemy
-- **Vector Store:** FAISS
-- **LLM:** Hugging Face Inference API
+```
+HF_TOKEN=your_huggingface_token_here
+SERPER_API_KEY=your_serper_api_key_here  # Optional
+```
 
-## 📝 How It Works
+## 📁 Project Structure
 
-**Correct Workflow:**
 ```
-Input: Shopify (CLIENT)
-    ↓
-Research Shopify's offerings
-    ↓
-Find prospects who need Shopify
-    ↓
-Research prospect pain points
-    ↓
-Find decision-makers at prospects
-    ↓
-Generate emails FROM Shopify TO prospects
+cx-ai-agent/
+├── app.py                    # Main Gradio application
+├── requirements.txt          # Python dependencies
+├── README.md                 # This file
+├── app/
+│   └── schema.py            # Pydantic data models
+└── mcp/
+    ├── agents/              # Autonomous AI agents
+    ├── servers/             # MCP server implementations
+    └── tools/
+        └── definitions.py   # MCP tool definitions
 ```
 
-**Key Point:** Emails are generated FROM your client company TO their prospects (not the other way around).
+## 📝 License
 
-## 🎓 Use Cases
+This project is open source and available under the MIT License.
 
-- **Sales Teams:** Automate prospect discovery and initial outreach
-- **Marketing Agencies:** Generate personalized emails for clients
-- **SDRs:** Scale outbound sales prospecting
-- **Business Development:** Identify and engage potential partners
+## 🙏 Acknowledgments
 
-## 🔜 Roadmap
+- **Anthropic** - Model Context Protocol specification
+- **HuggingFace** - AI model hosting and inference
+- **Gradio** - UI framework
+- **Serper** - Web search API
 
-- [ ] Reply handling with AI
-- [ ] Human escalation and handoff packets
-- [ ] Email sending via AWS SES
-- [ ] Advanced compliance checking
-- [ ] LinkedIn/Apollo contact enrichment
-- [ ] Separate function API endpoints
-
-## 📄 License
+---
 
-See LICENSE file for details.
+<div align="center">
 
----
+**Built with ❤️ for the Gradio Agents & MCP Hackathon 2025**
 
-**Track 2: MCP in Action** - Hugging Face Hackathon Project
+`mcp-in-action-track-enterprise`
 
-For configuration reference, see: https://huggingface.co/docs/hub/spaces-config-reference
+</div>

README_GRANITE4_MCP.md

@@ -1,515 +0,0 @@
-# 🤖 CX AI Agent - Autonomous MCP with Granite 4.0 H-1B
-
-## ✅ PROPER MCP Implementation with Open Source LLM
-
-This is the **correct MCP implementation** for the hackathon where:
-- ✅ **AI (Granite 4.0 H-1B) autonomously calls MCP servers** - Not hardcoded!
-- ✅ **100% Open Source** - IBM Granite 4.0 H-1B (1.5B params)
-- ✅ **Optimized for Tool Calling** - Strong function calling capabilities
-- ✅ **ReAct Pattern** - Reasoning + Acting for reliable tool calling
-- ✅ **Entry Point: app.py** - Main Gradio application
-- ✅ **Free Tier Compatible** - Works on HuggingFace Spaces (CPU)
-
----
-
-## 🚀 Quick Start
-
-### 1. Install Dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-### 2. Set Environment Variables
-
-```bash
-# Required: HuggingFace API token (for Granite 4 inference)
-export HF_API_TOKEN=hf_your_token_here
-
-# Optional: For real web search
-export SERPER_API_KEY=your_serper_key
-
-# Optional: In-memory MCP mode (default for HF Spaces)
-export USE_IN_MEMORY_MCP=true
-```
-
-### 3. Run the App
-
-```bash
-python app.py
-```
-
-Open `http://localhost:7860` in your browser!
-
----
-
-## 🎯 What Changed
-
-### ❌ Before (Wrong)
-- Used Claude 3.5 Sonnet (closed source, paid API)
-- Required Anthropic API key
-- Not suitable for free tier
-
-### ✅ After (Correct)
-- Uses **Granite 4.0 H-1B** (IBM, 1.5B params, optimized for tool calling)
-- **Local model loading** with transformers
-- Works on free CPU tier
-- Entry point is `app.py`
-
----
-
-## 🏗️ Architecture
-
-### Model: IBM Granite 4.0 H-1B
-
-**Why Granite 4.0 H-1B?**
-- ✅ Open source (Apache 2.0 license)
-- ✅ **1.5B active parameters** - Ultra-efficient for CPU
-- ✅ **Optimized for tool/function calling** - Key strength
-- ✅ Excellent instruction following (78.53% IFEval)
-- ✅ Strong code tasks (73% HumanEval pass@1)
-- ✅ **128K context window** - Long conversations
-- ✅ Hybrid Mamba2/Transformer architecture
-- ✅ Lower memory: ~2-4GB vs 6-8GB
-
-**Model ID:** `ibm-granite/granite-4.0-h-1b`
-
-### ReAct Pattern (Reasoning + Acting)
-
-Since open-source models don't have native tool calling like Claude, we use **ReAct**:
-
-```
-User Task
-    ↓
-AI: Thought: "I need to search for company info"
-    ↓
-AI: Action: search_web
-AI: Action Input: {"query": "Shopify company"}
-    ↓
-MCP Server: Execute search_web
-    ↓
-AI: Observation: [search results]
-    ↓
-AI: Thought: "Now I'll save the company"
-    ↓
-AI: Action: save_company
-AI: Action Input: {"name": "Shopify", ...}
-    ↓
-MCP Server: Execute save_company
-    ↓
-AI: Observation: {status: "saved"}
-    ↓
-AI: Thought: "Task complete!"
-AI: Final Answer: "Created prospect profile for Shopify"
-```
-
-**Key:** AI decides everything autonomously!
-
----
-
-## 📁 File Structure
-
-```
-cx_ai_agent/
-├── app.py                              ✅ MAIN ENTRY POINT
-├── mcp/
-│   ├── agents/
-│   │   └── autonomous_agent_granite.py ✅ Granite 4 agent with ReAct
-│   ├── tools/
-│   │   └── definitions.py              ✅ 15 MCP tool schemas
-│   ├── servers/                        ✅ MCP servers (HTTP mode)
-│   ├── in_memory_services.py           ✅ MCP services (in-memory)
-│   └── registry.py                     ✅ MCP registry
-├── requirements.txt                    ✅ Updated (no anthropic)
-└── README_GRANITE4_MCP.md              ✅ This file
-
-OLD (ignore):
-├── app_mcp_autonomous.py               ❌ Claude version
-├── mcp/agents/autonomous_agent.py      ❌ Claude version
-```
-
----
-
-## 🛠️ MCP Tools Available
-
-The AI can autonomously call these **15 MCP tools**:
-
-### 🔍 Search MCP Server
-- `search_web` - Search the web
-- `search_news` - Search for news
-
-### 💾 Store MCP Server
-- `save_prospect` - Save prospect
-- `get_prospect` - Get prospect by ID
-- `list_prospects` - List all prospects
-- `save_company` - Save company
-- `get_company` - Get company by ID
-- `save_fact` - Save enrichment fact
-- `save_contact` - Save contact
-- `list_contacts_by_domain` - Get contacts by domain
-- `check_suppression` - Check if suppressed (compliance)
-
-### 📧 Email MCP Server
-- `send_email` - Send email
-- `get_email_thread` - Get email thread
-
-### 📅 Calendar MCP Server
-- `suggest_meeting_slots` - Suggest meeting times
-- `generate_calendar_invite` - Generate .ics file
-
----
-
-## 🎓 How It Works
-
-### ReAct Prompting
-
-The AI is given this prompt structure:
-
-```
-You are an AI agent with access to MCP tools.
-
-Available tools:
-- search_web: Search for information
-- save_company: Save company data
-...
-
-Use this format:
-
-Thought: [your reasoning]
-Action: [tool_name]
-Action Input: {"param": "value"}
-
-[You'll see Observation with results]
-
-Thought: [next reasoning]
-Action: [next tool]
-...
-
-Thought: [final reasoning]
-Final Answer: [summary]
-```
-
-### Example Run
-
-**Task:** "Research Shopify"
-
-```
-🤖 Agent Start
-
-Iteration 1:
-💭 Thought: I need to search for Shopify information
-🔧 Action: search_web
-   Parameters: {"query": "Shopify company information"}
-✅ Tool completed
-   → Returned 5 items
-
-Iteration 2:
-💭 Thought: I'll save this company data
-🔧 Action: save_company
-   Parameters: {"name": "Shopify", "domain": "shopify.com", ...}
-✅ Tool completed
-   → Company ID: shopify
-
-Iteration 3:
-💭 Thought: Let me search for recent news
-🔧 Action: search_news
-   Parameters: {"query": "Shopify recent news"}
-✅ Tool completed
-   → Returned 5 items
-
-Iteration 4:
-💭 Thought: I'll save these facts
-🔧 Action: save_fact
-   Parameters: {"company_id": "shopify", "content": "...", ...}
-✅ Tool completed
-   → Fact ID: fact_123
-
-Iteration 5:
-💭 Thought: Now I'll create the prospect
-🔧 Action: save_prospect
-   Parameters: {"company_id": "shopify", "fit_score": 85, ...}
-✅ Tool completed
-   → Prospect ID: prospect_456
-
-✅ Task Complete!
-Final Answer: Successfully researched Shopify and created a prospect profile...
-```
-
----
-
-## 💡 Example Tasks to Try
-
-```
-"Research Shopify and create a prospect profile"
-
-"Find information about Stripe and save company details"
-
-"Search for Notion company info and save as prospect"
-
-"Investigate Figma and create a complete prospect entry"
-
-"Research Vercel and save company and facts"
-```
-
----
-
-## ⚙️ Configuration
-
-### Required Environment Variables
-
-```bash
-# HuggingFace API Token (REQUIRED)
-HF_API_TOKEN=hf_your_token_here
-# Or:
-HF_TOKEN=hf_your_token_here
-
-# Get token from: https://huggingface.co/settings/tokens
-```
-
-### Optional Environment Variables
-
-```bash
-# For real web search (free at serper.dev)
-SERPER_API_KEY=your_serper_key
-
-# MCP mode (default: true for HF Spaces)
-USE_IN_MEMORY_MCP=true
-
-# Skip web search if no API key (uses fallback data)
-SKIP_WEB_SEARCH=false
-```
-
-### HuggingFace Spaces Setup
-
-1. Go to your Space → **Settings → Repository secrets**
-2. Add secrets:
-   - `HF_TOKEN` = your HuggingFace token
-   - `SERPER_API_KEY` = your Serper key (optional)
-3. Restart the Space
-
----
-
-## 🎯 For Hackathon Judges
-
-### This Implementation Demonstrates:
-
-1. ✅ **AI Autonomous Tool Calling**
-   - Granite 4 decides which MCP tools to call
-   - No hardcoded workflow
-   - ReAct pattern for reliable reasoning
-
-2. ✅ **Proper MCP Protocol**
-   - 15 MCP tools with schemas
-   - 4 MCP servers (Search, Store, Email, Calendar)
-   - Tool definitions follow MCP spec
-
-3. ✅ **Open Source**
-   - IBM Granite 4.0 Micro (ultra-efficient)
-   - No proprietary APIs required
-   - Free tier compatible
-
-4. ✅ **Adaptable to Any Task**
-   - Not a fixed pipeline
-   - AI adapts based on task
-   - Can handle diverse B2B automation tasks
-
-5. ✅ **Production Ready**
-   - Works on HuggingFace Spaces
-   - Proper error handling
-   - Progress tracking
-   - User-friendly Gradio interface
-
----
-
-## 📊 Performance
-
-### Granite 4.0 H-1B Characteristics
-
-| Metric | Value |
-|--------|-------|
-| **Parameters** | 1.5B active (hybrid architecture) |
-| **Context Length** | 128K tokens |
-| **CPU Inference Speed** | 8-20 tokens/sec (free tier) |
-| **Memory Usage** | ~2-4GB (FP32/BF16) |
-| **Tool Call Accuracy** | 80-90% (optimized for this!) |
-| **Cost** | FREE (local model) |
-
-### Typical Task Performance
-
-| Task Type | Iterations | Time |
-|-----------|-----------|------|
-| Simple research | 3-5 | 15-30 sec |
-| Company profile | 5-8 | 30-60 sec |
-| Multi-prospect | 8-12 | 60-120 sec |
-
----
-
-## 🐛 Troubleshooting
-
-### "HF_API_TOKEN not found"
-
-```bash
-# Set locally
-export HF_API_TOKEN=hf_your_token_here
-
-# Or in HF Space:
-# Settings → Repository secrets → Add HF_TOKEN
-```
-
-### "Tool execution failed"
-
-- Check `USE_IN_MEMORY_MCP=true` is set
-- Check MCP registry initialized correctly
-- See console logs for details
-
-### "Search failed"
-
-```bash
-# Add Serper API key
-export SERPER_API_KEY=your_key
-
-# Or use fallback data
-export SKIP_WEB_SEARCH=true
-```
-
-### "ReAct parsing failed"
-
-- AI might be confused
-- Try simpler task
-- Check if task is clear and specific
-- Granite 4 will retry with feedback
-
----
-
-## 🔬 Technical Details
-
-### Why ReAct Instead of Native Tool Calling?
-
-**Native Tool Calling** (Claude, GPT-4):
-- Requires specific API format
-- Not available in most open-source models
-- Expensive proprietary APIs
-
-**ReAct Pattern** (Granite 4):
-- ✅ Works with any instruct-tuned model
-- ✅ Pure prompt engineering
-- ✅ No special API required
-- ✅ Free and open source
-- ✅ More transparent (see AI reasoning)
-
-### Parsing ReAct Responses
-
-```python
-# Extract thought
-thought_match = re.search(r'Thought:\s*(.+?)(?=\n(?:Action:|Final Answer:)|$)', response)
-
-# Extract action
-action_match = re.search(r'Action:\s*(\w+)', response)
-
-# Extract action input (JSON)
-action_input_match = re.search(r'Action Input:\s*(\{.+?\})', response)
-
-# Extract final answer
-final_answer_match = re.search(r'Final Answer:\s*(.+?)$', response)
-```
-
----
-
-## 📚 References
-
-### IBM Granite
-
-- **Homepage:** https://www.ibm.com/granite
-- **HuggingFace:** https://huggingface.co/ibm-granite/granite-4.0-h-1b
-- **Paper:** Granite Code Models (IBM Research)
-- **License:** Apache 2.0 (open source)
-
-### Model Context Protocol (MCP)
-
-- **Spec:** https://modelcontextprotocol.io/
-- **Anthropic:** https://docs.anthropic.com/en/docs/agents-and-tools
-
-### ReAct Pattern
-
-- **Paper:** "ReAct: Synergizing Reasoning and Acting in Language Models" (Yao et al., 2023)
-- **Pattern:** Thought → Action → Observation → Repeat
-
----
-
-## ✅ Checklist for Deployment
-
-### Local Development
-- [ ] Install dependencies: `pip install -r requirements.txt`
-- [ ] Set `HF_API_TOKEN` environment variable
-- [ ] (Optional) Set `SERPER_API_KEY` for web search
-- [ ] Run: `python app.py`
-- [ ] Test with example tasks
-
-### HuggingFace Spaces
-- [ ] Create Space with Python SDK
-- [ ] Set `app_file: app.py` in README
-- [ ] Add secrets: `HF_TOKEN`, `SERPER_API_KEY`
-- [ ] Push code to Space
-- [ ] Verify MCP servers initialize
-- [ ] Test autonomous agent
-
-### Hackathon Demo
-- [ ] Prepare 2-3 example tasks
-- [ ] Test tasks work end-to-end
-- [ ] Explain ReAct pattern
-- [ ] Show AI decision-making
-- [ ] Highlight MCP tool calls
-
----
-
-## 🎉 Summary
-
-You now have:
-
-✅ **Autonomous AI Agent**
-- Granite 4.0 H-1B (1.5B params, tool-calling optimized)
-- ReAct pattern for tool calling
-- Entry point: `app.py`
-
-✅ **15 MCP Tools**
-- Search, Store, Email, Calendar
-- Proper schemas
-- AI can call autonomously
-
-✅ **No Hardcoded Workflow**
-- AI decides everything
-- Adapts to any task
-- True MCP demonstration
-
-✅ **Free & Open Source**
-- No proprietary APIs
-- Works on HF free tier
-- 100% open source
-
-**Ready for MCP Hackathon!** 🏆
-
----
-
-## 📞 Support
-
-**Issues:**
-- Check HF_API_TOKEN is set
-- Check app.py is entry point
-- Check MCP servers initialize
-- See console logs for errors
-
-**Need Help:**
-- Read this README
-- Check example tasks
-- See ReAct pattern explanation
-- Review troubleshooting section
-
----
-
-**Built with:** IBM Granite 4.0 H-1B + Model Context Protocol (MCP) + ReAct Pattern
-
-**Entry Point:** `app.py`
-
-**License:** Apache 2.0 (open source)
-
-🚀 **Ready to demonstrate TRUE MCP with open source!**

README_HF_SPACES.md

@@ -1,322 +0,0 @@
----
-title: CX AI Agent - Autonomous Multi-Agent System
-emoji: 🤖
-colorFrom: blue
-colorTo: purple
-sdk: gradio
-sdk_version: 5.5.0
-app_file: app.py
-pinned: false
-tags:
-  - mcp-in-action-track-02
-  - autonomous-agents
-  - mcp
-  - rag
-  - customer-experience
-  - multi-agent-systems
-  - gradio
-license: mit
----
-
-# 🤖 CX AI Agent
-
-## Autonomous Multi-Agent Customer Experience Research & Outreach Platform
-
-[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-**Track 2: MCP in Action** submission for the Hugging Face + Anthropic Hackathon (November 2024)
-
----
-
-## 🎯 Overview
-
-CX AI Agent is a production-oriented autonomous multi-agent system that demonstrates:
-
-- ✅ **Autonomous Agent Behavior**: 8-agent orchestration with planning, reasoning, and execution
-- ✅ **MCP Servers as Tools**: Search, Email, Calendar, and Store servers integrated as agent tools
-- ✅ **Advanced Features**: RAG with FAISS, Context Engineering, Real-time LLM Streaming
-- ✅ **Real-world Application**: Automated customer experience research and personalized outreach
-
-### 🏗️ Architecture
-
-```
-8-Agent Pipeline:
-Hunter → Enricher → Contactor → Scorer → Writer → Compliance → Sequencer → Curator
-
-MCP Servers (Agent Tools):
-├── 🔍 Search: Company research and fact gathering
-├── 📧 Email: Email sending and thread management
-├── 📅 Calendar: Meeting scheduling and ICS generation
-└── 💾 Store: Prospect data persistence
-```
-
-### 🌟 Key Features
-
-#### 1. Autonomous Agent Orchestration
-- **Hunter**: Discovers prospects from seed companies
-- **Enricher**: Gathers facts using MCP Search server
-- **Contactor**: Finds decision-makers, checks suppression lists
-- **Scorer**: Calculates fit score based on industry alignment and pain points
-- **Writer**: Generates personalized content with RAG and LLM streaming
-- **Compliance**: Enforces regional email policies (CAN-SPAM, PECR, CASL)
-- **Sequencer**: Sends emails via MCP Email server
-- **Curator**: Prepares handoff packet for sales team
-
-#### 2. MCP Integration
-Each agent uses MCP servers as tools to accomplish its tasks:
-- **Search Server**: External data gathering and company research
-- **Email Server**: Communication management
-- **Calendar Server**: Meeting coordination
-- **Store Server**: Persistent state management
-
-#### 3. Advanced AI Capabilities
-- **RAG (Retrieval-Augmented Generation)**: FAISS vector store with sentence-transformers embeddings
-- **Context Engineering**: Comprehensive prompt engineering with company context, industry insights, and pain points
-- **Real-time Streaming**: Watch agents work with live LLM token streaming
-- **Compliance Framework**: Automated policy enforcement across multiple regions
-
----
-
-## 🚀 How It Works
-
-### 1. Pipeline Execution
-Run the autonomous agent pipeline to process prospects:
-- Enter company IDs (or leave empty to process all)
-- Click "Run Pipeline"
-- Watch agents work in real-time with streaming updates
-
-### 2. Real-time Monitoring
-- **Agent Output**: See generated summaries and email drafts as they're created
-- **Workflow Log**: Track agent activities and MCP server interactions
-- **Status**: Monitor current agent and processing stage
-
-### 3. System Management
-- **Health Check**: Verify MCP server connectivity and system status
-- **Reset System**: Clear data and reload seed companies
-
----
-
-## 🎥 Demo Video
-
-[Demo video will be included here showing the autonomous agent pipeline in action]
-
----
-
-## 🛠️ Technical Stack
-
-- **Framework**: Gradio 5.5 on Hugging Face Spaces
-- **LLM**: Hugging Face Inference API (Qwen2.5-7B-Instruct)
-- **Vector Store**: FAISS with sentence-transformers (all-MiniLM-L6-v2)
-- **MCP**: Model Context Protocol for tool integration
-- **Web Search**: Serper API (serper.dev - Google Search)
-- **Backend**: FastAPI with async operations
-- **Streaming**: Real-time NDJSON event streaming
-
----
-
-## 📋 Agent Details
-
-### Hunter Agent
-- **Role**: Prospect discovery
-- **Tools**: MCP Store (load companies)
-- **Output**: List of prospect objects initialized from seed data
-
-### Enricher Agent
-- **Role**: Company research and fact gathering
-- **Tools**: MCP Search (query company information)
-- **Output**: Prospects enriched with industry insights and facts
-
-### Contactor Agent
-- **Role**: Decision-maker identification
-- **Tools**: MCP Store (check suppression lists)
-- **Output**: Prospects with contact information and suppression checks
-
-### Scorer Agent
-- **Role**: Prospect qualification
-- **Tools**: Internal scoring algorithm
-- **Output**: Fit scores (0.0-1.0) based on industry, size, and pain points
-
-### Writer Agent
-- **Role**: Content generation
-- **Tools**:
-  - Vector Store (retrieve relevant facts via RAG)
-  - HuggingFace Inference API (LLM streaming)
-- **Output**: Personalized summaries and email drafts
-
-### Compliance Agent
-- **Role**: Policy enforcement
-- **Tools**: MCP Store (check email/domain suppressions)
-- **Output**: Compliant emails with required footers
-
-### Sequencer Agent
-- **Role**: Outreach execution
-- **Tools**:
-  - MCP Calendar (suggest meeting slots)
-  - MCP Email (send messages)
-- **Output**: Email threads with meeting invitations
-
-### Curator Agent
-- **Role**: Sales handoff preparation
-- **Tools**:
-  - MCP Email (retrieve threads)
-  - MCP Calendar (get available slots)
-- **Output**: Complete handoff packets ready for sales team
-
----
-
-## 🔬 Advanced Features Explained
-
-### RAG (Retrieval-Augmented Generation)
-The Writer agent uses a FAISS vector store to retrieve relevant facts before content generation:
-1. All company facts are embedded using sentence-transformers
-2. Facts are indexed in FAISS for fast similarity search
-3. During writing, the agent retrieves top-k most relevant facts
-4. These facts are injected into the LLM prompt for context-aware generation
-
-### Context Engineering
-Prompts include:
-- Company profile (name, industry, size, domain)
-- Pain points and business challenges
-- Relevant insights from vector store
-- Industry-specific best practices
-- Regional compliance requirements
-
-### Compliance Framework
-Automated enforcement of:
-- **CAN-SPAM** (US): Physical address, unsubscribe link
-- **PECR** (UK): Consent verification
-- **CASL** (Canada): Express consent requirements
-
----
-
-## 📊 Sample Output
-
-### Generated Summary Example
-```
-• TechCorp is a technology company with 500 employees
-• Main challenges: Customer data fragmentation, manual support processes
-• Opportunity: Implement AI-powered unified customer view
-• Recommended action: Schedule consultation to discuss CX automation
-```
-
-### Generated Email Example
-```
-Subject: Transform TechCorp's Customer Experience with AI
-
-Hi Sarah,
-
-As a technology company with 500 employees, you're likely facing challenges
-with customer data fragmentation and manual support processes. We've helped
-similar companies in the tech industry streamline their customer experience
-operations significantly.
-
-Our AI-powered platform provides a unified customer view and automated
-support workflows. Would you be available for a brief call next week to
-explore how we can address your specific needs?
-
-Best regards,
-The CX Team
-```
-
----
-
-## 🏆 Hackathon Submission Criteria
-
-### Track 2: MCP in Action ✅
-
-**Requirements Met:**
-- ✅ Demonstrates autonomous agent behavior with planning and execution
-- ✅ Uses MCP servers as tools throughout the pipeline
-- ✅ Built with Gradio on Hugging Face Spaces
-- ✅ Includes advanced features: RAG, Context Engineering, Streaming
-- ✅ Shows clear user value: automated CX research and outreach
-
-**Evaluation Criteria:**
-- ✅ **Design/Polished UI-UX**: Clean Gradio interface with real-time updates
-- ✅ **Functionality**: Full use of Gradio 6 features, MCP integration, agentic chatbot
-- ✅ **Creativity**: Novel 8-agent orchestration with compliance automation
-- ✅ **Documentation**: Comprehensive README with architecture details
-- ✅ **Real-world Impact**: Production-ready system for CX automation
-
----
-
-## 🎓 Learning Resources
-
-**MCP (Model Context Protocol):**
-- [Anthropic MCP Documentation](https://www.anthropic.com/mcp)
-- [MCP Specification](https://spec.modelcontextprotocol.io/)
-
-**Agent Systems:**
-- [LangChain Agents](https://python.langchain.com/docs/modules/agents/)
-- [Autonomous Agents Guide](https://www.anthropic.com/research/agents)
-
-**RAG:**
-- [Retrieval-Augmented Generation](https://arxiv.org/abs/2005.11401)
-- [FAISS Documentation](https://faiss.ai/)
-
----
-
-## 📝 Development
-
-### Local Setup
-```bash
-# Clone repository
-git clone https://github.com/yourusername/cx_ai_agent
-cd cx_ai_agent
-
-# Install dependencies
-pip install -r requirements_gradio.txt
-
-# Set up environment
-cp .env.example .env
-# Add your HF_API_TOKEN
-
-# Run Gradio app
-python app.py
-```
-
-### Environment Variables
-```bash
-HF_API_TOKEN=your_huggingface_token_here
-MODEL_NAME=Qwen/Qwen2.5-7B-Instruct
-SERPER_API_KEY=your_serper_api_key_here
-```
-
-**Getting a Serper API Key:**
-1. Visit [Serper.dev](https://serper.dev/)
-2. Sign up for a free account (includes 2,500 free searches/month)
-3. Get your API key from the dashboard
-4. Add it to your `.env` file
-
----
-
-## 🙏 Acknowledgments
-
-Built for the **Hugging Face + Anthropic Hackathon** (November 2024)
-
-Special thanks to:
-- Hugging Face for providing the Spaces platform and Inference API
-- Anthropic for the Model Context Protocol specification
-- The open-source community for FAISS, sentence-transformers, and Gradio
-
----
-
-## 📄 License
-
-MIT License - see LICENSE file for details
-
----
-
-## 🔗 Links
-
-- **Hugging Face Space**: [Link to your Space]
-- **GitHub Repository**: [Link to your repo]
-- **Social Media Post**: [Link to your X/LinkedIn post]
-- **Demo Video**: [Link to demo video]
-
----
-
-**Built with ❤️ for the Hugging Face + Anthropic Hackathon 2024**
-
-**Track**: MCP in Action (`mcp-in-action-track-02`)

README_HUGGINGFACE_MCP.md

@@ -1,417 +0,0 @@
-# 🤖 CX AI Agent - Autonomous MCP with HuggingFace Inference Providers
-
-## ✅ PROPER MCP Implementation with HuggingFace
-
-This is the **correct MCP implementation** for the hackathon where:
-- ✅ **AI autonomously calls MCP servers** - Not hardcoded!
-- ✅ **HuggingFace Inference Providers** - Unified API for multiple providers
-- ✅ **Native Tool Calling** - OpenAI-compatible function calling
-- ✅ **Models: Qwen2.5-72B, Llama-3.3-70B** - Strong tool calling capabilities
-- ✅ **Entry Point: app.py** - Main Gradio application
-- ✅ **Free Tier Compatible** - Works on HuggingFace Spaces
-
----
-
-## 🚀 Quick Start
-
-### 1. Install Dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-### 2. Set Environment Variables
-
-```bash
-# Required: HuggingFace token
-export HF_TOKEN=hf_your_token_here
-
-# Optional: Inference provider (default: nebius)
-export HF_PROVIDER=nebius  # or: together, sambanova, fireworks-ai, cerebras
-
-# Optional: Model to use
-export HF_MODEL=Qwen/Qwen2.5-72B-Instruct
-
-# Optional: For real web search
-export SERPER_API_KEY=your_serper_key
-
-# Optional: In-memory MCP mode (default for HF Spaces)
-export USE_IN_MEMORY_MCP=true
-```
-
-### 3. Run the App
-
-```bash
-python app.py
-```
-
-Open `http://localhost:7860` in your browser!
-
----
-
-## 🎯 What This Implementation Does
-
-### ✅ AI Autonomous Tool Calling
-- AI (Qwen2.5-72B or Llama-3.3-70B) decides which MCP tools to call
-- No hardcoded workflow - AI makes all decisions
-- Native function calling (not ReAct parsing)
-
-### ✅ HuggingFace Inference Providers
-- Single HF token works with multiple providers
-- Providers: Nebius, Together, Sambanova, Fireworks, Cerebras
-- Billing through HuggingFace account
-- Free tier available
-
-### ✅ No Local Model Loading
-- All inference runs in the cloud
-- No GPU/memory requirements
-- Fast startup time
-- Works on free HF Spaces
-
----
-
-## 🏗️ Architecture
-
-### HuggingFace Inference Providers
-
-HuggingFace routes your requests to inference providers:
-
-```
-Your App (HF_TOKEN)
-    ↓
-HuggingFace API
-    ↓
-┌─────────────────────────────────────┐
-│ Inference Providers                  │
-├─────────────────────────────────────┤
-│ • Nebius (default)                  │
-│ • Together AI                       │
-│ • Sambanova                         │
-│ • Fireworks AI                      │
-│ • Cerebras                          │
-└─────────────────────────────────────┘
-    ↓
-Model (Qwen2.5-72B, Llama-3.3-70B, etc.)
-```
-
-### Native Tool Calling Flow
-
-```
-User Task
-    ↓
-AI: Analyze task, decide on tools
-    ↓
-AI: tool_calls: [search_web, save_company]
-    ↓
-MCP Server: Execute tools
-    ↓
-AI: Process results
-    ↓
-AI: More tool calls if needed
-    ↓
-AI: Final Answer
-```
-
----
-
-## 📁 File Structure
-
-```
-cx_ai_agent/
-├── app.py                              ✅ MAIN ENTRY POINT
-├── mcp/
-│   ├── agents/
-│   │   └── autonomous_agent_hf.py      ✅ HuggingFace agent with tool calling
-│   ├── tools/
-│   │   └── definitions.py              ✅ 15 MCP tool schemas
-│   ├── servers/                        ✅ MCP servers (HTTP mode)
-│   ├── in_memory_services.py           ✅ MCP services (in-memory)
-│   └── registry.py                     ✅ MCP registry
-├── requirements.txt                    ✅ Updated (huggingface_hub)
-└── README_HUGGINGFACE_MCP.md           ✅ This file
-```
-
----
-
-## 🛠️ MCP Tools Available
-
-The AI can autonomously call these **15 MCP tools**:
-
-### 🔍 Search MCP Server
-- `search_web` - Search the web
-- `search_news` - Search for news
-
-### 💾 Store MCP Server
-- `save_prospect` - Save prospect
-- `get_prospect` - Get prospect by ID
-- `list_prospects` - List all prospects
-- `save_company` - Save company
-- `get_company` - Get company by ID
-- `save_fact` - Save enrichment fact
-- `save_contact` - Save contact
-- `list_contacts_by_domain` - Get contacts by domain
-- `check_suppression` - Check if suppressed (compliance)
-
-### 📧 Email MCP Server
-- `send_email` - Send email
-- `get_email_thread` - Get email thread
-
-### 📅 Calendar MCP Server
-- `suggest_meeting_slots` - Suggest meeting times
-- `generate_calendar_invite` - Generate .ics file
-
----
-
-## 🎓 Example Run
-
-**Task:** "Research Shopify"
-
-```
-🤖 Agent Start
-
-Iteration 1:
-🔧 Action: search_web
-   Parameters: {"query": "Shopify company information"}
-✅ Tool completed
-   → Returned 5 items
-
-Iteration 2:
-🔧 Action: save_company
-   Parameters: {"name": "Shopify", "domain": "shopify.com", ...}
-✅ Tool completed
-   → Company ID: shopify
-
-Iteration 3:
-🔧 Action: search_news
-   Parameters: {"query": "Shopify recent news"}
-✅ Tool completed
-   → Returned 5 items
-
-Iteration 4:
-🔧 Action: save_fact
-   Parameters: {"company_id": "shopify", "content": "...", ...}
-✅ Tool completed
-   → Fact ID: fact_123
-
-✅ Task Complete!
-Final Answer: Successfully researched Shopify and created a company profile...
-```
-
----
-
-## ⚙️ Configuration
-
-### Required Environment Variables
-
-```bash
-# HuggingFace Token (REQUIRED)
-HF_TOKEN=hf_your_token_here
-
-# Get token from: https://huggingface.co/settings/tokens
-```
-
-### Optional Environment Variables
-
-```bash
-# Inference provider (default: nebius)
-HF_PROVIDER=nebius
-
-# Available providers:
-# - nebius (default, good for Qwen models)
-# - together (good for Llama models)
-# - sambanova (fast inference)
-# - fireworks-ai
-# - cerebras
-
-# Model to use (default: Qwen/Qwen2.5-72B-Instruct)
-HF_MODEL=Qwen/Qwen2.5-72B-Instruct
-
-# Other models with tool calling:
-# - meta-llama/Llama-3.3-70B-Instruct
-# - meta-llama/Llama-3.1-70B-Instruct
-# - Qwen/Qwen3-32B
-
-# For real web search (free at serper.dev)
-SERPER_API_KEY=your_serper_key
-```
-
-### HuggingFace Spaces Setup
-
-1. Go to your Space → **Settings → Repository secrets**
-2. Add secrets:
-   - `HF_TOKEN` = your HuggingFace token
-   - `HF_PROVIDER` = nebius (optional)
-   - `SERPER_API_KEY` = your Serper key (optional)
-3. Restart the Space
-
----
-
-## 🎯 For Hackathon Judges
-
-### This Implementation Demonstrates:
-
-1. ✅ **AI Autonomous Tool Calling**
-   - AI decides which MCP tools to call
-   - No hardcoded workflow
-   - Native function calling
-
-2. ✅ **Proper MCP Protocol**
-   - 15 MCP tools with schemas
-   - 4 MCP servers (Search, Store, Email, Calendar)
-   - Tool definitions follow MCP spec
-
-3. ✅ **HuggingFace Integration**
-   - Uses HuggingFace Inference Providers
-   - Single token for multiple providers
-   - Free tier available
-
-4. ✅ **Adaptable to Any Task**
-   - Not a fixed pipeline
-   - AI adapts based on task
-   - Can handle diverse B2B automation tasks
-
-5. ✅ **Production Ready**
-   - Works on HuggingFace Spaces
-   - Proper error handling
-   - Progress tracking
-   - User-friendly Gradio interface
-
----
-
-## 📊 Performance
-
-### Inference Characteristics
-
-| Metric | Value |
-|--------|-------|
-| **Model** | Qwen2.5-72B-Instruct (configurable) |
-| **Provider** | Nebius (configurable) |
-| **Tool Call Accuracy** | 85-95% |
-| **Latency** | 1-3 seconds per iteration |
-| **Cost** | Free tier available |
-
-### Typical Task Performance
-
-| Task Type | Iterations | Time |
-|-----------|-----------|------|
-| Simple research | 2-4 | 5-15 sec |
-| Company profile | 4-6 | 15-30 sec |
-| Multi-step task | 6-10 | 30-60 sec |
-
----
-
-## 🐛 Troubleshooting
-
-### "HF_TOKEN not found"
-
-```bash
-# Set locally
-export HF_TOKEN=hf_your_token_here
-
-# Or in HF Space:
-# Settings → Repository secrets → Add HF_TOKEN
-```
-
-### "401 Unauthorized"
-
-- Check that your HF_TOKEN is valid
-- Make sure token has read permissions
-- Try regenerating the token
-
-### "Rate limit reached"
-
-- Free tier has rate limits
-- Wait a few minutes and try again
-- Consider upgrading to HF PRO ($9/month)
-
-### "Model not found"
-
-- Check the model name is correct
-- Some models may not be available on all providers
-- Try a different provider or model
-
----
-
-## 💡 Example Tasks to Try
-
-```
-"Research Shopify and create a prospect profile"
-
-"Find information about Stripe and save company details"
-
-"Search for Notion company info and save as prospect"
-
-"Investigate Figma and create a complete prospect entry"
-
-"Research Vercel and save company profile with industry insights"
-```
-
----
-
-## 📚 References
-
-### HuggingFace Inference Providers
-- **Docs:** https://huggingface.co/docs/inference-providers
-- **Chat Completion:** https://huggingface.co/docs/inference-providers/tasks/chat-completion
-
-### Model Context Protocol (MCP)
-- **Spec:** https://modelcontextprotocol.io/
-- **Anthropic:** https://docs.anthropic.com/en/docs/agents-and-tools
-
----
-
-## ✅ Checklist for Deployment
-
-### Local Development
-- [ ] Install dependencies: `pip install -r requirements.txt`
-- [ ] Set `HF_TOKEN` environment variable
-- [ ] (Optional) Set `HF_PROVIDER` and `HF_MODEL`
-- [ ] (Optional) Set `SERPER_API_KEY` for web search
-- [ ] Run: `python app.py`
-- [ ] Test with example tasks
-
-### HuggingFace Spaces
-- [ ] Create Space with Python SDK
-- [ ] Set `app_file: app.py` in README
-- [ ] Add secrets: `HF_TOKEN`, `SERPER_API_KEY`
-- [ ] Push code to Space
-- [ ] Verify agent initializes
-- [ ] Test autonomous agent
-
----
-
-## 🎉 Summary
-
-You now have:
-
-✅ **Autonomous AI Agent**
-- HuggingFace Inference Providers
-- Native tool calling
-- Entry point: `app.py`
-
-✅ **15 MCP Tools**
-- Search, Store, Email, Calendar
-- Proper schemas
-- AI can call autonomously
-
-✅ **No Hardcoded Workflow**
-- AI decides everything
-- Adapts to any task
-- True MCP demonstration
-
-✅ **Cloud Inference**
-- No local model loading
-- Works on free HF Spaces
-- Fast startup
-
-**Ready for MCP Hackathon!** 🏆
-
----
-
-**Built with:** HuggingFace Inference Providers + Model Context Protocol (MCP)
-
-**Entry Point:** `app.py`
-
-**License:** Apache 2.0 (open source)
-
-🚀 **Ready to demonstrate TRUE MCP with HuggingFace!**

SETUP_REAL_CONTACTS.md

@@ -1,308 +0,0 @@
-# Setup Guide: Real Contact Discovery
-
-## 🔑 IMPORTANT: API Key Required
-
-To find **real decision-makers** with actual names and work emails, you need to set up the **SERPER_API_KEY**.
-
-### Why This is Required
-
-The enhanced contact finder uses:
-1. **LinkedIn Profile Search** - Requires Google search via Serper.dev
-2. **Team Page Discovery** - Requires web search to find team pages
-3. **Contact Information Extraction** - Scrapes discovered pages
-
-**Without SERPER_API_KEY**, the system cannot search the web and will fall back to generated contacts.
-
----
-
-## Quick Setup (5 minutes)
-
-### Step 1: Get Free Serper API Key
-
-1. Go to https://serper.dev
-2. Sign up for a free account
-3. Navigate to "API Key" section
-4. Copy your API key
-
-**Free Tier:**
-- 2,500 searches/month
-- No credit card required
-- Perfect for testing and small-scale use
-
----
-
-### Step 2: Set Environment Variable
-
-**Windows (PowerShell):**
-```powershell
-# Temporary (current session only)
-$env:SERPER_API_KEY = "your-api-key-here"
-
-# Permanent (for your user account)
-[System.Environment]::SetEnvironmentVariable('SERPER_API_KEY', 'your-api-key-here', 'User')
-```
-
-**Windows (Command Prompt):**
-```cmd
-# Temporary (current session only)
-set SERPER_API_KEY=your-api-key-here
-
-# Permanent
-setx SERPER_API_KEY "your-api-key-here"
-```
-
-**Linux/Mac:**
-```bash
-# Temporary (current terminal session)
-export SERPER_API_KEY="your-api-key-here"
-
-# Permanent (add to ~/.bashrc or ~/.zshrc)
-echo 'export SERPER_API_KEY="your-api-key-here"' >> ~/.bashrc
-source ~/.bashrc
-```
-
----
-
-### Step 3: Create .env File (Recommended)
-
-Create a `.env` file in the project root:
-
-```
-# .env
-SERPER_API_KEY=your-actual-api-key-here
-HF_API_TOKEN=your-huggingface-token-here
-```
-
-The application will automatically load these on startup.
-
----
-
-### Step 4: Verify Setup
-
-Run the test script to verify everything works:
-
-```bash
-python test_contact_finder.py
-```
-
-**Expected Output:**
-```
-[TEST 1] Enhanced Contact Finder
---------------------------------------------------------------------------------
-Testing: Shopify (shopify.com)
---------------------------------------------------------------------------------
-
-[OK] Found 2 REAL contacts:
-
-  1. Tobi Lütke
-     Title: CEO
-     Email: [email protected]
-
-  2. Jean-Michel Lemieux
-     Title: Chief Technology Officer
-     Email: [email protected]
-```
-
-**If you see errors:**
-- `SERPER_API_KEY not found` - API key not set correctly
-- `SERPER_API_KEY not set. Cannot perform search` - Restart terminal after setting key
-- `[FAIL] No contacts found` - API key is set but quota exceeded or invalid
-
----
-
-## What Happens WITHOUT API Key?
-
-**Current Behavior:**
-```
-Log Output:
-- "SERPER_API_KEY not set. Cannot perform search."
-- "EnhancedFinder: Found 0 real contacts"
-- "ProspectDiscovery: Generating fallback contacts"
-
-Result:
-- System generates mock names like "Sarah Johnson", "Michael Chen"
-- Emails use generated names (not real people)
-- Email addresses are guessed (first.last@domain)
-```
-
-**With API Key:**
-```
-Log Output:
-- "EnhancedFinder: Using ENHANCED contact finder (LinkedIn + Team pages + AI)"
-- "ProspectDiscovery: Found REAL contact: John Smith (CEO) - [email protected]"
-- "Writer: Using contact: John Smith (CEO) - [email protected]"
-
-Result:
-- System finds actual decision-makers via LinkedIn/team pages
-- Emails addressed to real people by name
-- Email addresses are work emails from real profiles
-```
-
----
-
-## Testing Your Setup
-
-### Test 1: Check Environment Variable
-
-**Windows PowerShell:**
-```powershell
-$env:SERPER_API_KEY
-```
-
-**Windows CMD:**
-```cmd
-echo %SERPER_API_KEY%
-```
-
-**Linux/Mac:**
-```bash
-echo $SERPER_API_KEY
-```
-
-Should output your API key (not "not found" or blank).
-
----
-
-### Test 2: Run Simple Contact Search
-
-Create a test file `quick_test.py`:
-
-```python
-import asyncio
-from services.enhanced_contact_finder import get_enhanced_contact_finder
-
-async def test():
-    finder = get_enhanced_contact_finder()
-    contacts = await finder.find_real_contacts(
-        company_name="Shopify",
-        domain="shopify.com",
-        target_titles=["CEO"],
-        max_contacts=1
-    )
-
-    if contacts:
-        print(f"SUCCESS! Found: {contacts[0].name} - {contacts[0].email}")
-    else:
-        print("FAILED: No contacts found (check API key)")
-
-asyncio.run(test())
-```
-
-Run it:
-```bash
-python quick_test.py
-```
-
----
-
-### Test 3: Run Full Application
-
-Start the application:
-
-```bash
-python app.py
-```
-
-In the UI:
-1. Enter a client company: "Shopify"
-2. Click "Start Pipeline"
-3. **Watch the console logs**:
-   - Look for: `"Found REAL contact: [Name] ([Title]) - [Email]"`
-   - Or: `"Generating fallback contacts"` (means API key not working)
-
----
-
-## Troubleshooting
-
-### Issue: "SERPER_API_KEY not found"
-
-**Solution:**
-1. Verify you set the environment variable correctly
-2. Restart your terminal/IDE after setting it
-3. Use `.env` file instead (recommended)
-
----
-
-### Issue: "EnhancedFinder: Found 0 real contacts"
-
-**Possible Causes:**
-1. API key not set or invalid
-2. API quota exceeded (2,500 searches/month on free tier)
-3. Company doesn't have public LinkedIn profiles or team pages
-4. Website blocks scraping
-
-**Solution:**
-1. Verify API key works: https://serper.dev/dashboard
-2. Check API usage dashboard
-3. Try a different company with public profiles
-4. Check logs for specific errors
-
----
-
-### Issue: Emails still not personalized
-
-**Check:**
-1. Contacts are being found (check logs for "Found REAL contact")
-2. Contacts are attached to prospects (check logs in writer agent)
-3. Email template uses contact names (check `agents/writer.py`)
-
-**Verify in Logs:**
-```
-Writer: Using contact: John Smith (CEO) - [email protected]
-```
-
-If you see this, contacts are found but email generation might not be using them.
-
----
-
-## Alternative: Paid Contact APIs
-
-If you need more reliable contact data, consider professional APIs:
-
-### Hunter.io
-- **Pricing:** $49/month for 1,000 searches
-- **Features:** Email finder + verification
-- **Integration:** Modify `enhanced_contact_finder.py` to use Hunter API
-
-### Apollo.io
-- **Pricing:** $49-99/month
-- **Features:** 275M+ B2B contacts with verified emails
-- **Integration:** More complex but very reliable
-
-### RocketReach
-- **Pricing:** $39-119/month
-- **Features:** Contact finder with phone numbers
-- **Integration:** API available
-
----
-
-## Summary
-
-**Required for Real Contacts:**
-✅ SERPER_API_KEY set in environment or .env file
-✅ Free tier: 2,500 searches/month (sufficient for testing)
-✅ Restart terminal/application after setting  key
-
-**With API Key:**
-- Finds real decision-makers via LinkedIn
-- Discovers actual names and titles
-- Generates work email addresses
-- Personalizes emails with real names
-
-**Without API Key:**
-- Falls back to generated contacts
-- Uses mock names from predefined pool
-- Guesses email addresses
-- Generic email personalization
-
----
-
-## Next Steps
-
-1. ✅ **Set SERPER_API_KEY** (follow Step 2 above)
-2. ✅ **Run test** (`python test_contact_finder.py`)
-3. ✅ **Start application** (`python app.py`)
-4. ✅ **Create a prospect** and verify emails use real names
-5. ✅ **Check logs** to confirm: "Found REAL contact: [Name]..."
-
-**Questions?** Check the logs for detailed error messages or refer to ENHANCED_CONTACT_FINDER.md for technical details.

SKIP_WEB_SEARCH_FIX.md

@@ -1,349 +0,0 @@
-# SKIP_WEB_SEARCH Complete Fix
-
-## Problem
-
-Even though `SKIP_WEB_SEARCH=true` was configured in `.env.example`, the application was still making **extensive web search requests** that led to DuckDuckGo rate limiting.
-
-### Error Symptoms:
-```
-Search attempt 1/3 failed: DuckDuckGoSearchException: Ratelimit
-Search attempt 2/3 failed: DuckDuckGoSearchException: Ratelimit
-Search attempt 3/3 failed: DuckDuckGoSearchException: Ratelimit
-All 3 attempts failed for query 'Shopify official website'
-```
-
-**15+ failed search attempts per company** (domain search, 4 enricher queries, 9+ prospect queries)
-
-### Additional Error:
-```
-Warning: Email send failed: 'str' object has no attribute 'get'
-```
-
----
-
-## Root Cause Analysis
-
-The `SKIP_WEB_SEARCH` flag was only being checked in **one out of four places** that make web searches:
-
-| Agent/Service | Was Checking Flag? | Number of Searches |
-|---------------|-------------------|-------------------|
-| **Hunter** (company discovery) | ✅ YES | 1 search |
-| **Enricher** (fact gathering) | ❌ NO | 4 searches |
-| **ProspectDiscoveryService** (contacts) | ❌ NO | 9+ searches (3 per title × 3 titles) |
-| **Sequencer** (email send) | N/A | Email error |
-
-**Total searches when SKIP_WEB_SEARCH was ignored: 14+ per company**
-
----
-
-## Complete Fix
-
-### 1. Updated `agents/enricher.py`
-
-**Added SKIP_WEB_SEARCH check to skip all fact-gathering web searches:**
-
-```python
-# Import the flag
-from app.config import FACT_TTL_HOURS, SKIP_WEB_SEARCH
-
-# Check flag before searching
-async def run(self, prospect: Prospect) -> Prospect:
-    facts = []
-    seen_texts = set()
-
-    # Only do web search if not skipped
-    if not SKIP_WEB_SEARCH:
-        logger.info("Enricher: Performing web search for facts")
-        # ... 4 search queries here ...
-    else:
-        logger.info("Enricher: Skipping web search (SKIP_WEB_SEARCH=true)")
-
-    # Always add company pain points and notes as facts (from discovery)
-    for pain in prospect.company.pains:
-        # Create fact from pain point
-        # ...
-```
-
-**Result:** Enricher now skips 4 web searches when `SKIP_WEB_SEARCH=true`
-
----
-
-### 2. Updated `services/prospect_discovery.py`
-
-**Added `skip_search` parameter to ProspectDiscoveryService:**
-
-```python
-async def discover_contacts(
-    self,
-    company_name: str,
-    domain: str,
-    company_size: int,
-    max_contacts: int = 3,
-    skip_search: bool = False  # NEW PARAMETER
-) -> List[Contact]:
-
-    contacts = []
-    seen_emails = set()
-
-    # Only search if not skipped
-    if not skip_search:
-        logger.info("ProspectDiscovery: Performing web search for contacts")
-        # ... search for contacts ...
-    else:
-        logger.info("ProspectDiscovery: Skipping web search (skip_search=True)")
-
-    # Always generate fallback contacts if needed
-    if len(contacts) < max_contacts:
-        # Generate plausible fallback contacts
-        # ...
-```
-
-**Result:** ProspectDiscoveryService now skips 9+ web searches when `skip_search=True`
-
----
-
-### 3. Updated `agents/contactor.py`
-
-**Pass SKIP_WEB_SEARCH flag to ProspectDiscoveryService:**
-
-```python
-# Import the flag
-from app.config import SKIP_WEB_SEARCH
-
-# Pass to prospect discovery
-discovered_contacts = await self.prospect_discovery.discover_contacts(
-    company_name=prospect.company.name,
-    domain=prospect.company.domain,
-    company_size=prospect.company.size,
-    max_contacts=max_contacts,
-    skip_search=SKIP_WEB_SEARCH  # Respect SKIP_WEB_SEARCH flag
-)
-```
-
-**Result:** Contactor now respects the global SKIP_WEB_SEARCH setting
-
----
-
-### 4. Fixed `agents/sequencer.py`
-
-**Fixed email send error where result could be string or dict:**
-
-```python
-try:
-    result = await self.email_client.send(...)
-
-    # Handle both dict and string responses
-    if isinstance(result, dict):
-        prospect.thread_id = result.get("thread_id", str(uuid.uuid4()))
-    elif isinstance(result, str):
-        prospect.thread_id = result
-    else:
-        prospect.thread_id = str(uuid.uuid4())
-    prospect.status = "sequenced"
-
-except Exception as e:
-    # Graceful fallback
-    prospect.thread_id = f"mock-thread-{uuid.uuid4()}"
-    prospect.status = "sequenced"
-    print(f"Warning: Email send failed: {e}")
-```
-
-**Result:** No more `'str' object has no attribute 'get'` errors
-
----
-
-## Impact Summary
-
-### Before Fix (with SKIP_WEB_SEARCH=true):
-- ❌ Hunter: Skips search (1 search avoided) ✅
-- ❌ Enricher: **Still makes 4 searches** → Rate limiting
-- ❌ Contactor: **Still makes 9+ searches** → Rate limiting
-- ❌ Sequencer: Crashes with string error
-- **Total: 13+ searches per company despite flag**
-
-### After Fix (with SKIP_WEB_SEARCH=true):
-- ✅ Hunter: Skips search (uses fallback)
-- ✅ Enricher: Skips search (uses pain points/notes as facts)
-- ✅ Contactor: Skips search (generates fallback contacts)
-- ✅ Sequencer: Handles email response correctly
-- **Total: 0 searches per company**
-
----
-
-## Configuration
-
-### Environment Variable
-```bash
-# In .env or HF Spaces Settings → Variables
-SKIP_WEB_SEARCH=true
-```
-
-### Verification
-```python
-# Check if flag is properly loaded
-from app.config import SKIP_WEB_SEARCH
-print(f"SKIP_WEB_SEARCH: {SKIP_WEB_SEARCH}")
-# Should output: SKIP_WEB_SEARCH: True
-```
-
----
-
-## Expected Behavior After Fix
-
-### When SKIP_WEB_SEARCH=true:
-
-**Hunter (Company Discovery):**
-- ✅ Skips domain search
-- ✅ Uses intelligent fallback based on company name
-- ✅ Detects industry from keywords (e.g., "Shopify" → E-commerce)
-- ✅ Generates contextual pain points
-
-**Enricher (Fact Gathering):**
-- ✅ Skips all 4 web search queries
-- ✅ Creates facts from company pain points
-- ✅ Creates facts from company notes
-- ✅ No rate limiting errors
-
-**Contactor (Prospect Discovery):**
-- ✅ Skips all contact search queries
-- ✅ Generates plausible fallback contacts
-- ✅ Uses appropriate titles based on company size
-- ✅ No rate limiting errors
-
-**Sequencer (Email Send):**
-- ✅ Handles both string and dict responses
-- ✅ No attribute errors
-- ✅ Graceful fallback on failures
-
----
-
-## Testing
-
-### Test Demo Mode (No Web Searches)
-
-```bash
-# Set environment variable
-export SKIP_WEB_SEARCH=true
-
-# Run app
-python app.py
-
-# Try a company
-Input: "Shopify"
-
-# Expected log output:
-# ✅ Hunter: Skipping web search (SKIP_WEB_SEARCH=true)
-# ✅ Enricher: Skipping web search (SKIP_WEB_SEARCH=true)
-# ✅ ProspectDiscovery: Skipping web search (skip_search=True)
-# ✅ ProspectDiscovery: Generating 3 fallback contacts
-
-# Should complete in ~15-25 seconds with ZERO rate limit errors
-```
-
-### Test Web Search Mode (With Searches)
-
-```bash
-# Unset or set to false
-export SKIP_WEB_SEARCH=false
-
-# Run app
-python app.py
-
-# Try a company
-Input: "Shopify"
-
-# Expected log output:
-# ✅ Hunter: Performing web search for company
-# ✅ Enricher: Performing web search for facts
-# ✅ ProspectDiscovery: Performing web search for contacts
-
-# May encounter rate limiting (expected in web search mode)
-```
-
----
-
-## Files Modified
-
-1. ✅ `agents/enricher.py` - Added SKIP_WEB_SEARCH check
-2. ✅ `services/prospect_discovery.py` - Added skip_search parameter
-3. ✅ `agents/contactor.py` - Pass SKIP_WEB_SEARCH to discovery service
-4. ✅ `agents/sequencer.py` - Fixed email response handling
-
----
-
-## Performance
-
-| Mode | Searches per Company | Rate Limit Risk | Processing Time |
-|------|---------------------|-----------------|-----------------|
-| **Demo Mode (SKIP_WEB_SEARCH=true)** | 0 | None (0%) | 15-25s |
-| **Web Search Mode (SKIP_WEB_SEARCH=false)** | 14+ | High (70-95%) | 30-60s |
-
----
-
-## Recommended Deployment Configuration
-
-### For Hugging Face Spaces:
-```bash
-# Required
-HF_API_TOKEN=your_token_here
-
-# Highly Recommended
-SKIP_WEB_SEARCH=true          # Avoid rate limiting
-USE_IN_MEMORY_MCP=true        # Use in-memory services
-
-# Optional
-MODEL_NAME=Qwen/Qwen2.5-7B-Instruct
-```
-
----
-
-## Success Criteria
-
-After this fix, with `SKIP_WEB_SEARCH=true`:
-
-✅ No DuckDuckGo rate limiting errors
-✅ No "Ratelimit" in logs
-✅ No web search attempts
-✅ Fast processing (15-25s per company)
-✅ Intelligent fallback data used
-✅ No email send errors
-✅ 100% reliability
-
----
-
-## Troubleshooting
-
-### Still Getting Rate Limit Errors?
-
-**Check configuration:**
-```python
-from app.config import SKIP_WEB_SEARCH
-print(f"SKIP_WEB_SEARCH = {SKIP_WEB_SEARCH}")
-```
-
-If it shows `False`, ensure:
-1. Environment variable is set: `export SKIP_WEB_SEARCH=true`
-2. For HF Spaces: Add to Settings → Variables
-3. Restart the application
-
-### Still Making Web Searches?
-
-**Check logs for:**
-- "Performing web search" messages → Flag not working
-- "Skipping web search" messages → Flag working correctly
-
----
-
-## Summary
-
-**Problem:** `SKIP_WEB_SEARCH` was only being respected by Hunter, not by Enricher or Contactor
-
-**Solution:** Updated all agents and services to respect the flag globally
-
-**Result:** 100% reliable demo mode with zero web searches and zero rate limiting
-
----
-
-**Your app is now fully optimized for Hugging Face Spaces deployment with demo mode! 🚀**
-
-Set `SKIP_WEB_SEARCH=true` for guaranteed reliability.

TUTORIAL.md

@@ -1,887 +0,0 @@
-# OmniFlow CX - Complete Tutorial & Testing Guide
-
-**Welcome to OmniFlow CX!** This comprehensive guide will walk you through every feature of the application and show you how to test all 7 MCP services.
-
----
-
-## 📋 Table of Contents
-
-1. [Quick Start](#quick-start)
-2. [Understanding the Application](#understanding-the-application)
-3. [Tab-by-Tab Guide](#tab-by-tab-guide)
-4. [Testing All MCP Services](#testing-all-mcp-services)
-5. [Common Use Cases](#common-use-cases)
-6. [Troubleshooting](#troubleshooting)
-
----
-
-## 🚀 Quick Start
-
-### Prerequisites
-- Python 3.10+
-- SERPER_API_KEY (for web search) - Get free at https://serper.dev/
-
-### Installation
-```bash
-# Clone the repository
-cd cx_ai_agent
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Set up API key
-export SERPER_API_KEY="your_api_key_here"
-
-# Run the application
-python app.py
-```
-
-### First Steps
-1. Open the Gradio interface (usually http://localhost:7860)
-2. You'll see the **OmniFlow CX** logo and banner
-3. Start with the **"🚀 Full Pipeline"** tab for a complete demo
-
----
-
-## 🎯 Understanding the Application
-
-### What is OmniFlow CX?
-
-**OmniFlow CX** is a B2B sales automation platform built entirely on the Model Context Protocol (MCP). It automates the complete prospect-to-outreach workflow:
-
-```
-CLIENT Company Research
-        ↓
-PROSPECT Discovery
-        ↓
-Contact Finding
-        ↓
-Email Generation
-        ↓
-AI Reply Handling
-```
-
-### MCP Architecture
-
-The application uses **7 MCP Services**:
-
-| Service | Purpose | Tab to Test |
-|---------|---------|-------------|
-| **Store** | Data persistence (prospects, contacts) | 🔧 MCP Service Testing → 💾 Store |
-| **Search** | Real-time web research | 🔧 MCP Service Testing → 🔎 Search |
-| **Email** | Email communication (simulated) | 🚀 Full Pipeline |
-| **Calendar** | Meeting scheduling | 🚀 Full Pipeline |
-| **Analytics** | Performance tracking | 🔧 MCP Service Testing → 📊 Analytics |
-| **Enrichment** | Data enhancement | 🔧 MCP Service Testing → 🔍 Enrichment |
-| **Validation** | Email/domain validation | 🔧 MCP Service Testing → ✓ Validation |
-
----
-
-## 📚 Tab-by-Tab Guide
-
-### Tab 1: 🚀 Full Pipeline
-
-**Purpose**: Run the complete B2B sales automation workflow
-
-**How to Use**:
-
-1. **Enter Client Company**:
-   - Input: `Shopify`, `Stripe`, `HubSpot`, etc.
-   - This is the company you're selling FOR (not TO)
-
-2. **Set Number of Prospects**:
-   - Use slider: 1-5 prospects
-   - Recommended: Start with 2-3 for faster results
-
-3. **Click "🚀 Find Prospects & Generate Emails"**
-
-**What Happens**:
-1. ✅ AI researches your client company
-2. ✅ Client profile saved to database (7-day cache)
-3. ✅ AI finds prospect companies
-4. ✅ Prospects saved to MCP Store
-5. ✅ AI finds decision-makers at each prospect
-6. ✅ Contacts saved to MCP Store (deduplicated)
-7. ✅ AI generates personalized emails
-
-**Output**:
-- Pipeline execution log (real-time updates)
-- Generated emails with full content
-- Contact details for each prospect
-
-**Example**:
-```
-Input: Client = "Shopify", Prospects = 2
-
-Output:
-- Prospect 1: "Boutique Fashion Co" needs checkout solution
-  - Contact: Sarah Johnson, VP E-commerce
-  - Email: Personalized outreach about Shopify Plus
-
-- Prospect 2: "Artisan Marketplace" scaling issues
-  - Contact: Mike Chen, CTO
-  - Email: Custom email about infrastructure
-```
-
----
-
-#### AI Reply Handler & Escalation Simulator
-
-**Purpose**: See how AI handles prospect replies
-
-**How to Use**:
-
-1. **Select Reply Type**:
-   - "Interested + Asking for Pricing" → Escalates to human
-   - "Has Questions" → AI continues conversation
-   - "Objection / Using Competitor" → AI handles objection
-   - "Ready to Buy" → Escalates to sales rep
-   - "Not Interested" → AI gracefully closes
-
-2. **Email Context** (Optional):
-   - Leave empty to auto-load latest prospect from database
-   - Or provide custom JSON for testing
-
-3. **Click "💬 Simulate Prospect Reply & AI Conversation"**
-
-**What Happens**:
-1. Prospect sends simulated reply
-2. AI analyzes intent and sentiment
-3. AI generates appropriate response
-4. If high-intent detected → Escalates to human
-5. Generates comprehensive handoff packet
-
-**Output**:
-- Complete conversation flow
-- AI's reasoning and analysis
-- Handoff packet (if escalated) with:
-  - Prospect summary
-  - Conversation history
-  - Recommended next steps
-  - Key insights
-
----
-
-### Tab 2: 🧩 Individual Modules
-
-**Purpose**: Test each pipeline component independently
-
-#### Module 1: 🔍 Client Research
-
-**How to Test**:
-1. Enter company name: `Shopify`
-2. Click "🔍 Research Client"
-
-**Output**:
-- Company description
-- Website URL
-- Offerings and target market
-- Database storage confirmation
-- MCP services used
-
-**Example Result**:
-```markdown
-Company: Shopify
-Website: https://www.shopify.com
-Description: E-commerce platform for online stores...
-Offerings: Store builder, Payments, Marketing tools
-Target Market: Small to medium businesses
-
-✅ Saved to Database: ID 1, Last researched: 2024-11-17
-```
-
----
-
-#### Module 2: 🎯 Prospect Discovery
-
-**How to Test**:
-1. Enter client company: `Shopify`
-2. Set number of prospects: `2`
-3. Click "🎯 Find Prospects"
-
-**Output**:
-- Matched prospect companies
-- Fit reasoning
-- Pain points identified
-- Domain information
-- MCP services used
-
-**Example Result**:
-```markdown
-Prospect 1:
-Company: Fashion Boutique Co
-Domain: fashionboutique.com
-Reason: Growing e-commerce business needing better checkout
-Pain Points: Cart abandonment, Mobile optimization
-
-Prospect 2:
-Company: Artisan Marketplace
-Domain: artisanmarket.io
-Reason: Scaling challenges with current platform
-Pain Points: Infrastructure, Payment processing
-```
-
----
-
-#### Module 3: 👤 Contact Finder
-
-**How to Test**:
-1. Enter company name: `Zapier`
-2. Enter domain: `zapier.com`
-3. Click "👤 Find Contacts"
-
-**Output**:
-- Real decision-makers (names, titles, emails)
-- Source of contact information
-- Deduplication confirmation
-- MCP services used
-
-**Example Result**:
-```markdown
-Contact 1:
-Name: John Smith
-Title: VP of Customer Experience
-Email: [email protected]
-Source: LinkedIn Search
-
-Contact 2:
-Name: Sarah Johnson
-Title: Director of CX
-Email: [email protected]
-Source: Team Page Scraping
-```
-
----
-
-### Tab 3: 🔧 MCP Service Testing
-
-**Purpose**: Test MCP services directly to understand the protocol
-
-#### Service 1: 💾 MCP Store
-
-**Operations**:
-
-**A. Create (Add Test Data)**:
-1. Operation: `Create`
-2. Data Type: `Prospect` or `Contact`
-3. Test Data: (Optional JSON)
-4. Click "🔧 Test Store Operation"
-
-**B. Read (View Stored Data)**:
-1. Operation: `Read`
-2. Data Type: `Prospects` or `Contacts`
-3. Click "🔧 Test Store Operation"
-
-**C. Clear All**:
-1. Operation: `Clear All`
-2. Click "🔧 Test Store Operation"
-3. ⚠️ This clears in-memory data only
-
-**Example**:
-```json
-// Create Prospect
-{
-  "id": "test_123",
-  "company": {
-    "name": "Test Corp",
-    "domain": "test.com"
-  },
-  "reason": "Testing MCP Store"
-}
-```
-
----
-
-#### Service 2: 🔎 MCP Search
-
-**How to Test**:
-1. Enter search query: `Shopify e-commerce platform features`
-2. Set max results: `5`
-3. Click "🔎 Search"
-
-**Output**:
-- Search results with titles, URLs, snippets
-- Source attribution
-- Confidence scores
-- MCP protocol details
-
-**Try These Queries**:
-- `"Stripe payment processing for SaaS"`
-- `"Who is the CEO of Airbnb"`
-- `"HubSpot marketing automation features"`
-
----
-
-#### Service 3: 📊 MCP Analytics ⭐ NEW
-
-**How to Test**:
-
-**A. View Dashboard**:
-1. Action: `View Dashboard`
-2. Click "📊 Test Analytics"
-
-**Output**:
-- Total pipeline runs
-- Prospects discovered
-- Contacts found
-- Emails generated
-- Conversion rate
-- Daily statistics
-- Recent events
-
-**B. Track Test Event**:
-1. Action: `Track Test Event`
-2. Click "📊 Test Analytics"
-3. Refresh dashboard to see updated metrics
-
-**Real-World Use**:
-- Monitor which campaigns convert best
-- Calculate ROI on outreach efforts
-- Identify peak performance times
-- Optimize based on data
-
----
-
-#### Service 4: 🔍 MCP Enrichment ⭐ NEW
-
-**How to Test**:
-
-**A. Company Enrichment**:
-1. Company Domain: `shopify.com` or `stripe.com`
-2. Leave email empty
-3. Click "🔍 Enrich Data"
-
-**Output**:
-- Employee count
-- Founded year
-- Funding amount
-- Tech stack
-- Industry tags
-- Revenue range
-- Social media profiles (LinkedIn, Twitter)
-
-**B. Contact Enrichment**:
-1. Leave domain empty
-2. Contact Email: `[email protected]`
-3. Click "🔍 Enrich Data"
-
-**Output**:
-- LinkedIn profile URL
-- Twitter profile URL
-- GitHub profile URL
-- Estimated seniority level
-
-**Real-World Use**:
-- Personalize emails with company data
-- Research prospects before outreach
-- Find social proof and mutual connections
-- Estimate decision-making authority
-
----
-
-#### Service 5: ✓ MCP Validation ⭐ NEW
-
-**How to Test**:
-
-**A. Single Email Validation**:
-1. Email: `[email protected]`
-2. Click "✓ Validate"
-
-**Output**:
-- Valid: ✅ Yes/❌ No
-- Disposable: ⚠️ Yes/✅ No
-- Role-Based: ⚠️ Yes/✅ No
-- Deliverability Score: 0-100
-
-**B. Batch Email Validation**:
-1. Emails:
-   ```
-   [email protected],
-   [email protected],
-   [email protected]
-   ```
-2. Click "✓ Validate"
-
-**Output**:
-- Total emails processed
-- Valid count
-- Invalid count
-- Average deliverability score
-- Individual results
-
-**C. Domain Validation**:
-1. Domain: `shopify.com`
-2. Click "✓ Validate"
-
-**Output**:
-- Valid format
-- Has MX records
-- Active status
-
-**Real-World Use**:
-- Prevent bounces before sending
-- Clean email lists automatically
-- Protect sender reputation
-- Identify deliverability issues early
-
-**Try These Examples**:
-- ✅ Valid: `[email protected]`
-- ❌ Role-based: `[email protected]` (30% penalty)
-- ❌ Disposable: `[email protected]` (50% penalty)
-- ❌ Invalid format: `notanemail`
-
----
-
-### Tab 4: 💾 Data Management
-
-#### 📦 Sample Data Loader
-
-**Purpose**: Quickly load demo data for testing
-
-**How to Use**:
-1. Click "📦 Load Sample Data"
-2. Wait for confirmation
-
-**What Gets Loaded**:
-- 2 sample prospects (Acme Corp, GlobalTech Solutions)
-- 2 sample contacts (with names, titles, emails)
-
-**When to Use**:
-- First-time testing
-- After clearing data
-- Demonstrating to stakeholders
-
----
-
-#### 📤 Export Data
-
-**Purpose**: Backup or analyze your data
-
-**How to Use**:
-1. Select export type:
-   - `Prospects` - Only prospect data
-   - `Contacts` - Only contact data
-   - `All` - Everything
-2. Click "📤 Export Data"
-
-**Output**:
-- JSON file saved to `data/exports/`
-- Filename with timestamp
-- Preview of exported data
-
-**File Location**:
-```
-data/exports/prospects_export_20241117_143022.json
-data/exports/contacts_export_20241117_143045.json
-data/exports/full_export_20241117_143100.json
-```
-
----
-
-### Tab 5: 📊 Metrics & Health
-
-**Purpose**: Monitor system performance
-
-**How to Use**:
-1. Click "🔄 Refresh Metrics"
-
-**Output**:
-- **Database Metrics**:
-  - Client profiles count
-- **MCP Store Metrics**:
-  - Prospects count
-  - Contacts count
-- **System Health**:
-  - All 7 services status
-  - Healthy/Unhealthy indicators
-
-**Example**:
-```markdown
-## Database Metrics
-- Client Profiles: 3
-
-- Prospects (MCP Store): 8
-- Contacts (MCP Store): 15
-
-## System Health
-- search: healthy (in-memory)
-- email: healthy (in-memory)
-- calendar: healthy (in-memory)
-- store: healthy (in-memory)
-- analytics: healthy (in-memory)
-- enrichment: healthy (in-memory)
-- validation: healthy (in-memory)
-```
-
----
-
-### Tab 6: 📚 About MCP
-
-**Purpose**: Learn about the Model Context Protocol
-
-**Content**:
-- What is MCP?
-- OmniFlow CX architecture diagram
-- Benefits of MCP:
-  - Modularity
-  - Standardization
-  - Testability
-  - Scalability
-  - Maintainability
-- MCP services table
-- Why MCP for B2B sales automation
-- Hackathon demonstration highlights
-
-**Recommended**: Read this tab to understand the architectural decisions
-
----
-
-## 🧪 Testing All MCP Services
-
-### Complete Testing Checklist
-
-#### ✅ MCP Store Service
-- [ ] Create a test prospect
-- [ ] Read all prospects
-- [ ] Create a test contact
-- [ ] Read all contacts
-- [ ] Clear all data
-- [ ] Verify data persistence
-
-#### ✅ MCP Search Service
-- [ ] Search for company information
-- [ ] Search for contact information
-- [ ] Verify result quality
-- [ ] Test multiple queries
-
-#### ✅ MCP Email Service (Simulated)
-- [ ] Run full pipeline to generate emails
-- [ ] Verify email personalization
-- [ ] Test AI reply handler
-
-#### ✅ MCP Calendar Service (Mock)
-- [ ] Run full pipeline to see calendar integration
-- [ ] Verify meeting slot suggestions
-
-#### ✅ MCP Analytics Service ⭐
-- [ ] View empty dashboard
-- [ ] Track test event
-- [ ] Run full pipeline (generates analytics)
-- [ ] View updated dashboard
-- [ ] Verify metrics calculation
-
-#### ✅ MCP Enrichment Service ⭐
-- [ ] Enrich shopify.com
-- [ ] Enrich stripe.com
-- [ ] Enrich test email address
-- [ ] Verify data completeness
-
-#### ✅ MCP Validation Service ⭐
-- [ ] Validate valid email
-- [ ] Validate role-based email (info@)
-- [ ] Validate disposable email (tempmail.com)
-- [ ] Batch validate multiple emails
-- [ ] Validate domain
-- [ ] Verify scoring accuracy
-
----
-
-## 💼 Common Use Cases
-
-### Use Case 1: Find Prospects for Your Client
-
-**Scenario**: You have a client (Shopify) and need to find 5 potential customers
-
-**Steps**:
-1. Go to "🚀 Full Pipeline"
-2. Client: `Shopify`
-3. Prospects: `5`
-4. Click "🚀 Find Prospects & Generate Emails"
-5. Wait 30-60 seconds
-6. Review generated emails
-7. Go to "💾 Data Management" → Export → Export `All`
-8. Use exported data in your CRM
-
-**Result**: 5 prospects with personalized emails ready to send
-
----
-
-### Use Case 2: Validate Email List
-
-**Scenario**: You have a list of 50 emails to validate before sending campaign
-
-**Steps**:
-1. Go to "🔧 MCP Service Testing" → "✓ MCP Validation"
-2. Paste emails (comma or newline separated)
-3. Click "✓ Validate"
-4. Review batch summary
-5. Filter out emails with score < 70
-6. Use only valid emails for campaign
-
-**Result**: Clean email list with 50%+ lower bounce rate
-
----
-
-### Use Case 3: Enrich Prospect Data
-
-**Scenario**: You have a company domain and want more information
-
-**Steps**:
-1. Go to "🔧 MCP Service Testing" → "🔍 MCP Enrichment"
-2. Company Domain: `target-company.com`
-3. Click "🔍 Enrich Data"
-4. Review employee count, funding, tech stack
-5. Use insights to personalize outreach
-
-**Result**: Rich company profile for better email personalization
-
----
-
-### Use Case 4: Monitor Pipeline Performance
-
-**Scenario**: You want to track which campaigns perform best
-
-**Steps**:
-1. Run multiple pipelines with different clients
-2. Go to "🔧 MCP Service Testing" → "📊 MCP Analytics"
-3. Action: `View Dashboard`
-4. Review conversion rates and daily stats
-5. Identify top-performing sequences
-
-**Result**: Data-driven insights for optimization
-
----
-
-## 🔧 Troubleshooting
-
-### Images Not Displaying
-
-**Issue**: Logo, banner, or chatbot images show only alt text
-
-**Solution**:
-```python
-# Images should be in: assets/Logo.png, assets/Banner.png, assets/chatbot.png
-# Check file permissions and paths
-ls -la assets/
-
-# Restart Gradio if needed
-python app.py
-```
-
----
-
-### Search Not Working
-
-**Issue**: `SERPER_API_KEY not set. Cannot perform search.`
-
-**Solution**:
-```bash
-# Set API key (free at https://serper.dev/)
-export SERPER_API_KEY="your_key_here"
-
-# Or add to .env file
-echo "SERPER_API_KEY=your_key_here" >> .env
-```
-
----
-
-### No Prospects Found
-
-**Issue**: Pipeline completes but finds 0 prospects
-
-**Possible Causes**:
-1. SERPER_API_KEY not set → Fix: Set API key
-2. Client company too niche → Fix: Try well-known companies first
-3. Search quota exceeded → Fix: Wait or use new API key
-
-**Workaround**:
-1. Go to "💾 Data Management" → "📦 Sample Data"
-2. Click "Load Sample Data"
-3. Test with sample prospects
-
----
-
-### Database Errors
-
-**Issue**: `Failed to initialize database`
-
-**Solution**:
-```bash
-# Check data directory exists
-mkdir -p data
-
-# Check permissions
-chmod 755 data
-
-# Restart application
-python app.py
-```
-
----
-
-### MCP Service Unhealthy
-
-**Issue**: System Health shows service as unhealthy
-
-**Solution**:
-```python
-# In-memory mode (default) - services should always be healthy
-# If showing unhealthy, restart the application
-
-# HTTP mode - check if servers are running
-# Port 8001: Search
-# Port 8002: Email
-# Port 8003: Calendar
-# Port 8004: Store
-```
-
----
-
-## 📊 Expected Performance
-
-### Timing Benchmarks
-
-| Operation | Expected Time | Notes |
-|-----------|---------------|-------|
-| Client Research | 3-5 seconds | Depends on SERPER_API |
-| Prospect Discovery (per prospect) | 5-10 seconds | Web search intensive |
-| Contact Finding (per prospect) | 10-15 seconds | LinkedIn + team pages |
-| Email Generation (per contact) | 2-3 seconds | AI generation |
-| **Full Pipeline (3 prospects)** | **60-90 seconds** | Complete workflow |
-
-### Resource Usage
-
-| Resource | Usage | Recommendation |
-|----------|-------|----------------|
-| Memory | 200-500 MB | 1 GB minimum |
-| CPU | Low-Medium | 2 cores minimum |
-| Disk | 10-50 MB | For database |
-| Network | Medium | For API calls |
-
----
-
-## 🎓 Best Practices
-
-### 1. Start Small
-- Test with 1-2 prospects first
-- Verify quality before scaling
-- Use well-known companies initially
-
-### 2. Validate Before Sending
-- Always run validation service on email lists
-- Filter out scores < 70
-- Remove role-based emails
-
-### 3. Enrich for Personalization
-- Use enrichment before email generation
-- Add company-specific insights
-- Reference tech stack or recent funding
-
-### 4. Monitor with Analytics
-- Track conversion rates weekly
-- A/B test different client messaging
-- Optimize based on data
-
-### 5. Use Sample Data
-- Perfect for demonstrations
-- Quick testing without API calls
-- Consistent results
-
----
-
-## 🚀 Advanced Features
-
-### Custom MCP Service Integration
-
-Want to add your own MCP service? Here's how:
-
-```python
-# 1. Create service in mcp/your_service.py
-class MyMCPService:
-    async def my_method(self, params):
-        # Your logic here
-        return {"result": "data"}
-
-# 2. Add to registry in mcp/registry.py
-from mcp.your_service import MyMCPService
-
-self.my_service = MyMCPService()
-
-# 3. Create UI handler in app.py
-async def test_my_service_ui(input_param):
-    service = mcp_registry.my_service
-    result = await service.my_method(input_param)
-    return f"Result: {result}"
-
-# 4. Add tab in MCP Service Testing
-with gr.Tab("My Service"):
-    # Your UI here
-    pass
-```
-
----
-
-## 📚 Additional Resources
-
-### Documentation
-- **Architecture**: See "📚 About MCP" tab
-- **API Reference**: Check individual service files in `mcp/`
-- **Data Schema**: See `app/schema.py`
-
-### Support
-- **Issues**: Check console logs for errors
-- **Questions**: Review this tutorial
-- **Bugs**: Check GitHub issues
-
-### Contributing
-- Follow MCP protocol patterns
-- Add tests for new services
-- Update this tutorial for new features
-
----
-
-## ✅ Completion Checklist
-
-After finishing this tutorial, you should be able to:
-
-- [ ] Run the full B2B sales pipeline
-- [ ] Test each individual module
-- [ ] Use all 7 MCP services
-- [ ] Validate email lists
-- [ ] Enrich prospect data
-- [ ] Monitor analytics
-- [ ] Export and import data
-- [ ] Troubleshoot common issues
-- [ ] Understand MCP architecture
-- [ ] Explain the value proposition
-
----
-
-## 🎉 Next Steps
-
-1. **Run Your First Campaign**:
-   - Pick a real client
-   - Find 5 prospects
-   - Generate and review emails
-   - Export data
-
-2. **Experiment with Services**:
-   - Try different enrichment queries
-   - Validate various email types
-   - Track analytics over time
-
-3. **Integrate with Your Workflow**:
-   - Export to your CRM
-   - Use validation in your email tool
-   - Monitor analytics dashboard
-
-4. **Provide Feedback**:
-   - What worked well?
-   - What needs improvement?
-   - What features are missing?
-
----
-
-**🌊 Welcome to OmniFlow CX - Happy Automating!**
-
-*Built with the Model Context Protocol for the Hugging Face + Anthropic MCP Hackathon 2024*

UPGRADE_GUIDE.md

@@ -1,408 +0,0 @@
-# CX AI Agent - Dynamic Discovery Upgrade Guide
-
-## Overview
-
-This guide documents the major upgrade from **static sample data** to **dynamic web search-based discovery**.
-
-### What Changed?
-
-#### BEFORE (Static Mode):
-- ❌ Limited to 3 predefined companies in `data/companies.json`
-- ❌ Mock search results from hardcoded templates
-- ❌ Generated fake contacts with hardcoded name pools
-- ❌ No real-time data or current information
-
-#### AFTER (Dynamic Mode):
-- ✅ Process **ANY company** by name
-- ✅ **Real web search** using DuckDuckGo API
-- ✅ **Live company discovery** (domain, industry, size, pain points)
-- ✅ **Real prospect finding** with web search
-- ✅ **Current facts and news** from the web
-- ✅ Backwards compatible with legacy static mode
-
----
-
-## Architecture Changes
-
-### New Components
-
-#### 1. Web Search Service (`services/web_search.py`)
-- Uses **DuckDuckGo Search API** (completely free, no API key needed)
-- Provides web search and news search capabilities
-- Async/await support for non-blocking operations
-
-#### 2. Company Discovery Service (`services/company_discovery.py`)
-- Discovers company information from web search:
-  - Domain name
-  - Industry classification
-  - Company size (employee count)
-  - Pain points and challenges
-  - Recent news and context
-- Intelligent fallbacks when data is incomplete
-
-#### 3. Prospect Discovery Service (`services/prospect_discovery.py`)
-- Finds decision-makers at target companies
-- Searches for real contacts via web
-- Generates plausible contacts when search doesn't find results
-- Title selection based on company size
-
-### Updated Components
-
-#### Hunter Agent (`agents/hunter.py`)
-**Before:**
-```python
-# Load from static file
-with open(COMPANIES_FILE) as f:
-    companies = json.load(f)
-```
-
-**After:**
-```python
-# Dynamic discovery
-company = await self.discovery.discover_company(company_name)
-```
-
-**New Parameters:**
-- `company_names: List[str]` - Dynamic mode (NEW)
-- `company_ids: List[str]` - Legacy mode (backwards compatible)
-- `use_seed_file: bool` - Force legacy mode
-
-#### Enricher Agent (`agents/enricher.py`)
-- Now uses real web search instead of mock results
-- Enhanced search queries for better fact discovery
-- Deduplication of search results
-- Combines search facts with discovery data
-
-#### Contactor Agent (`agents/contactor.py`)
-- Discovers real decision-makers via web search
-- Falls back to plausible generated contacts
-- Improved title selection logic
-- Email suppression checking
-
-#### Search MCP Server (`mcp/servers/search_server.py`)
-- Replaced mock data with real DuckDuckGo search
-- Added `search.query` method with real web results
-- Added `search.news` method for news articles
-- Returns actual URLs, sources, and confidence scores
-
----
-
-## Usage
-
-### Dynamic Mode (NEW - Recommended)
-
-#### Gradio UI:
-```
-Enter company name: Shopify
-Click: "Discover & Process"
-```
-
-#### FastAPI:
-```python
-POST /run
-{
-  "company_names": ["Shopify", "Stripe", "Zendesk"]
-}
-```
-
-#### Python:
-```python
-from app.orchestrator import Orchestrator
-
-orchestrator = Orchestrator()
-
-async for event in orchestrator.run_pipeline(
-    company_names=["Shopify", "Stripe"],
-    use_seed_file=False
-):
-    print(event)
-```
-
-### Legacy Mode (Backwards Compatible)
-
-#### Gradio UI:
-Not exposed in UI (deprecated)
-
-#### FastAPI:
-```python
-POST /run
-{
-  "company_ids": ["acme", "techcorp"],
-  "use_seed_file": true
-}
-```
-
-#### Python:
-```python
-async for event in orchestrator.run_pipeline(
-    company_ids=["acme"],
-    use_seed_file=True
-):
-    print(event)
-```
-
----
-
-## Installation & Setup
-
-### 1. Install New Dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-Key new dependency:
-- `duckduckgo-search==4.1.1` - Free web search API
-
-### 2. Update Environment Variables
-
-No API keys needed for DuckDuckGo! Just ensure your existing `.env` has:
-
-```bash
-# Existing vars (keep these)
-HF_API_TOKEN=your_token_here
-MODEL_NAME=Qwen/Qwen2.5-7B-Instruct
-```
-
-### 3. Start MCP Servers
-
-```bash
-# The search server now uses real web search
-bash scripts/start_mcp_servers.sh
-```
-
-### 4. Run the Application
-
-```bash
-# Gradio UI (recommended)
-python app.py
-
-# Or FastAPI
-python app/main.py
-```
-
----
-
-## Features
-
-### Company Discovery
-The system automatically discovers:
-- **Domain**: Found via web search, validated
-- **Industry**: Classified using keyword matching from search results
-- **Size**: Extracted from search results or estimated
-- **Pain Points**: Discovered from news, reviews, and industry articles
-- **Notes**: Recent company news and developments
-
-### Prospect Discovery
-The system finds decision-makers:
-- Searches LinkedIn, company pages, news articles
-- Targets appropriate titles based on company size:
-  - Small (<100): CEO, Founder, Head of Customer Success
-  - Medium (100-1000): VP CX, Director of CX
-  - Large (>1000): CCO, SVP Customer Success
-- Falls back to plausible generated contacts if search finds nothing
-
-### Real-Time Facts
-- Searches for company news and updates
-- Finds industry-specific challenges
-- Discovers customer experience insights
-- All facts include source URLs and confidence scores
-
----
-
-## Error Handling
-
-The system gracefully handles:
-- **Company not found**: Creates minimal fallback company profile
-- **Search API errors**: Logs error and continues with fallback data
-- **No prospects found**: Generates plausible contacts based on company size
-- **Rate limiting**: None with DuckDuckGo (no API key, no limits)
-- **Invalid input**: Validates and sanitizes company names
-
----
-
-## API Changes
-
-### Schema Updates
-
-#### PipelineRequest (NEW)
-```python
-{
-  "company_names": ["Shopify"],        # NEW: Dynamic mode
-  "company_ids": ["acme"],              # LEGACY: Static mode
-  "use_seed_file": false                # Force legacy mode
-}
-```
-
-### Endpoints
-
-#### `/run` (Updated)
-- Now accepts `company_names` for dynamic discovery
-- Backwards compatible with `company_ids`
-
-#### `/health` (Unchanged)
-- Still checks MCP servers, HF API, vector store
-
----
-
-## Testing
-
-### Manual Testing
-
-Try these companies in dynamic mode:
-- **E-commerce**: Shopify, Etsy, BigCommerce
-- **SaaS**: Stripe, Slack, Monday.com, Zendesk
-- **FinTech**: Square, Plaid, Braintree
-- **Tech**: Atlassian, Asana, Notion
-
-### Automated Testing
-
-```bash
-# Run tests
-pytest tests/
-
-# Test company discovery
-python -c "
-import asyncio
-from services.company_discovery import get_company_discovery_service
-
-async def test():
-    service = get_company_discovery_service()
-    company = await service.discover_company('Shopify')
-    print(company)
-
-asyncio.run(test())
-"
-```
-
----
-
-## Performance Considerations
-
-### Web Search Latency
-- Each company discovery: ~2-5 seconds
-- Each prospect search: ~1-3 seconds per query
-- Total pipeline: ~30-60 seconds per company
-
-### Optimization Tips
-1. **Batch Processing**: Process multiple companies in parallel
-2. **Caching**: Store discovered company data to avoid re-discovery
-3. **Rate Limiting**: DuckDuckGo has no hard limits, but be respectful
-4. **Fallbacks**: System uses fallbacks to maintain speed when search fails
-
----
-
-## Deployment
-
-### Hugging Face Spaces
-
-The app works seamlessly on HF Spaces:
-
-1. **No API keys needed** for web search (DuckDuckGo is free)
-2. **No rate limits** to worry about
-3. **Works in sandboxed environment**
-
-#### Deployment Steps:
-```bash
-# Push to HF Spaces repo
-git add .
-git commit -m "Dynamic discovery upgrade"
-git push
-```
-
-Make sure `requirements_gradio.txt` includes `duckduckgo-search==4.1.1`
-
-### Self-Hosted
-
-Same as before, just install new dependencies:
-```bash
-pip install -r requirements.txt
-python app.py
-```
-
----
-
-## Migration from Static to Dynamic
-
-### Option 1: Full Migration (Recommended)
-Remove dependency on static files:
-```bash
-# Backup existing data
-cp data/companies.json data/companies.json.backup
-
-# Use dynamic mode exclusively
-# No changes needed - just use company_names in requests
-```
-
-### Option 2: Hybrid Approach
-Keep both modes available:
-- Use dynamic mode for new companies
-- Use legacy mode for specific test scenarios
-
-### Option 3: Gradual Migration
-1. Test dynamic mode with known companies
-2. Verify output quality
-3. Gradually transition users to dynamic mode
-4. Keep legacy mode as fallback
-
----
-
-## Troubleshooting
-
-### Issue: "Could not discover company"
-**Solution**: Check company name spelling, try variations:
-- "Shopify" ✅
-- "Shopify Inc" ✅
-- "shopify.com" ❌ (use company name, not domain)
-
-### Issue: "No contacts found"
-**Solution**: System will auto-generate plausible contacts. This is expected and intentional.
-
-### Issue: "Search is slow"
-**Solution**: This is normal for web search. Each company takes 30-60 seconds. Consider:
-- Processing fewer companies at once
-- Using cached/stored data for re-runs
-
-### Issue: "Module not found: duckduckgo_search"
-**Solution**:
-```bash
-pip install duckduckgo-search==4.1.1
-```
-
----
-
-## FAQ
-
-**Q: Do I need an API key for web search?**
-A: No! DuckDuckGo is completely free with no API key required.
-
-**Q: Are there rate limits?**
-A: DuckDuckGo has no hard rate limits for reasonable use. The system includes delays to be respectful.
-
-**Q: Can I still use the old static mode?**
-A: Yes! Set `use_seed_file=true` in your request. Fully backwards compatible.
-
-**Q: How accurate is company discovery?**
-A: Generally very good for well-known companies. For smaller/obscure companies, the system uses intelligent fallbacks.
-
-**Q: Can I use a different search API?**
-A: Yes! Edit `services/web_search.py` to integrate other APIs (Brave, SerpAPI, Tavily, etc.)
-
-**Q: Does this work offline?**
-A: No, web search requires internet connection. Use legacy mode with static files for offline use.
-
----
-
-## Support
-
-For issues or questions:
-1. Check this guide
-2. Review code comments in `services/` directory
-3. Check logs for detailed error messages
-4. Open an issue on GitHub
-
----
-
-## License
-
-Same as the main project. See LICENSE file.

WHATS_NEW_ENTERPRISE.md

@@ -1,415 +0,0 @@
-# 🎉 CX AI Agent - Enterprise Edition
-
-## What Was Built
-
-I've transformed your pipeline demo into a **full-featured enterprise CX automation platform**. Here's everything that was created:
-
----
-
-## 📁 New Files Created
-
-### Database Layer
-1. **`database/schema.sql`** (250+ lines)
-   - Complete SQL schema with 12 tables
-   - Indexes for performance
-   - Foreign key relationships
-   - Default settings and data
-
-2. **`models/database.py`** (450+ lines)
-   - SQLAlchemy ORM models for all tables
-   - Relationships and constraints
-   - Helper methods (`to_dict()`, properties)
-   - 12 model classes: Company, Contact, Campaign, Sequence, EmailActivity, Meeting, etc.
-
-3. **`database/manager.py`** (180+ lines)
-   - Database connection management
-   - Session handling with context managers
-   - Auto-initialization with default data
-   - Global instance pattern
-
-### UI Layer
-4. **`ui/theme.py`** (300+ lines)
-   - Enterprise Gradio theme
-   - Custom CSS styling (400+ lines of CSS)
-   - Reusable UI components (metric cards, badges, progress bars)
-   - Professional color scheme and typography
-
-### Main Application
-5. **`app_enterprise.py`** (600+ lines)
-   - Complete enterprise Gradio application
-   - 5 main views: Dashboard, Campaigns, Contacts, Sequences, Analytics
-   - Campaign creation and management
-   - Contact list with filtering and search
-   - Real-time metrics and activity feed
-   - Database integration throughout
-
-### Documentation
-6. **`ENTERPRISE_UPGRADE_PLAN.md`** (500+ lines)
-   - Complete 8-phase upgrade plan
-   - Detailed specifications for each feature
-   - Database schema documentation
-   - Implementation roadmap
-   - Technology stack details
-
-7. **`ENTERPRISE_DEPLOYMENT.md`** (400+ lines)
-   - Complete deployment guide
-   - Database structure explanation
-   - Configuration instructions
-   - Troubleshooting guide
-   - API reference
-   - Best practices
-
-8. **`WHATS_NEW_ENTERPRISE.md`** (this file)
-   - Summary of changes
-   - Quick start guide
-   - Feature comparison
-
-### Updates
-9. **`requirements.txt`** & **`requirements_gradio.txt`**
-   - Added SQLAlchemy 2.0+
-   - Added Alembic for migrations
-
----
-
-## 🌟 Key Features Implemented
-
-### 1. Campaign Management System
-
-**Create & Track Campaigns:**
-```
-📋 Campaigns View:
-┌─────────────────────────────────────────────────────┐
-│ + New Campaign                                      │
-├─────────────────────────────────────────────────────┤
-│ Campaign Name         Status      Progress          │
-│ Q1 SaaS Outreach     ● Active    ████████░░ 68%    │
-│ Enterprise Tech      ⏸ Paused    ███░░░░░░░ 23%    │
-│ Fintech Expansion    ✅ Done     ██████████ 100%   │
-└─────────────────────────────────────────────────────┘
-```
-
-**Features:**
-- Create campaigns with target companies
-- Auto-discover prospects via Serper API
-- Track through 8-agent pipeline stages
-- Real-time progress metrics
-- Status management (Draft, Active, Paused, Completed)
-
-### 2. Contact Database
-
-**Full Contact Management:**
-```
-👥 Contacts View:
-┌────────────────────────────────────────────────────┐
-│ [Search...] [Filter by status ▼]                  │
-├────────────────────────────────────────────────────┤
-│ Name           Company     Status        Score    │
-│ Sarah Johnson  TechCorp   ✅ Responded   ⭐⭐⭐⭐⭐ 0.89 │
-│ Mike Chen      DataInc    📧 Contacted   ⭐⭐⭐⭐ 0.75  │
-│ Emma Wilson    CloudSys   🆕 New         ⭐⭐⭐ 0.62    │
-└────────────────────────────────────────────────────┘
-```
-
-**Features:**
-- SQLite database with full persistence
-- Advanced scoring (fit, engagement, intent, overall)
-- Search and filter capabilities
-- Lifecycle stage tracking
-- Company relationships
-- Activity timeline
-
-### 3. Dashboard with Real-Time Metrics
-
-```
-📊 Dashboard:
-┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
-│  Total   │ │  Active  │ │  Cont   │ │ Meetings │
-│Campaigns │ │Campaigns │ │  acts   │ │  Booked  │
-│    12    │ │     5    │ │  1,247  │ │    47    │
-│  ↑ 5     │ │          │ │ ↑ 23%   │ │  ↑ 12    │
-└──────────┘ └──────────┘ └──────────┘ └──────────┘
-
-Recent Activity:
-• 10:45 AM - Campaign "Q1 SaaS" completed - 47 prospects
-• 10:30 AM - Email sent to John Doe (TechCorp)
-• 10:15 AM - Response from Sarah Smith (DataInc)
-```
-
-### 4. Email Sequence Templates
-
-**Pre-built Sequences:**
-- **Cold Outreach (3-Touch)**
-  - Email 1: Initial contact (Day 0)
-  - Email 2: Value proposition (Day 3)
-  - Email 3: Final touch (Day 7)
-
-**Variable Substitution:**
-- `{{first_name}}` - Contact first name
-- `{{company_name}}` - Company name
-- `{{industry}}` - Company industry
-- `{{pain_points}}` - Identified challenges
-- `{{sender_name}}` - Your name
-
-### 5. Professional UI/UX
-
-**Enterprise Theme:**
-- Clean, modern design
-- Consistent spacing and typography
-- Status badges with colors
-- Progress bars
-- Empty states with CTAs
-- Responsive tables
-- Activity feed
-- Metric cards
-
-**Navigation:**
-- Multi-tab interface
-- Quick view switching
-- Breadcrumb navigation
-- Search and filters
-
----
-
-## 🚀 How to Use
-
-### Quick Start
-
-```bash
-# 1. Install dependencies
-pip install -r requirements_gradio.txt
-
-# 2. Set up environment
-cp .env.example .env
-# Add HF_API_TOKEN and SERPER_API_KEY
-
-# 3. Run enterprise edition
-python app_enterprise.py
-
-# Visit http://localhost:7860
-```
-
-### Create Your First Campaign
-
-1. **Click "📋 Campaigns" tab**
-2. **Click "+ New Campaign"**
-3. **Fill in details:**
-   - Name: "Q1 Enterprise Outreach"
-   - Description: "Target SaaS companies in enterprise space"
-   - Companies: "Shopify, Stripe, Zendesk"
-4. **Click "Create & Launch Campaign"**
-
-**What Happens:**
-- System discovers company info via Serper API
-- Runs 8-agent pipeline (Hunter → Enricher → Contactor → Scorer → Writer → Compliance → Sequencer → Curator)
-- Creates contacts in database
-- Links to campaign
-- Updates metrics in real-time
-
-### View Contacts
-
-1. **Click "👥 Contacts" tab**
-2. **See all discovered contacts**
-3. **Use search bar** to find specific contacts
-4. **Filter by status** (New, Contacted, Responded, etc.)
-5. **Click contact** to see details (coming in next update)
-
-### Monitor Progress
-
-1. **Click "📊 Dashboard" tab**
-2. **View key metrics:**
-   - Total campaigns
-   - Active campaigns
-   - Total contacts
-   - Meetings booked
-3. **Check activity feed** for real-time updates
-
----
-
-## 📊 Feature Comparison
-
-| Feature | Demo Version (app.py) | Enterprise Version (app_enterprise.py) |
-|---------|----------------------|----------------------------------------|
-| **UI** | Single tab, basic | Multi-tab, professional |
-| **Database** | None (in-memory) | SQLite with 12 tables |
-| **Campaigns** | Single run | Create/manage multiple |
-| **Contacts** | View only | Full CRUD, search, filter |
-| **Sequences** | Hardcoded | Templates, customizable |
-| **Analytics** | Pipeline log | Dashboard, metrics, charts |
-| **Persistence** | No | Full database |
-| **Tracking** | Limited | Email activities, meetings |
-| **Scoring** | Basic | Multi-dimensional |
-| **Lifecycle** | No | Full stage tracking |
-
----
-
-## 🗄️ Database Schema
-
-**12 Tables Created:**
-
-1. **companies** - Target companies
-2. **contacts** - All prospects
-3. **campaigns** - Campaign definitions
-4. **campaign_contacts** - Campaign-contact relationships
-5. **sequences** - Email sequence templates
-6. **sequence_emails** - Individual emails in sequences
-7. **email_activities** - Email tracking (opens, clicks, replies)
-8. **meetings** - Meeting scheduling and outcomes
-9. **activities** - General activity log
-10. **ab_tests** - A/B test definitions
-11. **ab_test_results** - A/B test metrics
-12. **templates** - Email templates
-13. **analytics_snapshots** - Aggregated metrics
-14. **settings** - Application configuration
-
-**Total Lines of SQL:** 250+
-**Indexes:** 15+
-**Foreign Keys:** 10+
-
----
-
-## 📈 What's Working Now
-
-✅ **Database:**
-- Auto-initialization
-- SQLite storage
-- Default data loading
-- Session management
-
-✅ **UI:**
-- 5-tab navigation
-- Dashboard with metrics
-- Campaign list view
-- Contact list with search/filter
-- Activity feed
-- Professional styling
-
-✅ **Campaigns:**
-- Create campaigns
-- Run discovery pipeline
-- Store results in database
-- Track progress
-- View campaign table
-
-✅ **Contacts:**
-- Auto-discovery from campaigns
-- Scoring system
-- Status tracking
-- Company relationships
-- Search and filter
-
-✅ **Integration:**
-- MCP servers (Search, Email, Calendar, Store)
-- 8-agent pipeline
-- Serper API for live search
-- HuggingFace LLM for content generation
-
----
-
-## 🔮 What's Coming Next
-
-### Phase 2 (Sequences)
-- Full sequence builder UI
-- Drag-and-drop editor
-- Email preview
-- Variable tester
-- A/B test creation
-
-### Phase 3 (Analytics)
-- Charts with Plotly
-- Campaign performance
-- Funnel visualization
-- Export to CSV/PDF
-- Email reports
-
-### Phase 4 (Contact Details)
-- Contact detail view
-- Edit contact info
-- Add notes
-- Manual email sending
-- Meeting scheduling UI
-
-### Phase 5 (Advanced Features)
-- Sentiment analysis
-- Smart reply suggestions
-- Automated workflows
-- Team collaboration
-- CRM integrations
-
----
-
-## 💻 Code Stats
-
-**Total Lines of Code Added:** ~2,500+
-
-**Breakdown:**
-- Database layer: ~900 lines
-- UI components: ~800 lines
-- Main application: ~600 lines
-- Documentation: ~1,200 lines
-
-**Files Created:** 8 new files
-**Files Modified:** 2 (requirements)
-
----
-
-## 🎯 Success Metrics
-
-After deployment, track:
-- **Campaigns created**
-- **Contacts discovered**
-- **Emails sent**
-- **Response rate** (target: 10-20%)
-- **Meetings booked** (target: 5-10%)
-- **Pipeline value generated**
-
----
-
-## 📚 Resources
-
-**Documentation:**
-- `ENTERPRISE_UPGRADE_PLAN.md` - Full feature specification
-- `ENTERPRISE_DEPLOYMENT.md` - Deployment and usage guide
-- `MIGRATION.md` - Serper API migration details
-- `README_HF_SPACES.md` - Hugging Face Spaces deployment
-
-**Code:**
-- `app_enterprise.py` - Main enterprise application
-- `database/schema.sql` - Database schema
-- `models/database.py` - ORM models
-- `ui/theme.py` - UI components and styling
-
----
-
-## 🏁 Getting Started Checklist
-
-- [ ] Install dependencies: `pip install -r requirements_gradio.txt`
-- [ ] Set up `.env` with API keys (HF_API_TOKEN, SERPER_API_KEY)
-- [ ] Run enterprise app: `python app_enterprise.py`
-- [ ] Visit http://localhost:7860
-- [ ] Create your first campaign
-- [ ] Review discovered contacts
-- [ ] Monitor dashboard metrics
-- [ ] Plan next campaign based on results
-
----
-
-## 🎉 You Now Have:
-
-✅ A **full-featured enterprise CX automation platform**
-✅ **Campaign management** with multi-stage tracking
-✅ **Contact database** with advanced scoring
-✅ **Email sequences** with templates
-✅ **Professional UI** with 5 main views
-✅ **Real-time analytics** and activity feed
-✅ **SQLite database** with 12 tables
-✅ **Production-ready** architecture
-✅ **Comprehensive documentation**
-
-**Ready to transform your customer experience operations!** 🚀
-
----
-
-**Version:** 2.0.0-enterprise
-**Author:** Claude Code
-**Date:** 2025-01-15
-**Status:** ✅ Production Ready (Phase 1 Complete)

app.py

@@ -2759,6 +2759,10 @@ def create_app():
                     <span class="nav-icon">💬</span>
                     <span class="nav-text">AI Chat</span>
                 </div>
+                <div class="nav-item" data-page="about" onclick="window.selectPage && window.selectPage('about')">
+                    <span class="nav-icon">ℹ️</span>
+                    <span class="nav-text">About Us</span>
+                </div>
             </nav>
         </div>
         """)
@@ -2778,6 +2782,7 @@ def create_app():
                 btn_contacts = gr.Button("👥 Contacts", elem_id="btn-contacts", size="sm")
                 btn_emails = gr.Button("✉️ Emails", elem_id="btn-emails", size="sm")
                 btn_chat = gr.Button("💬 Chat", elem_id="btn-chat", size="sm")
+                btn_about = gr.Button("ℹ️ About", elem_id="btn-about", size="sm")
 
             # ===== SETUP PAGE =====
             with gr.Column(visible=True) as setup_page:
@@ -2973,40 +2978,247 @@ def create_app():
             with gr.Column(visible=False) as chat_page:
                 gr.HTML("""<div class="page-header"><div>
                     <h1 class="page-title">💬 AI Chat</h1>
-                    <p class="page-subtitle">Your AI sales assistant</p>
-                </div></div>
+                    <p class="page-subtitle">AI-powered communication hub</p>
+                </div></div>""")
+
+                with gr.Tabs(elem_classes="chat-subtabs"):
+                    # ----- SUB-TAB 1: Internal Sales Assistant -----
+                    with gr.Tab("🎯 Sales Assistant", elem_id="tab-sales-assistant"):
+                        gr.HTML("""
+                        <div class="info-box success">
+                            <span class="info-box-icon">🤖</span>
+                            <div class="info-box-content">
+                                <div class="info-box-title">Your AI Sales Assistant</div>
+                                <div class="info-box-text">
+                                    Chat with AI to research companies, draft emails, get talking points, or manage your pipeline. The AI has access to all your prospect data and can perform web searches for real-time info.
+                                </div>
+                            </div>
+                        </div>
+                        """)
 
-                <div class="info-box success">
-                    <span class="info-box-icon">🤖</span>
-                    <div class="info-box-content">
-                        <div class="info-box-title">Your AI Sales Assistant</div>
-                        <div class="info-box-text">
-                            Chat with AI to research companies, draft emails, get talking points, or manage your pipeline. The AI has access to all your prospect data and can perform web searches for real-time info.
+                        chatbot = gr.Chatbot(value=[], height=350, label="Sales Assistant Chat")
+
+                        with gr.Row():
+                            chat_input = gr.Textbox(
+                                label="Message",
+                                placeholder="Ask about prospects, search for companies, draft emails...",
+                                lines=1,
+                                scale=4
+                            )
+                            send_btn = gr.Button("Send", variant="primary", scale=1)
+
+                        gr.HTML("""<div class="action-card" style="margin-top: 16px;">
+                            <h4>💡 Try These Prompts</h4>
+                            <ul style="font-size: 13px; line-height: 1.8; margin: 8px 0 0 0; padding-left: 20px;">
+                                <li>"Search for DTC fashion brands that raised Series A"</li>
+                                <li>"Draft an email to the CEO of Warby Parker"</li>
+                                <li>"Give me talking points for my call with Glossier"</li>
+                                <li>"Summary of all prospects and their status"</li>
+                            </ul>
+                        </div>""")
+
+                    # ----- SUB-TAB 2: Prospect-Facing AI Chat -----
+                    with gr.Tab("👤 Prospect Chat Demo", elem_id="tab-prospect-chat"):
+                        gr.HTML("""
+                        <div class="info-box tip">
+                            <span class="info-box-icon">💬</span>
+                            <div class="info-box-content">
+                                <div class="info-box-title">Prospect Communication Demo</div>
+                                <div class="info-box-text">
+                                    This demonstrates how prospects can interact with your company's AI assistant. The AI can answer questions about your products/services, qualify leads, schedule meetings, and escalate to human agents when needed.
+                                </div>
+                            </div>
                         </div>
-                    </div>
-                </div>
-                """)
+                        """)
+
+                        prospect_chatbot = gr.Chatbot(
+                            value=[],
+                            height=350,
+                            label="Prospect Chat",
+                            avatar_images=(None, "https://api.dicebear.com/7.x/bottts/svg?seed=cx-agent")
+                        )
 
-                chatbot = gr.Chatbot(value=[], height=400, label="Chat")
+                        with gr.Row():
+                            prospect_input = gr.Textbox(
+                                label="Prospect Message",
+                                placeholder="Hi, I'm interested in learning more about your services...",
+                                lines=1,
+                                scale=4
+                            )
+                            prospect_send_btn = gr.Button("Send", variant="primary", scale=1)
 
-                with gr.Row():
-                    chat_input = gr.Textbox(
-                        label="Message",
-                        placeholder="Ask about prospects, search for companies, draft emails...",
-                        lines=1,
-                        scale=4
-                    )
-                    send_btn = gr.Button("Send", variant="primary", scale=1)
-
-                gr.HTML("""<div class="action-card" style="margin-top: 16px;">
-                    <h4>💡 Try These Prompts</h4>
-                    <ul style="font-size: 13px; line-height: 1.8; margin: 8px 0 0 0; padding-left: 20px;">
-                        <li>"Search for DTC fashion brands that raised Series A"</li>
-                        <li>"Draft an email to the CEO of Warby Parker"</li>
-                        <li>"Give me talking points for my call with Glossier"</li>
-                        <li>"Summary of all prospects and their status"</li>
-                    </ul>
-                </div>""")
+                        with gr.Row():
+                            with gr.Column(scale=2):
+                                gr.HTML("""<div class="action-card">
+                                    <h4>🎭 Demo Scenario</h4>
+                                    <p style="font-size: 13px; margin-bottom: 8px;">You are a prospect visiting the client's website. The AI will:</p>
+                                    <ul style="font-size: 13px; line-height: 1.6; margin: 0; padding-left: 20px;">
+                                        <li>Answer questions about products and services</li>
+                                        <li>Qualify you as a lead based on your needs</li>
+                                        <li>Offer to schedule a meeting with sales</li>
+                                        <li>Escalate complex inquiries to human agents</li>
+                                    </ul>
+                                </div>""")
+
+                            with gr.Column(scale=1):
+                                gr.HTML("""<div class="action-card">
+                                    <h4>⚡ Quick Actions</h4>
+                                </div>""")
+                                generate_handoff_btn = gr.Button("📋 Generate Handoff Packet", variant="secondary", size="sm")
+                                escalate_btn = gr.Button("🚨 Escalate to Human", variant="stop", size="sm")
+                                schedule_btn = gr.Button("📅 Schedule Meeting", variant="secondary", size="sm")
+
+                        handoff_output = gr.Markdown(visible=False, elem_classes="handoff-packet")
+
+            # ===== ABOUT US PAGE =====
+            with gr.Column(visible=False) as about_page:
+                gr.HTML("""<div class="page-header"><div>
+                    <h1 class="page-title">ℹ️ About Us</h1>
+                    <p class="page-subtitle">Learn more about CX AI Agent</p>
+                </div></div>""")
+
+                gr.Markdown("""
+# 🤖 CX AI Agent - B2B Sales Intelligence Platform
+
+[![Enterprise Application](https://img.shields.io/badge/MCP-Enterprise%20Track-blue)](https://github.com)
+[![Powered by AI](https://img.shields.io/badge/Powered%20by-HuggingFace-yellow)](https://huggingface.co)
+[![Gradio](https://img.shields.io/badge/Built%20with-Gradio-orange)](https://gradio.app)
+
+> **🏆 MCP in Action Track - Enterprise Applications**
+>
+> Tag: `mcp-in-action-track-enterprise`
+
+---
+
+## 📋 Overview
+
+**CX AI Agent** is an AI-powered B2B sales automation platform that helps sales teams discover prospects, find decision-makers, and draft personalized outreach emails—all powered by autonomous AI agents using the Model Context Protocol (MCP).
+
+### 🎯 Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **🔍 AI Discovery** | Automatically find and research prospect companies matching your ideal customer profile |
+| **👥 Contact Finder** | Locate decision-makers (CEOs, VPs, Founders) with verified email addresses |
+| **✉️ Email Drafting** | Generate personalized cold outreach emails based on company research |
+| **💬 AI Chat** | Interactive assistant for pipeline management and real-time research |
+| **👤 Prospect Chat** | Demo of prospect-facing AI with handoff & escalation capabilities |
+| **📊 Dashboard** | Real-time pipeline metrics and progress tracking |
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      CX AI Agent                            │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │   Gradio    │  │  Autonomous │  │    MCP      │         │
+│  │     UI      │──│    Agent    │──│   Servers   │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+│         │                │                │                 │
+│         ▼                ▼                ▼                 │
+│  ┌─────────────────────────────────────────────────┐       │
+│  │              MCP Tool Definitions               │       │
+│  │  • Search (Web, News)                          │       │
+│  │  • Store (Prospects, Contacts, Facts)          │       │
+│  │  • Email (Send, Thread Management)             │       │
+│  │  • Calendar (Meeting Slots, Invites)           │       │
+│  └─────────────────────────────────────────────────┘       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Python 3.8+
+- HuggingFace API Token ([Get one free](https://huggingface.co/settings/tokens))
+- Serper API Key (Optional, for web search)
+
+### Quick Start
+
+1. **Setup**: Enter your API credentials and company name
+2. **Discover**: Let AI find prospects matching your profile
+3. **Review**: Check discovered companies and contacts
+4. **Engage**: Use AI-drafted emails for outreach
+
+---
+
+## 🔧 MCP Tools Available
+
+### Search MCP Server
+- `search_web` - Search the web for company information
+- `search_news` - Find recent news about companies
+
+### Store MCP Server
+- `save_prospect` / `get_prospect` / `list_prospects` - Manage prospects
+- `save_company` / `get_company` - Store company data
+- `save_contact` / `list_contacts_by_domain` - Manage contacts
+- `save_fact` - Store research insights
+- `discover_prospects_with_contacts` - Full discovery pipeline
+- `find_verified_contacts` - Find decision-makers
+- `check_suppression` - Compliance checking
+
+### Email MCP Server
+- `send_email` - Send outreach emails
+- `get_email_thread` - Retrieve conversation history
+
+### Calendar MCP Server
+- `suggest_meeting_slots` - Generate available times
+- `generate_calendar_invite` - Create .ics files
+
+---
+
+## 🎭 Prospect Chat Demo
+
+The **Prospect Chat Demo** tab showcases how prospects can interact with your company's AI:
+
+- **Lead Qualification**: AI asks qualifying questions to understand prospect needs
+- **Handoff Packets**: Generate comprehensive summaries for human sales reps
+- **Escalation Flows**: Automatically escalate complex inquiries to humans
+- **Meeting Scheduling**: Integrate with calendar for instant booking
+
+---
+
+## 📊 Technology Stack
+
+| Component | Technology |
+|-----------|------------|
+| **Frontend** | Gradio 5.x |
+| **AI Model** | Qwen3-32B via HuggingFace |
+| **Protocol** | Model Context Protocol (MCP) |
+| **Search** | Serper API |
+| **Language** | Python 3.8+ |
+
+---
+
+## 📝 License
+
+This project is open source and available under the MIT License.
+
+---
+
+## 🙏 Acknowledgments
+
+- **Anthropic** - Model Context Protocol specification
+- **HuggingFace** - AI model hosting and inference
+- **Gradio** - UI framework
+- **Serper** - Web search API
+
+---
+
+<div align="center">
+
+**Built with ❤️ for the Gradio Agents & MCP Hackathon 2025**
+
+`mcp-in-action-track-enterprise`
+
+</div>
+                """)
 
         # Footer
         gr.HTML("""
@@ -3018,18 +3230,19 @@ def create_app():
 
         # ===== NAVIGATION HANDLERS =====
 
-        all_pages = [setup_page, dashboard_page, discovery_page, prospects_page, contacts_page, emails_page, chat_page]
+        all_pages = [setup_page, dashboard_page, discovery_page, prospects_page, contacts_page, emails_page, chat_page, about_page]
 
         def show_page(page_name):
             """Return visibility updates for all pages"""
             pages = {
-                "setup": [True, False, False, False, False, False, False],
-                "dashboard": [False, True, False, False, False, False, False],
-                "discovery": [False, False, True, False, False, False, False],
-                "prospects": [False, False, False, True, False, False, False],
-                "contacts": [False, False, False, False, True, False, False],
-                "emails": [False, False, False, False, False, True, False],
-                "chat": [False, False, False, False, False, False, True],
+                "setup": [True, False, False, False, False, False, False, False],
+                "dashboard": [False, True, False, False, False, False, False, False],
+                "discovery": [False, False, True, False, False, False, False, False],
+                "prospects": [False, False, False, True, False, False, False, False],
+                "contacts": [False, False, False, False, True, False, False, False],
+                "emails": [False, False, False, False, False, True, False, False],
+                "chat": [False, False, False, False, False, False, True, False],
+                "about": [False, False, False, False, False, False, False, True],
             }
             visibility = pages.get(page_name, pages["setup"])
             return [gr.update(visible=v) for v in visibility]
@@ -3045,19 +3258,20 @@ def create_app():
         btn_contacts.click(fn=lambda: show_page("contacts"), outputs=all_pages)
         btn_emails.click(fn=lambda: show_page("emails"), outputs=all_pages)
         btn_chat.click(fn=lambda: show_page("chat"), outputs=all_pages)
+        btn_about.click(fn=lambda: show_page("about"), outputs=all_pages)
 
         # JavaScript to connect sidebar nav items to Gradio buttons (optimized)
         gr.HTML("""
         <script>
             // Cache for navigation buttons - populated once on load
             window._navButtonCache = null;
-            window._pageOrder = ['setup', 'dashboard', 'discovery', 'prospects', 'contacts', 'emails', 'chat'];
+            window._pageOrder = ['setup', 'dashboard', 'discovery', 'prospects', 'contacts', 'emails', 'chat', 'about'];
 
             // Initialize button cache
             function initNavCache() {
                 if (window._navButtonCache) return window._navButtonCache;
                 const buttons = document.querySelectorAll('.nav-buttons-row button');
-                if (buttons.length >= 7) {
+                if (buttons.length >= 8) {
                     window._navButtonCache = {};
                     window._pageOrder.forEach((page, idx) => {
                         window._navButtonCache[page] = buttons[idx];
@@ -3157,6 +3371,157 @@ def create_app():
         send_btn.click(fn=chat_async_wrapper, inputs=[chat_input, chatbot], outputs=[chatbot, chat_input])
         chat_input.submit(fn=chat_async_wrapper, inputs=[chat_input, chatbot], outputs=[chatbot, chat_input])
 
+        # ===== PROSPECT CHAT HANDLERS =====
+
+        async def prospect_chat_wrapper(message, history):
+            """Handle prospect-facing chat with company representative AI"""
+            if not message.strip():
+                return history, ""
+
+            # Get client company info for context
+            client_info = client_company_state.get("name", "Our Company")
+
+            # Build prospect-facing system context
+            system_context = f"""You are an AI assistant representing {client_info}. You are speaking with a potential prospect who is interested in learning about the company's products and services.
+
+Your role is to:
+1. Answer questions about the company professionally and helpfully
+2. Qualify the prospect by understanding their needs, company size, and timeline
+3. Offer to schedule meetings with sales representatives when appropriate
+4. Escalate complex technical or pricing questions to human agents
+
+Be friendly, professional, and helpful. Focus on understanding the prospect's needs."""
+
+            history = history + [[message, None]]
+
+            # Use the AI to generate response
+            token = session_hf_token.get("token", "")
+            if token:
+                try:
+                    from huggingface_hub import InferenceClient
+                    client = InferenceClient(token=token)
+
+                    messages = [{"role": "system", "content": system_context}]
+                    for h in history[:-1]:
+                        if h[0]:
+                            messages.append({"role": "user", "content": h[0]})
+                        if h[1]:
+                            messages.append({"role": "assistant", "content": h[1]})
+                    messages.append({"role": "user", "content": message})
+
+                    response = client.chat_completion(
+                        model="Qwen/Qwen2.5-72B-Instruct",
+                        messages=messages,
+                        max_tokens=500
+                    )
+                    reply = response.choices[0].message.content
+                except Exception as e:
+                    reply = f"I apologize, I'm having trouble connecting right now. Please try again or contact us directly. (Error: {str(e)[:50]})"
+            else:
+                reply = f"Thank you for your interest in {client_info}! I'd be happy to help you learn more about our solutions. What specific challenges are you looking to address?"
+
+            history[-1][1] = reply
+            return history, ""
+
+        def generate_handoff_packet(chat_history):
+            """Generate a handoff packet from the prospect conversation"""
+            if not chat_history:
+                return gr.update(visible=True, value="**⚠️ No conversation to generate handoff from.** Start a conversation first.")
+
+            # Extract key info from conversation
+            conversation_text = "\n".join([f"Prospect: {h[0]}\nAgent: {h[1]}" for h in chat_history if h[0] and h[1]])
+
+            client_name = client_company_state.get("name", "Unknown Client")
+
+            packet = f"""
+## 📋 Handoff Packet
+
+**Generated:** {datetime.now().strftime("%Y-%m-%d %H:%M")}
+**Client Company:** {client_name}
+
+---
+
+### 📝 Conversation Summary
+
+{len(chat_history)} messages exchanged with prospect.
+
+### 💬 Full Conversation Log
+
+```
+{conversation_text[:1500]}{'...' if len(conversation_text) > 1500 else ''}
+```
+
+### 🎯 Recommended Actions
+
+1. Review conversation for prospect pain points
+2. Prepare personalized follow-up materials
+3. Schedule discovery call within 24-48 hours
+
+### 📊 Lead Score: Pending Assessment
+
+---
+
+*This packet was auto-generated by CX AI Agent*
+"""
+            return gr.update(visible=True, value=packet)
+
+        def escalate_to_human(chat_history):
+            """Escalate conversation to human agent"""
+            if not chat_history:
+                return gr.update(visible=True, value="**🚨 Escalation Created**\n\nNo conversation history to escalate. A human agent will reach out to assist you.")
+
+            return gr.update(visible=True, value=f"""
+## 🚨 Escalation Created
+
+**Status:** Pending Human Review
+**Priority:** High
+**Timestamp:** {datetime.now().strftime("%Y-%m-%d %H:%M")}
+
+A human sales representative will review this conversation and reach out shortly.
+
+**Messages in thread:** {len(chat_history)}
+""")
+
+        def schedule_meeting():
+            """Generate meeting scheduling info"""
+            from datetime import timedelta
+            now = datetime.now()
+            slots = []
+            for i in range(1, 4):
+                day = now + timedelta(days=i)
+                if day.weekday() < 5:  # Weekdays only
+                    slots.append(f"- {day.strftime('%A, %B %d')} at 10:00 AM EST")
+                    slots.append(f"- {day.strftime('%A, %B %d')} at 2:00 PM EST")
+
+            return gr.update(visible=True, value=f"""
+## 📅 Meeting Scheduling
+
+**Available Time Slots:**
+
+{chr(10).join(slots[:4])}
+
+To schedule a meeting, please reply with your preferred time slot, or [click here](#) to access our calendar booking system.
+
+*Times shown in EST. Meetings are typically 30 minutes.*
+""")
+
+        # Connect prospect chat handlers
+        prospect_send_btn.click(
+            fn=prospect_chat_wrapper,
+            inputs=[prospect_input, prospect_chatbot],
+            outputs=[prospect_chatbot, prospect_input]
+        )
+        prospect_input.submit(
+            fn=prospect_chat_wrapper,
+            inputs=[prospect_input, prospect_chatbot],
+            outputs=[prospect_chatbot, prospect_input]
+        )
+
+        # Connect action buttons
+        generate_handoff_btn.click(fn=generate_handoff_packet, inputs=[prospect_chatbot], outputs=[handoff_output])
+        escalate_btn.click(fn=escalate_to_human, inputs=[prospect_chatbot], outputs=[handoff_output])
+        schedule_btn.click(fn=schedule_meeting, outputs=[handoff_output])
+
     return demo
 
 

design_notes.md

@@ -1,191 +0,0 @@
-# Lucidya MCP Prototype - Design Notes
-
-## Architecture Rationale
-
-### Why Multi-Agent Architecture?
-
-The multi-agent pattern provides several enterprise advantages:
-
-1. **Separation of Concerns**: Each agent has a single, well-defined responsibility
-2. **Testability**: Agents can be unit tested in isolation
-3. **Scalability**: Agents can be distributed across workers in production
-4. **Observability**: Clear boundaries make debugging and monitoring easier
-5. **Compliance**: Dedicated Compliance agent ensures policy enforcement
-
-### Why MCP (Model Context Protocol)?
-
-MCP servers provide:
-- **Service Isolation**: Each capability (search, email, calendar, store) runs independently
-- **Language Agnostic**: MCP servers can be implemented in any language
-- **Standardized Interface**: JSON-RPC provides clear contracts
-- **Production Ready**: Similar to microservices architecture
-
-### Why FAISS with Normalized Embeddings?
-
-FAISS IndexFlatIP with L2-normalized embeddings offers:
-- **Exact Search**: No approximation errors for small datasets
-- **Cosine Similarity**: Normalized vectors make IP equivalent to cosine
-- **Simple Deployment**: No training required, immediate indexing
-- **Fast Retrieval**: Sub-millisecond searches for <100k vectors
-
-### Why Ollama Streaming?
-
-Real-time streaming provides:
-- **User Experience**: Immediate feedback reduces perceived latency
-- **Progressive Rendering**: Users see content as it's generated
-- **Cancellation**: Streams can be interrupted if needed
-- **Resource Efficiency**: No need to buffer entire responses
-
-
-### 1. Architecture
-
-**Pipeline Design**: Clear DAG with deterministic flow
-```
-Hunter → Enricher → Contactor → Scorer → Writer → Compliance → Sequencer → Curator
-```
-
-**Event-Driven**: NDJSON streaming for real-time observability
-
-**Clean Interfaces**: Every agent follows `run(state) -> state` pattern
-
-### 2. Technical Execution
-
-**Streaming Implementation**: 
-- Ollama `/api/generate` with `stream: true`
-- NDJSON event stream from backend to UI
-- `st.write_stream` for progressive rendering
-
-**Vector System**:
-- sentence-transformers for embeddings
-- FAISS for similarity search
-- Persistent index with metadata
-
-**MCP Integration**:
-- Real Python servers (not mocks)
-- Proper RPC communication
-- Typed client wrappers
-
-**Compliance Framework**: Regional policy toggles, suppression ledger, footer enforcement
-
-**Handoff Packets**: Complete context transfer for human takeover
-
-**Calendar Integration**: ICS generation for meeting scheduling
-
-**Progressive Enrichment**: TTL-based fact expiry, confidence scoring
-
-**Comprehensive Documentation**:
-- README with setup, usage, and examples
-- Design notes explaining decisions
-- Inline code comments
-- Test coverage for key behaviors
-
-## Production Migration Path
-
-### Phase 1: Containerization
-```yaml
-services:
-  api:
-    build: ./app
-    depends_on: [mcp-search, mcp-email, mcp-calendar, mcp-store]
-  
-  mcp-search:
-    build: ./mcp/servers/search
-    ports: ["9001:9001"]
-```
-
-### Phase 2: Message Queue
-Replace direct calls with event bus:
-```python
-# Current
-result = await self.enricher.run(prospect)
-
-# Production
-await queue.publish("enricher.process", prospect)
-prospect = await queue.consume("enricher.complete")
-```
-
-### Phase 3: Distributed Execution
-- Deploy agents as Kubernetes Jobs/CronJobs
-- Use Airflow/Prefect for orchestration
-- Implement circuit breakers and retries
-
-### Phase 4: Enhanced Observability
-- OpenTelemetry for distributed tracing
-- Structured logging to ELK stack
-- Metrics to Prometheus/Grafana
-- Error tracking with Sentry
-
-## Performance Optimizations
-
-### Current Limitations
-- Single-threaded MCP servers
-- In-memory state management
-- Sequential agent execution
-- No connection pooling
-
-### Production Optimizations
-1. **Parallel Processing**: Run independent agents concurrently
-2. **Batch Operations**: Process multiple prospects simultaneously
-3. **Caching Layer**: Redis for hot data
-4. **Connection Pooling**: Reuse HTTP/database connections
-5. **Async Everything**: Full async/await from edge to storage
-
-## Security Considerations
-
-### Current State (Prototype)
-- No authentication
-- Plain HTTP communication
-- Unencrypted storage
-- No rate limiting
-
-### Production Requirements
-- OAuth2/JWT authentication
-- TLS for all communication
-- Encrypted data at rest
-- Rate limiting per client
-- Input validation and sanitization
-- Audit logging for compliance
-
-## Scaling Strategies
-
-### Horizontal Scaling
-- Stateless API servers behind load balancer
-- Multiple MCP server instances with service discovery
-- Distributed vector index with sharding
-
-### Vertical Scaling
-- GPU acceleration for embeddings
-- Larger Ollama models for better quality
-- More sophisticated scoring algorithms
-
-### Data Scaling
-- PostgreSQL for transactional data
-- S3 for document storage
-- ElasticSearch for full-text search
-- Pinecone/Weaviate for vector search at scale
-
-## Success Metrics
-
-### Technical Metrics
-- Pipeline completion rate > 95%
-- Streaming latency < 100ms per token
-- Vector search < 50ms for 1M documents
-- MCP server availability > 99.9%
-
-### Business Metrics
-- Prospect → Meeting conversion rate
-- Email engagement rates
-- Time to handoff < 5 minutes
-- Compliance violation rate < 0.1%
-
-## Future Enhancements
-
-1. **Multi-modal Input**: Support for images, PDFs, audio
-2. **A/B Testing**: Test different prompts and strategies
-3. **Feedback Loop**: Learn from successful conversions
-4. **Advanced Personalization**: Industry-specific templates
-5. **Real-time Collaboration**: Multiple users working on same prospect
-6. **Workflow Customization**: Configurable agent pipeline
-7. **Smart Scheduling**: ML-based optimal send time prediction
-8. **Conversation Intelligence**: Analyze reply sentiment and intent
-```