Add application files (text files only)

.dockerignore

@@ -0,0 +1,45 @@
+# Git
+.git
+.gitignore
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Test
+tests/
+pytest_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Documentation
+*.md
+!README.md
+
+# Build artifacts
+dist/
+build/
+*.egg-info/

.env.example

@@ -0,0 +1,49 @@
+# file: .env.example
+
+# =============================================================================
+# CX AI Agent Configuration
+# =============================================================================
+
+# Hugging Face Configuration (REQUIRED)
+HF_API_TOKEN=your_huggingface_api_token_here
+MODEL_NAME=Qwen/Qwen2.5-7B-Instruct
+MODEL_NAME_FALLBACK=mistralai/Mistral-7B-Instruct-v0.2
+
+# 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
+
+# MCP Mode (for deployment)
+# Set to "true" for Hugging Face Spaces (uses in-memory services)
+# Set to "false" for local development (uses separate MCP servers)
+USE_IN_MEMORY_MCP=true
+
+# Paths
+COMPANY_FOOTER_PATH=./data/footer.txt
+VECTOR_INDEX_PATH=./data/faiss.index
+COMPANIES_FILE=./data/companies.json
+SUPPRESSION_FILE=./data/suppression.json
+
+# Vector Store
+EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
+EMBEDDING_DIM=384
+
+# MCP Server Ports
+MCP_SEARCH_PORT=9001
+MCP_EMAIL_PORT=9002
+MCP_CALENDAR_PORT=9003
+MCP_STORE_PORT=9004
+
+# Compliance Flags
+ENABLE_CAN_SPAM=true
+ENABLE_PECR=true
+ENABLE_CASL=true
+
+# Scoring Thresholds
+MIN_FIT_SCORE=0.5
+FACT_TTL_HOURS=168

.gitignore

@@ -0,0 +1,32 @@
+# Ignore Python virtual environment
+.venv/
+
+# Ignore Python cache files
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+
+# Ignore database files
+*.db
+*.sqlite
+*.sqlite3
+
+# Ignore environment files
+.env
+.env.local
+
+# Ignore IDE files
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Ignore OS files
+.DS_Store
+Thumbs.db
+nul
+
+# Ignore Claude Code local settings
+.claude/settings.local.json

DEMO_SCRIPT.md

@@ -0,0 +1,258 @@
+# CX AI Agent - Demo Video Script (Silent Screen Recording)
+
+## Video Details
+- **Duration**: 3-5 minutes recommended
+- **Format**: Screen recording with on-screen text/captions
+- **No narration**: Use text overlays to explain each step
+
+---
+
+## SCENE 1: Title Card (5 seconds)
+**On-screen text:**
+```
+CX AI Agent
+AI-Powered B2B Sales Intelligence Platform
+
+MCP in Action Track - Enterprise Applications
+Gradio Agents & MCP Hackathon 2025
+```
+
+---
+
+## SCENE 2: Landing Page Overview (10 seconds)
+**Action**: Show the app's main interface with sidebar navigation
+
+**On-screen text:**
+```
+Built with:
+• Model Context Protocol (MCP)
+• Gradio 5.x
+• HuggingFace AI (Qwen2.5-72B)
+• Autonomous AI Agents
+```
+
+---
+
+## SCENE 3: Setup Page (20 seconds)
+**Action**:
+1. Click on "Setup" in sidebar (should already be selected)
+2. Enter HuggingFace Token (paste your token)
+3. Enter Serper API Key (optional - paste if available)
+4. Type a company name: "TechFlow Solutions"
+5. Click "Setup Company" button
+6. Wait for AI to research the company
+
+**On-screen text:**
+```
+Step 1: Setup Your Company
+
+• Enter API credentials
+• AI automatically researches your company
+• Builds knowledge base for prospect matching
+```
+
+---
+
+## SCENE 4: Dashboard Overview (15 seconds)
+**Action**:
+1. Click "Dashboard" in sidebar
+2. Show the stats cards (Prospects: 0, Contacts: 0, Emails: 0)
+3. Show company status indicator
+
+**On-screen text:**
+```
+Dashboard: Real-time Pipeline Metrics
+
+• Track prospects discovered
+• Monitor contacts found
+• View email drafts generated
+```
+
+---
+
+## SCENE 5: AI Discovery - The Core Feature (45 seconds)
+**Action**:
+1. Click "Discovery" in sidebar
+2. Set number of prospects to find: 3
+3. Click "Find Prospects" button
+4. Wait and watch the AI work (this is the main demo!)
+5. Observe the output showing discovered companies
+
+**On-screen text (sequence):**
+```
+Step 2: AI-Powered Discovery
+
+[When clicking button]
+Autonomous AI Agent activates...
+
+[While processing]
+MCP Tools in Action:
+• search_web - Finding prospect companies
+• save_prospect - Storing company data
+• find_verified_contacts - Locating decision makers
+• save_contact - Saving contact information
+
+[When complete]
+AI discovered 3 matching prospects with contacts!
+```
+
+---
+
+## SCENE 6: Prospects List (15 seconds)
+**Action**:
+1. Click "Prospects" in sidebar
+2. Scroll through discovered companies
+3. Show company details (name, industry, description)
+
+**On-screen text:**
+```
+Prospects: AI-Discovered Companies
+
+• Automatically researched
+• ICP-matched profiles
+• Ready for outreach
+```
+
+---
+
+## SCENE 7: Contacts Found (15 seconds)
+**Action**:
+1. Click "Contacts" in sidebar
+2. Show list of decision makers
+3. Point out titles (CEO, VP, Founder, etc.)
+
+**On-screen text:**
+```
+Contacts: Decision Makers Found
+
+• C-level executives
+• Department heads
+• Verified contact info
+• Title-based targeting
+```
+
+---
+
+## SCENE 8: AI-Drafted Emails (20 seconds)
+**Action**:
+1. Click "Emails" in sidebar
+2. Show the personalized email drafts
+3. Scroll to show email content
+4. Highlight personalization elements
+
+**On-screen text:**
+```
+Emails: AI-Personalized Outreach
+
+• Tailored to each prospect
+• Based on company research
+• Ready to send
+• One-click copy
+```
+
+---
+
+## SCENE 9: AI Chat Assistant (30 seconds)
+**Action**:
+1. Click "AI Chat" in sidebar
+2. Type: "What prospects have we found?"
+3. Wait for AI response
+4. Type: "Tell me more about [first prospect name]"
+5. Show the response
+
+**On-screen text:**
+```
+AI Chat: Your Sales Assistant
+
+• Ask about your pipeline
+• Get prospect insights
+• Request additional research
+• Natural language interface
+```
+
+---
+
+## SCENE 10: Prospect Chat Demo (30 seconds)
+**Action**:
+1. Stay on "AI Chat" page, scroll to "Prospect Chat Demo" section
+2. Type as if you're a prospect: "Hi, I'm interested in your services"
+3. Wait for AI response
+4. Type: "What solutions do you offer for small businesses?"
+5. Click "Generate Handoff Packet"
+6. Show the generated packet
+
+**On-screen text:**
+```
+Prospect Chat Demo: Customer-Facing AI
+
+• Qualifies leads automatically
+• Answers product questions
+• Generates handoff packets for sales team
+• Escalation-ready workflows
+```
+
+---
+
+## SCENE 11: MCP Architecture Highlight (15 seconds)
+**Action**:
+1. Click "About Us" in sidebar
+2. Scroll to show architecture or features section
+
+**On-screen text:**
+```
+Powered by Model Context Protocol (MCP)
+
+MCP Servers:
+• Search Server - Web & news research
+• Store Server - Data persistence
+• Email Server - Outreach management
+• Calendar Server - Meeting scheduling
+```
+
+---
+
+## SCENE 12: Closing Card (10 seconds)
+**On-screen text:**
+```
+CX AI Agent
+Autonomous B2B Sales Intelligence
+
+Key Highlights:
+✓ MCP-powered tool orchestration
+✓ Autonomous AI agent architecture
+✓ End-to-end sales workflow automation
+�� Real-time prospect discovery
+
+Built for Gradio Agents & MCP Hackathon 2025
+#mcp-in-action-track-enterprise
+
+GitHub: [your-repo-url]
+HuggingFace Space: [your-space-url]
+```
+
+---
+
+## Recording Tips
+
+1. **Resolution**: Record at 1920x1080 or higher
+2. **Browser**: Use Chrome/Edge in a clean window (no bookmarks bar)
+3. **Zoom**: Set browser zoom to 100% or 110% for readability
+4. **Cursor**: Use a cursor highlighter tool for visibility
+5. **Speed**: Move slowly, let viewers read the on-screen text
+6. **Pauses**: Pause 2-3 seconds on important screens
+7. **Loading**: If AI is processing, add text "AI Processing..." overlay
+
+## Text Overlay Tools (Free)
+- **Kapwing** - Online video editor with text overlays
+- **DaVinci Resolve** - Professional free editor
+- **Clipchamp** - Windows 11 built-in editor
+- **Canva Video** - Simple text animations
+
+## Suggested Background Music (Optional)
+- Upbeat, corporate-friendly
+- Low volume, non-distracting
+- Royalty-free from YouTube Audio Library
+
+---
+
+**Total Estimated Duration: ~3.5 minutes**

README.md

@@ -1,12 +1,171 @@
 ---
-title: Cx Ai Agent V1
-emoji: 📚
-colorFrom: red
-colorTo: red
+title: CX AI Agent - B2B Sales Intelligence
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
 sdk: gradio
-sdk_version: 6.0.2
+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
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🤖 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
+
+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 |
+
+## 🚀 Quick Start
+
+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
+
+## 🏗️ 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)        │        │
+│  └─────────────────────────────────────────────────┘        │
+└─────────────────────────────────────────────_────────────────┘
+```
+
+## 🔧 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
+- `discover_prospects_with_contacts` - Full discovery pipeline
+- `find_verified_contacts` - Find decision-makers
+
+### 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** 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** | Qwen2.5-72B / Qwen3-32B via HuggingFace |
+| **Protocol** | Model Context Protocol (MCP) |
+| **Search** | Serper API |
+| **Language** | Python 3.8+ |
+
+## 🔑 Environment Variables
+
+Set these in your Space Secrets:
+
+```
+HF_TOKEN=your_huggingface_token_here
+SERPER_API_KEY=your_serper_api_key_here  # Optional
+```
+
+## 📁 Project Structure
+
+```
+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
+```
+
+## 📝 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
+
+---
+
+## 👨‍💻 Developer
+
+**Syed Muzakkir Hussain**
+
+[![HuggingFace](https://img.shields.io/badge/HuggingFace-muzakkirhussain011-yellow?logo=huggingface)](https://huggingface.co/muzakkirhussain011)
+
+---
+
+<div align="center">
+
+**Built with ❤️ by [Syed Muzakkir Hussain](https://huggingface.co/muzakkirhussain011) for the Gradio Agents & MCP Hackathon 2025**
+
+`mcp-in-action-track-enterprise`
+
+</div>

agents/__init__.py

@@ -0,0 +1,14 @@
+# file: agents/__init__.py
+from .hunter import Hunter
+from .enricher import Enricher
+from .contactor import Contactor
+from .scorer import Scorer
+from .writer import Writer
+from .compliance import Compliance
+from .sequencer import Sequencer
+from .curator import Curator
+
+__all__ = [
+    "Hunter", "Enricher", "Contactor", "Scorer",
+    "Writer", "Compliance", "Sequencer", "Curator"
+]

agents/compliance.py

@@ -0,0 +1,92 @@
+# file: agents/compliance.py
+from pathlib import Path
+from app.schema import Prospect
+from app.config import (
+    COMPANY_FOOTER_PATH, ENABLE_CAN_SPAM, 
+    ENABLE_PECR, ENABLE_CASL
+)
+
+class Compliance:
+    """Enforces email compliance and policies"""
+    
+    def __init__(self, mcp_registry):
+        self.mcp = mcp_registry
+        self.store = mcp_registry.get_store_client()
+        
+        # Load footer
+        footer_path = Path(COMPANY_FOOTER_PATH)
+        if footer_path.exists():
+            self.footer = footer_path.read_text()
+        else:
+            self.footer = "\n\n---\nLucidya Inc.\n123 Market St, San Francisco, CA 94105\nUnsubscribe: https://lucidya.example.com/unsubscribe"
+    
+    async def run(self, prospect: Prospect) -> Prospect:
+        """Check compliance and enforce policies"""
+        
+        if not prospect.email_draft:
+            prospect.status = "blocked"
+            prospect.dropped_reason = "No email draft to check"
+            await self.store.save_prospect(prospect)
+            return prospect
+        
+        policy_failures = []
+        
+        # Check suppression
+        for contact in prospect.contacts:
+            if await self.store.check_suppression("email", contact.email):
+                policy_failures.append(f"Email suppressed: {contact.email}")
+            
+            domain = contact.email.split("@")[1]
+            if await self.store.check_suppression("domain", domain):
+                policy_failures.append(f"Domain suppressed: {domain}")
+        
+        if await self.store.check_suppression("company", prospect.company.id):
+            policy_failures.append(f"Company suppressed: {prospect.company.name}")
+        
+        # Check content requirements
+        body = prospect.email_draft.get("body", "")
+        
+        # CAN-SPAM requirements
+        if ENABLE_CAN_SPAM:
+            if "unsubscribe" not in body.lower() and "unsubscribe" not in self.footer.lower():
+                policy_failures.append("CAN-SPAM: Missing unsubscribe mechanism")
+            
+            if not any(addr in self.footer for addr in ["St", "Ave", "Rd", "Blvd"]):
+                policy_failures.append("CAN-SPAM: Missing physical postal address")
+        
+        # PECR requirements (UK)
+        if ENABLE_PECR:
+            # Check for soft opt-in or existing relationship
+            # In production, would check CRM for prior relationship
+            if "existing customer" not in body.lower():
+                # For demo, we'll be lenient
+                pass
+        
+        # CASL requirements (Canada)
+        if ENABLE_CASL:
+            if "consent" not in body.lower() and prospect.company.domain.endswith(".ca"):
+                policy_failures.append("CASL: May need express consent for Canadian recipients")
+        
+        # Check for unverifiable claims
+        forbidden_phrases = [
+            "guaranteed", "100%", "no risk", "best in the world",
+            "revolutionary", "breakthrough"
+        ]
+        
+        for phrase in forbidden_phrases:
+            if phrase in body.lower():
+                policy_failures.append(f"Unverifiable claim: '{phrase}'")
+        
+        # Append footer to email
+        if not policy_failures:
+            prospect.email_draft["body"] = body + "\n" + self.footer
+        
+        # Final decision
+        if policy_failures:
+            prospect.status = "blocked"
+            prospect.dropped_reason = "; ".join(policy_failures)
+        else:
+            prospect.status = "compliant"
+        
+        await self.store.save_prospect(prospect)
+        return prospect

agents/contactor.py

@@ -0,0 +1,105 @@
+# file: agents/contactor.py
+"""
+Contactor Agent - Discovers decision-makers at target companies
+Now uses web search to find real contacts instead of generating mock data
+"""
+from app.schema import Prospect, Contact
+from app.config import SKIP_WEB_SEARCH
+import logging
+from services.prospect_discovery import get_prospect_discovery_service
+
+logger = logging.getLogger(__name__)
+
+
+class Contactor:
+    """
+    Discovers and validates decision-maker contacts
+
+    IMPROVED: Now uses web search to discover real decision-makers
+    Falls back to plausible generated contacts when search doesn't find results
+    """
+
+    def __init__(self, mcp_registry):
+        self.mcp = mcp_registry
+        self.store = mcp_registry.get_store_client()
+        self.prospect_discovery = get_prospect_discovery_service()
+
+    async def run(self, prospect: Prospect) -> Prospect:
+        """Discover decision-maker contacts"""
+
+        logger.info(f"Contactor: Finding contacts for '{prospect.company.name}'")
+
+        # Check domain suppression first
+        suppressed = await self.store.check_suppression(
+            "domain",
+            prospect.company.domain
+        )
+
+        if suppressed:
+            logger.warning(f"Contactor: Domain suppressed: {prospect.company.domain}")
+            prospect.status = "dropped"
+            prospect.dropped_reason = f"Domain suppressed: {prospect.company.domain}"
+            await self.store.save_prospect(prospect)
+            return prospect
+
+        # Get existing contacts to dedupe
+        seen_emails = set()
+        try:
+            existing = await self.store.list_contacts_by_domain(prospect.company.domain)
+            for contact in existing:
+                if hasattr(contact, 'email'):
+                    seen_emails.add(contact.email.lower())
+        except Exception as e:
+            logger.error(f"Contactor: Error fetching existing contacts: {str(e)}")
+
+        # Discover contacts using web search
+        contacts = []
+        try:
+            # Determine number of contacts based on company size
+            max_contacts = 2 if prospect.company.size < 100 else 3
+
+            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
+            )
+
+            # Filter out already seen emails and check individual email suppression
+            for contact in discovered_contacts:
+                email_lower = contact.email.lower()
+
+                # Skip if already seen
+                if email_lower in seen_emails:
+                    logger.info(f"Contactor: Skipping duplicate email: {contact.email}")
+                    continue
+
+                # Check email-level suppression
+                email_suppressed = await self.store.check_suppression("email", contact.email)
+                if email_suppressed:
+                    logger.warning(f"Contactor: Email suppressed: {contact.email}")
+                    continue
+
+                # Set prospect ID
+                contact.prospect_id = prospect.id
+
+                # Save and add to list
+                await self.store.save_contact(contact)
+                contacts.append(contact)
+                seen_emails.add(email_lower)
+
+                logger.info(f"Contactor: Added contact: {contact.name} ({contact.title})")
+
+        except Exception as e:
+            logger.error(f"Contactor: Error discovering contacts: {str(e)}")
+            # Continue with empty contacts list
+
+        # Update prospect
+        prospect.contacts = contacts
+        prospect.status = "contacted"
+        await self.store.save_prospect(prospect)
+
+        logger.info(f"Contactor: Found {len(contacts)} contacts for '{prospect.company.name}'")
+
+        return prospect

agents/curator.py

@@ -0,0 +1,40 @@
+# file: agents/curator.py
+from datetime import datetime
+from app.schema import Prospect, HandoffPacket
+
+class Curator:
+    """Creates handoff packets for sales team"""
+    
+    def __init__(self, mcp_registry):
+        self.mcp = mcp_registry
+        self.store = mcp_registry.get_store_client()
+        self.email_client = mcp_registry.get_email_client()
+        self.calendar_client = mcp_registry.get_calendar_client()
+    
+    async def run(self, prospect: Prospect) -> Prospect:
+        """Create handoff packet"""
+        
+        # Get thread
+        thread = None
+        if prospect.thread_id:
+            thread = await self.email_client.get_thread(prospect.id)
+        
+        # Get calendar slots
+        slots = await self.calendar_client.suggest_slots()
+        
+        # Create packet
+        packet = HandoffPacket(
+            prospect=prospect,
+            thread=thread,
+            calendar_slots=slots,
+            generated_at=datetime.utcnow()
+        )
+        
+        # Save packet
+        await self.store.save_handoff(packet)
+        
+        # Update prospect status
+        prospect.status = "ready_for_handoff"
+        await self.store.save_prospect(prospect)
+        
+        return prospect

agents/enricher.py

@@ -0,0 +1,137 @@
+# file: agents/enricher.py
+"""
+Enricher Agent - Enriches prospects with real-time web search data
+Now uses actual web search instead of static/mock data
+"""
+from datetime import datetime
+from app.schema import Prospect, Fact
+from app.config import FACT_TTL_HOURS, SKIP_WEB_SEARCH
+import uuid
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class Enricher:
+    """
+    Enriches prospects with facts from real web search
+
+    IMPROVED: Now uses actual web search to find:
+    - Company news and updates
+    - Industry trends and challenges
+    - Customer experience insights
+    - Recent developments
+    """
+
+    def __init__(self, mcp_registry):
+        self.mcp = mcp_registry
+        self.search = mcp_registry.get_search_client()
+        self.store = mcp_registry.get_store_client()
+
+    async def run(self, prospect: Prospect) -> Prospect:
+        """Enrich prospect with facts from web search"""
+
+        logger.info(f"Enricher: Enriching prospect '{prospect.company.name}'")
+
+        facts = []
+        seen_texts = set()  # Deduplication
+
+        # Only do web search if not skipped
+        if not SKIP_WEB_SEARCH:
+            logger.info("Enricher: Performing web search for facts")
+
+            # Enhanced search queries for better fact discovery
+            queries = [
+                # Company news and updates
+                f"{prospect.company.name} news latest updates",
+                # Industry-specific challenges
+                f"{prospect.company.name} {prospect.company.industry} customer experience",
+                # Pain points and challenges
+                f"{prospect.company.name} challenges problems",
+                # Contact and support information
+                f"{prospect.company.domain} customer support contact"
+            ]
+
+            for query in queries:
+                try:
+                    logger.info(f"Enricher: Searching for: '{query}'")
+                    results = await self.search.query(query)
+
+                    # Process search results
+                    for result in results[:3]:  # Top 3 per query
+                        text = result.get("text", "").strip()
+                        title = result.get("title", "").strip()
+
+                        # Skip empty or very short results
+                        if not text or len(text) < 20:
+                            continue
+
+                        # Combine title and text for better context
+                        if title and title not in text:
+                            full_text = f"{title}. {text}"
+                        else:
+                            full_text = text
+
+                        # Deduplicate
+                        if full_text in seen_texts:
+                            continue
+                        seen_texts.add(full_text)
+
+                        # Create fact
+                        fact = Fact(
+                            id=str(uuid.uuid4()),
+                            source=result.get("source", "web search"),
+                            text=full_text[:500],  # Limit length
+                            collected_at=datetime.utcnow(),
+                            ttl_hours=FACT_TTL_HOURS,
+                            confidence=result.get("confidence", 0.75),
+                            company_id=prospect.company.id
+                        )
+                        facts.append(fact)
+                        await self.store.save_fact(fact)
+
+                        logger.info(f"Enricher: Added fact from {fact.source}")
+
+                except Exception as e:
+                    logger.error(f"Enricher: Error searching for '{query}': {str(e)}")
+                    continue
+        else:
+            logger.info("Enricher: Skipping web search (SKIP_WEB_SEARCH=true)")
+
+        # Also add company pain points as facts (from discovery)
+        for pain in prospect.company.pains:
+            if pain and len(pain) > 10:  # Valid pain point
+                fact = Fact(
+                    id=str(uuid.uuid4()),
+                    source="company_discovery",
+                    text=f"Known challenge: {pain}",
+                    collected_at=datetime.utcnow(),
+                    ttl_hours=FACT_TTL_HOURS * 2,  # Discovery data lasts longer
+                    confidence=0.85,
+                    company_id=prospect.company.id
+                )
+                facts.append(fact)
+                await self.store.save_fact(fact)
+
+        # Add company notes as facts
+        for note in prospect.company.notes:
+            if note and len(note) > 10:  # Valid note
+                fact = Fact(
+                    id=str(uuid.uuid4()),
+                    source="company_discovery",
+                    text=note,
+                    collected_at=datetime.utcnow(),
+                    ttl_hours=FACT_TTL_HOURS * 2,
+                    confidence=0.8,
+                    company_id=prospect.company.id
+                )
+                facts.append(fact)
+                await self.store.save_fact(fact)
+
+        prospect.facts = facts
+        prospect.status = "enriched"
+        await self.store.save_prospect(prospect)
+
+        logger.info(f"Enricher: Added {len(facts)} facts for '{prospect.company.name}'")
+
+        return prospect

agents/hunter.py

@@ -0,0 +1,156 @@
+# file: agents/hunter.py
+"""
+Hunter Agent - Discovers companies dynamically
+Now uses web search to find company information instead of static files
+"""
+import json
+from typing import List, Optional
+from app.schema import Company, Prospect
+from app.config import COMPANIES_FILE, SKIP_WEB_SEARCH
+from services.company_discovery import get_company_discovery_service
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class Hunter:
+    """
+    Discovers companies and creates prospects dynamically
+
+    NEW: Can now discover companies from user input (company names)
+    LEGACY: Still supports loading from seed file for backwards compatibility
+    """
+
+    def __init__(self, mcp_registry):
+        self.mcp = mcp_registry
+        self.store = mcp_registry.get_store_client()
+        self.discovery = get_company_discovery_service()
+
+    async def run(
+        self,
+        company_names: Optional[List[str]] = None,
+        company_ids: Optional[List[str]] = None,
+        use_seed_file: bool = False
+    ) -> List[Prospect]:
+        """
+        Discover companies and create prospects
+
+        Args:
+            company_names: List of company names to discover (NEW - dynamic mode)
+            company_ids: List of company IDs from seed file (LEGACY - static mode)
+            use_seed_file: If True, load from seed file instead of discovery
+
+        Returns:
+            List of Prospect objects
+        """
+        prospects = []
+
+        # Mode 1: Dynamic discovery from company names (NEW)
+        if company_names and not use_seed_file:
+            logger.info(f"Hunter: Dynamic discovery mode - discovering {len(company_names)} companies")
+
+            for company_name in company_names:
+                try:
+                    logger.info(f"Hunter: Discovering '{company_name}'...")
+
+                    # Discover company information from web (or use fallback if configured)
+                    company = await self.discovery.discover_company(company_name, skip_search=SKIP_WEB_SEARCH)
+
+                    if not company:
+                        logger.warning(f"Hunter: Could not discover company '{company_name}'")
+                        # Create a minimal fallback company
+                        company = self._create_fallback_company(company_name)
+
+                    # Create prospect
+                    prospect = Prospect(
+                        id=company.id,
+                        company=company,
+                        status="new"
+                    )
+
+                    # Save to store
+                    await self.store.save_prospect(prospect)
+                    prospects.append(prospect)
+
+                    logger.info(f"Hunter: Successfully created prospect for '{company_name}'")
+
+                except Exception as e:
+                    logger.error(f"Hunter: Error discovering '{company_name}': {str(e)}")
+                    # Create fallback and continue
+                    company = self._create_fallback_company(company_name)
+                    prospect = Prospect(
+                        id=company.id,
+                        company=company,
+                        status="new"
+                    )
+                    await self.store.save_prospect(prospect)
+                    prospects.append(prospect)
+
+        # Mode 2: Legacy mode - load from seed file (BACKWARDS COMPATIBLE)
+        else:
+            logger.info("Hunter: Legacy mode - loading from seed file")
+
+            try:
+                # Load from seed file
+                with open(COMPANIES_FILE) as f:
+                    companies_data = json.load(f)
+
+                for company_data in companies_data:
+                    # Filter by IDs if specified
+                    if company_ids and company_data["id"] not in company_ids:
+                        continue
+
+                    company = Company(**company_data)
+
+                    # Create prospect
+                    prospect = Prospect(
+                        id=company.id,
+                        company=company,
+                        status="new"
+                    )
+
+                    # Save to store
+                    await self.store.save_prospect(prospect)
+                    prospects.append(prospect)
+
+                logger.info(f"Hunter: Loaded {len(prospects)} companies from seed file")
+
+            except FileNotFoundError:
+                logger.error(f"Hunter: Seed file not found: {COMPANIES_FILE}")
+                # If no seed file and no company names provided, return empty
+                if not company_names:
+                    return []
+            except Exception as e:
+                logger.error(f"Hunter: Error loading seed file: {str(e)}")
+                return []
+
+        return prospects
+
+    def _create_fallback_company(self, company_name: str) -> Company:
+        """Create a minimal fallback company when discovery fails"""
+        import re
+        import uuid
+
+        # Generate ID
+        slug = re.sub(r'[^a-zA-Z0-9]', '', company_name.lower())[:20]
+        company_id = f"{slug}_{str(uuid.uuid4())[:8]}"
+
+        # Create minimal company
+        company = Company(
+            id=company_id,
+            name=company_name,
+            domain=f"{slug}.com",
+            industry="Technology",
+            size=100,
+            pains=[
+                "Customer experience improvement needed",
+                "Operational efficiency challenges"
+            ],
+            notes=[
+                "Company information discovery in progress",
+                "Limited data available"
+            ]
+        )
+
+        logger.info(f"Hunter: Created fallback company for '{company_name}'")
+        return company

agents/scorer.py

@@ -0,0 +1,75 @@
+# file: agents/scorer.py
+from datetime import datetime, timedelta
+from app.schema import Prospect
+from app.config import MIN_FIT_SCORE
+
+class Scorer:
+    """Scores prospects and drops low-quality ones"""
+    
+    def __init__(self, mcp_registry):
+        self.mcp = mcp_registry
+        self.store = mcp_registry.get_store_client()
+    
+    async def run(self, prospect: Prospect) -> Prospect:
+        """Score prospect based on various factors"""
+        
+        score = 0.0
+        
+        # Industry scoring
+        high_value_industries = ["SaaS", "FinTech", "E-commerce", "Healthcare Tech"]
+        if prospect.company.industry in high_value_industries:
+            score += 0.3
+        else:
+            score += 0.1
+        
+        # Size scoring
+        if 100 <= prospect.company.size <= 5000:
+            score += 0.2  # Sweet spot
+        elif prospect.company.size > 5000:
+            score += 0.1  # Enterprise, harder to sell
+        else:
+            score += 0.05  # Too small
+        
+        # Pain points alignment
+        cx_related_pains = ["customer retention", "NPS", "support efficiency", "personalization"]
+        matching_pains = sum(
+            1 for pain in prospect.company.pains 
+            if any(keyword in pain.lower() for keyword in cx_related_pains)
+        )
+        score += min(0.3, matching_pains * 0.1)
+        
+        # Facts freshness
+        fresh_facts = 0
+        stale_facts = 0
+        now = datetime.utcnow()
+        
+        for fact in prospect.facts:
+            age_hours = (now - fact.collected_at).total_seconds() / 3600
+            if age_hours > fact.ttl_hours:
+                stale_facts += 1
+            else:
+                fresh_facts += 1
+        
+        if fresh_facts > 0:
+            score += min(0.2, fresh_facts * 0.05)
+        
+        # Confidence from facts
+        if prospect.facts:
+            avg_confidence = sum(f.confidence for f in prospect.facts) / len(prospect.facts)
+            score += avg_confidence * 0.2
+        
+        # Normalize score
+        prospect.fit_score = min(1.0, score)
+        
+        # Decision
+        if prospect.fit_score < MIN_FIT_SCORE:
+            prospect.status = "dropped"
+            prospect.dropped_reason = f"Low fit score: {prospect.fit_score:.2f}"
+        elif stale_facts > fresh_facts:
+            prospect.status = "dropped"
+            prospect.dropped_reason = f"Stale facts: {stale_facts}/{len(prospect.facts)}"
+        else:
+            prospect.status = "scored"
+        
+        await self.store.save_prospect(prospect)
+        return prospect

agents/sequencer.py

@@ -0,0 +1,106 @@
+# file: agents/sequencer.py
+from datetime import datetime
+from app.schema import Prospect, Message
+import uuid
+
+class Sequencer:
+    """Sequences and sends outreach emails"""
+    
+    def __init__(self, mcp_registry):
+        self.mcp = mcp_registry
+        self.email_client = mcp_registry.get_email_client()
+        self.calendar_client = mcp_registry.get_calendar_client()
+        self.store = mcp_registry.get_store_client()
+    
+    async def run(self, prospect: Prospect) -> Prospect:
+        """Send email and create thread"""
+        
+        # Check if we have minimum requirements
+        if not prospect.contacts:
+            # Try to generate a default contact if none exist
+            from app.schema import Contact
+            default_contact = Contact(
+                id=str(uuid.uuid4()),
+                name=f"Customer Success at {prospect.company.name}",
+                email=f"contact@{prospect.company.domain}",
+                title="Customer Success",
+                prospect_id=prospect.id
+            )
+            prospect.contacts = [default_contact]
+            await self.store.save_contact(default_contact)
+        
+        if not prospect.email_draft:
+            # Generate a simple default email if none exists
+            prospect.email_draft = {
+                "subject": f"Improving {prospect.company.name}'s Customer Experience",
+                "body": f"""Dear {prospect.company.name} team,
+
+We noticed your company is in the {prospect.company.industry} industry with {prospect.company.size} employees. 
+We'd love to discuss how we can help improve your customer experience.
+
+Looking forward to connecting with you.
+
+Best regards,
+Lucidya Team"""
+            }
+        
+        # Now proceed with sending
+        primary_contact = prospect.contacts[0]
+        
+        # Get calendar slots
+        try:
+            slots = await self.calendar_client.suggest_slots()
+        except:
+            slots = []  # Continue even if calendar fails
+        
+        # Generate ICS attachment for first slot
+        ics_content = ""
+        if slots:
+            try:
+                slot = slots[0]
+                ics_content = await self.calendar_client.generate_ics(
+                    f"Meeting with {prospect.company.name}",
+                    slot["start_iso"],
+                    slot["end_iso"]
+                )
+            except:
+                pass  # Continue without ICS
+        
+        # Add calendar info to email
+        calendar_text = ""
+        if slots:
+            calendar_text = f"\n\nI have a few time slots available this week:\n"
+            for slot in slots[:3]:
+                calendar_text += f"- {slot['start_iso'][:16].replace('T', ' at ')}\n"
+        
+        # Send email
+        email_body = prospect.email_draft["body"]
+        if calendar_text:
+            email_body = email_body.rstrip() + calendar_text
+        
+        try:
+            result = await self.email_client.send(
+                to=primary_contact.email,
+                subject=prospect.email_draft["subject"],
+                body=email_body,
+                prospect_id=prospect.id  # Add prospect_id for thread tracking
+            )
+
+            # Update prospect with thread ID
+            # 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:
+            # Even if email sending fails, don't block the prospect
+            prospect.thread_id = f"mock-thread-{uuid.uuid4()}"
+            prospect.status = "sequenced"
+            print(f"Warning: Email send failed for {prospect.company.name}: {e}")
+        
+        await self.store.save_prospect(prospect)
+        return prospect

agents/writer.py

@@ -0,0 +1,261 @@
+# file: agents/writer.py
+import json
+import re
+import logging
+from typing import AsyncGenerator
+from app.schema import Prospect
+from app.config import MODEL_NAME, HF_API_TOKEN, MODEL_NAME_FALLBACK
+from app.logging_utils import log_event
+from vector.retriever import Retriever
+from huggingface_hub import AsyncInferenceClient
+
+logger = logging.getLogger(__name__)
+
+class Writer:
+    """Generates outreach content with HuggingFace Inference API streaming"""
+
+    def __init__(self, mcp_registry):
+        self.mcp = mcp_registry
+        self.store = mcp_registry.get_store_client()
+        self.retriever = Retriever()
+        # Initialize HF client
+        self.hf_client = AsyncInferenceClient(token=HF_API_TOKEN if HF_API_TOKEN else None)
+    
+    async def run_streaming(self, prospect: Prospect) -> AsyncGenerator[dict, None]:
+        """Generate content with streaming tokens"""
+
+        # IMPORTANT: Log contact information for debugging
+        if prospect.contacts:
+            for contact in prospect.contacts:
+                log_event("writer", f"Using contact: {contact.name} ({contact.title}) - {contact.email}", "agent_log")
+                logger.info(f"Writer: Using contact: {contact.name} ({contact.title}) - {contact.email}")
+        else:
+            log_event("writer", "WARNING: No contacts found for this prospect!", "agent_log")
+            logger.warning(f"Writer: No contacts found for prospect {prospect.company.name}")
+
+        # Get relevant facts from vector store
+        try:
+            relevant_facts = self.retriever.retrieve(prospect.company.id, k=5)
+        except:
+            relevant_facts = []
+        
+        # Build comprehensive context
+        context = f"""
+COMPANY PROFILE:
+Name: {prospect.company.name}
+Industry: {prospect.company.industry}
+Size: {prospect.company.size} employees
+Domain: {prospect.company.domain}
+
+KEY CHALLENGES:
+{chr(10).join(f'• {pain}' for pain in prospect.company.pains)}
+
+BUSINESS CONTEXT:
+{chr(10).join(f'• {note}' for note in prospect.company.notes) if prospect.company.notes else '• No additional notes'}
+
+RELEVANT INSIGHTS:
+{chr(10).join(f'• {fact["text"]} (confidence: {fact.get("score", 0.7):.2f})' for fact in relevant_facts[:3]) if relevant_facts else '• Industry best practices suggest focusing on customer experience improvements'}
+"""
+        
+        # Generate comprehensive summary first
+        summary_prompt = f"""{context}
+
+Generate a comprehensive bullet-point summary for {prospect.company.name} that includes:
+1. Company overview (industry, size)
+2. Main challenges they face
+3. Specific opportunities for improvement
+4. Recommended actions
+
+Format: Use 5-7 bullets, each starting with "•". Be specific and actionable.
+Include the industry and size context in your summary."""
+        
+        summary_text = ""
+
+        # Emit company header first
+        yield log_event("writer", f"Generating content for {prospect.company.name}", "company_start",
+                       {"company": prospect.company.name,
+                        "industry": prospect.company.industry,
+                        "size": prospect.company.size})
+
+        # Summary generation with HF Inference API
+        try:
+            # Use text generation with streaming
+            stream = await self.hf_client.text_generation(
+                summary_prompt,
+                model=MODEL_NAME,
+                max_new_tokens=500,
+                temperature=0.7,
+                stream=True
+            )
+
+            async for token in stream:
+                summary_text += token
+                yield log_event(
+                    "writer",
+                    token,
+                    "llm_token",
+                    {
+                        "type": "summary",
+                        "token": token,
+                        "prospect_id": prospect.id,
+                        "company_id": prospect.company.id,
+                        "company_name": prospect.company.name,
+                    },
+                )
+
+        except Exception as e:
+            # Fallback summary if generation fails
+            summary_text = f"""• {prospect.company.name} is a {prospect.company.industry} company with {prospect.company.size} employees
+• Main challenge: {prospect.company.pains[0] if prospect.company.pains else 'Customer experience improvement'}
+• Opportunity: Implement modern CX solutions to improve customer satisfaction
+• Recommended action: Schedule a consultation to discuss specific needs"""
+            yield log_event("writer", f"Summary generation failed, using default: {e}", "llm_error")
+        
+        # Generate personalized email
+        # If we have a contact, instruct the greeting explicitly with name and title
+        greeting_hint = ""
+        contact_context = ""
+        if prospect.contacts:
+            contact = prospect.contacts[0]
+            first_name = (contact.name or "").split()[0]
+            full_name = contact.name
+            title = contact.title
+
+            if first_name:
+                greeting_hint = f"IMPORTANT: Start the email EXACTLY with this greeting: 'Hi {first_name},'\n"
+                contact_context = f"\nTARGET RECIPIENT:\nName: {full_name}\nTitle: {title}\nEmail: {contact.email}\n"
+
+        email_prompt = f"""{context}
+{contact_context}
+Company Summary:
+{summary_text}
+
+Write a highly personalized outreach email from a CX AI platform provider to {prospect.contacts[0].name if prospect.contacts else 'leaders'} at {prospect.company.name}.
+{greeting_hint}
+Requirements:
+- Subject line that mentions their company name and industry
+- Body: 150-180 words, professional and friendly
+- Reference their specific industry ({prospect.company.industry}) and size ({prospect.company.size} employees)
+- Address them by their first name in the greeting (e.g., "Hi {prospect.contacts[0].name.split()[0] if prospect.contacts else 'there'},")
+- Acknowledge their role as {prospect.contacts[0].title if prospect.contacts else 'a leader'} in the organization
+- Clearly connect their challenges to AI-powered customer experience solutions
+- One clear call-to-action to schedule a short conversation or demo next week
+- Do not write as if the email is from the company to us
+- No exaggerated claims
+- Sign off as: "The CX Team"
+
+Format response exactly as:
+Subject: [subject line]
+Body: [email body]
+"""
+        
+        email_text = ""
+        
+        # Emit email generation start
+        yield log_event("writer", f"Generating email for {prospect.company.name}", "email_start",
+                       {"company": prospect.company.name})
+
+        # Email generation with HF Inference API
+        try:
+            stream = await self.hf_client.text_generation(
+                email_prompt,
+                model=MODEL_NAME,
+                max_new_tokens=400,
+                temperature=0.7,
+                stream=True
+            )
+
+            async for token in stream:
+                email_text += token
+                yield log_event(
+                    "writer",
+                    token,
+                    "llm_token",
+                    {
+                        "type": "email",
+                        "token": token,
+                        "prospect_id": prospect.id,
+                        "company_id": prospect.company.id,
+                        "company_name": prospect.company.name,
+                    },
+                )
+
+        except Exception as e:
+            # Fallback email if generation fails - use contact name if available
+            contact_greeting = "Hi there,"
+            if prospect.contacts:
+                first_name = prospect.contacts[0].name.split()[0] if prospect.contacts[0].name else "there"
+                contact_greeting = f"Hi {first_name},"
+
+            email_text = f"""Subject: Improve {prospect.company.name}'s Customer Experience
+
+Body: {contact_greeting}
+
+As a {prospect.company.industry} company with {prospect.company.size} employees, you face unique customer experience challenges. We understand that {prospect.company.pains[0] if prospect.company.pains else 'improving customer satisfaction'} is a priority for your organization.
+
+Our AI-powered platform has helped similar companies in the {prospect.company.industry} industry improve their customer experience metrics significantly. We'd love to discuss how we can help {prospect.company.name} achieve similar results.
+
+Would you be available for a brief call next week to explore how we can address your specific needs?
+
+Best regards,
+The CX Team"""
+            yield log_event("writer", f"Email generation failed, using default: {e}", "llm_error")
+        
+        # Parse email
+        email_parts = {"subject": "", "body": ""}
+        if "Subject:" in email_text and "Body:" in email_text:
+            parts = email_text.split("Body:")
+            email_parts["subject"] = parts[0].replace("Subject:", "").strip()
+            email_parts["body"] = parts[1].strip()
+        else:
+            # Fallback with company details - personalize with contact name
+            contact_greeting = "Hi there,"
+            if prospect.contacts:
+                first_name = prospect.contacts[0].name.split()[0] if prospect.contacts[0].name else "there"
+                contact_greeting = f"Hi {first_name},"
+
+            email_parts["subject"] = f"Transform {prospect.company.name}'s Customer Experience"
+            email_parts["body"] = email_text or f"""{contact_greeting}
+
+As a leading {prospect.company.industry} company with {prospect.company.size} employees, we know you're focused on delivering exceptional customer experiences.
+
+We'd like to discuss how our AI-powered platform can help address your specific challenges and improve your customer satisfaction metrics.
+
+Best regards,
+The CX Team"""
+
+        # Replace any placeholder tokens like [Team Name] with actual contact name if available
+        if prospect.contacts:
+            contact_name = prospect.contacts[0].name
+            if email_parts.get("subject"):
+                email_parts["subject"] = re.sub(r"\[[^\]]+\]", contact_name, email_parts["subject"])
+            if email_parts.get("body"):
+                email_parts["body"] = re.sub(r"\[[^\]]+\]", contact_name, email_parts["body"])
+
+        # Update prospect
+        prospect.summary = f"**{prospect.company.name} ({prospect.company.industry}, {prospect.company.size} employees)**\n\n{summary_text}"
+        prospect.email_draft = email_parts
+        prospect.status = "drafted"
+        await self.store.save_prospect(prospect)
+        
+        # Emit completion event with company info
+        yield log_event(
+            "writer",
+            f"Generation complete for {prospect.company.name}",
+            "llm_done",
+            {
+                "prospect": prospect,
+                "summary": prospect.summary,
+                "email": email_parts,
+                "company_name": prospect.company.name,
+                "prospect_id": prospect.id,
+                "company_id": prospect.company.id,
+            },
+        )
+    
+    async def run(self, prospect: Prospect) -> Prospect:
+        """Non-streaming version for compatibility"""
+        async for event in self.run_streaming(prospect):
+            if event["type"] == "llm_done":
+                return event["payload"]["prospect"]
+        return prospect

alembic.ini

@@ -0,0 +1,43 @@
+# Alembic configuration file for CX AI Agent database migrations
+
+[alembic]
+# Path to migration scripts
+script_location = migrations
+
+# Template used to generate migration files
+file_template = %%(year)d_%%(month).2d_%%(day).2d_%%(hour).2d%%(minute).2d-%%(rev)s_%%(slug)s
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

app/__init__.py

@@ -0,0 +1,3 @@
+# file: app/__init__.py
+"""Lucidya MCP Prototype - Core Application Package"""
+__version__ = "0.1.0"

app/config.py

@@ -0,0 +1,51 @@
+# file: app/config.py
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Paths
+BASE_DIR = Path(__file__).parent.parent
+DATA_DIR = BASE_DIR / "data"
+
+# Hugging Face Inference API
+HF_API_TOKEN = os.getenv("HF_API_TOKEN", "")
+
+# LLM Configuration - Optimized for FREE HF CPU Inference
+# Primary: Qwen2.5-3B (3B params - 2.3x faster than 7B, better for CPU)
+# Alternative options for CPU:
+#   - "Qwen/Qwen2.5-3B-Instruct" (3B - fast, high quality)
+#   - "microsoft/Phi-3-mini-4k-instruct" (3.8B - ultra efficient)
+#   - "HuggingFaceTB/SmolLM2-1.7B-Instruct" (1.7B - fastest)
+MODEL_NAME = os.getenv("MODEL_NAME", "Qwen/Qwen2.5-3B-Instruct")
+MODEL_NAME_FALLBACK = os.getenv("MODEL_NAME_FALLBACK", "microsoft/Phi-3-mini-4k-instruct")
+
+# Web Search Configuration
+# Set to "true" to skip web search and use fallback data (recommended for demo/rate-limited environments)
+SKIP_WEB_SEARCH = os.getenv("SKIP_WEB_SEARCH", "false").lower() == "true"
+
+# Vector Store
+VECTOR_INDEX_PATH = os.getenv("VECTOR_INDEX_PATH", str(DATA_DIR / "faiss.index"))
+EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
+EMBEDDING_DIM = 384
+
+# MCP Servers
+MCP_SEARCH_PORT = int(os.getenv("MCP_SEARCH_PORT", "9001"))
+MCP_EMAIL_PORT = int(os.getenv("MCP_EMAIL_PORT", "9002"))
+MCP_CALENDAR_PORT = int(os.getenv("MCP_CALENDAR_PORT", "9003"))
+MCP_STORE_PORT = int(os.getenv("MCP_STORE_PORT", "9004"))
+
+# Compliance
+COMPANY_FOOTER_PATH = os.getenv("COMPANY_FOOTER_PATH", str(DATA_DIR / "footer.txt"))
+ENABLE_CAN_SPAM = os.getenv("ENABLE_CAN_SPAM", "true").lower() == "true"
+ENABLE_PECR = os.getenv("ENABLE_PECR", "true").lower() == "true"
+ENABLE_CASL = os.getenv("ENABLE_CASL", "true").lower() == "true"
+
+# Scoring
+MIN_FIT_SCORE = float(os.getenv("MIN_FIT_SCORE", "0.5"))
+FACT_TTL_HOURS = int(os.getenv("FACT_TTL_HOURS", "168"))  # 1 week
+
+# Data Files
+COMPANIES_FILE = DATA_DIR / "companies.json"
+SUPPRESSION_FILE = DATA_DIR / "suppression.json"

app/logging_utils.py

@@ -0,0 +1,25 @@
+# file: app/logging_utils.py
+import logging
+from datetime import datetime
+from rich.logging import RichHandler
+
+def setup_logging(level=logging.INFO):
+    """Configure rich logging"""
+    logging.basicConfig(
+        level=level,
+        format="%(message)s",
+        datefmt="[%X]",
+        handlers=[RichHandler(rich_tracebacks=True)]
+    )
+
+def log_event(agent: str, message: str, type: str = "agent_log", payload: dict = None) -> dict:
+    """Create a pipeline event for streaming"""
+    return {
+        "ts": datetime.utcnow().isoformat(),
+        "type": type,
+        "agent": agent,
+        "message": message,
+        "payload": payload or {}
+    }
+
+logger = logging.getLogger(__name__)

app/main.py

@@ -0,0 +1,223 @@
+# file: app/main.py
+import json
+from datetime import datetime
+from typing import AsyncGenerator
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import StreamingResponse, JSONResponse
+from fastapi.encoders import jsonable_encoder
+from app.schema import PipelineRequest, WriterStreamRequest, Prospect, HandoffPacket
+from app.orchestrator import Orchestrator
+from app.config import MODEL_NAME, HF_API_TOKEN
+from app.logging_utils import setup_logging
+from mcp.registry import MCPRegistry
+from vector.store import VectorStore
+import requests
+
+setup_logging()
+
+app = FastAPI(title="CX AI Agent", version="1.0.0")
+orchestrator = Orchestrator()
+mcp = MCPRegistry()
+vector_store = VectorStore()
+
+@app.on_event("startup")
+async def startup():
+    """Initialize connections on startup"""
+    await mcp.connect()
+
+@app.get("/health")
+async def health():
+    """Health check with HF API connectivity test"""
+    try:
+        # Check HF API
+        hf_ok = bool(HF_API_TOKEN)
+
+        # Check MCP servers
+        mcp_status = await mcp.health_check()
+
+        return {
+            "status": "healthy",
+            "timestamp": datetime.utcnow().isoformat(),
+            "hf_inference": {
+                "configured": hf_ok,
+                "model": MODEL_NAME
+            },
+            "mcp": mcp_status,
+            "vector_store": vector_store.is_initialized()
+        }
+    except Exception as e:
+        return JSONResponse(
+            status_code=503,
+            content={"status": "unhealthy", "error": str(e)}
+        )
+
+async def stream_pipeline(request: PipelineRequest) -> AsyncGenerator[bytes, None]:
+    """
+    Stream NDJSON events from pipeline
+
+    Supports both dynamic (company_names) and legacy (company_ids) modes
+    """
+    async for event in orchestrator.run_pipeline(
+        company_ids=request.company_ids,
+        company_names=request.company_names,
+        use_seed_file=request.use_seed_file
+    ):
+        # Ensure nested Pydantic models (e.g., Prospect) are JSON-serializable
+        yield (json.dumps(jsonable_encoder(event)) + "\n").encode()
+
+@app.post("/run")
+async def run_pipeline(request: PipelineRequest):
+    """
+    Run the full pipeline with NDJSON streaming
+
+    NEW: Accepts company_names for dynamic discovery
+    LEGACY: Still supports company_ids for backwards compatibility
+
+    Example (Dynamic):
+    {"company_names": ["Shopify", "Stripe", "Zendesk"]}
+
+    Example (Legacy):
+    {"company_ids": ["acme", "techcorp"], "use_seed_file": true}
+    """
+    return StreamingResponse(
+        stream_pipeline(request),
+        media_type="application/x-ndjson"
+    )
+
+async def stream_writer_test(company_id: str) -> AsyncGenerator[bytes, None]:
+    """Stream only Writer agent output for testing"""
+    from agents.writer import Writer
+    
+    # Get company from store
+    store = mcp.get_store_client()
+    company = await store.get_company(company_id)
+    
+    if not company:
+        yield (json.dumps({"error": f"Company {company_id} not found"}) + "\n").encode()
+        return
+    
+    # Create a test prospect
+    prospect = Prospect(
+        id=f"{company_id}_test",
+        company=company,
+        contacts=[],
+        facts=[],
+        fit_score=0.8,
+        status="scored"
+    )
+    
+    writer = Writer(mcp)
+    async for event in writer.run_streaming(prospect):
+        # Ensure nested Pydantic models (e.g., Prospect) are JSON-serializable
+        yield (json.dumps(jsonable_encoder(event)) + "\n").encode()
+
+@app.post("/writer/stream")
+async def writer_stream_test(request: WriterStreamRequest):
+    """Test endpoint for Writer streaming"""
+    return StreamingResponse(
+        stream_writer_test(request.company_id),
+        media_type="application/x-ndjson"
+    )
+
+@app.get("/prospects")
+async def list_prospects():
+    """List all prospects with status and scores"""
+    store = mcp.get_store_client()
+    prospects = await store.list_prospects()
+    return {
+        "count": len(prospects),
+        "prospects": [
+            {
+                "id": p.id,
+                "company": p.company.name,
+                "status": p.status,
+                "fit_score": p.fit_score,
+                "contacts": len(p.contacts),
+                "facts": len(p.facts)
+            }
+            for p in prospects
+        ]
+    }
+
+@app.get("/prospects/{prospect_id}")
+async def get_prospect(prospect_id: str):
+    """Get detailed prospect information"""
+    store = mcp.get_store_client()
+    prospect = await store.get_prospect(prospect_id)
+    
+    if not prospect:
+        raise HTTPException(status_code=404, detail="Prospect not found")
+    
+    # Get thread if exists
+    email_client = mcp.get_email_client()
+    thread = None
+    if prospect.thread_id:
+        thread = await email_client.get_thread(prospect.id)
+    
+    return {
+        "prospect": prospect.dict(),
+        "thread": thread.dict() if thread else None
+    }
+
+@app.get("/handoff/{prospect_id}")
+async def get_handoff(prospect_id: str):
+    """Get handoff packet for a prospect"""
+    store = mcp.get_store_client()
+    prospect = await store.get_prospect(prospect_id)
+    
+    if not prospect:
+        raise HTTPException(status_code=404, detail="Prospect not found")
+    
+    if prospect.status != "ready_for_handoff":
+        raise HTTPException(status_code=400, 
+                          detail=f"Prospect not ready for handoff (status: {prospect.status})")
+    
+    # Get thread
+    email_client = mcp.get_email_client()
+    thread = None
+    if prospect.thread_id:
+        thread = await email_client.get_thread(prospect.id)
+    
+    # Get calendar slots
+    calendar_client = mcp.get_calendar_client()
+    slots = await calendar_client.suggest_slots()
+    
+    packet = HandoffPacket(
+        prospect=prospect,
+        thread=thread,
+        calendar_slots=slots,
+        generated_at=datetime.utcnow()
+    )
+    
+    return packet.dict()
+
+@app.post("/reset")
+async def reset_system():
+    """Clear store, reload seeds, rebuild FAISS"""
+    store = mcp.get_store_client()
+    
+    # Clear all data
+    await store.clear_all()
+    
+    # Reload seed companies
+    import json
+    from app.config import COMPANIES_FILE
+    
+    with open(COMPANIES_FILE) as f:
+        companies = json.load(f)
+    
+    for company_data in companies:
+        await store.save_company(company_data)
+    
+    # Rebuild vector index
+    vector_store.rebuild_index()
+    
+    return {
+        "status": "reset_complete",
+        "companies_loaded": len(companies),
+        "timestamp": datetime.utcnow().isoformat()
+    }
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

app/orchestrator.py

@@ -0,0 +1,230 @@
+# file: app/orchestrator.py
+import asyncio
+from typing import List, AsyncGenerator, Optional
+from app.schema import Prospect, PipelineEvent, Company
+from app.logging_utils import log_event, logger
+from agents import (
+    Hunter, Enricher, Contactor, Scorer, 
+    Writer, Compliance, Sequencer, Curator
+)
+from mcp.registry import MCPRegistry
+
+class Orchestrator:
+    def __init__(self):
+        self.mcp = MCPRegistry()
+        self.hunter = Hunter(self.mcp)
+        self.enricher = Enricher(self.mcp)
+        self.contactor = Contactor(self.mcp)
+        self.scorer = Scorer(self.mcp)
+        self.writer = Writer(self.mcp)
+        self.compliance = Compliance(self.mcp)
+        self.sequencer = Sequencer(self.mcp)
+        self.curator = Curator(self.mcp)
+    
+    async def run_pipeline(
+        self,
+        company_ids: Optional[List[str]] = None,
+        company_names: Optional[List[str]] = None,
+        use_seed_file: bool = False
+    ) -> AsyncGenerator[dict, None]:
+        """
+        Run the full pipeline with streaming events and detailed MCP tracking
+
+        Args:
+            company_ids: Legacy mode - company IDs from seed file
+            company_names: Dynamic mode - company names to discover
+            use_seed_file: Force legacy mode with seed file
+        """
+
+        # Hunter phase
+        if company_names and not use_seed_file:
+            yield log_event("hunter", "Starting dynamic company discovery", "agent_start")
+            yield log_event("hunter", f"Discovering {len(company_names)} companies via web search", "mcp_call",
+                           {"mcp_server": "web_search", "method": "discover_companies", "count": len(company_names)})
+
+            prospects = await self.hunter.run(company_names=company_names, use_seed_file=False)
+
+            yield log_event("hunter", f"Discovered {len(prospects)} companies from web search", "mcp_response",
+                           {"mcp_server": "web_search", "companies_discovered": len(prospects)})
+        else:
+            yield log_event("hunter", "Starting prospect discovery (legacy mode)", "agent_start")
+            yield log_event("hunter", "Calling MCP Store to load seed companies", "mcp_call",
+                           {"mcp_server": "store", "method": "load_companies"})
+
+            prospects = await self.hunter.run(company_ids=company_ids, use_seed_file=True)
+        
+        yield log_event("hunter", f"MCP Store returned {len(prospects)} companies", "mcp_response",
+                       {"mcp_server": "store", "companies_count": len(prospects)})
+        yield log_event("hunter", f"Found {len(prospects)} prospects", "agent_end", 
+                       {"count": len(prospects)})
+        
+        for prospect in prospects:
+            try:
+                company_name = prospect.company.name
+                
+                # Enricher phase
+                yield log_event("enricher", f"Enriching {company_name}", "agent_start")
+                yield log_event("enricher", f"Calling MCP Search for company facts", "mcp_call",
+                               {"mcp_server": "search", "company": company_name})
+                
+                prospect = await self.enricher.run(prospect)
+                
+                yield log_event("enricher", f"MCP Search returned facts", "mcp_response",
+                               {"mcp_server": "search", "facts_found": len(prospect.facts)})
+                yield log_event("enricher", f"Calling MCP Store to save {len(prospect.facts)} facts", "mcp_call",
+                               {"mcp_server": "store", "method": "save_facts"})
+                yield log_event("enricher", f"Added {len(prospect.facts)} facts", "agent_end",
+                               {"facts_count": len(prospect.facts)})
+                
+                # Contactor phase
+                yield log_event("contactor", f"Finding contacts for {company_name}", "agent_start")
+                yield log_event("contactor", f"Calling MCP Store to check suppressions", "mcp_call",
+                               {"mcp_server": "store", "method": "check_suppression", "domain": prospect.company.domain})
+                
+                # Check suppression
+                store = self.mcp.get_store_client()
+                suppressed = await store.check_suppression("domain", prospect.company.domain)
+                
+                if suppressed:
+                    yield log_event("contactor", f"Domain {prospect.company.domain} is suppressed", "mcp_response",
+                                   {"mcp_server": "store", "suppressed": True})
+                else:
+                    yield log_event("contactor", f"Domain {prospect.company.domain} is not suppressed", "mcp_response",
+                                   {"mcp_server": "store", "suppressed": False})
+                
+                prospect = await self.contactor.run(prospect)
+                
+                if prospect.contacts:
+                    yield log_event("contactor", f"Calling MCP Store to save {len(prospect.contacts)} contacts", "mcp_call",
+                                   {"mcp_server": "store", "method": "save_contacts"})
+                
+                yield log_event("contactor", f"Found {len(prospect.contacts)} contacts", "agent_end",
+                               {"contacts_count": len(prospect.contacts)})
+                
+                # Scorer phase
+                yield log_event("scorer", f"Scoring {company_name}", "agent_start")
+                yield log_event("scorer", "Calculating fit score based on industry, size, and pain points", "agent_log")
+                
+                prospect = await self.scorer.run(prospect)
+                
+                yield log_event("scorer", f"Calling MCP Store to save prospect with score", "mcp_call",
+                               {"mcp_server": "store", "method": "save_prospect", "fit_score": prospect.fit_score})
+                yield log_event("scorer", f"Fit score: {prospect.fit_score:.2f}", "agent_end",
+                               {"fit_score": prospect.fit_score, "status": prospect.status})
+                
+                if prospect.status == "dropped":
+                    yield log_event("scorer", f"Dropped: {prospect.dropped_reason}", "agent_log",
+                                   {"reason": prospect.dropped_reason})
+                    continue
+                
+                # Writer phase with streaming
+                yield log_event("writer", f"Drafting outreach for {company_name}", "agent_start")
+                yield log_event("writer", "Calling Vector Store for relevant facts", "mcp_call",
+                               {"mcp_server": "vector", "method": "retrieve", "company_id": prospect.company.id})
+                yield log_event("writer", "Calling HuggingFace Inference API for content generation", "mcp_call",
+                               {"mcp_server": "hf_inference", "model": "Qwen/Qwen2.5-7B-Instruct"})
+                
+                async for event in self.writer.run_streaming(prospect):
+                    if event["type"] == "llm_token":
+                        yield event
+                    elif event["type"] == "llm_done":
+                        yield event
+                        prospect = event["payload"]["prospect"]
+                        yield log_event("writer", "HuggingFace Inference completed generation", "mcp_response",
+                                       {"mcp_server": "hf_inference", "has_summary": bool(prospect.summary),
+                                        "has_email": bool(prospect.email_draft)})
+                
+                yield log_event("writer", f"Calling MCP Store to save draft", "mcp_call",
+                               {"mcp_server": "store", "method": "save_prospect"})
+                yield log_event("writer", "Draft complete", "agent_end",
+                               {"has_summary": bool(prospect.summary),
+                                "has_email": bool(prospect.email_draft)})
+                
+                # Compliance phase
+                yield log_event("compliance", f"Checking compliance for {company_name}", "agent_start")
+                yield log_event("compliance", "Calling MCP Store to check email/domain suppressions", "mcp_call",
+                               {"mcp_server": "store", "method": "check_suppression"})
+                
+                # Check each contact for suppression
+                for contact in prospect.contacts:
+                    email_suppressed = await store.check_suppression("email", contact.email)
+                    if email_suppressed:
+                        yield log_event("compliance", f"Email {contact.email} is suppressed", "mcp_response",
+                                       {"mcp_server": "store", "suppressed": True})
+                
+                yield log_event("compliance", "Checking CAN-SPAM, PECR, CASL requirements", "agent_log")
+                
+                prospect = await self.compliance.run(prospect)
+                
+                if prospect.status == "blocked":
+                    yield log_event("compliance", f"Blocked: {prospect.dropped_reason}", "policy_block",
+                                   {"reason": prospect.dropped_reason})
+                    continue
+                else:
+                    yield log_event("compliance", "All compliance checks passed", "policy_pass")
+                    yield log_event("compliance", "Footer appended to email", "agent_log")
+                
+                # Sequencer phase
+                yield log_event("sequencer", f"Sequencing outreach for {company_name}", "agent_start")
+                
+                if not prospect.contacts or not prospect.email_draft:
+                    yield log_event("sequencer", "Missing contacts or email draft", "agent_log",
+                                   {"has_contacts": bool(prospect.contacts),
+                                    "has_email": bool(prospect.email_draft)})
+                    prospect.status = "blocked"
+                    prospect.dropped_reason = "No contacts or email draft available"
+                    await store.save_prospect(prospect)
+                    yield log_event("sequencer", f"Blocked: {prospect.dropped_reason}", "agent_end")
+                    continue
+                
+                yield log_event("sequencer", "Calling MCP Calendar for available slots", "mcp_call",
+                               {"mcp_server": "calendar", "method": "suggest_slots"})
+                
+                calendar = self.mcp.get_calendar_client()
+                slots = await calendar.suggest_slots()
+                
+                yield log_event("sequencer", f"MCP Calendar returned {len(slots)} slots", "mcp_response",
+                               {"mcp_server": "calendar", "slots_count": len(slots)})
+                
+                if slots:
+                    yield log_event("sequencer", "Calling MCP Calendar to generate ICS", "mcp_call",
+                                   {"mcp_server": "calendar", "method": "generate_ics"})
+                
+                yield log_event("sequencer", f"Calling MCP Email to send to {prospect.contacts[0].email}", "mcp_call",
+                               {"mcp_server": "email", "method": "send", "recipient": prospect.contacts[0].email})
+                
+                prospect = await self.sequencer.run(prospect)
+                
+                yield log_event("sequencer", f"MCP Email created thread", "mcp_response",
+                               {"mcp_server": "email", "thread_id": prospect.thread_id})
+                yield log_event("sequencer", f"Thread created: {prospect.thread_id}", "agent_end",
+                               {"thread_id": prospect.thread_id})
+                
+                # Curator phase
+                yield log_event("curator", f"Creating handoff for {company_name}", "agent_start")
+                yield log_event("curator", "Calling MCP Email to retrieve thread", "mcp_call",
+                               {"mcp_server": "email", "method": "get_thread", "prospect_id": prospect.id})
+                
+                email_client = self.mcp.get_email_client()
+                thread = await email_client.get_thread(prospect.id) if prospect.thread_id else None
+                
+                if thread:
+                    yield log_event("curator", f"MCP Email returned thread with messages", "mcp_response",
+                                   {"mcp_server": "email", "has_thread": True})
+                
+                yield log_event("curator", "Calling MCP Calendar for meeting slots", "mcp_call",
+                               {"mcp_server": "calendar", "method": "suggest_slots"})
+                
+                prospect = await self.curator.run(prospect)
+                
+                yield log_event("curator", "Calling MCP Store to save handoff packet", "mcp_call",
+                               {"mcp_server": "store", "method": "save_handoff"})
+                yield log_event("curator", "Handoff packet created and saved", "mcp_response",
+                               {"mcp_server": "store", "saved": True})
+                yield log_event("curator", "Handoff ready", "agent_end",
+                               {"prospect_id": prospect.id, "status": "ready_for_handoff"})
+                
+            except Exception as e:
+                logger.error(f"Pipeline error for {prospect.company.name}: {e}")
+                yield log_event("orchestrator", f"Error: {str(e)}", "agent_log",
+                               {"error": str(e), "prospect_id": prospect.id})

app/schema.py

@@ -0,0 +1,90 @@
+# file: app/schema.py
+from datetime import datetime
+from typing import List, Optional, Dict, Any
+from pydantic import BaseModel, Field, EmailStr
+
+class Company(BaseModel):
+    id: Optional[str] = None  # Auto-generated if not provided
+    name: str
+    domain: str
+    industry: str
+    size: Optional[str] = None  # Changed to string to accept "500-1000 employees" format
+    pains: List[str] = []
+    notes: List[str] = []
+    summary: Optional[str] = None
+
+class Contact(BaseModel):
+    id: str
+    name: str
+    email: EmailStr
+    title: str
+    prospect_id: str
+
+class Fact(BaseModel):
+    id: str
+    source: str
+    text: str
+    collected_at: datetime
+    ttl_hours: int
+    confidence: float
+    company_id: str
+
+class Prospect(BaseModel):
+    id: str
+    company: Company
+    contacts: List[Contact] = []
+    facts: List[Fact] = []
+    fit_score: float = 0.0
+    status: str = "new"  # new, enriched, scored, drafted, compliant, sequenced, ready_for_handoff, dropped
+    dropped_reason: Optional[str] = None
+    summary: Optional[str] = None
+    email_draft: Optional[Dict[str, str]] = None
+    thread_id: Optional[str] = None
+
+class Message(BaseModel):
+    id: str
+    thread_id: str
+    prospect_id: str
+    direction: str  # outbound, inbound
+    subject: str
+    body: str
+    sent_at: datetime
+
+class Thread(BaseModel):
+    id: str
+    prospect_id: str
+    messages: List[Message] = []
+
+class Suppression(BaseModel):
+    id: str
+    type: str  # email, domain, company
+    value: str
+    reason: str
+    expires_at: Optional[datetime] = None
+
+class HandoffPacket(BaseModel):
+    prospect: Prospect
+    thread: Optional[Thread]
+    calendar_slots: List[Dict[str, str]] = []
+    generated_at: datetime
+
+class PipelineEvent(BaseModel):
+    ts: datetime
+    type: str  # agent_start, agent_log, agent_end, llm_token, llm_done, policy_block, policy_pass
+    agent: str
+    message: str
+    payload: Dict[str, Any] = {}
+
+class PipelineRequest(BaseModel):
+    """
+    Pipeline request supporting both dynamic and static modes
+
+    NEW: company_names - List of company names to discover dynamically
+    LEGACY: company_ids - List of company IDs from seed file (backwards compatible)
+    """
+    company_names: Optional[List[str]] = None  # NEW: Dynamic discovery mode
+    company_ids: Optional[List[str]] = None     # LEGACY: Static mode
+    use_seed_file: bool = False                 # Force legacy mode
+
+class WriterStreamRequest(BaseModel):
+    company_id: str

app_mcp_autonomous.py

@@ -0,0 +1,242 @@
+"""
+CX AI Agent - Autonomous MCP Demo
+
+This is the PROPER MCP implementation where:
+- AI (Claude 3.5 Sonnet) autonomously calls MCP tools
+- NO hardcoded workflow
+- AI decides which tools to use and when
+- Full Model Context Protocol demonstration
+
+Perfect for MCP hackathon!
+"""
+
+import os
+import gradio as gr
+import asyncio
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# Set in-memory MCP mode for HF Spaces
+os.environ["USE_IN_MEMORY_MCP"] = "true"
+
+from mcp.registry import get_mcp_registry
+from mcp.agents.autonomous_agent import AutonomousMCPAgent
+
+
+# Initialize MCP registry
+mcp_registry = get_mcp_registry()
+
+
+async def run_autonomous_agent(task: str, api_key: str):
+    """
+    Run the autonomous AI agent with MCP tool calling.
+
+    Args:
+        task: The task for the AI to complete autonomously
+        api_key: Anthropic API key for Claude
+
+    Yields:
+        Progress updates from the agent
+    """
+
+    if not api_key:
+        yield "❌ Error: Please provide an Anthropic API key"
+        return
+
+    if not task:
+        yield "❌ Error: Please provide a task description"
+        return
+
+    # Create autonomous agent
+    try:
+        agent = AutonomousMCPAgent(mcp_registry=mcp_registry, api_key=api_key)
+    except Exception as e:
+        yield f"❌ Error initializing agent: {str(e)}"
+        return
+
+    # Run agent autonomously
+    output_text = ""
+
+    try:
+        async for event in agent.run(task, max_iterations=15):
+            event_type = event.get("type")
+            message = event.get("message", "")
+
+            # Format the message based on event type
+            if event_type == "agent_start":
+                output_text += f"\n{'='*60}\n"
+                output_text += f"{message}\n"
+                output_text += f"Model: {event.get('model')}\n"
+                output_text += f"{'='*60}\n\n"
+
+            elif event_type == "iteration_start":
+                output_text += f"\n{message}\n"
+
+            elif event_type == "tool_call":
+                tool = event.get("tool")
+                tool_input = event.get("input", {})
+                output_text += f"\n{message}\n"
+                output_text += f"  Input: {tool_input}\n"
+
+            elif event_type == "tool_result":
+                tool = event.get("tool")
+                result = event.get("result", {})
+                output_text += f"{message}\n"
+
+                # Show some result details
+                if isinstance(result, dict):
+                    if "count" in result:
+                        output_text += f"  → Returned {result['count']} items\n"
+                    elif "status" in result:
+                        output_text += f"  → Status: {result['status']}\n"
+
+            elif event_type == "tool_error":
+                tool = event.get("tool")
+                error = event.get("error")
+                output_text += f"\n{message}\n"
+                output_text += f"  Error: {error}\n"
+
+            elif event_type == "agent_complete":
+                final_response = event.get("final_response", "")
+                iterations = event.get("iterations", 0)
+                output_text += f"\n{'='*60}\n"
+                output_text += f"{message}\n"
+                output_text += f"Iterations: {iterations}\n"
+                output_text += f"{'='*60}\n\n"
+                output_text += f"**Final Response:**\n\n{final_response}\n"
+
+            elif event_type == "agent_error":
+                error = event.get("error")
+                output_text += f"\n{message}\n"
+                output_text += f"Error: {error}\n"
+
+            elif event_type == "agent_max_iterations":
+                iterations = event.get("iterations", 0)
+                output_text += f"\n{message}\n"
+
+            yield output_text
+
+    except Exception as e:
+        output_text += f"\n\n❌ Agent execution failed: {str(e)}\n"
+        yield output_text
+
+
+def create_demo():
+    """Create Gradio demo interface"""
+
+    with gr.Blocks(title="CX AI Agent - Autonomous MCP Demo", theme=gr.themes.Soft()) as demo:
+        gr.Markdown("""
+        # 🤖 CX AI Agent - Autonomous MCP Demo
+
+        This demo shows **true AI-driven MCP usage** where Claude 3.5 Sonnet:
+        - ✅ Autonomously decides which MCP tools to call
+        - ✅ Uses Model Context Protocol servers (Search, Store, Email, Calendar)
+        - ✅ NO hardcoded workflow - AI makes all decisions
+        - ✅ Proper MCP protocol implementation
+
+        ## Available MCP Tools:
+        - 🔍 **Search**: Web search, news search
+        - 💾 **Store**: Save/retrieve prospects, companies, contacts, facts
+        - 📧 **Email**: Send emails, track threads
+        - 📅 **Calendar**: Suggest meeting times, generate invites
+
+        ## Example Tasks:
+        - "Research Shopify and determine if they're a good B2B prospect"
+        - "Find 3 e-commerce companies and save them as prospects"
+        - "Create a personalized outreach campaign for Stripe"
+        - "Find recent news about AI startups and save as facts"
+        """)
+
+        with gr.Row():
+            with gr.Column():
+                api_key_input = gr.Textbox(
+                    label="Anthropic API Key",
+                    type="password",
+                    placeholder="sk-ant-...",
+                    info="Required for Claude 3.5 Sonnet (get one at console.anthropic.com)"
+                )
+
+                task_input = gr.Textbox(
+                    label="Task for AI Agent",
+                    placeholder="Research Shopify and create a prospect profile with facts",
+                    lines=3,
+                    info="Describe what you want the AI to do autonomously"
+                )
+
+                # Example tasks dropdown
+                example_tasks = gr.Dropdown(
+                    label="Example Tasks (click to use)",
+                    choices=[
+                        "Research Shopify and determine if they're a good B2B SaaS prospect",
+                        "Find recent news about Stripe and save as facts in the database",
+                        "Create a prospect profile for Notion including company info and facts",
+                        "Search for B2B SaaS companies in the e-commerce space and save top 3 prospects",
+                        "Research Figma's recent product launches and save relevant facts",
+                    ],
+                    interactive=True
+                )
+
+                def use_example(example):
+                    return example
+
+                example_tasks.change(fn=use_example, inputs=[example_tasks], outputs=[task_input])
+
+                run_btn = gr.Button("🚀 Run Autonomous Agent", variant="primary", size="lg")
+
+            with gr.Column():
+                output = gr.Textbox(
+                    label="Agent Progress & Results",
+                    lines=25,
+                    max_lines=50,
+                    show_copy_button=True
+                )
+
+        run_btn.click(
+            fn=run_autonomous_agent,
+            inputs=[task_input, api_key_input],
+            outputs=[output]
+        )
+
+        gr.Markdown("""
+        ## 🎯 How It Works
+
+        1. **You provide a task** - Tell the AI what you want to accomplish
+        2. **AI analyzes the task** - Claude understands what needs to be done
+        3. **AI decides which tools to use** - Autonomously chooses MCP tools
+        4. **AI executes tools** - Calls MCP servers (search, store, email, calendar)
+        5. **AI continues until complete** - Keeps working until task is done
+
+        ## 🏆 True MCP Implementation
+
+        This is **NOT** a hardcoded workflow! The AI:
+        - ✅ Decides which tools to call based on context
+        - ✅ Adapts to new information
+        - ✅ Can call tools in any order
+        - ✅ Reasons about what information it needs
+        - ✅ Stores data for later use
+
+        ## 💡 Tips
+
+        - Be specific about what you want
+        - The AI can search, save data, and reason about prospects
+        - Try multi-step tasks to see autonomous decision-making
+        - Check the progress log to see which tools the AI chooses
+
+        ---
+
+        **Powered by:** Claude 3.5 Sonnet + Model Context Protocol (MCP)
+        """)
+
+    return demo
+
+
+if __name__ == "__main__":
+    demo = create_demo()
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        show_error=True
+    )

assets/.gitkeep

@@ -0,0 +1 @@
+

check_api_keys.py

@@ -0,0 +1,73 @@
+"""
+Quick diagnostic to check if API keys are accessible
+"""
+import os
+from dotenv import load_dotenv
+
+# Load .env file
+load_dotenv()
+
+print("=" * 80)
+print("API KEY DIAGNOSTIC CHECK")
+print("=" * 80)
+print()
+
+# Check SERPER_API_KEY
+serper_key = os.getenv('SERPER_API_KEY')
+print(f"SERPER_API_KEY: {'✓ FOUND' if serper_key else '✗ NOT FOUND'}")
+if serper_key:
+    print(f"  Value: {serper_key[:10]}..." if len(serper_key) > 10 else f"  Value: {serper_key}")
+    print(f"  Length: {len(serper_key)} characters")
+else:
+    print("  ⚠ This key is REQUIRED for real contact discovery!")
+    print("  Get it from: https://serper.dev")
+
+print()
+
+# Check HF_API_TOKEN
+hf_token = os.getenv('HF_API_TOKEN')
+print(f"HF_API_TOKEN: {'✓ FOUND' if hf_token else '✗ NOT FOUND'}")
+if hf_token:
+    print(f"  Value: {hf_token[:10]}..." if len(hf_token) > 10 else f"  Value: {hf_token}")
+    print(f"  Length: {len(hf_token)} characters")
+else:
+    print("  ⚠ This key is needed for AI email generation")
+
+print()
+
+# Check if running in HF Space
+space_id = os.getenv('SPACE_ID')
+space_author = os.getenv('SPACE_AUTHOR_NAME')
+if space_id or space_author:
+    print(f"🚀 Running in HuggingFace Space")
+    print(f"   Space ID: {space_id}")
+    print(f"   Author: {space_author}")
+    print()
+    print("NOTE: In HF Spaces, secrets should be set in:")
+    print("  Settings → Repository secrets")
+    print("  Then restart the Space for changes to take effect")
+else:
+    print("💻 Running locally")
+    print()
+    print("For local development, create a .env file with:")
+    print("  SERPER_API_KEY=your-key-here")
+    print("  HF_API_TOKEN=your-token-here")
+
+print()
+print("=" * 80)
+
+# Test web search service
+print("\nTesting WebSearchService initialization...")
+try:
+    from services.web_search import get_search_service
+    search = get_search_service()
+    if search.api_key:
+        print("✓ WebSearchService initialized with API key")
+    else:
+        print("✗ WebSearchService initialized WITHOUT API key")
+        print("  Web search will fail!")
+except Exception as e:
+    print(f"✗ Error initializing WebSearchService: {e}")
+
+print()
+print("=" * 80)

create_branding_images.py

@@ -0,0 +1,130 @@
+"""
+Create placeholder branding images for OmniFlow CX
+These are simple placeholder images that can be replaced with professional designs
+"""
+from PIL import Image, ImageDraw, ImageFont
+import os
+
+def create_logo():
+    """Create Logo.png - App logo"""
+    width, height = 400, 120
+    img = Image.new('RGB', (width, height), color='#1e3a8a')  # Dark blue
+    draw = ImageDraw.Draw(img)
+
+    # Try to use a nice font, fallback to default
+    try:
+        font = ImageFont.truetype("arial.ttf", 48)
+        small_font = ImageFont.truetype("arial.ttf", 20)
+    except:
+        font = ImageFont.load_default()
+        small_font = ImageFont.load_default()
+
+    # Draw wave emoji and text
+    text = "🌊 OmniFlow CX"
+    bbox = draw.textbbox((0, 0), text, font=font)
+    text_width = bbox[2] - bbox[0]
+    text_height = bbox[3] - bbox[1]
+    x = (width - text_width) / 2
+    y = (height - text_height) / 2 - 10
+
+    draw.text((x, y), text, fill='white', font=font)
+
+    # Subtitle
+    subtitle = "MCP-Powered B2B Sales Automation"
+    bbox2 = draw.textbbox((0, 0), subtitle, font=small_font)
+    text_width2 = bbox2[2] - bbox2[0]
+    x2 = (width - text_width2) / 2
+
+    draw.text((x2, y + 60), subtitle, fill='#93c5fd', font=small_font)  # Light blue
+
+    img.save('Logo.png')
+    print("[OK] Created Logo.png")
+
+def create_banner():
+    """Create Banner.png - Banner image"""
+    width, height = 1200, 300
+    img = Image.new('RGB', (width, height), color='#0f172a')  # Very dark blue
+    draw = ImageDraw.Draw(img)
+
+    try:
+        font = ImageFont.truetype("arial.ttf", 72)
+        subtitle_font = ImageFont.truetype("arial.ttf", 32)
+    except:
+        font = ImageFont.load_default()
+        subtitle_font = ImageFont.load_default()
+
+    # Main title
+    text = "🌊 OmniFlow CX"
+    bbox = draw.textbbox((0, 0), text, font=font)
+    text_width = bbox[2] - bbox[0]
+    x = (width - text_width) / 2
+
+    draw.text((x, 60), text, fill='white', font=font)
+
+    # Subtitle
+    subtitle = "Intelligent B2B Sales Automation • Model Context Protocol"
+    bbox2 = draw.textbbox((0, 0), subtitle, font=subtitle_font)
+    text_width2 = bbox2[2] - bbox2[0]
+    x2 = (width - text_width2) / 2
+
+    draw.text((x2, 160), subtitle, fill='#60a5fa', font=subtitle_font)
+
+    # Bottom text
+    bottom_text = "🏆 Hugging Face + Anthropic MCP Hackathon 2024"
+    try:
+        bottom_font = ImageFont.truetype("arial.ttf", 24)
+    except:
+        bottom_font = ImageFont.load_default()
+    bbox3 = draw.textbbox((0, 0), bottom_text, font=bottom_font)
+    text_width3 = bbox3[2] - bbox3[0]
+    x3 = (width - text_width3) / 2
+
+    draw.text((x3, 230), bottom_text, fill='#fbbf24', font=bottom_font)  # Yellow
+
+    img.save('Banner.png')
+    print("[OK] Created Banner.png")
+
+def create_ai_chatbot_logo():
+    """Create AI_chatbot_logo.png - AI assistant avatar"""
+    width, height = 200, 200
+    img = Image.new('RGBA', (width, height), color=(30, 58, 138, 255))  # Dark blue with transparency
+    draw = ImageDraw.Draw(img)
+
+    # Draw a circle
+    draw.ellipse([20, 20, 180, 180], fill='#3b82f6', outline='white', width=4)
+
+    try:
+        font = ImageFont.truetype("arial.ttf", 80)
+    except:
+        font = ImageFont.load_default()
+
+    # Robot emoji
+    text = "🤖"
+    bbox = draw.textbbox((0, 0), text, font=font)
+    text_width = bbox[2] - bbox[0]
+    text_height = bbox[3] - bbox[1]
+    x = (width - text_width) / 2
+    y = (height - text_height) / 2
+
+    draw.text((x, y), text, font=font)
+
+    img.save('AI_chatbot_logo.png')
+    print("[OK] Created AI_chatbot_logo.png")
+
+if __name__ == "__main__":
+    print("Creating OmniFlow CX branding images...")
+    print()
+
+    create_logo()
+    create_banner()
+    create_ai_chatbot_logo()
+
+    print()
+    print("[SUCCESS] All branding images created successfully!")
+    print()
+    print("Images created:")
+    print("  - Logo.png (400x120) - Main application logo")
+    print("  - Banner.png (1200x300) - Header banner")
+    print("  - AI_chatbot_logo.png (200x200) - AI assistant avatar")
+    print()
+    print("These are placeholder images. Replace with professional designs for production.")

data/companies.json

@@ -0,0 +1,56 @@
+[
+  {
+    "id": "acme",
+    "name": "Acme Corporation",
+    "domain": "acme.com",
+    "industry": "SaaS",
+    "size": 500,
+    "pains": [
+      "Low NPS scores in enterprise segment",
+      "Customer churn increasing 15% YoY",
+      "Support ticket volume overwhelming team",
+      "No unified view of customer journey"
+    ],
+    "notes": [
+      "Recently raised Series C funding",
+      "Expanding into European market",
+      "Current support stack is fragmented"
+    ]
+  },
+  {
+    "id": "techcorp",
+    "name": "TechCorp Industries",
+    "domain": "techcorp.io",
+    "industry": "FinTech",
+    "size": 1200,
+    "pains": [
+      "Regulatory compliance for customer communications",
+      "Multi-channel support inconsistency",
+      "Customer onboarding takes too long",
+      "Poor personalization in customer interactions"
+    ],
+    "notes": [
+      "IPO planned for next year",
+      "Heavy investment in AI initiatives",
+      "Customer base growing 40% annually"
+    ]
+  },
+  {
+    "id": "retailplus",
+    "name": "RetailPlus",
+    "domain": "retailplus.com",
+    "industry": "E-commerce",
+    "size": 300,
+    "pains": [
+      "Seasonal support spikes unmanageable",
+      "Customer retention below industry average",
+      "No proactive customer engagement",
+      "Reviews and feedback not actionable"
+    ],
+    "notes": [
+      "Omnichannel retail strategy",
+      "Looking to improve post-purchase experience",
+      "Current NPS score is 42"
+    ]
+  }
+]

data/companies_store.json

@@ -0,0 +1,56 @@
+[
+  {
+    "id": "acme",
+    "name": "Acme Corporation",
+    "domain": "acme.com",
+    "industry": "SaaS",
+    "size": 500,
+    "pains": [
+      "Low NPS scores in enterprise segment",
+      "Customer churn increasing 15% YoY",
+      "Support ticket volume overwhelming team",
+      "No unified view of customer journey"
+    ],
+    "notes": [
+      "Recently raised Series C funding",
+      "Expanding into European market",
+      "Current support stack is fragmented"
+    ]
+  },
+  {
+    "id": "techcorp",
+    "name": "TechCorp Industries",
+    "domain": "techcorp.io",
+    "industry": "FinTech",
+    "size": 1200,
+    "pains": [
+      "Regulatory compliance for customer communications",
+      "Multi-channel support inconsistency",
+      "Customer onboarding takes too long",
+      "Poor personalization in customer interactions"
+    ],
+    "notes": [
+      "IPO planned for next year",
+      "Heavy investment in AI initiatives",
+      "Customer base growing 40% annually"
+    ]
+  },
+  {
+    "id": "retailplus",
+    "name": "RetailPlus",
+    "domain": "retailplus.com",
+    "industry": "E-commerce",
+    "size": 300,
+    "pains": [
+      "Seasonal support spikes unmanageable",
+      "Customer retention below industry average",
+      "No proactive customer engagement",
+      "Reviews and feedback not actionable"
+    ],
+    "notes": [
+      "Omnichannel retail strategy",
+      "Looking to improve post-purchase experience",
+      "Current NPS score is 42"
+    ]
+  }
+]

data/contacts.json

@@ -0,0 +1 @@
+[]

data/facts.json

@@ -0,0 +1 @@
+[]

data/footer.txt

@@ -0,0 +1,9 @@
+
+---
+Lucidya Inc.
+Prince Turki Bin Abdulaziz Al Awwal Rd
+Al Mohammadiyyah, Riyadh 12362
+Saudi Arabia
+
+This email was sent by Lucidya's AI-powered outreach system.
+To opt out of future communications, click here: https://lucidya.com/unsubscribe

data/handoffs.json

@@ -0,0 +1 @@
+[]

data/prospects.json

@@ -0,0 +1 @@
+[]

data/suppression.json

@@ -0,0 +1,16 @@
+[
+  {
+    "id": "supp-001",
+    "type": "domain",
+    "value": "competitor.com",
+    "reason": "Competitor - do not contact",
+    "expires_at": null
+  },
+  {
+    "id": "supp-002",
+    "type": "email",
+    "value": "[email protected]",
+    "reason": "Bounced email",
+    "expires_at": "2024-12-31T23:59:59Z"
+  }
+]

database/manager.py

@@ -0,0 +1,297 @@
+"""
+Database Manager for B2B Sales AI Agent
+Handles database initialization, migrations, and session management
+"""
+from sqlalchemy import create_engine, event
+from sqlalchemy.orm import sessionmaker, scoped_session
+from sqlalchemy.pool import StaticPool
+import os
+import logging
+from pathlib import Path
+from contextlib import contextmanager
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseManager:
+    """
+    Manages SQLite database connections and sessions
+    """
+
+    def __init__(self, db_path: str = None):
+        """
+        Initialize database manager
+
+        Args:
+            db_path: Path to SQLite database file
+        """
+        if db_path is None:
+            # Default to data/cx_agent.db
+            # For HuggingFace Spaces, try /data first (persistent), fallback to /tmp
+            default_path = os.getenv('DATABASE_PATH', './data/cx_agent.db')
+
+            # Check if we're on HuggingFace Spaces
+            if os.path.exists('/data'):
+                # HF Spaces with persistent storage
+                default_path = '/data/cx_agent.db'
+            elif os.path.exists('/tmp'):
+                # Fallback to tmp if data dir not available
+                default_path = '/tmp/cx_agent.db'
+
+            db_path = default_path
+
+        self.db_path = db_path
+        self.engine = None
+        self.Session = None
+
+    def initialize(self):
+        """Initialize database connection and create tables"""
+        try:
+            print(f"📂 Initializing database at: {self.db_path}")
+            logger.info(f"Initializing database at: {self.db_path}")
+
+            # Ensure data directory exists
+            db_dir = Path(self.db_path).parent
+            db_dir.mkdir(parents=True, exist_ok=True)
+            print(f"📁 Database directory: {db_dir}")
+            logger.info(f"Database directory created/verified: {db_dir}")
+
+            # Create engine
+            self.engine = create_engine(
+                f'sqlite:///{self.db_path}',
+                connect_args={'check_same_thread': False},
+                poolclass=StaticPool,
+                echo=False  # Set to True for SQL debugging
+            )
+
+            # Enable foreign keys for SQLite
+            @event.listens_for(self.engine, "connect")
+            def set_sqlite_pragma(dbapi_conn, connection_record):
+                cursor = dbapi_conn.cursor()
+                cursor.execute("PRAGMA foreign_keys=ON")
+                cursor.close()
+
+            # Create session factory
+            # expire_on_commit=False keeps objects accessible after commit
+            session_factory = sessionmaker(bind=self.engine, expire_on_commit=False)
+            self.Session = scoped_session(session_factory)
+
+            # Import models and create tables
+            try:
+                from models.database import Base as EnterpriseBase
+                EnterpriseBase.metadata.create_all(self.engine)
+                print("✅ Enterprise tables created")
+                logger.info("Enterprise tables created")
+            except ImportError as e:
+                print(f"⚠️  Could not import enterprise models: {e}")
+                logger.warning(f"Could not import enterprise models: {e}")
+
+            logger.info(f"Database initialized at {self.db_path}")
+
+            # Initialize with default data
+            self._initialize_default_data()
+
+            return True
+
+        except Exception as e:
+            logger.error(f"Failed to initialize database: {str(e)}")
+            raise
+
+    def _initialize_default_data(self):
+        """Insert default data for new databases"""
+        try:
+            from models.database import Setting, Sequence, SequenceEmail, Template
+
+            session = self.Session()
+
+            # Check if already initialized
+            existing_settings = session.query(Setting).first()
+            if existing_settings:
+                session.close()
+                return
+
+            # Default settings
+            default_settings = [
+                Setting(key='company_name', value='Your Company', description='Company name for email footers'),
+                Setting(key='company_address', value='123 Main St, City, State 12345', description='Physical address for CAN-SPAM compliance'),
+                Setting(key='sender_name', value='Sales Team', description='Default sender name'),
+                Setting(key='sender_email', value='[email protected]', description='Default sender email'),
+                Setting(key='daily_email_limit', value='1000', description='Max emails per day'),
+                Setting(key='enable_tracking', value='1', description='Enable email tracking'),
+            ]
+            session.add_all(default_settings)
+
+            # Default sequence template: Cold Outreach (3-touch)
+            cold_outreach = Sequence(
+                name='Cold Outreach - 3 Touch',
+                description='Standard 3-email cold outreach sequence',
+                category='outbound',
+                is_template=True
+            )
+            session.add(cold_outreach)
+            session.flush()
+
+            sequence_emails = [
+                SequenceEmail(
+                    sequence_id=cold_outreach.id,
+                    step_number=1,
+                    wait_days=0,
+                    subject='Quick question about {{company_name}}',
+                    body='''Hi {{first_name}},
+
+I noticed {{company_name}} is in the {{industry}} space with {{company_size}} employees.
+
+Companies like yours often face challenges with {{pain_points}}.
+
+We've helped similar companies reduce support costs by 35% and improve customer satisfaction significantly.
+
+Would you be open to a brief 15-minute call to explore if we might be able to help?
+
+Best regards,
+{{sender_name}}'''
+                ),
+                SequenceEmail(
+                    sequence_id=cold_outreach.id,
+                    step_number=2,
+                    wait_days=3,
+                    subject='Re: Quick question about {{company_name}}',
+                    body='''Hi {{first_name}},
+
+I wanted to follow up on my previous email. I understand you're busy, so I'll keep this brief.
+
+We recently helped a company similar to {{company_name}} achieve:
+• 40% reduction in support ticket volume
+• 25% improvement in customer satisfaction scores
+• 30% faster response times
+
+I'd love to share how we did it. Are you available for a quick call this week?
+
+Best,
+{{sender_name}}'''
+                ),
+                SequenceEmail(
+                    sequence_id=cold_outreach.id,
+                    step_number=3,
+                    wait_days=7,
+                    subject='Last attempt - {{company_name}}',
+                    body='''Hi {{first_name}},
+
+This is my last attempt to reach you. I completely understand if now isn't the right time.
+
+If you're interested in learning how we can help {{company_name}} improve customer experience, I'm happy to send over some quick resources.
+
+Otherwise, I'll assume this isn't a priority right now and won't bother you again.
+
+Thanks for your time,
+{{sender_name}}
+
+P.S. If you'd prefer to be removed from my list, just reply "Not interested" and I'll make sure you don't hear from me again.'''
+                ),
+            ]
+            session.add_all(sequence_emails)
+
+            # Default email templates
+            templates = [
+                Template(
+                    name='Meeting Request',
+                    category='meeting_request',
+                    subject='Meeting invitation - {{company_name}}',
+                    body='''Hi {{first_name}},
+
+Thank you for your interest! I'd love to schedule a call to discuss how we can help {{company_name}}.
+
+Here are a few time slots that work for me:
+• {{time_slot_1}}
+• {{time_slot_2}}
+• {{time_slot_3}}
+
+Let me know which works best for you, or feel free to suggest another time.
+
+Looking forward to speaking with you!
+
+Best,
+{{sender_name}}''',
+                    variables='["first_name", "company_name", "time_slot_1", "time_slot_2", "time_slot_3", "sender_name"]'
+                ),
+                Template(
+                    name='Follow-up After Meeting',
+                    category='follow_up',
+                    subject='Great speaking with you, {{first_name}}',
+                    body='''Hi {{first_name}},
+
+Thanks for taking the time to speak with me today about {{company_name}}'s customer experience goals.
+
+As discussed, here are the next steps:
+• {{next_step_1}}
+• {{next_step_2}}
+
+I'll follow up on {{follow_up_date}} as we agreed.
+
+Please don't hesitate to reach out if you have any questions in the meantime.
+
+Best regards,
+{{sender_name}}''',
+                    variables='["first_name", "company_name", "next_step_1", "next_step_2", "follow_up_date", "sender_name"]'
+                ),
+            ]
+            session.add_all(templates)
+
+            session.commit()
+            session.close()
+
+            logger.info("Default data initialized successfully")
+
+        except Exception as e:
+            logger.error(f"Failed to initialize default data: {str(e)}")
+            if session:
+                session.rollback()
+                session.close()
+
+
+    @contextmanager
+    def get_session(self):
+        """
+        Context manager for database sessions
+
+        Usage:
+            with db_manager.get_session() as session:
+                session.query(Contact).all()
+        """
+        session = self.Session()
+        try:
+            yield session
+            session.commit()
+        except Exception:
+            session.rollback()
+            raise
+        finally:
+            session.close()
+
+    def close(self):
+        """Close database connection"""
+        if self.Session:
+            self.Session.remove()
+        if self.engine:
+            self.engine.dispose()
+        logger.info("Database connection closed")
+
+
+# Global database manager instance
+_db_manager = None
+
+
+def get_db_manager() -> DatabaseManager:
+    """Get or create global database manager instance"""
+    global _db_manager
+    if _db_manager is None:
+        _db_manager = DatabaseManager()
+        _db_manager.initialize()
+    return _db_manager
+
+
+def init_database(db_path: str = None):
+    """Initialize database with custom path"""
+    global _db_manager
+    _db_manager = DatabaseManager(db_path)
+    _db_manager.initialize()
+    return _db_manager

database/schema.sql

@@ -0,0 +1,358 @@
+-- CX AI Agent - Enterprise Database Schema
+-- SQLite Schema for Campaign Management, Contact Tracking, and Analytics
+
+-- =============================================================================
+-- COMPANIES
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS 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 array
+    website TEXT,
+    linkedin_url TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_companies_domain ON companies(domain);
+CREATE INDEX idx_companies_industry ON companies(industry);
+
+-- =============================================================================
+-- CONTACTS
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS 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,
+    department TEXT,
+    seniority_level TEXT, -- C-Level, VP, Director, Manager, Individual Contributor
+    linkedin_url TEXT,
+    twitter_url TEXT,
+    location TEXT,
+    timezone TEXT,
+
+    -- Scoring
+    fit_score REAL DEFAULT 0.0,
+    engagement_score REAL DEFAULT 0.0,
+    intent_score REAL DEFAULT 0.0,
+    overall_score REAL DEFAULT 0.0,
+
+    -- Status & Lifecycle
+    status TEXT DEFAULT 'new', -- new, contacted, responded, meeting_scheduled, qualified, lost, customer
+    lifecycle_stage TEXT DEFAULT 'lead', -- lead, mql, sql, opportunity, customer, churned
+
+    -- Tracking
+    source TEXT, -- discovery_agent, manual_import, api, referral
+    first_contacted_at TIMESTAMP,
+    last_contacted_at TIMESTAMP,
+    last_activity_at TIMESTAMP,
+
+    -- Metadata
+    tags TEXT, -- JSON array
+    notes TEXT,
+    custom_fields TEXT, -- JSON object for extensibility
+    is_suppressed BOOLEAN DEFAULT 0,
+    suppression_reason TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (company_id) REFERENCES companies(id) ON DELETE SET NULL
+);
+
+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_contacts_lifecycle_stage ON contacts(lifecycle_stage);
+CREATE INDEX idx_contacts_overall_score ON contacts(overall_score);
+
+-- =============================================================================
+-- CAMPAIGNS
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS campaigns (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    description TEXT,
+    status TEXT DEFAULT 'draft', -- draft, active, paused, completed, archived
+
+    -- Targeting
+    target_industries TEXT, -- JSON array
+    target_company_sizes TEXT, -- JSON array
+    target_locations TEXT, -- JSON array
+    target_job_titles TEXT, -- JSON array
+
+    -- Configuration
+    sequence_id INTEGER,
+    goal_contacts INTEGER,
+    goal_response_rate REAL,
+    goal_meetings INTEGER,
+
+    -- Tracking
+    contacts_discovered INTEGER DEFAULT 0,
+    contacts_enriched INTEGER DEFAULT 0,
+    contacts_scored INTEGER DEFAULT 0,
+    contacts_contacted INTEGER DEFAULT 0,
+    contacts_responded INTEGER DEFAULT 0,
+    meetings_booked INTEGER DEFAULT 0,
+
+    -- Dates
+    started_at TIMESTAMP,
+    completed_at TIMESTAMP,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    created_by TEXT,
+
+    FOREIGN KEY (sequence_id) REFERENCES sequences(id) ON DELETE SET NULL
+);
+
+CREATE INDEX idx_campaigns_status ON campaigns(status);
+
+-- =============================================================================
+-- CAMPAIGN CONTACTS (Many-to-Many with Stage Tracking)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS campaign_contacts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    campaign_id INTEGER NOT NULL,
+    contact_id INTEGER NOT NULL,
+    stage TEXT DEFAULT 'discovery', -- discovery, enrichment, scoring, outreach, responded, meeting, closed_won, closed_lost
+    stage_updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    notes TEXT,
+
+    FOREIGN KEY (campaign_id) REFERENCES campaigns(id) ON DELETE CASCADE,
+    FOREIGN KEY (contact_id) REFERENCES contacts(id) ON DELETE CASCADE,
+    UNIQUE(campaign_id, contact_id)
+);
+
+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_campaign_contacts_stage ON campaign_contacts(stage);
+
+-- =============================================================================
+-- EMAIL SEQUENCES
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS sequences (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    description TEXT,
+    category TEXT DEFAULT 'outbound', -- outbound, nurture, re-engagement
+    is_active BOOLEAN DEFAULT 1,
+    is_template BOOLEAN DEFAULT 0,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    created_by TEXT
+);
+
+-- =============================================================================
+-- SEQUENCE EMAILS (Steps in a sequence)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS sequence_emails (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    sequence_id INTEGER NOT NULL,
+    step_number INTEGER NOT NULL,
+    wait_days INTEGER DEFAULT 0, -- Days to wait after previous email
+    subject TEXT NOT NULL,
+    body TEXT NOT NULL,
+    send_time_preference TEXT, -- morning, afternoon, evening, or specific time
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (sequence_id) REFERENCES sequences(id) ON DELETE CASCADE,
+    UNIQUE(sequence_id, step_number)
+);
+
+CREATE INDEX idx_sequence_emails_sequence ON sequence_emails(sequence_id);
+
+-- =============================================================================
+-- EMAIL ACTIVITIES (Tracking email interactions)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS email_activities (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    contact_id INTEGER NOT NULL,
+    campaign_id INTEGER,
+    sequence_email_id INTEGER,
+    type TEXT NOT NULL, -- sent, delivered, opened, clicked, replied, bounced, unsubscribed, complained
+    subject TEXT,
+    preview TEXT,
+    link_url TEXT, -- For click tracking
+    meta_data TEXT, -- JSON for additional data
+    occurred_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (contact_id) REFERENCES contacts(id) ON DELETE CASCADE,
+    FOREIGN KEY (campaign_id) REFERENCES campaigns(id) ON DELETE SET NULL,
+    FOREIGN KEY (sequence_email_id) REFERENCES sequence_emails(id) ON DELETE SET NULL
+);
+
+CREATE INDEX idx_email_activities_contact ON email_activities(contact_id);
+CREATE INDEX idx_email_activities_campaign ON email_activities(campaign_id);
+CREATE INDEX idx_email_activities_type ON email_activities(type);
+CREATE INDEX idx_email_activities_occurred ON email_activities(occurred_at);
+
+-- =============================================================================
+-- MEETINGS
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS meetings (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    contact_id INTEGER NOT NULL,
+    campaign_id INTEGER,
+    title TEXT NOT NULL,
+    description TEXT,
+    scheduled_at TIMESTAMP NOT NULL,
+    duration_minutes INTEGER DEFAULT 30,
+    meeting_url TEXT,
+    location TEXT,
+    status TEXT DEFAULT 'scheduled', -- scheduled, completed, cancelled, no_show, rescheduled
+    outcome TEXT, -- interested, not_interested, needs_follow_up, closed_won
+    notes TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (contact_id) REFERENCES contacts(id) ON DELETE CASCADE,
+    FOREIGN KEY (campaign_id) REFERENCES campaigns(id) ON DELETE SET NULL
+);
+
+CREATE INDEX idx_meetings_contact ON meetings(contact_id);
+CREATE INDEX idx_meetings_campaign ON meetings(campaign_id);
+CREATE INDEX idx_meetings_scheduled ON meetings(scheduled_at);
+CREATE INDEX idx_meetings_status ON meetings(status);
+
+-- =============================================================================
+-- ACTIVITIES (General activity log)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS activities (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    contact_id INTEGER,
+    campaign_id INTEGER,
+    meeting_id INTEGER,
+    type TEXT NOT NULL, -- discovery, enrichment, email_sent, email_opened, reply_received, meeting_scheduled, meeting_completed, note_added, status_changed
+    description TEXT,
+    meta_data TEXT, -- JSON for additional context
+    performed_by TEXT, -- agent_name or 'user'
+    occurred_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (contact_id) REFERENCES contacts(id) ON DELETE CASCADE,
+    FOREIGN KEY (campaign_id) REFERENCES campaigns(id) ON DELETE SET NULL,
+    FOREIGN KEY (meeting_id) REFERENCES meetings(id) ON DELETE SET NULL
+);
+
+CREATE INDEX idx_activities_contact ON activities(contact_id);
+CREATE INDEX idx_activities_campaign ON activities(campaign_id);
+CREATE INDEX idx_activities_type ON activities(type);
+CREATE INDEX idx_activities_occurred ON activities(occurred_at);
+
+-- =============================================================================
+-- AB TESTS (for email sequences)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS ab_tests (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    campaign_id INTEGER NOT NULL,
+    sequence_id INTEGER NOT NULL,
+    name TEXT NOT NULL,
+    description TEXT,
+    test_type TEXT NOT NULL, -- subject_line, body, send_time, from_name
+    variant_a TEXT NOT NULL, -- JSON configuration
+    variant_b TEXT NOT NULL, -- JSON configuration
+    winner TEXT, -- 'a', 'b', or null if test ongoing
+    status TEXT DEFAULT 'running', -- running, completed, cancelled
+    started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    completed_at TIMESTAMP,
+
+    FOREIGN KEY (campaign_id) REFERENCES campaigns(id) ON DELETE CASCADE,
+    FOREIGN KEY (sequence_id) REFERENCES sequences(id) ON DELETE CASCADE
+);
+
+-- =============================================================================
+-- AB TEST RESULTS
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS ab_test_results (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ab_test_id INTEGER NOT NULL,
+    variant TEXT NOT NULL, -- 'a' or 'b'
+    emails_sent INTEGER DEFAULT 0,
+    emails_delivered INTEGER DEFAULT 0,
+    emails_opened INTEGER DEFAULT 0,
+    emails_clicked INTEGER DEFAULT 0,
+    emails_replied INTEGER DEFAULT 0,
+    meetings_booked INTEGER DEFAULT 0,
+
+    FOREIGN KEY (ab_test_id) REFERENCES ab_tests(id) ON DELETE CASCADE,
+    UNIQUE(ab_test_id, variant)
+);
+
+-- =============================================================================
+-- TEMPLATES (Email templates)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS templates (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    category TEXT, -- cold_outreach, follow_up, meeting_request, thank_you
+    subject TEXT NOT NULL,
+    body TEXT NOT NULL,
+    variables TEXT, -- JSON array of variable names
+    is_active BOOLEAN DEFAULT 1,
+    usage_count INTEGER DEFAULT 0,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- =============================================================================
+-- ANALYTICS SNAPSHOTS (Daily/hourly aggregated metrics)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS analytics_snapshots (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    campaign_id INTEGER,
+    date DATE NOT NULL,
+    hour INTEGER, -- null for daily snapshots
+
+    -- Metrics
+    contacts_discovered INTEGER DEFAULT 0,
+    contacts_enriched INTEGER DEFAULT 0,
+    emails_sent INTEGER DEFAULT 0,
+    emails_opened INTEGER DEFAULT 0,
+    emails_clicked INTEGER DEFAULT 0,
+    emails_replied INTEGER DEFAULT 0,
+    meetings_booked INTEGER DEFAULT 0,
+
+    -- Rates
+    open_rate REAL DEFAULT 0.0,
+    click_rate REAL DEFAULT 0.0,
+    response_rate REAL DEFAULT 0.0,
+    meeting_rate REAL DEFAULT 0.0,
+
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (campaign_id) REFERENCES campaigns(id) ON DELETE CASCADE,
+    UNIQUE(campaign_id, date, hour)
+);
+
+CREATE INDEX idx_analytics_campaign ON analytics_snapshots(campaign_id);
+CREATE INDEX idx_analytics_date ON analytics_snapshots(date);
+
+-- =============================================================================
+-- SETTINGS (Application configuration)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS settings (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    description TEXT,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Insert default settings
+INSERT OR IGNORE INTO settings (key, value, description) VALUES
+    ('company_name', 'Your Company', 'Company name for email footers'),
+    ('company_address', '123 Main St, City, State 12345', 'Physical address for CAN-SPAM compliance'),
+    ('sender_name', 'Sales Team', 'Default sender name for emails'),
+    ('sender_email', '[email protected]', 'Default sender email'),
+    ('daily_email_limit', '1000', 'Maximum emails to send per day'),
+    ('enable_tracking', '1', 'Enable email open and click tracking'),
+    ('auto_pause_on_low_score', '1', 'Automatically pause contacts with low engagement'),
+    ('min_engagement_score', '0.3', 'Minimum engagement score before auto-pause');

database/schema_extended.sql

@@ -0,0 +1,472 @@
+-- CX Platform - Extended Database Schema
+-- Adds tickets, knowledge base, chat, and customer interaction tracking
+
+-- =============================================================================
+-- CUSTOMERS (Enhanced from contacts)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_customers (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    email TEXT UNIQUE NOT NULL,
+    first_name TEXT,
+    last_name TEXT,
+    company TEXT,
+    phone TEXT,
+
+    -- Segmentation
+    segment TEXT DEFAULT 'standard', -- vip, standard, at_risk, churned
+    lifecycle_stage TEXT DEFAULT 'active', -- new, active, at_risk, churned
+
+    -- Metrics
+    lifetime_value REAL DEFAULT 0.0,
+    satisfaction_score REAL DEFAULT 0.0, -- CSAT average
+    nps_score INTEGER, -- Net Promoter Score
+    sentiment TEXT DEFAULT 'neutral', -- positive, neutral, negative
+
+    -- Tracking
+    first_interaction_at TIMESTAMP,
+    last_interaction_at TIMESTAMP,
+    total_interactions INTEGER DEFAULT 0,
+    total_tickets INTEGER DEFAULT 0,
+
+    -- Metadata
+    tags TEXT, -- JSON array
+    custom_fields TEXT, -- JSON object
+    notes TEXT,
+
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_cx_customers_email ON cx_customers(email);
+CREATE INDEX idx_cx_customers_segment ON cx_customers(segment);
+CREATE INDEX idx_cx_customers_sentiment ON cx_customers(sentiment);
+
+-- =============================================================================
+-- TICKETS
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_tickets (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    customer_id INTEGER NOT NULL,
+
+    -- Core fields
+    subject TEXT NOT NULL,
+    description TEXT,
+    status TEXT DEFAULT 'new', -- new, open, pending, resolved, closed
+    priority TEXT DEFAULT 'medium', -- low, medium, high, urgent
+    category TEXT, -- technical, billing, feature_request, etc.
+
+    -- Assignment
+    assigned_to TEXT, -- agent name/id
+    assigned_team TEXT,
+
+    -- SLA
+    sla_due_at TIMESTAMP,
+    first_response_at TIMESTAMP,
+    resolved_at TIMESTAMP,
+    closed_at TIMESTAMP,
+
+    -- Metrics
+    response_time_minutes INTEGER,
+    resolution_time_minutes INTEGER,
+    reopened_count INTEGER DEFAULT 0,
+
+    -- AI fields
+    sentiment TEXT, -- detected from description
+    ai_suggested_category TEXT,
+    ai_confidence REAL,
+    auto_resolved BOOLEAN DEFAULT 0,
+
+    -- Metadata
+    source TEXT DEFAULT 'manual', -- manual, email, chat, api, web_form
+    tags TEXT, -- JSON array
+    custom_fields TEXT, -- JSON
+
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (customer_id) REFERENCES cx_customers(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_cx_tickets_customer ON cx_tickets(customer_id);
+CREATE INDEX idx_cx_tickets_status ON cx_tickets(status);
+CREATE INDEX idx_cx_tickets_priority ON cx_tickets(priority);
+CREATE INDEX idx_cx_tickets_assigned_to ON cx_tickets(assigned_to);
+CREATE INDEX idx_cx_tickets_sla_due ON cx_tickets(sla_due_at);
+
+-- =============================================================================
+-- TICKET MESSAGES
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_ticket_messages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ticket_id INTEGER NOT NULL,
+
+    -- Sender
+    sender_type TEXT NOT NULL, -- customer, agent, system, ai_bot
+    sender_id TEXT, -- customer_id, agent_id, or 'system'
+    sender_name TEXT,
+
+    -- Message
+    message TEXT NOT NULL,
+    message_html TEXT,
+    is_internal BOOLEAN DEFAULT 0, -- internal note vs customer-visible
+
+    -- AI fields
+    sentiment TEXT,
+    intent TEXT, -- question, complaint, praise, feedback
+
+    -- Metadata
+    meta_data TEXT, -- JSON
+
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (ticket_id) REFERENCES cx_tickets(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_cx_ticket_messages_ticket ON cx_ticket_messages(ticket_id);
+CREATE INDEX idx_cx_ticket_messages_created ON cx_ticket_messages(created_at);
+
+-- =============================================================================
+-- TICKET ATTACHMENTS
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_ticket_attachments (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ticket_id INTEGER NOT NULL,
+    message_id INTEGER,
+
+    filename TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    file_size INTEGER,
+    mime_type TEXT,
+
+    uploaded_by TEXT,
+    uploaded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (ticket_id) REFERENCES cx_tickets(id) ON DELETE CASCADE,
+    FOREIGN KEY (message_id) REFERENCES cx_ticket_messages(id) ON DELETE SET NULL
+);
+
+-- =============================================================================
+-- KNOWLEDGE BASE
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_kb_categories (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    description TEXT,
+    parent_id INTEGER,
+    display_order INTEGER DEFAULT 0,
+    icon TEXT,
+
+    is_active BOOLEAN DEFAULT 1,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (parent_id) REFERENCES cx_kb_categories(id) ON DELETE SET NULL
+);
+
+CREATE TABLE IF NOT EXISTS cx_kb_articles (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    category_id INTEGER,
+
+    -- Content
+    title TEXT NOT NULL,
+    summary TEXT,
+    content TEXT NOT NULL,
+    content_html TEXT,
+
+    -- Status
+    status TEXT DEFAULT 'draft', -- draft, published, archived
+    visibility TEXT DEFAULT 'public', -- public, internal, private
+
+    -- SEO
+    slug TEXT UNIQUE,
+    meta_description TEXT,
+
+    -- Metrics
+    view_count INTEGER DEFAULT 0,
+    helpful_count INTEGER DEFAULT 0,
+    not_helpful_count INTEGER DEFAULT 0,
+    average_rating REAL DEFAULT 0.0,
+
+    -- AI fields
+    ai_generated BOOLEAN DEFAULT 0,
+    ai_confidence REAL,
+    keywords TEXT, -- JSON array for semantic search
+
+    -- Versioning
+    version INTEGER DEFAULT 1,
+
+    -- Metadata
+    tags TEXT, -- JSON array
+    related_articles TEXT, -- JSON array of article IDs
+
+    -- Authoring
+    author TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    published_at TIMESTAMP,
+
+    FOREIGN KEY (category_id) REFERENCES cx_kb_categories(id) ON DELETE SET NULL
+);
+
+CREATE INDEX idx_cx_kb_articles_category ON cx_kb_articles(category_id);
+CREATE INDEX idx_cx_kb_articles_status ON cx_kb_articles(status);
+CREATE INDEX idx_cx_kb_articles_slug ON cx_kb_articles(slug);
+
+-- =============================================================================
+-- KB ARTICLE VERSIONS
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_kb_article_versions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    article_id INTEGER NOT NULL,
+
+    version INTEGER NOT NULL,
+    title TEXT NOT NULL,
+    content TEXT NOT NULL,
+
+    changed_by TEXT,
+    change_note TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (article_id) REFERENCES cx_kb_articles(id) ON DELETE CASCADE,
+    UNIQUE(article_id, version)
+);
+
+-- =============================================================================
+-- LIVE CHAT SESSIONS
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_chat_sessions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    customer_id INTEGER,
+
+    -- Session info
+    session_id TEXT UNIQUE NOT NULL,
+    status TEXT DEFAULT 'active', -- active, waiting, assigned, closed
+
+    -- Routing
+    assigned_to TEXT, -- agent name/id
+    assigned_at TIMESTAMP,
+
+    -- AI bot
+    bot_active BOOLEAN DEFAULT 1,
+    bot_handed_off BOOLEAN DEFAULT 0,
+    bot_handoff_reason TEXT,
+
+    -- Metrics
+    wait_time_seconds INTEGER DEFAULT 0,
+    response_time_seconds INTEGER DEFAULT 0,
+    message_count INTEGER DEFAULT 0,
+
+    -- Metadata
+    page_url TEXT,
+    referrer TEXT,
+    user_agent TEXT,
+    ip_address TEXT,
+
+    -- Satisfaction
+    rated BOOLEAN DEFAULT 0,
+    rating INTEGER,
+    feedback TEXT,
+
+    started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    ended_at TIMESTAMP,
+
+    FOREIGN KEY (customer_id) REFERENCES cx_customers(id) ON DELETE SET NULL
+);
+
+CREATE INDEX idx_cx_chat_sessions_customer ON cx_chat_sessions(customer_id);
+CREATE INDEX idx_cx_chat_sessions_status ON cx_chat_sessions(status);
+CREATE INDEX idx_cx_chat_sessions_assigned_to ON cx_chat_sessions(assigned_to);
+
+-- =============================================================================
+-- CHAT MESSAGES
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_chat_messages (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    session_id INTEGER NOT NULL,
+
+    -- Sender
+    sender_type TEXT NOT NULL, -- customer, agent, bot, system
+    sender_id TEXT,
+    sender_name TEXT,
+
+    -- Message
+    message TEXT NOT NULL,
+    message_type TEXT DEFAULT 'text', -- text, image, file, system_message
+
+    -- AI fields
+    is_bot_response BOOLEAN DEFAULT 0,
+    bot_confidence REAL,
+    intent TEXT,
+
+    -- Status
+    is_read BOOLEAN DEFAULT 0,
+    read_at TIMESTAMP,
+
+    -- Metadata
+    meta_data TEXT, -- JSON
+
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (session_id) REFERENCES cx_chat_sessions(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_cx_chat_messages_session ON cx_chat_messages(session_id);
+CREATE INDEX idx_cx_chat_messages_created ON cx_chat_messages(created_at);
+
+-- =============================================================================
+-- AUTOMATION RULES
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_automation_rules (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+
+    name TEXT NOT NULL,
+    description TEXT,
+    is_active BOOLEAN DEFAULT 1,
+
+    -- Trigger
+    trigger_type TEXT NOT NULL, -- ticket_created, ticket_updated, time_based, etc.
+    trigger_conditions TEXT NOT NULL, -- JSON
+
+    -- Actions
+    actions TEXT NOT NULL, -- JSON array of actions
+
+    -- Execution
+    execution_count INTEGER DEFAULT 0,
+    last_executed_at TIMESTAMP,
+
+    -- Priority
+    priority INTEGER DEFAULT 0,
+
+    created_by TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- =============================================================================
+-- CUSTOMER INTERACTIONS
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_interactions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    customer_id INTEGER NOT NULL,
+
+    type TEXT NOT NULL, -- ticket, chat, email, call, meeting
+    channel TEXT, -- web, email, phone, chat, api
+
+    summary TEXT,
+    sentiment TEXT,
+    intent TEXT,
+
+    -- References
+    reference_type TEXT, -- ticket, chat_session, email, etc.
+    reference_id INTEGER,
+
+    -- Metrics
+    duration_seconds INTEGER,
+    satisfaction_rating INTEGER,
+
+    -- Agent
+    handled_by TEXT,
+
+    occurred_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    FOREIGN KEY (customer_id) REFERENCES cx_customers(id) ON DELETE CASCADE
+);
+
+CREATE INDEX idx_cx_interactions_customer ON cx_interactions(customer_id);
+CREATE INDEX idx_cx_interactions_type ON cx_interactions(type);
+CREATE INDEX idx_cx_interactions_occurred ON cx_interactions(occurred_at);
+
+-- =============================================================================
+-- ANALYTICS SNAPSHOTS (Enhanced)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_analytics_daily (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    date DATE NOT NULL UNIQUE,
+
+    -- Ticket metrics
+    tickets_created INTEGER DEFAULT 0,
+    tickets_resolved INTEGER DEFAULT 0,
+    tickets_reopened INTEGER DEFAULT 0,
+    avg_resolution_time_minutes REAL DEFAULT 0.0,
+    avg_first_response_minutes REAL DEFAULT 0.0,
+
+    -- Chat metrics
+    chats_started INTEGER DEFAULT 0,
+    chats_completed INTEGER DEFAULT 0,
+    avg_wait_time_seconds REAL DEFAULT 0.0,
+    bot_resolution_rate REAL DEFAULT 0.0,
+
+    -- Satisfaction
+    avg_csat REAL DEFAULT 0.0,
+    avg_nps INTEGER DEFAULT 0,
+
+    -- KB metrics
+    kb_views INTEGER DEFAULT 0,
+    kb_helpful_votes INTEGER DEFAULT 0,
+    kb_searches INTEGER DEFAULT 0,
+
+    -- Sentiment
+    positive_interactions INTEGER DEFAULT 0,
+    neutral_interactions INTEGER DEFAULT 0,
+    negative_interactions INTEGER DEFAULT 0,
+
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX idx_cx_analytics_daily_date ON cx_analytics_daily(date);
+
+-- =============================================================================
+-- CANNED RESPONSES (Templates)
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_canned_responses (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+
+    name TEXT NOT NULL,
+    shortcut TEXT UNIQUE, -- e.g., "/greeting"
+    category TEXT,
+
+    subject TEXT,
+    content TEXT NOT NULL,
+
+    -- Usage
+    use_count INTEGER DEFAULT 0,
+    last_used_at TIMESTAMP,
+
+    is_active BOOLEAN DEFAULT 1,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- =============================================================================
+-- AGENT PERFORMANCE
+-- =============================================================================
+CREATE TABLE IF NOT EXISTS cx_agent_stats (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    agent_id TEXT NOT NULL,
+    agent_name TEXT NOT NULL,
+    date DATE NOT NULL,
+
+    -- Tickets
+    tickets_handled INTEGER DEFAULT 0,
+    tickets_resolved INTEGER DEFAULT 0,
+    avg_resolution_time_minutes REAL DEFAULT 0.0,
+
+    -- Chats
+    chats_handled INTEGER DEFAULT 0,
+    avg_chat_duration_minutes REAL DEFAULT 0.0,
+
+    -- Quality
+    avg_csat REAL DEFAULT 0.0,
+    positive_feedbacks INTEGER DEFAULT 0,
+    negative_feedbacks INTEGER DEFAULT 0,
+
+    -- Efficiency
+    avg_response_time_minutes REAL DEFAULT 0.0,
+    first_contact_resolutions INTEGER DEFAULT 0,
+
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+
+    UNIQUE(agent_id, date)
+);
+
+CREATE INDEX idx_cx_agent_stats_agent ON cx_agent_stats(agent_id);
+CREATE INDEX idx_cx_agent_stats_date ON cx_agent_stats(date);

mcp/__init__.py

@@ -0,0 +1,2 @@
+# file: mcp/__init__.py
+"""Model Context Protocol implementation"""

mcp/agents/autonomous_agent.py

@@ -0,0 +1,413 @@
+"""
+Autonomous AI Agent with MCP Tool Calling
+
+This agent uses Claude 3.5 Sonnet (or compatible LLM) to autonomously
+decide which MCP tools to call based on the user's task.
+
+This is TRUE AI-driven MCP usage - no hardcoded workflow!
+"""
+
+import os
+import json
+import uuid
+import logging
+from typing import List, Dict, Any, AsyncGenerator
+from anthropic import AsyncAnthropic
+
+from mcp.tools.definitions import MCP_TOOLS
+from mcp.registry import MCPRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class AutonomousMCPAgent:
+    """
+    AI Agent that autonomously uses MCP servers as tools.
+
+    Key Features:
+    - Uses Claude 3.5 Sonnet for tool calling
+    - Autonomously decides which MCP tools to use
+    - No hardcoded workflow - AI makes all decisions
+    - Proper MCP protocol implementation
+    """
+
+    def __init__(self, mcp_registry: MCPRegistry, api_key: str = None):
+        """
+        Initialize the autonomous agent
+
+        Args:
+            mcp_registry: MCP registry with all servers
+            api_key: Anthropic API key (or use ANTHROPIC_API_KEY env var)
+        """
+        self.mcp_registry = mcp_registry
+        self.api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
+
+        if not self.api_key:
+            raise ValueError(
+                "Anthropic API key required for autonomous agent. "
+                "Set ANTHROPIC_API_KEY environment variable or pass api_key parameter."
+            )
+
+        self.client = AsyncAnthropic(api_key=self.api_key)
+        self.model = "claude-3-5-sonnet-20241022"
+
+        # System prompt for the agent
+        self.system_prompt = """You are an autonomous AI agent for B2B sales automation.
+
+You have access to MCP (Model Context Protocol) servers that provide tools for:
+- Web search (find company information, news, insights)
+- Data storage (save prospects, companies, contacts, facts)
+- Email management (send emails, track threads)
+- Calendar (schedule meetings)
+
+Your goal is to help with B2B sales tasks like:
+- Finding and researching potential customers
+- Enriching company data with facts and insights
+- Finding decision-maker contacts
+- Drafting personalized outreach emails
+- Managing prospect pipeline
+
+IMPORTANT:
+1. Think step-by-step about what information you need
+2. Use tools autonomously to gather information
+3. Save important data to the store for persistence
+4. Be thorough in research before making recommendations
+5. Always check suppression list before suggesting email sends
+
+You should:
+- Search for company information when needed
+- Save prospects and companies to the database
+- Find and save contacts
+- Generate personalized outreach based on research
+- Track your progress and findings
+
+Work autonomously - decide which tools to use and when!"""
+
+        logger.info(f"Autonomous MCP Agent initialized with model: {self.model}")
+
+    async def run(
+        self,
+        task: str,
+        max_iterations: int = 15
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """
+        Run the agent autonomously on a task.
+
+        The agent will:
+        1. Understand the task
+        2. Decide which MCP tools to call
+        3. Execute tools autonomously
+        4. Continue until task is complete or max iterations reached
+
+        Args:
+            task: The task to complete (e.g., "Research and create outreach for Shopify")
+            max_iterations: Maximum tool calls to prevent infinite loops
+
+        Yields:
+            Events showing agent's progress and tool calls
+        """
+
+        yield {
+            "type": "agent_start",
+            "message": f"🤖 Autonomous AI Agent starting task: {task}",
+            "model": self.model
+        }
+
+        # Initialize conversation
+        messages = [
+            {
+                "role": "user",
+                "content": task
+            }
+        ]
+
+        iteration = 0
+
+        while iteration < max_iterations:
+            iteration += 1
+
+            yield {
+                "type": "iteration_start",
+                "iteration": iteration,
+                "message": f"🔄 Iteration {iteration}: AI deciding next action..."
+            }
+
+            try:
+                # Call Claude with tools
+                response = await self.client.messages.create(
+                    model=self.model,
+                    max_tokens=4096,
+                    system=self.system_prompt,
+                    messages=messages,
+                    tools=MCP_TOOLS
+                )
+
+                # Add assistant response to conversation
+                messages.append({
+                    "role": "assistant",
+                    "content": response.content
+                })
+
+                # Check if AI wants to use tools
+                tool_calls = [block for block in response.content if block.type == "tool_use"]
+
+                if not tool_calls:
+                    # AI is done - no more tools to call
+                    final_text = next(
+                        (block.text for block in response.content if hasattr(block, "text")),
+                        "Task completed!"
+                    )
+
+                    yield {
+                        "type": "agent_complete",
+                        "message": f"✅ Task complete!",
+                        "final_response": final_text,
+                        "iterations": iteration
+                    }
+                    break
+
+                # Execute tool calls
+                tool_results = []
+
+                for tool_call in tool_calls:
+                    tool_name = tool_call.name
+                    tool_input = tool_call.input
+
+                    yield {
+                        "type": "tool_call",
+                        "tool": tool_name,
+                        "input": tool_input,
+                        "message": f"🔧 AI calling tool: {tool_name}"
+                    }
+
+                    # Execute the MCP tool
+                    try:
+                        result = await self._execute_mcp_tool(tool_name, tool_input)
+
+                        yield {
+                            "type": "tool_result",
+                            "tool": tool_name,
+                            "result": result,
+                            "message": f"✓ Tool {tool_name} completed"
+                        }
+
+                        # Add tool result to conversation
+                        tool_results.append({
+                            "type": "tool_result",
+                            "tool_use_id": tool_call.id,
+                            "content": json.dumps(result, default=str)
+                        })
+
+                    except Exception as e:
+                        error_msg = str(e)
+                        logger.error(f"Tool execution failed: {tool_name} - {error_msg}")
+
+                        yield {
+                            "type": "tool_error",
+                            "tool": tool_name,
+                            "error": error_msg,
+                            "message": f"❌ Tool {tool_name} failed: {error_msg}"
+                        }
+
+                        tool_results.append({
+                            "type": "tool_result",
+                            "tool_use_id": tool_call.id,
+                            "content": json.dumps({"error": error_msg}),
+                            "is_error": True
+                        })
+
+                # Add tool results to conversation
+                messages.append({
+                    "role": "user",
+                    "content": tool_results
+                })
+
+            except Exception as e:
+                logger.error(f"Agent iteration failed: {e}")
+                yield {
+                    "type": "agent_error",
+                    "error": str(e),
+                    "message": f"❌ Agent error: {str(e)}"
+                }
+                break
+
+        if iteration >= max_iterations:
+            yield {
+                "type": "agent_max_iterations",
+                "message": f"⚠️ Reached maximum iterations ({max_iterations})",
+                "iterations": iteration
+            }
+
+    async def _execute_mcp_tool(self, tool_name: str, tool_input: Dict[str, Any]) -> Any:
+        """
+        Execute an MCP tool by routing to the appropriate MCP server.
+
+        This is where we actually call the MCP servers!
+        """
+
+        # ============ SEARCH MCP SERVER ============
+        if tool_name == "search_web":
+            query = tool_input["query"]
+            max_results = tool_input.get("max_results", 5)
+
+            results = await self.mcp_registry.search.query(query, max_results=max_results)
+            return {
+                "results": results,
+                "count": len(results)
+            }
+
+        elif tool_name == "search_news":
+            query = tool_input["query"]
+            max_results = tool_input.get("max_results", 5)
+
+            results = await self.mcp_registry.search.query(f"{query} news", max_results=max_results)
+            return {
+                "results": results,
+                "count": len(results)
+            }
+
+        # ============ STORE MCP SERVER ============
+        elif tool_name == "save_prospect":
+            prospect_data = {
+                "id": tool_input.get("prospect_id", str(uuid.uuid4())),
+                "company": {
+                    "id": tool_input.get("company_id"),
+                    "name": tool_input.get("company_name"),
+                    "domain": tool_input.get("company_domain")
+                },
+                "fit_score": tool_input.get("fit_score", 0),
+                "status": tool_input.get("status", "new"),
+                "metadata": tool_input.get("metadata", {})
+            }
+
+            result = await self.mcp_registry.store.save_prospect(prospect_data)
+            return {"status": result, "prospect_id": prospect_data["id"]}
+
+        elif tool_name == "get_prospect":
+            prospect_id = tool_input["prospect_id"]
+            prospect = await self.mcp_registry.store.get_prospect(prospect_id)
+            return prospect or {"error": "Prospect not found"}
+
+        elif tool_name == "list_prospects":
+            prospects = await self.mcp_registry.store.list_prospects()
+            status_filter = tool_input.get("status")
+
+            if status_filter:
+                prospects = [p for p in prospects if p.get("status") == status_filter]
+
+            return {
+                "prospects": prospects,
+                "count": len(prospects)
+            }
+
+        elif tool_name == "save_company":
+            company_data = {
+                "id": tool_input.get("company_id", str(uuid.uuid4())),
+                "name": tool_input["name"],
+                "domain": tool_input["domain"],
+                "industry": tool_input.get("industry"),
+                "description": tool_input.get("description"),
+                "employee_count": tool_input.get("employee_count")
+            }
+
+            result = await self.mcp_registry.store.save_company(company_data)
+            return {"status": result, "company_id": company_data["id"]}
+
+        elif tool_name == "get_company":
+            company_id = tool_input["company_id"]
+            company = await self.mcp_registry.store.get_company(company_id)
+            return company or {"error": "Company not found"}
+
+        elif tool_name == "save_fact":
+            fact_data = {
+                "id": tool_input.get("fact_id", str(uuid.uuid4())),
+                "company_id": tool_input["company_id"],
+                "fact_type": tool_input["fact_type"],
+                "content": tool_input["content"],
+                "source_url": tool_input.get("source_url"),
+                "confidence_score": tool_input.get("confidence_score", 0.8)
+            }
+
+            result = await self.mcp_registry.store.save_fact(fact_data)
+            return {"status": result, "fact_id": fact_data["id"]}
+
+        elif tool_name == "save_contact":
+            contact_data = {
+                "id": tool_input.get("contact_id", str(uuid.uuid4())),
+                "company_id": tool_input["company_id"],
+                "email": tool_input["email"],
+                "first_name": tool_input.get("first_name"),
+                "last_name": tool_input.get("last_name"),
+                "title": tool_input.get("title"),
+                "seniority": tool_input.get("seniority")
+            }
+
+            result = await self.mcp_registry.store.save_contact(contact_data)
+            return {"status": result, "contact_id": contact_data["id"]}
+
+        elif tool_name == "list_contacts_by_domain":
+            domain = tool_input["domain"]
+            contacts = await self.mcp_registry.store.list_contacts_by_domain(domain)
+            return {
+                "contacts": contacts,
+                "count": len(contacts)
+            }
+
+        elif tool_name == "check_suppression":
+            supp_type = tool_input["suppression_type"]
+            value = tool_input["value"]
+
+            is_suppressed = await self.mcp_registry.store.check_suppression(supp_type, value)
+            return {
+                "suppressed": is_suppressed,
+                "value": value,
+                "type": supp_type
+            }
+
+        # ============ EMAIL MCP SERVER ============
+        elif tool_name == "send_email":
+            to = tool_input["to"]
+            subject = tool_input["subject"]
+            body = tool_input["body"]
+            prospect_id = tool_input["prospect_id"]
+
+            thread_id = await self.mcp_registry.email.send(to, subject, body, prospect_id)
+            return {
+                "status": "sent",
+                "thread_id": thread_id,
+                "to": to
+            }
+
+        elif tool_name == "get_email_thread":
+            prospect_id = tool_input["prospect_id"]
+            thread = await self.mcp_registry.email.get_thread(prospect_id)
+            return thread or {"error": "No email thread found"}
+
+        # ============ CALENDAR MCP SERVER ============
+        elif tool_name == "suggest_meeting_slots":
+            num_slots = tool_input.get("num_slots", 3)
+            slots = await self.mcp_registry.calendar.suggest_slots()
+            return {
+                "slots": slots[:num_slots],
+                "count": len(slots[:num_slots])
+            }
+
+        elif tool_name == "generate_calendar_invite":
+            start_time = tool_input["start_time"]
+            end_time = tool_input["end_time"]
+            title = tool_input["title"]
+
+            slot = {
+                "start_iso": start_time,
+                "end_iso": end_time,
+                "title": title
+            }
+
+            ics = await self.mcp_registry.calendar.generate_ics(slot)
+            return {
+                "ics_content": ics,
+                "meeting": slot
+            }
+
+        else:
+            raise ValueError(f"Unknown MCP tool: {tool_name}")

mcp/agents/autonomous_agent_granite.py

@@ -0,0 +1,686 @@
+"""
+Autonomous AI Agent with MCP Tool Calling using Granite 4.0 H-1B (Open Source)
+
+This agent uses IBM Granite 4.0 H-1B (1.5B params) loaded locally via transformers
+to autonomously decide which MCP tools to call.
+
+Granite 4.0 H-1B is optimized for tool calling and function calling tasks.
+Uses ReAct (Reasoning + Acting) prompting pattern for reliable tool calling.
+"""
+
+import os
+import re
+import json
+import uuid
+import logging
+import asyncio
+from typing import List, Dict, Any, AsyncGenerator
+from transformers import pipeline, AutoTokenizer, AutoModelForCausalLM
+import torch
+
+from mcp.tools.definitions import MCP_TOOLS, list_all_tools
+from mcp.registry import MCPRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class AutonomousMCPAgentGranite:
+    """
+    AI Agent that autonomously uses MCP servers as tools using Granite 4.
+
+    Uses ReAct (Reasoning + Acting) pattern:
+    1. Thought: AI reasons about what to do next
+    2. Action: AI decides which tool to call
+    3. Observation: AI sees the tool result
+    4. Repeat until task complete
+    """
+
+    def __init__(self, mcp_registry: MCPRegistry, hf_token: str = None):
+        """
+        Initialize the autonomous agent with Granite 4.0 H-1B
+
+        Args:
+            mcp_registry: MCP registry with all servers
+            hf_token: HuggingFace token (optional, for accessing private models)
+        """
+        self.mcp_registry = mcp_registry
+        self.hf_token = hf_token or os.getenv("HF_API_TOKEN") or os.getenv("HF_TOKEN")
+
+        # Use Granite 4.0 H-1B (1.5B params, optimized for tool calling)
+        self.model_name = "ibm-granite/granite-4.0-h-1b"
+
+        logger.info(f"Loading Granite 4.0 H-1B model locally...")
+
+        # Load model with optimizations for CPU/limited memory
+        try:
+            logger.info(f"📥 Downloading tokenizer from {self.model_name}...")
+            # Use bfloat16 for better efficiency, float32 fallback for CPU
+            self.tokenizer = AutoTokenizer.from_pretrained(
+                self.model_name,
+                token=self.hf_token,
+                trust_remote_code=True
+            )
+            logger.info(f"✓ Tokenizer loaded successfully")
+
+            # Check device availability
+            device = "cuda" if torch.cuda.is_available() else "cpu"
+            dtype = torch.bfloat16 if torch.cuda.is_available() else torch.float32
+            logger.info(f"💻 Device: {device}, dtype: {dtype}")
+
+            logger.info(f"📥 Downloading model weights (~1.5GB)...")
+
+            # For hybrid models like Granite H-1B, we need explicit device placement
+            if torch.cuda.is_available():
+                # GPU available - use device_map
+                self.model = AutoModelForCausalLM.from_pretrained(
+                    self.model_name,
+                    token=self.hf_token,
+                    torch_dtype=dtype,
+                    device_map="auto",
+                    low_cpu_mem_usage=True,
+                    trust_remote_code=True
+                )
+            else:
+                # CPU only - load with 8-bit quantization to reduce memory
+                logger.info(f"⚠️ Loading on CPU (no GPU available)")
+                logger.info(f"💾 Using 8-bit quantization to reduce memory usage")
+
+                try:
+                    # Try loading with 8-bit quantization (requires bitsandbytes)
+                    from transformers import BitsAndBytesConfig
+
+                    quantization_config = BitsAndBytesConfig(
+                        load_in_8bit=True,
+                        llm_int8_threshold=6.0
+                    )
+
+                    self.model = AutoModelForCausalLM.from_pretrained(
+                        self.model_name,
+                        token=self.hf_token,
+                        quantization_config=quantization_config,
+                        low_cpu_mem_usage=False,
+                        trust_remote_code=True
+                    )
+                    logger.info(f"✓ Loaded with 8-bit quantization (~50% memory reduction)")
+                except (ImportError, Exception) as e:
+                    # Fallback to float32 if 8-bit fails
+                    logger.warning(f"⚠️ 8-bit quantization failed: {e}")
+                    logger.info(f"⚠️ Falling back to float32 (may use ~4-6GB RAM)")
+
+                    self.model = AutoModelForCausalLM.from_pretrained(
+                        self.model_name,
+                        token=self.hf_token,
+                        torch_dtype=torch.float32,  # Use float32 for CPU
+                        low_cpu_mem_usage=False,  # Disable to avoid meta device
+                        trust_remote_code=True
+                    )
+
+                # Verify all parameters are on CPU, not meta
+                logger.info(f"🔍 Verifying model is materialized on CPU...")
+                param_devices = set()
+                for param in self.model.parameters():
+                    param_devices.add(str(param.device))
+
+                if 'meta' in param_devices:
+                    logger.error(f"❌ Model still has parameters on meta device!")
+                    raise RuntimeError("Model not properly materialized. Try upgrading transformers: pip install --upgrade transformers")
+
+                logger.info(f"✓ All parameters on: {param_devices}")
+
+            logger.info(f"✓ Model weights loaded")
+
+            # Set model to eval mode
+            self.model.eval()
+            logger.info(f"✓ Model set to evaluation mode")
+
+            # Get model device and memory info
+            try:
+                model_device = next(self.model.parameters()).device
+                logger.info(f"✓ Model loaded successfully on device: {model_device}")
+            except StopIteration:
+                logger.warning(f"⚠️ Could not determine model device (no parameters)")
+
+            # Memory info if available
+            if torch.cuda.is_available():
+                memory_allocated = torch.cuda.memory_allocated() / 1024**3
+                logger.info(f"📊 GPU Memory allocated: {memory_allocated:.2f} GB")
+
+        except Exception as e:
+            logger.error(f"❌ Failed to load model: {e}", exc_info=True)
+            raise
+
+        # Create tool descriptions for the AI
+        self.tools_description = self._create_tools_description()
+
+        logger.info(f"Autonomous MCP Agent initialized with model: {self.model_name}")
+
+    def _generate_text(self, prompt: str) -> str:
+        """
+        Generate text using the local Granite model (synchronous, for use in executor)
+
+        Args:
+            prompt: The input prompt
+
+        Returns:
+            Generated text
+        """
+        import time
+        import gc
+        start_time = time.time()
+
+        # Force garbage collection before inference to free memory
+        gc.collect()
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+        # Tokenize input with aggressive truncation to save memory
+        logger.info(f"🔤 Tokenizing input (length: {len(prompt)} chars)...")
+        inputs = self.tokenizer(
+            prompt,
+            return_tensors="pt",
+            truncation=True,
+            max_length=2048  # Reduced from 4096 to save memory
+        )
+        num_input_tokens = inputs["input_ids"].shape[-1]
+        logger.info(f"✓ Tokenized to {num_input_tokens} tokens")
+
+        # Get target device - handle models split across devices
+        try:
+            target_device = next(self.model.parameters()).device
+        except StopIteration:
+            # Fallback if no parameters found
+            target_device = torch.device('cpu')
+
+        logger.info(f"📍 Moving inputs to device: {target_device}")
+
+        # Move to same device as model
+        inputs = {k: v.to(target_device) for k, v in inputs.items()}
+
+        # Generate with memory-efficient settings
+        logger.info(f"🤖 Generating response (max 400 tokens, temp=0.1)...")
+        with torch.no_grad():
+            outputs = self.model.generate(
+                **inputs,
+                max_new_tokens=400,  # Reduced from 800 to save memory
+                temperature=0.1,  # Low temperature for deterministic reasoning
+                top_p=0.9,
+                do_sample=True,
+                pad_token_id=self.tokenizer.eos_token_id,
+                eos_token_id=self.tokenizer.eos_token_id,
+                use_cache=True,  # Use KV cache for efficiency
+                num_beams=1,  # Greedy decoding to save memory
+            )
+
+        # Decode only the new tokens
+        response = self.tokenizer.decode(
+            outputs[0][inputs["input_ids"].shape[-1]:],
+            skip_special_tokens=True
+        )
+
+        elapsed = time.time() - start_time
+        num_output_tokens = outputs.shape[-1] - num_input_tokens
+        tokens_per_sec = num_output_tokens / elapsed if elapsed > 0 else 0
+
+        logger.info(f"✓ Generated {num_output_tokens} tokens in {elapsed:.1f}s ({tokens_per_sec:.1f} tokens/sec)")
+        logger.info(f"📝 Response preview: {response[:100]}...")
+
+        # Clean up to free memory
+        del inputs, outputs
+        gc.collect()
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+        return response
+
+    def _create_tools_description(self) -> str:
+        """Create a formatted description of all available tools for the AI"""
+        tools_text = "## Available MCP Tools:\n\n"
+
+        for tool in MCP_TOOLS:
+            tools_text += f"**{tool['name']}**\n"
+            tools_text += f"  Description: {tool['description']}\n"
+            tools_text += f"  Parameters:\n"
+
+            for prop_name, prop_data in tool['input_schema']['properties'].items():
+                required = prop_name in tool['input_schema'].get('required', [])
+                tools_text += f"    - {prop_name} ({prop_data['type']}){'*' if required else ''}: {prop_data.get('description', '')}\n"
+
+            tools_text += "\n"
+
+        return tools_text
+
+    def _create_system_prompt(self) -> str:
+        """Create the system prompt for ReAct pattern"""
+        return f"""You are an autonomous AI agent for B2B sales automation using the ReAct (Reasoning + Acting) framework.
+
+You have access to MCP (Model Context Protocol) tools that let you:
+- Search the web for company information and news
+- Save prospects, companies, contacts, and facts to a database
+- Send emails and manage email threads
+- Schedule meetings and generate calendar invites
+
+{self.tools_description}
+
+## ReAct Format:
+
+You must respond using this EXACT format:
+
+Thought: [Your reasoning about what to do next]
+Action: [tool_name]
+Action Input: {{"param1": "value1", "param2": "value2"}}
+
+After you see the Observation, you can continue with more Thought/Action/Observation cycles.
+
+When you've completed the task, respond with:
+Thought: [Your final reasoning]
+Final Answer: [Your complete response to the user]
+
+## Important Rules:
+1. Always use "Thought:" to reason before acting
+2. Always use "Action:" followed by exact tool name
+3. Always use "Action Input:" with valid JSON
+4. Use tools multiple times if needed
+5. Save important data to the database
+6. When done, give a "Final Answer:"
+
+## Example:
+
+Thought: I need to research Shopify first
+Action: search_web
+Action Input: {{"query": "Shopify company information"}}
+
+[You'll see Observation with results]
+
+Thought: Now I should save the company data
+Action: save_company
+Action Input: {{"company_id": "shopify", "name": "Shopify", "domain": "shopify.com"}}
+
+[Continue until task complete...]
+
+Thought: I've gathered all the information and saved it
+Final Answer: I've successfully researched Shopify and created a prospect profile with company information and recent facts.
+
+Now complete your assigned task!"""
+
+    async def run(
+        self,
+        task: str,
+        max_iterations: int = 15
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """
+        Run the agent autonomously on a task using ReAct pattern.
+
+        Args:
+            task: The task to complete
+            max_iterations: Maximum tool calls to prevent infinite loops
+
+        Yields:
+            Events showing agent's progress and tool calls
+        """
+
+        yield {
+            "type": "agent_start",
+            "message": f"🤖 Autonomous AI Agent (Granite 4) starting task",
+            "task": task,
+            "model": self.model
+        }
+
+        # Initialize conversation with system prompt and task
+        conversation_history = f"""{self._create_system_prompt()}
+
+## Task:
+{task}
+
+Begin!
+
+"""
+
+        iteration = 0
+
+        while iteration < max_iterations:
+            iteration += 1
+
+            yield {
+                "type": "iteration_start",
+                "iteration": iteration,
+                "message": f"🔄 Iteration {iteration}: AI reasoning..."
+            }
+
+            try:
+                # Get AI response using ReAct pattern
+                response_text = ""
+
+                try:
+                    # Generate using local model
+                    # Run in executor to avoid blocking the event loop
+                    response_text = await asyncio.get_event_loop().run_in_executor(
+                        None,
+                        self._generate_text,
+                        conversation_history
+                    )
+
+                except Exception as gen_error:
+                    logger.error(f"Text generation failed: {gen_error}", exc_info=True)
+                    yield {
+                        "type": "agent_error",
+                        "error": str(gen_error),
+                        "message": f"❌ Model error: {str(gen_error)}"
+                    }
+                    break
+
+                # Check if we got a response
+                if not response_text or not response_text.strip():
+                    logger.warning("Empty response from model")
+                    yield {
+                        "type": "parse_error",
+                        "message": "⚠️ Model returned empty response. Retrying...",
+                        "response": ""
+                    }
+                    continue
+
+                # Log the raw response for debugging
+                logger.info(f"Model response (iteration {iteration}): {response_text[:200]}...")
+
+                # Parse the response for Thought, Action, Action Input
+                thought_match = re.search(r'Thought:\s*(.+?)(?=\n(?:Action:|Final Answer:)|$)', response_text, re.DOTALL)
+                action_match = re.search(r'Action:\s*(\w+)', response_text)
+                action_input_match = re.search(r'Action Input:\s*(\{.+?\})', response_text, re.DOTALL)
+                final_answer_match = re.search(r'Final Answer:\s*(.+?)$', response_text, re.DOTALL)
+
+                # Extract thought
+                if thought_match:
+                    thought = thought_match.group(1).strip()
+                    yield {
+                        "type": "thought",
+                        "thought": thought,
+                        "message": f"💭 Thought: {thought}"
+                    }
+
+                # Check if AI wants to finish
+                if final_answer_match:
+                    final_answer = final_answer_match.group(1).strip()
+
+                    yield {
+                        "type": "agent_complete",
+                        "message": "✅ Task complete!",
+                        "final_answer": final_answer,
+                        "iterations": iteration
+                    }
+                    break
+
+                # Execute action if present
+                if action_match and action_input_match:
+                    tool_name = action_match.group(1).strip()
+                    action_input_str = action_input_match.group(1).strip()
+
+                    # Parse action input JSON
+                    try:
+                        tool_input = json.loads(action_input_str)
+                    except json.JSONDecodeError as e:
+                        error_msg = f"Invalid JSON in Action Input: {e}"
+                        logger.error(error_msg)
+
+                        # Give feedback to AI
+                        conversation_history += response_text
+                        conversation_history += f"\nObservation: Error - {error_msg}. Please provide valid JSON.\n\n"
+                        continue
+
+                    yield {
+                        "type": "tool_call",
+                        "tool": tool_name,
+                        "input": tool_input,
+                        "message": f"🔧 Action: {tool_name}"
+                    }
+
+                    # Execute the MCP tool
+                    try:
+                        result = await self._execute_mcp_tool(tool_name, tool_input)
+
+                        yield {
+                            "type": "tool_result",
+                            "tool": tool_name,
+                            "result": result,
+                            "message": f"✓ Tool {tool_name} completed"
+                        }
+
+                        # Add to conversation history
+                        conversation_history += response_text
+                        conversation_history += f"\nObservation: {json.dumps(result, default=str)}\n\n"
+
+                    except Exception as e:
+                        error_msg = str(e)
+                        logger.error(f"Tool execution failed: {tool_name} - {error_msg}")
+
+                        yield {
+                            "type": "tool_error",
+                            "tool": tool_name,
+                            "error": error_msg,
+                            "message": f"❌ Tool {tool_name} failed: {error_msg}"
+                        }
+
+                        # Give error feedback to AI
+                        conversation_history += response_text
+                        conversation_history += f"\nObservation: Error - {error_msg}\n\n"
+
+                else:
+                    # No action found - AI might be confused
+                    yield {
+                        "type": "parse_error",
+                        "message": "⚠️ Could not parse Action from AI response",
+                        "response": response_text
+                    }
+
+                    # Give feedback to AI
+                    conversation_history += response_text
+                    conversation_history += "\nObservation: Please follow the format: 'Action: tool_name' and 'Action Input: {...}'\n\n"
+
+            except (RuntimeError, StopIteration, StopAsyncIteration) as stop_err:
+                # Handle StopIteration errors that get wrapped in RuntimeError
+                error_msg = str(stop_err)
+                logger.error(f"Stop iteration in agent loop: {error_msg}", exc_info=True)
+
+                if "StopIteration" in error_msg or "StopAsyncIteration" in error_msg:
+                    yield {
+                        "type": "agent_error",
+                        "error": "Model inference error - possibly model not available or API issue",
+                        "message": f"❌ Model inference failed. Please check:\n"
+                                   f"  1. HF_API_TOKEN is valid\n"
+                                   f"  2. Model '{self.model}' is accessible\n"
+                                   f"  3. HuggingFace Inference API is operational"
+                    }
+                else:
+                    yield {
+                        "type": "agent_error",
+                        "error": error_msg,
+                        "message": f"❌ Agent error: {error_msg}"
+                    }
+                break
+            except Exception as e:
+                logger.error(f"Agent iteration failed: {e}", exc_info=True)
+                yield {
+                    "type": "agent_error",
+                    "error": str(e),
+                    "message": f"❌ Agent error: {str(e)}"
+                }
+                break
+
+        if iteration >= max_iterations:
+            yield {
+                "type": "agent_max_iterations",
+                "message": f"⚠️ Reached maximum iterations ({max_iterations})",
+                "iterations": iteration
+            }
+
+    async def _execute_mcp_tool(self, tool_name: str, tool_input: Dict[str, Any]) -> Any:
+        """
+        Execute an MCP tool by routing to the appropriate MCP server.
+
+        This is where we actually call the MCP servers!
+        """
+
+        # ============ SEARCH MCP SERVER ============
+        if tool_name == "search_web":
+            query = tool_input["query"]
+            max_results = tool_input.get("max_results", 5)
+
+            results = await self.mcp_registry.search.query(query, max_results=max_results)
+            return {
+                "results": results[:max_results],
+                "count": len(results[:max_results])
+            }
+
+        elif tool_name == "search_news":
+            query = tool_input["query"]
+            max_results = tool_input.get("max_results", 5)
+
+            results = await self.mcp_registry.search.query(f"{query} news", max_results=max_results)
+            return {
+                "results": results[:max_results],
+                "count": len(results[:max_results])
+            }
+
+        # ============ STORE MCP SERVER ============
+        elif tool_name == "save_prospect":
+            prospect_data = {
+                "id": tool_input.get("prospect_id", str(uuid.uuid4())),
+                "company": {
+                    "id": tool_input.get("company_id"),
+                    "name": tool_input.get("company_name"),
+                    "domain": tool_input.get("company_domain")
+                },
+                "fit_score": tool_input.get("fit_score", 0),
+                "status": tool_input.get("status", "new"),
+                "metadata": tool_input.get("metadata", {})
+            }
+
+            result = await self.mcp_registry.store.save_prospect(prospect_data)
+            return {"status": result, "prospect_id": prospect_data["id"]}
+
+        elif tool_name == "get_prospect":
+            prospect_id = tool_input["prospect_id"]
+            prospect = await self.mcp_registry.store.get_prospect(prospect_id)
+            return prospect or {"error": "Prospect not found"}
+
+        elif tool_name == "list_prospects":
+            prospects = await self.mcp_registry.store.list_prospects()
+            status_filter = tool_input.get("status")
+
+            if status_filter:
+                prospects = [p for p in prospects if p.get("status") == status_filter]
+
+            return {
+                "prospects": prospects,
+                "count": len(prospects)
+            }
+
+        elif tool_name == "save_company":
+            company_data = {
+                "id": tool_input.get("company_id", str(uuid.uuid4())),
+                "name": tool_input["name"],
+                "domain": tool_input["domain"],
+                "industry": tool_input.get("industry"),
+                "description": tool_input.get("description"),
+                "employee_count": tool_input.get("employee_count")
+            }
+
+            result = await self.mcp_registry.store.save_company(company_data)
+            return {"status": result, "company_id": company_data["id"]}
+
+        elif tool_name == "get_company":
+            company_id = tool_input["company_id"]
+            company = await self.mcp_registry.store.get_company(company_id)
+            return company or {"error": "Company not found"}
+
+        elif tool_name == "save_fact":
+            fact_data = {
+                "id": tool_input.get("fact_id", str(uuid.uuid4())),
+                "company_id": tool_input["company_id"],
+                "fact_type": tool_input["fact_type"],
+                "content": tool_input["content"],
+                "source_url": tool_input.get("source_url"),
+                "confidence_score": tool_input.get("confidence_score", 0.8)
+            }
+
+            result = await self.mcp_registry.store.save_fact(fact_data)
+            return {"status": result, "fact_id": fact_data["id"]}
+
+        elif tool_name == "save_contact":
+            contact_data = {
+                "id": tool_input.get("contact_id", str(uuid.uuid4())),
+                "company_id": tool_input["company_id"],
+                "email": tool_input["email"],
+                "first_name": tool_input.get("first_name"),
+                "last_name": tool_input.get("last_name"),
+                "title": tool_input.get("title"),
+                "seniority": tool_input.get("seniority")
+            }
+
+            result = await self.mcp_registry.store.save_contact(contact_data)
+            return {"status": result, "contact_id": contact_data["id"]}
+
+        elif tool_name == "list_contacts_by_domain":
+            domain = tool_input["domain"]
+            contacts = await self.mcp_registry.store.list_contacts_by_domain(domain)
+            return {
+                "contacts": contacts,
+                "count": len(contacts)
+            }
+
+        elif tool_name == "check_suppression":
+            supp_type = tool_input["suppression_type"]
+            value = tool_input["value"]
+
+            is_suppressed = await self.mcp_registry.store.check_suppression(supp_type, value)
+            return {
+                "suppressed": is_suppressed,
+                "value": value,
+                "type": supp_type
+            }
+
+        # ============ EMAIL MCP SERVER ============
+        elif tool_name == "send_email":
+            to = tool_input["to"]
+            subject = tool_input["subject"]
+            body = tool_input["body"]
+            prospect_id = tool_input["prospect_id"]
+
+            thread_id = await self.mcp_registry.email.send(to, subject, body, prospect_id)
+            return {
+                "status": "sent",
+                "thread_id": thread_id,
+                "to": to
+            }
+
+        elif tool_name == "get_email_thread":
+            prospect_id = tool_input["prospect_id"]
+            thread = await self.mcp_registry.email.get_thread(prospect_id)
+            return thread or {"error": "No email thread found"}
+
+        # ============ CALENDAR MCP SERVER ============
+        elif tool_name == "suggest_meeting_slots":
+            num_slots = tool_input.get("num_slots", 3)
+            slots = await self.mcp_registry.calendar.suggest_slots()
+            return {
+                "slots": slots[:num_slots],
+                "count": len(slots[:num_slots])
+            }
+
+        elif tool_name == "generate_calendar_invite":
+            start_time = tool_input["start_time"]
+            end_time = tool_input["end_time"]
+            title = tool_input["title"]
+
+            slot = {
+                "start_iso": start_time,
+                "end_iso": end_time,
+                "title": title
+            }
+
+            ics = await self.mcp_registry.calendar.generate_ics(slot)
+            return {
+                "ics_content": ics,
+                "meeting": slot
+            }
+
+        else:
+            raise ValueError(f"Unknown MCP tool: {tool_name}")

mcp/agents/autonomous_agent_groq.py

@@ -0,0 +1,334 @@
+"""
+Autonomous AI Agent with MCP Tool Calling using Groq API
+
+Groq offers FREE API access with fast inference on Llama, Mixtral models.
+No payment required - just need a free API key from console.groq.com
+"""
+
+import os
+import json
+import uuid
+import logging
+import asyncio
+from typing import List, Dict, Any, AsyncGenerator, Optional
+
+from mcp.tools.definitions import MCP_TOOLS
+from mcp.registry import MCPRegistry
+
+logger = logging.getLogger(__name__)
+
+# Groq FREE models
+GROQ_MODELS = [
+    "llama-3.1-70b-versatile",    # Best quality, free
+    "llama-3.1-8b-instant",       # Fast, free
+    "mixtral-8x7b-32768",         # Good for complex tasks
+    "gemma2-9b-it",               # Google's model
+]
+
+DEFAULT_MODEL = "llama-3.1-70b-versatile"
+
+
+class AutonomousMCPAgentGroq:
+    """
+    AI Agent using Groq API (FREE, fast inference)
+
+    Get your free API key at: https://console.groq.com
+    """
+
+    def __init__(
+        self,
+        mcp_registry: MCPRegistry,
+        api_key: str = None,
+        model: str = None
+    ):
+        self.mcp_registry = mcp_registry
+        self.api_key = api_key or os.getenv("GROQ_API_KEY")
+        self.model = model or os.getenv("GROQ_MODEL", DEFAULT_MODEL)
+
+        if not self.api_key:
+            raise ValueError("GROQ_API_KEY is required. Get free key at https://console.groq.com")
+
+        # Build tools for the prompt
+        self.tools_description = self._build_tools_description()
+
+        logger.info(f"Groq Agent initialized with model: {self.model}")
+
+    def _build_tools_description(self) -> str:
+        """Build tool descriptions for the system prompt"""
+        tools_text = ""
+        for tool in MCP_TOOLS:
+            tools_text += f"\n- **{tool['name']}**: {tool['description']}"
+            props = tool.get('input_schema', {}).get('properties', {})
+            required = tool.get('input_schema', {}).get('required', [])
+            if props:
+                tools_text += "\n  Parameters:"
+                for param, details in props.items():
+                    req = "(required)" if param in required else "(optional)"
+                    tools_text += f"\n    - {param} {req}: {details.get('description', '')}"
+        return tools_text
+
+    def _build_system_prompt(self) -> str:
+        return f"""You are an AI sales agent with access to tools. Use tools to complete tasks.
+
+AVAILABLE TOOLS:
+{self.tools_description}
+
+TO USE A TOOL, respond with JSON in this exact format:
+```json
+{{"tool": "tool_name", "parameters": {{"param1": "value1"}}}}
+```
+
+RULES:
+1. Use search_web to find information
+2. Use save_prospect, save_contact to store data
+3. Use send_email to draft emails
+4. After completing all tasks, provide a summary
+5. Say "DONE" when finished
+
+Be concise and focused."""
+
+    async def run(self, task: str, max_iterations: int = 15) -> AsyncGenerator[Dict[str, Any], None]:
+        """Run the agent on a task"""
+        import requests
+
+        yield {
+            "type": "agent_start",
+            "message": f"Starting task with {self.model}",
+            "model": self.model
+        }
+
+        system_prompt = self._build_system_prompt()
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": task}
+        ]
+
+        for iteration in range(1, max_iterations + 1):
+            yield {
+                "type": "iteration_start",
+                "iteration": iteration,
+                "message": f"Iteration {iteration}: AI reasoning..."
+            }
+
+            try:
+                # Call Groq API
+                response = self._call_groq(messages)
+                assistant_content = response.get("choices", [{}])[0].get("message", {}).get("content", "")
+
+                if not assistant_content:
+                    continue
+
+                # Check for completion
+                if "DONE" in assistant_content.upper():
+                    yield {
+                        "type": "thought",
+                        "thought": assistant_content.replace("DONE", "").strip(),
+                        "message": "Task complete"
+                    }
+                    yield {
+                        "type": "agent_complete",
+                        "message": "Task complete!",
+                        "final_answer": assistant_content.replace("DONE", "").strip(),
+                        "iterations": iteration
+                    }
+                    return
+
+                # Try to parse tool calls
+                tool_calls = self._parse_tool_calls(assistant_content)
+
+                if tool_calls:
+                    messages.append({"role": "assistant", "content": assistant_content})
+                    tool_results = []
+
+                    for tool_call in tool_calls:
+                        tool_name = tool_call.get("tool", "")
+                        tool_params = tool_call.get("parameters", {})
+
+                        yield {
+                            "type": "tool_call",
+                            "tool": tool_name,
+                            "input": tool_params,
+                            "message": f"Calling: {tool_name}"
+                        }
+
+                        try:
+                            result = await self._execute_tool(tool_name, tool_params)
+                            yield {
+                                "type": "tool_result",
+                                "tool": tool_name,
+                                "result": result,
+                                "message": f"Tool {tool_name} completed"
+                            }
+                            tool_results.append({"tool": tool_name, "result": result})
+                        except Exception as e:
+                            yield {
+                                "type": "tool_error",
+                                "tool": tool_name,
+                                "error": str(e),
+                                "message": f"Tool error: {e}"
+                            }
+                            tool_results.append({"tool": tool_name, "error": str(e)})
+
+                    # Add tool results to conversation
+                    results_text = "Tool results:\n" + json.dumps(tool_results, indent=2, default=str)[:2000]
+                    messages.append({"role": "user", "content": results_text})
+                else:
+                    # No tool calls - just a response
+                    yield {
+                        "type": "thought",
+                        "thought": assistant_content,
+                        "message": f"AI: {assistant_content[:100]}..."
+                    }
+                    messages.append({"role": "assistant", "content": assistant_content})
+                    messages.append({"role": "user", "content": "Continue with the task. Use tools to gather data. Say DONE when finished."})
+
+            except Exception as e:
+                logger.error(f"Error in iteration {iteration}: {e}")
+                yield {
+                    "type": "agent_error",
+                    "error": str(e),
+                    "message": f"Error: {e}"
+                }
+                return
+
+        yield {
+            "type": "agent_max_iterations",
+            "message": f"Reached max iterations ({max_iterations})",
+            "iterations": max_iterations
+        }
+
+    def _call_groq(self, messages: List[Dict]) -> Dict:
+        """Call Groq API"""
+        import requests
+
+        url = "https://api.groq.com/openai/v1/chat/completions"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json"
+        }
+        payload = {
+            "model": self.model,
+            "messages": messages,
+            "max_tokens": 2048,
+            "temperature": 0.7
+        }
+
+        response = requests.post(url, headers=headers, json=payload, timeout=60)
+        response.raise_for_status()
+        return response.json()
+
+    def _parse_tool_calls(self, text: str) -> List[Dict]:
+        """Parse tool calls from response text"""
+        import re
+
+        tool_calls = []
+
+        # Match JSON blocks
+        patterns = [
+            r'```json\s*(\{[^`]+\})\s*```',
+            r'```\s*(\{[^`]+\})\s*```',
+            r'(\{"tool":\s*"[^"]+",\s*"parameters":\s*\{[^}]*\}\})',
+        ]
+
+        for pattern in patterns:
+            matches = re.findall(pattern, text, re.DOTALL)
+            for match in matches:
+                try:
+                    data = json.loads(match.strip())
+                    if "tool" in data:
+                        tool_calls.append(data)
+                except json.JSONDecodeError:
+                    continue
+
+        return tool_calls
+
+    async def _execute_tool(self, tool_name: str, tool_input: Dict[str, Any]) -> Any:
+        """Execute an MCP tool"""
+
+        if tool_name == "search_web":
+            query = tool_input.get("query", "")
+            max_results = tool_input.get("max_results", 5)
+            results = await self.mcp_registry.search.query(query, max_results=max_results)
+            return {"results": results[:max_results], "count": len(results[:max_results])}
+
+        elif tool_name == "search_news":
+            query = tool_input.get("query", "")
+            max_results = tool_input.get("max_results", 5)
+            results = await self.mcp_registry.search.query(f"{query} news", max_results=max_results)
+            return {"results": results[:max_results], "count": len(results[:max_results])}
+
+        elif tool_name == "save_prospect":
+            prospect_data = {
+                "id": tool_input.get("prospect_id", str(uuid.uuid4())),
+                "company": {
+                    "id": tool_input.get("company_id"),
+                    "name": tool_input.get("company_name"),
+                    "domain": tool_input.get("company_domain")
+                },
+                "fit_score": tool_input.get("fit_score", 0),
+                "status": tool_input.get("status", "new"),
+                "metadata": tool_input.get("metadata", {})
+            }
+            result = await self.mcp_registry.store.save_prospect(prospect_data)
+            return {"status": result, "prospect_id": prospect_data["id"]}
+
+        elif tool_name == "save_company":
+            company_data = {
+                "id": tool_input.get("company_id", str(uuid.uuid4())),
+                "name": tool_input.get("name", ""),
+                "domain": tool_input.get("domain", ""),
+                "industry": tool_input.get("industry"),
+                "description": tool_input.get("description"),
+                "employee_count": tool_input.get("employee_count")
+            }
+            result = await self.mcp_registry.store.save_company(company_data)
+            return {"status": result, "company_id": company_data["id"]}
+
+        elif tool_name == "save_contact":
+            contact_data = {
+                "id": tool_input.get("contact_id", str(uuid.uuid4())),
+                "company_id": tool_input.get("company_id", ""),
+                "email": tool_input.get("email", ""),
+                "first_name": tool_input.get("first_name"),
+                "last_name": tool_input.get("last_name"),
+                "title": tool_input.get("title"),
+                "seniority": tool_input.get("seniority")
+            }
+            result = await self.mcp_registry.store.save_contact(contact_data)
+            return {"status": result, "contact_id": contact_data["id"]}
+
+        elif tool_name == "save_fact":
+            fact_data = {
+                "id": tool_input.get("fact_id", str(uuid.uuid4())),
+                "company_id": tool_input.get("company_id", ""),
+                "fact_type": tool_input.get("fact_type", ""),
+                "content": tool_input.get("content", ""),
+                "source_url": tool_input.get("source_url"),
+                "confidence_score": tool_input.get("confidence_score", 0.8)
+            }
+            result = await self.mcp_registry.store.save_fact(fact_data)
+            return {"status": result, "fact_id": fact_data["id"]}
+
+        elif tool_name == "send_email":
+            to = tool_input.get("to", "")
+            subject = tool_input.get("subject", "")
+            body = tool_input.get("body", "")
+            prospect_id = tool_input.get("prospect_id", "")
+            thread_id = await self.mcp_registry.email.send(to, subject, body, prospect_id)
+            return {"status": "sent", "thread_id": thread_id, "to": to}
+
+        elif tool_name == "list_prospects":
+            prospects = await self.mcp_registry.store.list_prospects()
+            return {"prospects": prospects, "count": len(prospects)}
+
+        elif tool_name == "get_prospect":
+            prospect_id = tool_input.get("prospect_id", "")
+            prospect = await self.mcp_registry.store.get_prospect(prospect_id)
+            return prospect or {"error": "Prospect not found"}
+
+        elif tool_name == "suggest_meeting_slots":
+            slots = await self.mcp_registry.calendar.suggest_slots()
+            return {"slots": slots[:3], "count": len(slots[:3])}
+
+        else:
+            raise ValueError(f"Unknown tool: {tool_name}")

mcp/agents/autonomous_agent_hf.py

@@ -0,0 +1,1215 @@
+"""
+Autonomous AI Agent with MCP Tool Calling using HuggingFace Inference Providers
+
+This agent uses HuggingFace's Inference Providers API with native tool calling
+support to autonomously decide which MCP tools to call.
+
+Benefits:
+- Uses HuggingFace unified API (single HF token for all providers)
+- Native tool calling support (OpenAI-compatible API)
+- Multiple providers: Nebius, Together, Sambanova, etc.
+- Models like Qwen2.5-72B-Instruct with strong tool calling
+- Free tier available with HuggingFace account
+"""
+
+import os
+import json
+import uuid
+import logging
+import asyncio
+from typing import List, Dict, Any, AsyncGenerator
+
+from mcp.tools.definitions import MCP_TOOLS, list_all_tools
+from mcp.registry import MCPRegistry
+
+logger = logging.getLogger(__name__)
+
+# Free models available via HuggingFace Serverless Inference API
+# These don't require paid provider credits
+FREE_MODELS = [
+    "mistralai/Mistral-7B-Instruct-v0.3",     # Fast, good quality
+    "microsoft/Phi-3-mini-4k-instruct",        # Small, fast
+    "HuggingFaceH4/zephyr-7b-beta",            # Good for chat
+    "meta-llama/Llama-3.2-3B-Instruct",        # Meta's small model
+    "Qwen/Qwen2.5-3B-Instruct",                # Qwen small
+]
+
+# Paid provider models (require credits)
+QWEN3_MODELS = [
+    "Qwen/Qwen3-32B",
+    "Qwen/Qwen3-8B",
+    "Qwen/Qwen3-4B",
+]
+
+# HuggingFace Inference Providers
+HF_PROVIDERS = {
+    "nscale": {"models": QWEN3_MODELS, "default": "Qwen/Qwen3-32B"},  # nscale provider
+    "nebius": {"models": QWEN3_MODELS, "default": "Qwen/Qwen3-32B"},
+    "together": {"models": QWEN3_MODELS, "default": "Qwen/Qwen3-32B"},
+    "sambanova": {"models": QWEN3_MODELS, "default": "Qwen/Qwen3-8B"},
+    "fireworks-ai": {"models": QWEN3_MODELS, "default": "Qwen/Qwen3-8B"},
+    "cerebras": {"models": ["Qwen/Qwen3-32B"], "default": "Qwen/Qwen3-32B"},
+}
+
+# Default to FREE serverless API (no provider = serverless)
+DEFAULT_PROVIDER = "hf-inference"  # Special value for free serverless
+DEFAULT_MODEL = "mistralai/Mistral-7B-Instruct-v0.3"
+
+
+class AutonomousMCPAgentHF:
+    """
+    AI Agent that autonomously uses MCP servers as tools using HuggingFace Inference Providers.
+
+    Uses native tool calling (OpenAI-compatible) for reliable tool execution.
+    HuggingFace routes requests to inference providers like Nebius, Together, etc.
+    """
+
+    def __init__(
+        self,
+        mcp_registry: MCPRegistry,
+        hf_token: str = None,
+        provider: str = None,
+        model: str = None
+    ):
+        """
+        Initialize the autonomous agent with HuggingFace Inference Providers
+
+        Args:
+            mcp_registry: MCP registry with all servers
+            hf_token: HuggingFace token (get at huggingface.co/settings/tokens)
+            provider: Inference provider (nebius, together, sambanova, etc.)
+            model: Model to use (default: Qwen/Qwen2.5-72B-Instruct)
+        """
+        self.mcp_registry = mcp_registry
+        self.hf_token = hf_token or os.getenv("HF_TOKEN") or os.getenv("HF_API_TOKEN")
+        self.model = model or os.getenv("HF_MODEL") or DEFAULT_MODEL
+
+        # Use provider in this order: passed param > env var > auto-detect
+        if provider:
+            self.provider = provider
+        elif os.getenv("HF_PROVIDER"):
+            self.provider = os.getenv("HF_PROVIDER")
+        elif self.model in QWEN3_MODELS or self.model.startswith("Qwen/Qwen3"):
+            # Qwen3 models need a provider (use nscale by default)
+            self.provider = "nscale"
+        else:
+            self.provider = DEFAULT_PROVIDER
+
+        if not self.hf_token:
+            raise ValueError(
+                "HF_TOKEN is required!\n"
+                "Get a token at: https://huggingface.co/settings/tokens\n"
+                "Then set: export HF_TOKEN=hf_your_token_here"
+            )
+
+        # Initialize HuggingFace InferenceClient
+        try:
+            from huggingface_hub import InferenceClient
+            # For serverless API (hf-inference), don't pass provider
+            if self.provider == "hf-inference":
+                self.client = InferenceClient(token=self.hf_token)
+            else:
+                self.client = InferenceClient(
+                    provider=self.provider,
+                    token=self.hf_token
+                )
+            logger.info(f"HuggingFace InferenceClient initialized")
+            logger.info(f"  Provider: {self.provider}")
+            logger.info(f"  Model: {self.model}")
+        except ImportError:
+            raise ImportError(
+                "huggingface_hub package not installed or outdated!\n"
+                "Install/upgrade with: pip install --upgrade huggingface_hub"
+            )
+
+        # Create tool definitions in OpenAI/HF format
+        self.tools = self._create_tool_definitions()
+
+        logger.info(f"Autonomous MCP Agent initialized with HuggingFace ({self.provider})")
+        logger.info(f"Available tools: {len(self.tools)}")
+
+    def _create_tool_definitions(self) -> List[Dict[str, Any]]:
+        """Convert MCP tool definitions to OpenAI/HuggingFace function calling format"""
+        tools = []
+
+        for mcp_tool in MCP_TOOLS:
+            tool = {
+                "type": "function",
+                "function": {
+                    "name": mcp_tool["name"],
+                    "description": mcp_tool["description"],
+                    "parameters": mcp_tool["input_schema"]
+                }
+            }
+            tools.append(tool)
+
+        return tools
+
+    async def run(
+        self,
+        task: str,
+        max_iterations: int = 15
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """
+        Run the agent autonomously on a task using native tool calling.
+
+        Args:
+            task: The task to complete
+            max_iterations: Maximum tool calls to prevent infinite loops
+
+        Yields:
+            Events showing agent's progress and tool calls
+        """
+
+        yield {
+            "type": "agent_start",
+            "message": f"Autonomous AI Agent (HuggingFace) starting task",
+            "task": task,
+            "model": self.model,
+            "provider": self.provider
+        }
+
+        # System prompt for the agent
+        system_prompt = """You are an autonomous AI agent for B2B sales automation.
+
+You have access to MCP tools including:
+- search_web: Search the web for company information
+- find_verified_contacts: Find REAL decision-makers (searches LinkedIn, company websites, directories)
+- save_prospect: Save a prospect company to the database
+- send_email: Draft outreach emails
+
+CRITICAL RULE: Only save prospects that have verified contacts. No contacts = don't save.
+
+REQUIRED WORKFLOW:
+1. search_web to find potential prospect companies
+2. find_verified_contacts FIRST to check if contacts exist
+3. IF contacts found (count > 0): save_prospect, then send_email
+4. IF no contacts found (count = 0): SKIP this company, try the next one
+
+TOOL CALL FORMAT - output valid JSON:
+
+Step 1 - Find contacts FIRST:
+{"company_name": "Acme Corp", "company_domain": "acme.com", "target_titles": ["CEO", "Founder", "VP Sales", "CTO"], "max_contacts": 3}
+
+Step 2 - ONLY if contacts found, save prospect:
+{"prospect_id": "prospect_1", "company_id": "company_1", "company_name": "Acme Corp", "company_domain": "acme.com", "fit_score": 85}
+
+The find_verified_contacts tool searches:
+- Company website (team/about pages)
+- LinkedIn profiles
+- Crunchbase, ZoomInfo, directories
+- Press releases and news
+- Social media profiles
+
+IMPORTANT:
+- A prospect without contacts is USELESS - don't save it
+- NEVER invent contact names or emails
+- Keep searching until you find prospects WITH verified contacts
+
+After completing, summarize:
+- Prospects saved (with contacts)
+- Companies skipped (no contacts)"""
+
+        # Initialize conversation
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": task}
+        ]
+
+        iteration = 0
+
+        while iteration < max_iterations:
+            iteration += 1
+
+            yield {
+                "type": "iteration_start",
+                "iteration": iteration,
+                "message": f"Iteration {iteration}: AI reasoning..."
+            }
+
+            try:
+                # Call HuggingFace Inference API with tools
+                logger.info(f"Calling HuggingFace API (iteration {iteration})...")
+                logger.info(f"  Provider: {self.provider}, Model: {self.model}")
+
+                # Run synchronous API call in executor
+                response = await asyncio.get_event_loop().run_in_executor(
+                    None,
+                    self._call_inference_api,
+                    messages
+                )
+
+                # Handle response
+                if response is None:
+                    yield {
+                        "type": "agent_error",
+                        "error": "Empty response from API",
+                        "message": "API returned empty response"
+                    }
+                    break
+
+                # Get the assistant message
+                assistant_message = response.choices[0].message
+
+                # Check if AI wants to call tools
+                if hasattr(assistant_message, 'tool_calls') and assistant_message.tool_calls:
+                    # Process each tool call
+                    tool_results = []
+
+                    for tool_call in assistant_message.tool_calls:
+                        tool_name = tool_call.function.name
+
+                        try:
+                            tool_input = json.loads(tool_call.function.arguments)
+                        except json.JSONDecodeError:
+                            tool_input = {}
+
+                        yield {
+                            "type": "tool_call",
+                            "tool": tool_name,
+                            "input": tool_input,
+                            "message": f"Action: {tool_name}"
+                        }
+
+                        # Execute the MCP tool
+                        try:
+                            result = await self._execute_mcp_tool(tool_name, tool_input)
+
+                            yield {
+                                "type": "tool_result",
+                                "tool": tool_name,
+                                "result": result,
+                                "message": f"Tool {tool_name} completed"
+                            }
+
+                            tool_results.append({
+                                "tool_call_id": tool_call.id,
+                                "role": "tool",
+                                "content": json.dumps(result, default=str)
+                            })
+
+                        except Exception as e:
+                            error_msg = str(e)
+                            logger.error(f"Tool execution failed: {tool_name} - {error_msg}")
+
+                            yield {
+                                "type": "tool_error",
+                                "tool": tool_name,
+                                "error": error_msg,
+                                "message": f"Tool {tool_name} failed: {error_msg}"
+                            }
+
+                            tool_results.append({
+                                "tool_call_id": tool_call.id,
+                                "role": "tool",
+                                "content": json.dumps({"error": error_msg})
+                            })
+
+                    # Add assistant message and tool results to conversation
+                    messages.append({
+                        "role": "assistant",
+                        "content": assistant_message.content or "",
+                        "tool_calls": [
+                            {
+                                "id": tc.id,
+                                "type": "function",
+                                "function": {
+                                    "name": tc.function.name,
+                                    "arguments": tc.function.arguments
+                                }
+                            }
+                            for tc in assistant_message.tool_calls
+                        ]
+                    })
+                    messages.extend(tool_results)
+
+                else:
+                    # No tool calls - AI is done or providing response
+                    final_content = assistant_message.content or ""
+                    raw_content = getattr(assistant_message, 'raw_content', final_content)
+
+                    # Log for debugging
+                    logger.info(f"Iteration {iteration}: No tool calls")
+                    logger.info(f"  Raw content length: {len(raw_content)}")
+                    logger.info(f"  Stripped content length: {len(final_content)}")
+                    if raw_content and not final_content:
+                        logger.info(f"  Raw content preview: {raw_content[:200]}...")
+
+                    # Always yield thought event if we have ANY content (for tracking)
+                    if final_content:
+                        yield {
+                            "type": "thought",
+                            "thought": final_content,
+                            "message": f"AI Response: {final_content[:100]}..." if len(final_content) > 100 else f"AI Response: {final_content}"
+                        }
+                    elif raw_content:
+                        # Content was stripped but raw exists - yield a minimal thought
+                        yield {
+                            "type": "thought",
+                            "thought": f"[Processing: {len(raw_content)} chars of reasoning]",
+                            "message": "AI is reasoning..."
+                        }
+
+                    # Check if this looks like a final answer (after at least one iteration)
+                    if iteration > 1:
+                        # Ensure we have some content for final answer
+                        if not final_content and raw_content:
+                            # Try to extract something useful from raw thinking
+                            import re
+                            think_match = re.search(r'<think>(.*?)</think>', raw_content, flags=re.DOTALL)
+                            if think_match:
+                                think_text = think_match.group(1).strip()
+                                # Get last meaningful portion
+                                sentences = [s.strip() for s in think_text.split('.') if len(s.strip()) > 20]
+                                if sentences:
+                                    final_content = '. '.join(sentences[-5:]) + '.'
+                                    logger.info(f"Extracted final answer from thinking: {final_content[:100]}...")
+
+                        yield {
+                            "type": "agent_complete",
+                            "message": "Task complete!",
+                            "final_answer": final_content,
+                            "iterations": iteration
+                        }
+                        break
+
+                    # Add response to messages and continue
+                    messages.append({
+                        "role": "assistant",
+                        "content": final_content or raw_content[:500] if raw_content else ""
+                    })
+
+            except Exception as e:
+                error_msg = str(e)
+                logger.error(f"HuggingFace API error: {error_msg}", exc_info=True)
+
+                # Check for common errors
+                if "401" in error_msg or "unauthorized" in error_msg.lower():
+                    yield {
+                        "type": "agent_error",
+                        "error": "Invalid HF_TOKEN",
+                        "message": "Authentication failed. Please check your HF_TOKEN."
+                    }
+                elif "rate" in error_msg.lower() or "limit" in error_msg.lower():
+                    yield {
+                        "type": "agent_error",
+                        "error": "Rate limit reached",
+                        "message": "Rate limit reached. Try again later or upgrade to HF PRO."
+                    }
+                else:
+                    yield {
+                        "type": "agent_error",
+                        "error": error_msg,
+                        "message": f"API error: {error_msg}"
+                    }
+                break
+
+        if iteration >= max_iterations:
+            yield {
+                "type": "agent_max_iterations",
+                "message": f"Reached maximum iterations ({max_iterations})",
+                "iterations": iteration
+            }
+
+    def _call_inference_api(self, messages: List[Dict], retry_count: int = 0) -> Any:
+        """
+        Call HuggingFace Inference API via the new router endpoint.
+        Uses the configured provider (e.g., nscale for Qwen3-32B).
+        """
+        import requests
+
+        headers = {
+            "Authorization": f"Bearer {self.hf_token}",
+            "Content-Type": "application/json"
+        }
+        last_error = None
+
+        # Add provider header if using a specific provider
+        if self.provider and self.provider != "hf-inference":
+            headers["X-HF-Provider"] = self.provider
+
+        # Use the router endpoint for chat completions
+        api_url = "https://router.huggingface.co/v1/chat/completions"
+
+        # Try the configured model first
+        try:
+            logger.info(f"Trying primary model: {self.model} via {self.provider}")
+
+            payload = {
+                "model": self.model,
+                "messages": messages,
+                "max_tokens": 2048,
+                "temperature": 0.7,
+                "stream": False,
+                "tools": self.tools,  # Include tool definitions!
+                "tool_choice": "auto"  # Let model decide when to use tools
+            }
+
+            response = requests.post(api_url, headers=headers, json=payload, timeout=120)
+
+            if response.status_code == 200:
+                result = response.json()
+                logger.info(f"Success with {self.model} via {self.provider}")
+                return self._create_chat_response(result)
+            elif response.status_code == 402:
+                logger.warning(f"Payment required for {self.model} via {self.provider}. Falling back...")
+                last_error = "Payment required - exceeded monthly credits"
+            elif response.status_code == 404:
+                logger.warning(f"Model {self.model} not found via {self.provider}. Falling back...")
+                last_error = f"Model not found via {self.provider}"
+            else:
+                logger.warning(f"Model {self.model} returned {response.status_code}: {response.text[:200]}")
+                last_error = f"HTTP {response.status_code}"
+
+        except Exception as e:
+            last_error = str(e)
+            logger.warning(f"Primary model failed: {last_error}")
+
+        # Fallback models with their providers
+        fallback_models = [
+            ("Qwen/Qwen2.5-72B-Instruct", None),  # No provider = serverless
+            ("meta-llama/Llama-3.1-70B-Instruct", None),
+            ("mistralai/Mixtral-8x7B-Instruct-v0.1", None),
+            ("Qwen/Qwen3-32B", "nebius"),  # Try nebius as backup
+            ("Qwen/Qwen3-8B", "together"),  # Try together as backup
+        ]
+
+        for model, provider in fallback_models:
+            try:
+                logger.info(f"Trying fallback model: {model}" + (f" via {provider}" if provider else ""))
+
+                payload = {
+                    "model": model,
+                    "messages": messages,
+                    "max_tokens": 2048,
+                    "temperature": 0.7,
+                    "stream": False,
+                    "tools": self.tools,  # Include tool definitions!
+                    "tool_choice": "auto"
+                }
+
+                # Set headers for this fallback
+                fallback_headers = {
+                    "Authorization": f"Bearer {self.hf_token}",
+                    "Content-Type": "application/json"
+                }
+                if provider:
+                    fallback_headers["X-HF-Provider"] = provider
+
+                response = requests.post(api_url, headers=fallback_headers, json=payload, timeout=120)
+
+                if response.status_code == 200:
+                    result = response.json()
+                    logger.info(f"Success with fallback model: {model}")
+                    return self._create_chat_response(result)
+                elif response.status_code in [402, 404]:
+                    logger.warning(f"Model {model} returned {response.status_code}, trying next...")
+                    continue
+                elif response.status_code == 503:
+                    logger.info(f"Model {model} is loading, trying next...")
+                    continue
+                else:
+                    logger.warning(f"Model {model} returned {response.status_code}")
+                    continue
+
+            except Exception as e:
+                last_error = str(e)
+                logger.warning(f"Model {model} failed: {str(e)[:100]}")
+                continue
+
+        logger.error(f"All models failed. Last error: {last_error}")
+        raise Exception(f"All inference attempts failed: {last_error}")
+
+    def _strip_thinking_tags(self, text: str) -> str:
+        """Remove Qwen3's <think>...</think> tags and return the actual response"""
+        import re
+        if not text:
+            return ""
+        # Remove <think>...</think> blocks (Qwen3 chain-of-thought)
+        cleaned = re.sub(r'<think>.*?</think>', '', text, flags=re.DOTALL)
+        result = cleaned.strip()
+
+        # If stripped content is empty but original had thinking, extract a summary
+        if not result and '<think>' in text:
+            # Try to extract the last meaningful sentence from thinking as a fallback
+            think_match = re.search(r'<think>(.*?)</think>', text, flags=re.DOTALL)
+            if think_match:
+                think_content = think_match.group(1).strip()
+                # Get last few sentences as summary (model's conclusion)
+                sentences = [s.strip() for s in think_content.split('.') if s.strip()]
+                if sentences:
+                    # Return last 2-3 meaningful sentences as the response
+                    result = '. '.join(sentences[-3:]) + '.'
+                    logger.info(f"Extracted thinking summary: {result[:100]}...")
+
+        return result
+
+    def _create_chat_response(self, result: dict) -> Any:
+        """Create a response object from chat completion result"""
+        strip_thinking = self._strip_thinking_tags
+
+        class MockChoice:
+            def __init__(self, message_data):
+                self.message = MockMessage(message_data)
+
+        class MockMessage:
+            def __init__(self, data):
+                # Handle None content properly (API might return {"content": null})
+                raw_content = data.get("content") or ""
+                # Strip Qwen3 thinking tags to get actual response
+                self.content = strip_thinking(raw_content)
+                # Store raw content for debugging/fallback
+                self.raw_content = raw_content
+                self.tool_calls = self._parse_tool_calls_from_response(data, raw_content)
+
+            def _parse_tool_calls_from_response(self, data, raw_content):
+                """Parse tool calls from API response or from content"""
+                # Check if API returned tool_calls directly
+                if "tool_calls" in data and data["tool_calls"]:
+                    return [MockToolCall(tc) for tc in data["tool_calls"]]
+
+                # Otherwise try to parse from content (use raw content to find tool calls)
+                return self._parse_tool_calls_from_text(raw_content)
+
+            def _infer_tool_from_params(self, params):
+                """Infer tool name from parameter keys"""
+                if not isinstance(params, dict):
+                    return None
+                keys = set(params.keys())
+
+                # Check for discover_prospects_with_contacts (HIGHEST PRIORITY - all-in-one tool)
+                if "client_company" in keys and "client_industry" in keys:
+                    return "discover_prospects_with_contacts"
+                if "client_company" in keys and "target_prospects" in keys:
+                    return "discover_prospects_with_contacts"
+                # Check for find_verified_contacts patterns (single company)
+                if "company_name" in keys and "company_domain" in keys and "target_titles" in keys:
+                    return "find_verified_contacts"
+                if "company_name" in keys and "company_domain" in keys and "max_contacts" in keys:
+                    return "find_verified_contacts"
+                # Check for save_prospect patterns
+                if "prospect_id" in keys or ("company_name" in keys and "fit_score" in keys):
+                    return "save_prospect"
+                # Check for save_company patterns
+                if "company_id" in keys and ("name" in keys or "domain" in keys) and "prospect_id" not in keys:
+                    return "save_company"
+                # Check for save_contact patterns (only for contacts returned by find_verified_contacts)
+                if "contact_id" in keys or ("email" in keys and ("first_name" in keys or "last_name" in keys)):
+                    return "save_contact"
+                # Check for send_email patterns
+                if "to" in keys and "subject" in keys and "body" in keys:
+                    return "send_email"
+                # Check for search patterns
+                if "query" in keys and len(keys) <= 2:
+                    return "search_web"
+                # Check for save_fact patterns
+                if "fact_type" in keys or ("content" in keys and "company_id" in keys):
+                    return "save_fact"
+
+                return None
+
+            def _parse_tool_calls_from_text(self, text):
+                """Try to parse tool calls from text response - handles Qwen3 text-based tool descriptions"""
+                import re
+                tool_calls = []
+
+                def extract_json_objects(text):
+                    """Extract all JSON objects from text, handling nested braces"""
+                    objects = []
+                    i = 0
+                    while i < len(text):
+                        if text[i] == '{':
+                            start = i
+                            depth = 1
+                            i += 1
+                            while i < len(text) and depth > 0:
+                                if text[i] == '{':
+                                    depth += 1
+                                elif text[i] == '}':
+                                    depth -= 1
+                                i += 1
+                            if depth == 0:
+                                try:
+                                    obj = json.loads(text[start:i])
+                                    objects.append(obj)
+                                except:
+                                    pass
+                        else:
+                            i += 1
+                    return objects
+
+                # IMPORTANT: Search BOTH raw text AND stripped text for JSON objects
+                # Qwen3 may put tool calls inside <think> tags
+                all_json_objects = extract_json_objects(text)  # Search raw first
+
+                # Also search stripped version in case JSON is outside think tags
+                text_clean = strip_thinking(text)
+                if text_clean != text:
+                    all_json_objects.extend(extract_json_objects(text_clean))
+                logger.info(f"Found {len(all_json_objects)} JSON objects in response")
+
+                # Process each JSON object and infer tool
+                seen_signatures = set()  # Avoid duplicates
+                for obj in all_json_objects:
+                    tool_name = self._infer_tool_from_params(obj)
+                    if tool_name:
+                        # Create a signature to avoid duplicates
+                        sig = f"{tool_name}:{json.dumps(obj, sort_keys=True)}"
+                        if sig not in seen_signatures:
+                            seen_signatures.add(sig)
+                            tool_calls.append(MockToolCallFromText({"tool": tool_name, "parameters": obj}))
+                            logger.info(f"Parsed tool call: {tool_name} with params: {list(obj.keys())}")
+
+                # Also check code fence blocks (sometimes JSON is formatted there)
+                code_blocks = re.findall(r'```(?:json)?\s*(.+?)\s*```', text_clean, re.DOTALL)
+                for block in code_blocks:
+                    block_objects = extract_json_objects(block)
+                    for obj in block_objects:
+                        tool_name = self._infer_tool_from_params(obj)
+                        if tool_name:
+                            sig = f"{tool_name}:{json.dumps(obj, sort_keys=True)}"
+                            if sig not in seen_signatures:
+                                seen_signatures.add(sig)
+                                tool_calls.append(MockToolCallFromText({"tool": tool_name, "parameters": obj}))
+                                logger.info(f"Parsed tool from code block: {tool_name}")
+
+                if tool_calls:
+                    logger.info(f"Total tool calls parsed from text: {len(tool_calls)}")
+                return tool_calls if tool_calls else None
+
+        class MockToolCall:
+            def __init__(self, data):
+                self.function = MockFunction(data.get("function", {}))
+                self.id = data.get("id", f"call_{id(self)}")
+
+        class MockToolCallFromText:
+            def __init__(self, data):
+                self.function = MockFunctionFromText(data)
+                self.id = f"call_{id(self)}"
+
+        class MockFunction:
+            def __init__(self, data):
+                self.name = data.get("name", "")
+                self.arguments = data.get("arguments", "{}")
+
+        class MockFunctionFromText:
+            def __init__(self, data):
+                self.name = data.get("tool", data.get("name", ""))
+                self.arguments = json.dumps(data.get("parameters", data.get("arguments", {})))
+
+        class MockResponse:
+            def __init__(self, result):
+                choices_data = result.get("choices", [])
+                if choices_data:
+                    self.choices = [MockChoice(c.get("message", {})) for c in choices_data]
+                else:
+                    self.choices = []
+
+        return MockResponse(result)
+
+    async def _execute_mcp_tool(self, tool_name: str, tool_input: Dict[str, Any]) -> Any:
+        """
+        Execute an MCP tool by routing to the appropriate MCP server.
+
+        This is where we actually call the MCP servers!
+        """
+
+        # ============ SEARCH MCP SERVER ============
+        if tool_name == "search_web":
+            query = tool_input["query"]
+            max_results = tool_input.get("max_results", 5)
+
+            results = await self.mcp_registry.search.query(query, max_results=max_results)
+            return {
+                "results": results[:max_results],
+                "count": len(results[:max_results])
+            }
+
+        elif tool_name == "search_news":
+            query = tool_input["query"]
+            max_results = tool_input.get("max_results", 5)
+
+            results = await self.mcp_registry.search.query(f"{query} news", max_results=max_results)
+            return {
+                "results": results[:max_results],
+                "count": len(results[:max_results])
+            }
+
+        # ============ OPTIMIZED PROSPECT DISCOVERY WITH CONTACTS ============
+        elif tool_name == "discover_prospects_with_contacts":
+            from services.enhanced_contact_finder import EnhancedContactFinder
+            from urllib.parse import urlparse
+
+            client_company = tool_input["client_company"]
+            client_industry = tool_input["client_industry"]
+            target_prospects = tool_input.get("target_prospects", 3)
+            target_titles = tool_input.get("target_titles", ["CEO", "Founder", "VP Sales", "CTO", "Head of Sales"])
+
+            logger.info(f"Discovering {target_prospects} prospects with contacts for {client_company}")
+            print(f"\n[PROSPECT DISCOVERY] ========================================")
+            print(f"[PROSPECT DISCOVERY] Finding {target_prospects} prospects WITH verified contacts")
+            print(f"[PROSPECT DISCOVERY] Client: {client_company}")
+            print(f"[PROSPECT DISCOVERY] ========================================")
+
+            contact_finder = EnhancedContactFinder(mcp_registry=self.mcp_registry)
+
+            saved_prospects = []
+            all_contacts = []
+            skipped_companies = []
+            companies_checked = 0
+            max_companies_to_check = target_prospects * 8  # Check more companies to find enough with contacts
+
+            # Build smart search queries based on what the client company does
+            # The goal is to find CUSTOMERS for the client, not articles ABOUT the client
+            client_lower = client_company.lower()
+            industry_lower = client_industry.lower()
+
+            # Determine prospect type based on client business
+            # E-commerce platforms (Shopify, BigCommerce, etc.) -> retailers, DTC brands
+            # CRM software -> B2B companies, sales teams
+            # Marketing tools -> businesses needing marketing
+            # etc.
+
+            search_queries = []
+
+            # Check for e-commerce/retail platform clients
+            if any(kw in client_lower or kw in industry_lower for kw in ['ecommerce', 'e-commerce', 'shopify', 'online store', 'retail platform', 'shopping cart']):
+                search_queries = [
+                    "DTC brands fashion apparel company",
+                    "online boutique store founder CEO",
+                    "independent retail brand ecommerce",
+                    "emerging consumer brands direct to consumer",
+                    "small business online store owner",
+                    "handmade crafts seller business",
+                    "subscription box company founder",
+                ]
+            # Check for CRM/Sales software clients
+            elif any(kw in client_lower or kw in industry_lower for kw in ['crm', 'salesforce', 'sales software', 'customer relationship']):
+                search_queries = [
+                    "B2B SaaS company sales team",
+                    "growing startup sales operations",
+                    "enterprise software company VP Sales",
+                    "technology company Head of Sales",
+                ]
+            # Check for marketing/advertising clients
+            elif any(kw in client_lower or kw in industry_lower for kw in ['marketing', 'advertising', 'ads', 'seo', 'content']):
+                search_queries = [
+                    "growing startup marketing director",
+                    "ecommerce brand marketing team",
+                    "B2B company CMO marketing",
+                    "technology startup growth marketing",
+                ]
+            # Default: find growing companies that might need the client's services
+            else:
+                search_queries = [
+                    f"growing companies {industry_lower} customers list",
+                    f"startups using {industry_lower} solutions",
+                    f"businesses {industry_lower} case study customer",
+                    f"companies similar to {client_company} customers",
+                    "fast growing startups Series A B2B",
+                    "emerging technology companies founder CEO",
+                    "mid-market companies digital transformation",
+                ]
+
+            # Add generic business-finding queries
+            search_queries.extend([
+                "Inc 5000 fastest growing companies",
+                "emerging brands startup founders",
+                "venture backed startups series A",
+            ])
+
+            seen_domains = set()
+
+            # Skip domains that are NOT actual company websites
+            skip_domains = [
+                # Social media
+                'linkedin.com', 'facebook.com', 'twitter.com', 'instagram.com', 'tiktok.com',
+                # Reference/directory sites
+                'wikipedia.org', 'crunchbase.com', 'zoominfo.com', 'apollo.io', 'yelp.com',
+                'glassdoor.com', 'g2.com', 'capterra.com', 'trustpilot.com', 'bbb.org',
+                # News/media sites
+                'forbes.com', 'businessinsider.com', 'techcrunch.com', 'bloomberg.com',
+                'cnbc.com', 'reuters.com', 'wsj.com', 'nytimes.com', 'theverge.com',
+                'wired.com', 'mashable.com', 'venturebeat.com', 'inc.com', 'entrepreneur.com',
+                # Blog/article/review sites
+                'medium.com', 'hubspot.com', 'blog.', 'wordpress.com', 'blogspot.com',
+                'quora.com', 'reddit.com', 'youtube.com', 'vimeo.com',
+                # Generic/aggregator sites
+                'amazon.com', 'ebay.com', 'alibaba.com', 'aliexpress.com',
+                'google.com', 'bing.com', 'yahoo.com', 'duckduckgo.com',
+                # The client company itself (don't prospect yourself!)
+                client_company.lower().replace(' ', '') + '.com',
+            ]
+
+            # Also skip titles that look like articles, not company names
+            skip_title_patterns = [
+                'what is', 'how to', 'guide', 'review', 'best ', 'top ', 'vs ',
+                ' vs ', 'comparison', 'tutorial', 'tips', 'ways to', 'complete',
+                'everything you need', 'beginner', 'introduction', 'explained',
+                '2024', '2025', '2023', '[', ']', 'list of', 'examples'
+            ]
+
+            for query in search_queries:
+                if len(saved_prospects) >= target_prospects:
+                    break
+
+                try:
+                    print(f"\n[PROSPECT DISCOVERY] Searching: {query}")
+                    results = await self.mcp_registry.search.query(query, max_results=10)
+
+                    for result in results:
+                        if len(saved_prospects) >= target_prospects:
+                            break
+                        if companies_checked >= max_companies_to_check:
+                            break
+
+                        url = result.get('url', '')
+                        title = result.get('title', '')
+
+                        # Extract domain from URL
+                        try:
+                            parsed = urlparse(url)
+                            domain = parsed.netloc.replace('www.', '')
+                            if not domain or domain in seen_domains:
+                                continue
+                            seen_domains.add(domain)
+                        except:
+                            continue
+
+                        # Skip non-company domains
+                        if any(skip in domain.lower() for skip in skip_domains):
+                            print(f"[PROSPECT DISCOVERY] ⏭️ Skipping non-company domain: {domain}")
+                            continue
+
+                        # Skip titles that look like articles, not companies
+                        title_lower = title.lower()
+                        if any(pattern in title_lower for pattern in skip_title_patterns):
+                            print(f"[PROSPECT DISCOVERY] ⏭️ Skipping article title: {title[:50]}...")
+                            continue
+
+                        # Extract company name from title - be smarter about it
+                        # Try to get actual company name, not article title
+                        company_name = title.split(' - ')[0].split(' | ')[0].split(':')[0].strip()
+
+                        # If company name is too long (probably article title), use domain
+                        if len(company_name) > 40 or ' ' in company_name and len(company_name.split()) > 5:
+                            # Extract company name from domain instead
+                            company_name = domain.split('.')[0].replace('-', ' ').title()
+
+                        if not company_name or len(company_name) < 2:
+                            continue
+
+                        companies_checked += 1
+                        print(f"\n[PROSPECT DISCOVERY] Checking ({companies_checked}/{max_companies_to_check}): {company_name} ({domain})")
+
+                        # Find contacts for this company
+                        try:
+                            contacts = await contact_finder.find_real_contacts(
+                                company_name=company_name,
+                                domain=domain,
+                                target_titles=target_titles,
+                                max_contacts=3
+                            )
+
+                            if contacts and len(contacts) > 0:
+                                # Save prospect
+                                prospect_id = f"prospect_{len(saved_prospects) + 1}"
+                                company_id = domain.replace(".", "_")
+
+                                prospect_data = {
+                                    "id": prospect_id,
+                                    "company": {
+                                        "id": company_id,
+                                        "name": company_name,
+                                        "domain": domain
+                                    },
+                                    "fit_score": 75,
+                                    "status": "new",
+                                    "metadata": {"source": "automated_discovery"}
+                                }
+
+                                await self.mcp_registry.store.save_prospect(prospect_data)
+
+                                # Save contacts
+                                contact_list = []
+                                for contact in contacts:
+                                    contact_data = {
+                                        "id": contact.id,
+                                        "name": contact.name,
+                                        "email": contact.email,
+                                        "title": contact.title,
+                                        "company": company_name,
+                                        "domain": domain,
+                                        "verified": True,
+                                        "source": "web_search_and_scraping"
+                                    }
+                                    contact_list.append(contact_data)
+                                    all_contacts.append(contact_data)
+
+                                    await self.mcp_registry.store.save_contact({
+                                        "id": contact.id,
+                                        "company_id": company_id,
+                                        "email": contact.email,
+                                        "first_name": contact.name.split()[0] if contact.name else "",
+                                        "last_name": contact.name.split()[-1] if len(contact.name.split()) > 1 else "",
+                                        "title": contact.title
+                                    })
+
+                                saved_prospects.append({
+                                    "prospect_id": prospect_id,
+                                    "company_name": company_name,
+                                    "domain": domain,
+                                    "contacts": contact_list,
+                                    "contact_count": len(contact_list)
+                                })
+
+                                print(f"[PROSPECT DISCOVERY] ✅ SAVED: {company_name} with {len(contacts)} contacts")
+                            else:
+                                skipped_companies.append({"name": company_name, "domain": domain, "reason": "no_contacts"})
+                                print(f"[PROSPECT DISCOVERY] ⏭️ SKIPPED: {company_name} (no verified contacts)")
+
+                        except Exception as e:
+                            logger.debug(f"Error checking {company_name}: {str(e)}")
+                            skipped_companies.append({"name": company_name, "domain": domain, "reason": str(e)})
+                            continue
+
+                except Exception as e:
+                    logger.debug(f"Search error: {str(e)}")
+                    continue
+
+            print(f"\n[PROSPECT DISCOVERY] ========================================")
+            print(f"[PROSPECT DISCOVERY] DISCOVERY COMPLETE")
+            print(f"[PROSPECT DISCOVERY] ========================================")
+            print(f"[PROSPECT DISCOVERY] Prospects saved: {len(saved_prospects)}/{target_prospects}")
+            print(f"[PROSPECT DISCOVERY] Total contacts: {len(all_contacts)}")
+            print(f"[PROSPECT DISCOVERY] Companies checked: {companies_checked}")
+            print(f"[PROSPECT DISCOVERY] Companies skipped: {len(skipped_companies)}")
+            print(f"[PROSPECT DISCOVERY] ========================================\n")
+
+            return {
+                "status": "success" if len(saved_prospects) > 0 else "no_prospects_found",
+                "prospects": saved_prospects,
+                "prospects_count": len(saved_prospects),
+                "contacts_count": len(all_contacts),
+                "companies_checked": companies_checked,
+                "companies_skipped": len(skipped_companies),
+                "target_met": len(saved_prospects) >= target_prospects,
+                "message": f"Found {len(saved_prospects)} prospects with {len(all_contacts)} verified contacts. Checked {companies_checked} companies, skipped {len(skipped_companies)} (no contacts)."
+            }
+
+        # ============ VERIFIED CONTACT FINDER (Single Company) ============
+        elif tool_name == "find_verified_contacts":
+            from services.enhanced_contact_finder import EnhancedContactFinder
+
+            company_name = tool_input["company_name"]
+            company_domain = tool_input["company_domain"]
+            target_titles = tool_input.get("target_titles", ["CEO", "Founder", "VP Sales", "CTO", "Head of Sales"])
+            max_contacts = tool_input.get("max_contacts", 3)
+
+            logger.info(f"Finding verified contacts for {company_name} ({company_domain})")
+
+            contact_finder = EnhancedContactFinder(mcp_registry=self.mcp_registry)
+
+            try:
+                contacts = await contact_finder.find_real_contacts(
+                    company_name=company_name,
+                    domain=company_domain,
+                    target_titles=target_titles,
+                    max_contacts=max_contacts
+                )
+
+                contact_list = []
+                for contact in contacts:
+                    contact_data = {
+                        "id": contact.id,
+                        "name": contact.name,
+                        "email": contact.email,
+                        "title": contact.title,
+                        "company": company_name,
+                        "domain": company_domain,
+                        "verified": True,
+                        "source": "web_search_and_scraping"
+                    }
+                    contact_list.append(contact_data)
+
+                    await self.mcp_registry.store.save_contact({
+                        "id": contact.id,
+                        "company_id": company_domain.replace(".", "_"),
+                        "email": contact.email,
+                        "first_name": contact.name.split()[0] if contact.name else "",
+                        "last_name": contact.name.split()[-1] if contact.name and len(contact.name.split()) > 1 else "",
+                        "title": contact.title
+                    })
+
+                if contact_list:
+                    return {
+                        "status": "success",
+                        "contacts": contact_list,
+                        "count": len(contact_list),
+                        "message": f"Found {len(contact_list)} verified contacts at {company_name}",
+                        "should_save_prospect": True
+                    }
+                else:
+                    return {
+                        "status": "no_contacts_found",
+                        "contacts": [],
+                        "count": 0,
+                        "message": f"No verified contacts found for {company_name}. Skip this prospect.",
+                        "should_save_prospect": False
+                    }
+
+            except Exception as e:
+                logger.error(f"Error finding contacts for {company_name}: {str(e)}")
+                return {
+                    "status": "error",
+                    "contacts": [],
+                    "count": 0,
+                    "message": f"Error searching for contacts: {str(e)}",
+                    "should_save_prospect": False
+                }
+
+        # ============ STORE MCP SERVER ============
+        elif tool_name == "save_prospect":
+            prospect_data = {
+                "id": tool_input.get("prospect_id", str(uuid.uuid4())),
+                "company": {
+                    "id": tool_input.get("company_id"),
+                    "name": tool_input.get("company_name"),
+                    "domain": tool_input.get("company_domain")
+                },
+                "fit_score": tool_input.get("fit_score", 0),
+                "status": tool_input.get("status", "new"),
+                "metadata": tool_input.get("metadata", {})
+            }
+
+            result = await self.mcp_registry.store.save_prospect(prospect_data)
+            return {"status": result, "prospect_id": prospect_data["id"]}
+
+        elif tool_name == "get_prospect":
+            prospect_id = tool_input["prospect_id"]
+            prospect = await self.mcp_registry.store.get_prospect(prospect_id)
+            return prospect or {"error": "Prospect not found"}
+
+        elif tool_name == "list_prospects":
+            prospects = await self.mcp_registry.store.list_prospects()
+            status_filter = tool_input.get("status")
+
+            if status_filter:
+                prospects = [p for p in prospects if p.get("status") == status_filter]
+
+            return {
+                "prospects": prospects,
+                "count": len(prospects)
+            }
+
+        elif tool_name == "save_company":
+            company_data = {
+                "id": tool_input.get("company_id", str(uuid.uuid4())),
+                "name": tool_input["name"],
+                "domain": tool_input["domain"],
+                "industry": tool_input.get("industry"),
+                "description": tool_input.get("description"),
+                "employee_count": tool_input.get("employee_count")
+            }
+
+            result = await self.mcp_registry.store.save_company(company_data)
+            return {"status": result, "company_id": company_data["id"]}
+
+        elif tool_name == "get_company":
+            company_id = tool_input["company_id"]
+            company = await self.mcp_registry.store.get_company(company_id)
+            return company or {"error": "Company not found"}
+
+        elif tool_name == "save_fact":
+            fact_data = {
+                "id": tool_input.get("fact_id", str(uuid.uuid4())),
+                "company_id": tool_input["company_id"],
+                "fact_type": tool_input["fact_type"],
+                "content": tool_input["content"],
+                "source_url": tool_input.get("source_url"),
+                "confidence_score": tool_input.get("confidence_score", 0.8)
+            }
+
+            result = await self.mcp_registry.store.save_fact(fact_data)
+            return {"status": result, "fact_id": fact_data["id"]}
+
+        elif tool_name == "save_contact":
+            contact_data = {
+                "id": tool_input.get("contact_id", str(uuid.uuid4())),
+                "company_id": tool_input["company_id"],
+                "email": tool_input["email"],
+                "first_name": tool_input.get("first_name"),
+                "last_name": tool_input.get("last_name"),
+                "title": tool_input.get("title"),
+                "seniority": tool_input.get("seniority")
+            }
+
+            result = await self.mcp_registry.store.save_contact(contact_data)
+            return {"status": result, "contact_id": contact_data["id"]}
+
+        elif tool_name == "list_contacts_by_domain":
+            domain = tool_input["domain"]
+            contacts = await self.mcp_registry.store.list_contacts_by_domain(domain)
+            return {
+                "contacts": contacts,
+                "count": len(contacts)
+            }
+
+        elif tool_name == "check_suppression":
+            supp_type = tool_input["suppression_type"]
+            value = tool_input["value"]
+
+            is_suppressed = await self.mcp_registry.store.check_suppression(supp_type, value)
+            return {
+                "suppressed": is_suppressed,
+                "value": value,
+                "type": supp_type
+            }
+
+        # ============ EMAIL MCP SERVER ============
+        elif tool_name == "send_email":
+            to = tool_input["to"]
+            subject = tool_input["subject"]
+            body = tool_input["body"]
+            prospect_id = tool_input["prospect_id"]
+
+            thread_id = await self.mcp_registry.email.send(to, subject, body, prospect_id)
+            return {
+                "status": "sent",
+                "thread_id": thread_id,
+                "to": to
+            }
+
+        elif tool_name == "get_email_thread":
+            prospect_id = tool_input["prospect_id"]
+            thread = await self.mcp_registry.email.get_thread(prospect_id)
+            return thread or {"error": "No email thread found"}
+
+        # ============ CALENDAR MCP SERVER ============
+        elif tool_name == "suggest_meeting_slots":
+            num_slots = tool_input.get("num_slots", 3)
+            slots = await self.mcp_registry.calendar.suggest_slots()
+            return {
+                "slots": slots[:num_slots],
+                "count": len(slots[:num_slots])
+            }
+
+        elif tool_name == "generate_calendar_invite":
+            start_time = tool_input["start_time"]
+            end_time = tool_input["end_time"]
+            title = tool_input["title"]
+
+            slot = {
+                "start_iso": start_time,
+                "end_iso": end_time,
+                "title": title
+            }
+
+            ics = await self.mcp_registry.calendar.generate_ics(slot)
+            return {
+                "ics_content": ics,
+                "meeting": slot
+            }
+
+        else:
+            raise ValueError(f"Unknown MCP tool: {tool_name}")

mcp/agents/autonomous_agent_ollama.py

@@ -0,0 +1,356 @@
+"""
+Autonomous AI Agent with MCP Tool Calling using Ollama Python Client
+
+Uses the ollama Python package for LLM inference.
+Based on: https://github.com/ollama/ollama-python
+
+Example usage (from the guide):
+    from ollama import chat
+    response = chat(
+        model='granite4:1b',
+        messages=[
+            {'role': 'system', 'content': 'You are a helpful assistant.'},
+            {'role': 'user', 'content': user_input}
+        ],
+        options={'temperature': 0.0, 'top_p': 1.0}
+    )
+    output = response.message.content
+"""
+
+import os
+import json
+import uuid
+import logging
+import asyncio
+from typing import List, Dict, Any, AsyncGenerator
+
+from mcp.tools.definitions import MCP_TOOLS
+from mcp.registry import MCPRegistry
+
+logger = logging.getLogger(__name__)
+
+# Default model - IBM Granite 4 1B
+DEFAULT_MODEL = "granite4:1b"
+
+
+class AutonomousMCPAgentOllama:
+    """
+    AI Agent using Ollama Python client (FREE local LLM)
+
+    Uses ollama.chat() directly as per the official documentation.
+    Temperature=0.0 and top_p=1.0 recommended for Granite family models.
+    """
+
+    def __init__(
+        self,
+        mcp_registry: MCPRegistry,
+        model: str = None
+    ):
+        self.mcp_registry = mcp_registry
+        self.model = model or os.getenv("OLLAMA_MODEL", DEFAULT_MODEL)
+        self.tools_description = self._build_tools_description()
+
+        logger.info(f"Ollama Agent initialized with model: {self.model}")
+
+    def _build_tools_description(self) -> str:
+        """Build tool descriptions for the system prompt"""
+        tools_text = ""
+        for tool in MCP_TOOLS:
+            tools_text += f"\n- **{tool['name']}**: {tool['description']}"
+            props = tool.get('input_schema', {}).get('properties', {})
+            required = tool.get('input_schema', {}).get('required', [])
+            if props:
+                tools_text += "\n  Parameters:"
+                for param, details in props.items():
+                    req = "(required)" if param in required else "(optional)"
+                    tools_text += f"\n    - {param} {req}: {details.get('description', '')}"
+        return tools_text
+
+    def _build_system_prompt(self) -> str:
+        return f"""You are an AI sales agent with access to tools.
+
+AVAILABLE TOOLS:
+{self.tools_description}
+
+TO USE A TOOL, respond with JSON:
+```json
+{{"tool": "tool_name", "parameters": {{"param1": "value1"}}}}
+```
+
+RULES:
+1. Use search_web to find information
+2. Use save_prospect, save_contact to store data
+3. Use send_email to draft emails
+4. Say "DONE" when finished with a summary
+
+Be concise."""
+
+    async def run(self, task: str, max_iterations: int = 15) -> AsyncGenerator[Dict[str, Any], None]:
+        """Run the agent on a task"""
+
+        yield {
+            "type": "agent_start",
+            "message": f"Starting with Ollama ({self.model})",
+            "model": self.model
+        }
+
+        system_prompt = self._build_system_prompt()
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": task}
+        ]
+
+        for iteration in range(1, max_iterations + 1):
+            yield {
+                "type": "iteration_start",
+                "iteration": iteration,
+                "message": f"Iteration {iteration}: Thinking..."
+            }
+
+            try:
+                # Call Ollama using the Python client
+                response = await self._call_ollama(messages)
+                assistant_content = response.get("content", "")
+
+                if not assistant_content:
+                    continue
+
+                # Check for completion
+                if "DONE" in assistant_content.upper():
+                    final_text = assistant_content.replace("DONE", "").replace("done", "").strip()
+                    yield {
+                        "type": "thought",
+                        "thought": final_text,
+                        "message": "Task complete"
+                    }
+                    yield {
+                        "type": "agent_complete",
+                        "message": "Task complete!",
+                        "final_answer": final_text,
+                        "iterations": iteration
+                    }
+                    return
+
+                # Parse tool calls
+                tool_calls = self._parse_tool_calls(assistant_content)
+
+                if tool_calls:
+                    messages.append({"role": "assistant", "content": assistant_content})
+                    tool_results = []
+
+                    for tool_call in tool_calls:
+                        tool_name = tool_call.get("tool", "")
+                        tool_params = tool_call.get("parameters", {})
+
+                        yield {
+                            "type": "tool_call",
+                            "tool": tool_name,
+                            "input": tool_params,
+                            "message": f"Calling: {tool_name}"
+                        }
+
+                        try:
+                            result = await self._execute_tool(tool_name, tool_params)
+                            yield {
+                                "type": "tool_result",
+                                "tool": tool_name,
+                                "result": result,
+                                "message": f"{tool_name} completed"
+                            }
+                            tool_results.append({"tool": tool_name, "result": result})
+                        except Exception as e:
+                            yield {
+                                "type": "tool_error",
+                                "tool": tool_name,
+                                "error": str(e)
+                            }
+                            tool_results.append({"tool": tool_name, "error": str(e)})
+
+                    # Add results to conversation
+                    results_text = "Tool results:\n" + json.dumps(tool_results, indent=2, default=str)[:2000]
+                    messages.append({"role": "user", "content": results_text})
+                else:
+                    # No tool calls
+                    yield {
+                        "type": "thought",
+                        "thought": assistant_content,
+                        "message": f"AI: {assistant_content[:100]}..."
+                    }
+                    messages.append({"role": "assistant", "content": assistant_content})
+                    messages.append({"role": "user", "content": "Continue. Use tools to complete the task. Say DONE when finished."})
+
+            except Exception as e:
+                logger.error(f"Error: {e}")
+                yield {
+                    "type": "agent_error",
+                    "error": str(e),
+                    "message": f"Error: {e}"
+                }
+                return
+
+        yield {
+            "type": "agent_max_iterations",
+            "message": f"Reached max iterations ({max_iterations})",
+            "iterations": max_iterations
+        }
+
+    async def _call_ollama(self, messages: List[Dict]) -> Dict:
+        """
+        Call Ollama using the official Python client.
+
+        Uses ollama.chat() directly as per the guide:
+        https://github.com/ollama/ollama-python
+
+        Temperature=0.0 and top_p=1.0 recommended for Granite models.
+        """
+        try:
+            from ollama import chat, ResponseError
+        except ImportError:
+            raise ImportError("ollama package not installed. Run: pip install ollama")
+
+        try:
+            # Use ollama.chat() directly as shown in the guide
+            # Run in executor to not block the async event loop
+            loop = asyncio.get_event_loop()
+            response = await loop.run_in_executor(
+                None,
+                lambda: chat(
+                    model=self.model,
+                    messages=messages,
+                    options={
+                        "temperature": 0.0,  # Deterministic output for tool calling
+                        "top_p": 1.0         # Full probability mass (Granite recommended)
+                    }
+                )
+            )
+
+            # Extract response content: response.message.content
+            content = ""
+            if hasattr(response, 'message') and hasattr(response.message, 'content'):
+                content = response.message.content
+            elif isinstance(response, dict):
+                content = response.get("message", {}).get("content", "")
+
+            return {"content": content}
+
+        except ResponseError as e:
+            # Handle Ollama-specific errors (model not available, etc.)
+            logger.error(f"Ollama ResponseError: {e}")
+            raise Exception(f"Ollama error: {e}. Make sure Ollama is running and the model '{self.model}' is pulled.")
+        except Exception as e:
+            logger.error(f"Ollama call failed: {e}")
+            raise Exception(f"Ollama error: {e}")
+
+    def _parse_tool_calls(self, text: str) -> List[Dict]:
+        """Parse tool calls from response"""
+        import re
+
+        tool_calls = []
+        patterns = [
+            r'```json\s*(\{[^`]+\})\s*```',
+            r'```\s*(\{[^`]+\})\s*```',
+            r'(\{"tool":\s*"[^"]+",\s*"parameters":\s*\{[^}]*\}\})',
+        ]
+
+        for pattern in patterns:
+            matches = re.findall(pattern, text, re.DOTALL)
+            for match in matches:
+                try:
+                    data = json.loads(match.strip())
+                    if "tool" in data:
+                        tool_calls.append(data)
+                except:
+                    continue
+
+        return tool_calls
+
+    async def _execute_tool(self, tool_name: str, tool_input: Dict[str, Any]) -> Any:
+        """Execute an MCP tool"""
+
+        if tool_name == "search_web":
+            query = tool_input.get("query", "")
+            max_results = tool_input.get("max_results", 5)
+            results = await self.mcp_registry.search.query(query, max_results=max_results)
+            return {"results": results[:max_results], "count": len(results[:max_results])}
+
+        elif tool_name == "search_news":
+            query = tool_input.get("query", "")
+            max_results = tool_input.get("max_results", 5)
+            results = await self.mcp_registry.search.query(f"{query} news", max_results=max_results)
+            return {"results": results[:max_results], "count": len(results[:max_results])}
+
+        elif tool_name == "save_prospect":
+            prospect_data = {
+                "id": tool_input.get("prospect_id", str(uuid.uuid4())),
+                "company": {
+                    "id": tool_input.get("company_id"),
+                    "name": tool_input.get("company_name"),
+                    "domain": tool_input.get("company_domain")
+                },
+                "fit_score": tool_input.get("fit_score", 0),
+                "status": tool_input.get("status", "new"),
+                "metadata": tool_input.get("metadata", {})
+            }
+            result = await self.mcp_registry.store.save_prospect(prospect_data)
+            return {"status": result, "prospect_id": prospect_data["id"]}
+
+        elif tool_name == "save_company":
+            company_data = {
+                "id": tool_input.get("company_id", str(uuid.uuid4())),
+                "name": tool_input.get("name", ""),
+                "domain": tool_input.get("domain", ""),
+                "industry": tool_input.get("industry"),
+                "description": tool_input.get("description"),
+                "employee_count": tool_input.get("employee_count")
+            }
+            result = await self.mcp_registry.store.save_company(company_data)
+            return {"status": result, "company_id": company_data["id"]}
+
+        elif tool_name == "save_contact":
+            contact_data = {
+                "id": tool_input.get("contact_id", str(uuid.uuid4())),
+                "company_id": tool_input.get("company_id", ""),
+                "email": tool_input.get("email", ""),
+                "first_name": tool_input.get("first_name"),
+                "last_name": tool_input.get("last_name"),
+                "title": tool_input.get("title"),
+                "seniority": tool_input.get("seniority")
+            }
+            result = await self.mcp_registry.store.save_contact(contact_data)
+            return {"status": result, "contact_id": contact_data["id"]}
+
+        elif tool_name == "save_fact":
+            fact_data = {
+                "id": tool_input.get("fact_id", str(uuid.uuid4())),
+                "company_id": tool_input.get("company_id", ""),
+                "fact_type": tool_input.get("fact_type", ""),
+                "content": tool_input.get("content", ""),
+                "source_url": tool_input.get("source_url"),
+                "confidence_score": tool_input.get("confidence_score", 0.8)
+            }
+            result = await self.mcp_registry.store.save_fact(fact_data)
+            return {"status": result, "fact_id": fact_data["id"]}
+
+        elif tool_name == "send_email":
+            to = tool_input.get("to", "")
+            subject = tool_input.get("subject", "")
+            body = tool_input.get("body", "")
+            prospect_id = tool_input.get("prospect_id", "")
+            thread_id = await self.mcp_registry.email.send(to, subject, body, prospect_id)
+            return {"status": "drafted", "thread_id": thread_id, "to": to}
+
+        elif tool_name == "list_prospects":
+            prospects = await self.mcp_registry.store.list_prospects()
+            return {"prospects": prospects, "count": len(prospects)}
+
+        elif tool_name == "get_prospect":
+            prospect_id = tool_input.get("prospect_id", "")
+            prospect = await self.mcp_registry.store.get_prospect(prospect_id)
+            return prospect or {"error": "Not found"}
+
+        elif tool_name == "suggest_meeting_slots":
+            slots = await self.mcp_registry.calendar.suggest_slots()
+            return {"slots": slots[:3], "count": len(slots[:3])}
+
+        else:
+            raise ValueError(f"Unknown tool: {tool_name}")

mcp/agents/autonomous_agent_transformers.py

@@ -0,0 +1,609 @@
+"""
+Autonomous AI Agent with MCP Tool Calling using Local Transformers
+
+This agent uses Hugging Face Transformers library to run models locally,
+avoiding inference API delays and availability issues.
+
+Uses Qwen3-0.6B for fast, local inference with tool calling support.
+"""
+
+import os
+import json
+import uuid
+import logging
+import asyncio
+import re
+from typing import List, Dict, Any, AsyncGenerator, Optional
+
+from mcp.tools.definitions import MCP_TOOLS, list_all_tools
+from mcp.registry import MCPRegistry
+
+logger = logging.getLogger(__name__)
+
+# Default model - small but capable
+DEFAULT_MODEL = "Qwen/Qwen3-0.6B"
+
+
+class AutonomousMCPAgentTransformers:
+    """
+    AI Agent that autonomously uses MCP servers as tools using local Transformers.
+
+    Runs models locally for fast, reliable inference without API dependencies.
+    """
+
+    def __init__(
+        self,
+        mcp_registry: MCPRegistry,
+        model_name: str = None,
+        device: str = None
+    ):
+        """
+        Initialize the autonomous agent with local Transformers
+
+        Args:
+            mcp_registry: MCP registry with all servers
+            model_name: Model to use (default: Qwen/Qwen3-0.6B)
+            device: Device to run on ('cuda', 'cpu', or 'auto')
+        """
+        self.mcp_registry = mcp_registry
+        self.model_name = model_name or os.getenv("TRANSFORMERS_MODEL", DEFAULT_MODEL)
+        self.device = device or os.getenv("TRANSFORMERS_DEVICE", "auto")
+
+        # Lazy load model and tokenizer
+        self.pipeline = None
+        self.tokenizer = None
+        self.model = None
+        self._initialized = False
+
+        # Create tool definitions for the prompt
+        self.tools_description = self._create_tools_description()
+
+        logger.info(f"Autonomous MCP Agent (Transformers) initialized")
+        logger.info(f"  Model: {self.model_name}")
+        logger.info(f"  Device: {self.device}")
+        logger.info(f"  Available tools: {len(MCP_TOOLS)}")
+
+    def _initialize_model(self):
+        """Lazy initialization of the model"""
+        if self._initialized:
+            return
+
+        logger.info(f"Loading model {self.model_name}...")
+
+        try:
+            from transformers import pipeline, AutoTokenizer, AutoModelForCausalLM
+            import torch
+
+            # Determine device
+            if self.device == "auto":
+                device = "cuda" if torch.cuda.is_available() else "cpu"
+            else:
+                device = self.device
+
+            logger.info(f"Using device: {device}")
+
+            # Load tokenizer
+            self.tokenizer = AutoTokenizer.from_pretrained(
+                self.model_name,
+                trust_remote_code=True
+            )
+
+            # Load model with appropriate settings
+            model_kwargs = {
+                "trust_remote_code": True,
+            }
+
+            if device == "cuda":
+                model_kwargs["torch_dtype"] = torch.float16
+                model_kwargs["device_map"] = "auto"
+            else:
+                model_kwargs["torch_dtype"] = torch.float32
+
+            self.model = AutoModelForCausalLM.from_pretrained(
+                self.model_name,
+                **model_kwargs
+            )
+
+            if device == "cpu":
+                self.model = self.model.to(device)
+
+            # Create pipeline for easier generation
+            self.pipeline = pipeline(
+                "text-generation",
+                model=self.model,
+                tokenizer=self.tokenizer,
+                device=None if device == "cuda" else device,  # device_map handles cuda
+            )
+
+            self._initialized = True
+            logger.info(f"Model {self.model_name} loaded successfully")
+
+        except ImportError as e:
+            raise ImportError(
+                f"transformers package not installed or missing dependencies!\n"
+                f"Install with: pip install transformers torch\n"
+                f"Error: {e}"
+            )
+        except Exception as e:
+            logger.error(f"Failed to load model: {e}")
+            raise
+
+    def _create_tools_description(self) -> str:
+        """Create a description of available tools for the prompt"""
+        tools_text = "Available tools:\n\n"
+
+        for tool in MCP_TOOLS:
+            tools_text += f"- **{tool['name']}**: {tool['description']}\n"
+            if tool.get('input_schema', {}).get('properties'):
+                tools_text += "  Parameters:\n"
+                for param, details in tool['input_schema']['properties'].items():
+                    required = param in tool['input_schema'].get('required', [])
+                    req_str = " (required)" if required else " (optional)"
+                    tools_text += f"    - {param}{req_str}: {details.get('description', '')}\n"
+            tools_text += "\n"
+
+        return tools_text
+
+    def _build_system_prompt(self) -> str:
+        """Build the system prompt with tool instructions"""
+        return f"""You are an autonomous AI agent for B2B sales automation.
+
+You have access to MCP (Model Context Protocol) tools that let you:
+- Search the web for company information and news
+- Save prospects, companies, contacts, and facts to a database
+- Send emails and manage email threads
+- Schedule meetings and generate calendar invites
+
+{self.tools_description}
+
+To use a tool, respond with a JSON block in this exact format:
+```tool
+{{"tool": "tool_name", "parameters": {{"param1": "value1", "param2": "value2"}}}}
+```
+
+You can call multiple tools by including multiple tool blocks.
+
+After using tools and gathering information, provide your final response.
+When the task is complete, end with "TASK_COMPLETE" on a new line.
+
+Be concise and efficient. Focus on completing the task."""
+
+    def _parse_tool_calls(self, response: str) -> List[Dict[str, Any]]:
+        """Parse tool calls from the model's response"""
+        tool_calls = []
+
+        # Pattern to match tool JSON blocks
+        # Match ```tool ... ``` or ```json ... ``` or just JSON objects with "tool" key
+        patterns = [
+            r'```tool\s*\n?(.*?)\n?```',
+            r'```json\s*\n?(.*?)\n?```',
+            r'\{"tool":\s*"[^"]+",\s*"parameters":\s*\{[^}]*\}\}',
+        ]
+
+        for pattern in patterns[:2]:  # First two patterns use groups
+            matches = re.findall(pattern, response, re.DOTALL | re.IGNORECASE)
+            for match in matches:
+                try:
+                    tool_data = json.loads(match.strip())
+                    if "tool" in tool_data:
+                        tool_calls.append(tool_data)
+                except json.JSONDecodeError:
+                    continue
+
+        # Try direct JSON pattern
+        direct_matches = re.findall(patterns[2], response)
+        for match in direct_matches:
+            try:
+                tool_data = json.loads(match)
+                if tool_data not in tool_calls:  # Avoid duplicates
+                    tool_calls.append(tool_data)
+            except json.JSONDecodeError:
+                continue
+
+        return tool_calls
+
+    def _generate_response(self, messages: List[Dict[str, str]], max_new_tokens: int = 512) -> str:
+        """Generate a response from the model"""
+        self._initialize_model()
+
+        try:
+            # Apply chat template
+            inputs = self.tokenizer.apply_chat_template(
+                messages,
+                add_generation_prompt=True,
+                tokenize=True,
+                return_dict=True,
+                return_tensors="pt",
+            )
+
+            # Move to model device
+            if hasattr(self.model, 'device'):
+                inputs = {k: v.to(self.model.device) for k, v in inputs.items()}
+
+            # Generate
+            outputs = self.model.generate(
+                **inputs,
+                max_new_tokens=max_new_tokens,
+                do_sample=True,
+                temperature=0.7,
+                top_p=0.9,
+                pad_token_id=self.tokenizer.eos_token_id,
+            )
+
+            # Decode only the new tokens
+            input_length = inputs["input_ids"].shape[-1]
+            response = self.tokenizer.decode(
+                outputs[0][input_length:],
+                skip_special_tokens=True
+            )
+
+            return response.strip()
+
+        except Exception as e:
+            logger.error(f"Generation error: {e}")
+            raise
+
+    async def run(
+        self,
+        task: str,
+        max_iterations: int = 10
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """
+        Run the agent autonomously on a task.
+
+        Args:
+            task: The task to complete
+            max_iterations: Maximum tool calls to prevent infinite loops
+
+        Yields:
+            Events showing agent's progress and tool calls
+        """
+
+        yield {
+            "type": "agent_start",
+            "message": f"Autonomous AI Agent (Transformers) starting task",
+            "task": task,
+            "model": self.model_name
+        }
+
+        # Initialize model (lazy load)
+        try:
+            self._initialize_model()
+            yield {
+                "type": "model_loaded",
+                "message": f"Model {self.model_name} ready"
+            }
+        except Exception as e:
+            yield {
+                "type": "agent_error",
+                "error": str(e),
+                "message": f"Failed to load model: {e}"
+            }
+            return
+
+        # Build conversation
+        system_prompt = self._build_system_prompt()
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": task}
+        ]
+
+        iteration = 0
+        accumulated_results = []
+
+        while iteration < max_iterations:
+            iteration += 1
+
+            yield {
+                "type": "iteration_start",
+                "iteration": iteration,
+                "message": f"Iteration {iteration}: Thinking..."
+            }
+
+            try:
+                # Generate response
+                response = await asyncio.get_event_loop().run_in_executor(
+                    None,
+                    self._generate_response,
+                    messages,
+                    512
+                )
+
+                logger.info(f"Model response (iteration {iteration}): {response[:200]}...")
+
+                # Check for task completion
+                if "TASK_COMPLETE" in response:
+                    # Extract final answer (everything before TASK_COMPLETE)
+                    final_answer = response.replace("TASK_COMPLETE", "").strip()
+
+                    yield {
+                        "type": "thought",
+                        "thought": final_answer,
+                        "message": f"AI Response: {final_answer[:100]}..."
+                    }
+
+                    yield {
+                        "type": "agent_complete",
+                        "message": "Task complete!",
+                        "final_answer": final_answer,
+                        "iterations": iteration
+                    }
+                    return
+
+                # Parse tool calls
+                tool_calls = self._parse_tool_calls(response)
+
+                if tool_calls:
+                    # Execute each tool call
+                    tool_results = []
+
+                    for tool_call in tool_calls:
+                        tool_name = tool_call.get("tool", "")
+                        tool_params = tool_call.get("parameters", {})
+
+                        yield {
+                            "type": "tool_call",
+                            "tool": tool_name,
+                            "input": tool_params,
+                            "message": f"Action: {tool_name}"
+                        }
+
+                        try:
+                            result = await self._execute_mcp_tool(tool_name, tool_params)
+
+                            yield {
+                                "type": "tool_result",
+                                "tool": tool_name,
+                                "result": result,
+                                "message": f"Tool {tool_name} completed"
+                            }
+
+                            tool_results.append({
+                                "tool": tool_name,
+                                "result": result
+                            })
+                            accumulated_results.append({
+                                "tool": tool_name,
+                                "params": tool_params,
+                                "result": result
+                            })
+
+                        except Exception as e:
+                            error_msg = str(e)
+                            logger.error(f"Tool execution failed: {tool_name} - {error_msg}")
+
+                            yield {
+                                "type": "tool_error",
+                                "tool": tool_name,
+                                "error": error_msg,
+                                "message": f"Tool {tool_name} failed: {error_msg}"
+                            }
+
+                            tool_results.append({
+                                "tool": tool_name,
+                                "error": error_msg
+                            })
+
+                    # Add assistant response and tool results to conversation
+                    messages.append({"role": "assistant", "content": response})
+
+                    # Format tool results for the model
+                    results_text = "Tool results:\n"
+                    for tr in tool_results:
+                        if "error" in tr:
+                            results_text += f"- {tr['tool']}: Error - {tr['error']}\n"
+                        else:
+                            result_str = json.dumps(tr['result'], default=str)[:500]
+                            results_text += f"- {tr['tool']}: {result_str}\n"
+
+                    messages.append({"role": "user", "content": results_text})
+
+                else:
+                    # No tool calls - this might be a thought or partial response
+                    yield {
+                        "type": "thought",
+                        "thought": response,
+                        "message": f"AI Response: {response[:100]}..."
+                    }
+
+                    # Add to conversation and prompt for continuation
+                    messages.append({"role": "assistant", "content": response})
+                    messages.append({
+                        "role": "user",
+                        "content": "Continue with the task. Use the available tools to gather information and complete the task. When done, say TASK_COMPLETE."
+                    })
+
+            except Exception as e:
+                error_msg = str(e)
+                logger.error(f"Error in iteration {iteration}: {error_msg}", exc_info=True)
+
+                yield {
+                    "type": "agent_error",
+                    "error": error_msg,
+                    "message": f"Error: {error_msg}"
+                }
+
+                # Try to continue if we have results
+                if accumulated_results:
+                    break
+                return
+
+        # Max iterations reached
+        yield {
+            "type": "agent_max_iterations",
+            "message": f"Reached maximum iterations ({max_iterations})",
+            "iterations": iteration,
+            "accumulated_results": accumulated_results
+        }
+
+    async def _execute_mcp_tool(self, tool_name: str, tool_input: Dict[str, Any]) -> Any:
+        """
+        Execute an MCP tool by routing to the appropriate MCP server.
+        """
+
+        # ============ SEARCH MCP SERVER ============
+        if tool_name == "search_web":
+            query = tool_input.get("query", "")
+            max_results = tool_input.get("max_results", 5)
+
+            results = await self.mcp_registry.search.query(query, max_results=max_results)
+            return {
+                "results": results[:max_results],
+                "count": len(results[:max_results])
+            }
+
+        elif tool_name == "search_news":
+            query = tool_input.get("query", "")
+            max_results = tool_input.get("max_results", 5)
+
+            results = await self.mcp_registry.search.query(f"{query} news", max_results=max_results)
+            return {
+                "results": results[:max_results],
+                "count": len(results[:max_results])
+            }
+
+        # ============ STORE MCP SERVER ============
+        elif tool_name == "save_prospect":
+            prospect_data = {
+                "id": tool_input.get("prospect_id", str(uuid.uuid4())),
+                "company": {
+                    "id": tool_input.get("company_id"),
+                    "name": tool_input.get("company_name"),
+                    "domain": tool_input.get("company_domain")
+                },
+                "fit_score": tool_input.get("fit_score", 0),
+                "status": tool_input.get("status", "new"),
+                "metadata": tool_input.get("metadata", {})
+            }
+
+            result = await self.mcp_registry.store.save_prospect(prospect_data)
+            return {"status": result, "prospect_id": prospect_data["id"]}
+
+        elif tool_name == "get_prospect":
+            prospect_id = tool_input.get("prospect_id", "")
+            prospect = await self.mcp_registry.store.get_prospect(prospect_id)
+            return prospect or {"error": "Prospect not found"}
+
+        elif tool_name == "list_prospects":
+            prospects = await self.mcp_registry.store.list_prospects()
+            status_filter = tool_input.get("status")
+
+            if status_filter:
+                prospects = [p for p in prospects if p.get("status") == status_filter]
+
+            return {
+                "prospects": prospects,
+                "count": len(prospects)
+            }
+
+        elif tool_name == "save_company":
+            company_data = {
+                "id": tool_input.get("company_id", str(uuid.uuid4())),
+                "name": tool_input.get("name", ""),
+                "domain": tool_input.get("domain", ""),
+                "industry": tool_input.get("industry"),
+                "description": tool_input.get("description"),
+                "employee_count": tool_input.get("employee_count")
+            }
+
+            result = await self.mcp_registry.store.save_company(company_data)
+            return {"status": result, "company_id": company_data["id"]}
+
+        elif tool_name == "get_company":
+            company_id = tool_input.get("company_id", "")
+            company = await self.mcp_registry.store.get_company(company_id)
+            return company or {"error": "Company not found"}
+
+        elif tool_name == "save_fact":
+            fact_data = {
+                "id": tool_input.get("fact_id", str(uuid.uuid4())),
+                "company_id": tool_input.get("company_id", ""),
+                "fact_type": tool_input.get("fact_type", ""),
+                "content": tool_input.get("content", ""),
+                "source_url": tool_input.get("source_url"),
+                "confidence_score": tool_input.get("confidence_score", 0.8)
+            }
+
+            result = await self.mcp_registry.store.save_fact(fact_data)
+            return {"status": result, "fact_id": fact_data["id"]}
+
+        elif tool_name == "save_contact":
+            contact_data = {
+                "id": tool_input.get("contact_id", str(uuid.uuid4())),
+                "company_id": tool_input.get("company_id", ""),
+                "email": tool_input.get("email", ""),
+                "first_name": tool_input.get("first_name"),
+                "last_name": tool_input.get("last_name"),
+                "title": tool_input.get("title"),
+                "seniority": tool_input.get("seniority")
+            }
+
+            result = await self.mcp_registry.store.save_contact(contact_data)
+            return {"status": result, "contact_id": contact_data["id"]}
+
+        elif tool_name == "list_contacts_by_domain":
+            domain = tool_input.get("domain", "")
+            contacts = await self.mcp_registry.store.list_contacts_by_domain(domain)
+            return {
+                "contacts": contacts,
+                "count": len(contacts)
+            }
+
+        elif tool_name == "check_suppression":
+            supp_type = tool_input.get("suppression_type", "email")
+            value = tool_input.get("value", "")
+
+            is_suppressed = await self.mcp_registry.store.check_suppression(supp_type, value)
+            return {
+                "suppressed": is_suppressed,
+                "value": value,
+                "type": supp_type
+            }
+
+        # ============ EMAIL MCP SERVER ============
+        elif tool_name == "send_email":
+            to = tool_input.get("to", "")
+            subject = tool_input.get("subject", "")
+            body = tool_input.get("body", "")
+            prospect_id = tool_input.get("prospect_id", "")
+
+            thread_id = await self.mcp_registry.email.send(to, subject, body, prospect_id)
+            return {
+                "status": "sent",
+                "thread_id": thread_id,
+                "to": to
+            }
+
+        elif tool_name == "get_email_thread":
+            prospect_id = tool_input.get("prospect_id", "")
+            thread = await self.mcp_registry.email.get_thread(prospect_id)
+            return thread or {"error": "No email thread found"}
+
+        # ============ CALENDAR MCP SERVER ============
+        elif tool_name == "suggest_meeting_slots":
+            num_slots = tool_input.get("num_slots", 3)
+            slots = await self.mcp_registry.calendar.suggest_slots()
+            return {
+                "slots": slots[:num_slots],
+                "count": len(slots[:num_slots])
+            }
+
+        elif tool_name == "generate_calendar_invite":
+            start_time = tool_input.get("start_time", "")
+            end_time = tool_input.get("end_time", "")
+            title = tool_input.get("title", "Meeting")
+
+            slot = {
+                "start_iso": start_time,
+                "end_iso": end_time,
+                "title": title
+            }
+
+            ics = await self.mcp_registry.calendar.generate_ics(slot)
+            return {
+                "ics_content": ics,
+                "meeting": slot
+            }
+
+        else:
+            raise ValueError(f"Unknown MCP tool: {tool_name}")

mcp/auth/__init__.py

@@ -0,0 +1,40 @@
+"""
+Enterprise Authentication and Authorization Module for MCP Servers
+
+Provides:
+- API key authentication
+- Request signing
+- Rate limiting
+- RBAC (Role-Based Access Control)
+"""
+
+from .api_key_auth import (
+    APIKey,
+    APIKeyManager,
+    APIKeyAuthMiddleware,
+    RequestSigningAuth,
+    get_key_manager
+)
+
+from .rate_limiter import (
+    TokenBucket,
+    RateLimiter,
+    RateLimitMiddleware,
+    RedisRateLimiter,
+    get_rate_limiter
+)
+
+__all__ = [
+    # API Key Auth
+    'APIKey',
+    'APIKeyManager',
+    'APIKeyAuthMiddleware',
+    'RequestSigningAuth',
+    'get_key_manager',
+    # Rate Limiting
+    'TokenBucket',
+    'RateLimiter',
+    'RateLimitMiddleware',
+    'RedisRateLimiter',
+    'get_rate_limiter',
+]

mcp/auth/api_key_auth.py

@@ -0,0 +1,377 @@
+"""
+Enterprise API Key Authentication System for MCP Servers
+
+Features:
+- API key generation and validation
+- Key rotation support
+- Expiry and rate limiting per key
+- Audit logging of authentication attempts
+- Multiple authentication methods (header, query param)
+"""
+import os
+import secrets
+import hashlib
+import hmac
+import logging
+from typing import Optional, Dict, Set, Tuple
+from datetime import datetime, timedelta
+from dataclasses import dataclass
+from aiohttp import web
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class APIKey:
+    """API Key with metadata"""
+    key_id: str
+    key_hash: str  # Hashed version of the key
+    name: str
+    tenant_id: Optional[str] = None
+    created_at: datetime = None
+    expires_at: Optional[datetime] = None
+    is_active: bool = True
+    permissions: Set[str] = None
+    rate_limit: int = 100  # requests per minute
+    metadata: Dict = None
+
+    def __post_init__(self):
+        if self.created_at is None:
+            self.created_at = datetime.utcnow()
+        if self.permissions is None:
+            self.permissions = set()
+        if self.metadata is None:
+            self.metadata = {}
+
+    def is_expired(self) -> bool:
+        """Check if key is expired"""
+        if self.expires_at is None:
+            return False
+        return datetime.utcnow() > self.expires_at
+
+    def is_valid(self) -> bool:
+        """Check if key is valid"""
+        return self.is_active and not self.is_expired()
+
+
+class APIKeyManager:
+    """
+    API Key Manager with secure key storage and validation
+    """
+
+    def __init__(self):
+        self.keys: Dict[str, APIKey] = {}
+        self._load_keys_from_env()
+        logger.info(f"API Key Manager initialized with {len(self.keys)} keys")
+
+    def _load_keys_from_env(self):
+        """Load API keys from environment variables"""
+        # Primary API key
+        primary_key = os.getenv("MCP_API_KEY")
+        if primary_key:
+            key_id = "primary"
+            key_hash = self._hash_key(primary_key)
+            self.keys[key_hash] = APIKey(
+                key_id=key_id,
+                key_hash=key_hash,
+                name="Primary API Key",
+                is_active=True,
+                permissions={"*"},  # All permissions
+                rate_limit=1000
+            )
+            logger.info("Loaded primary API key from environment")
+
+        # Additional keys (comma-separated)
+        additional_keys = os.getenv("MCP_API_KEYS", "")
+        if additional_keys:
+            for idx, key in enumerate(additional_keys.split(",")):
+                key = key.strip()
+                if key:
+                    key_id = f"key_{idx + 1}"
+                    key_hash = self._hash_key(key)
+                    self.keys[key_hash] = APIKey(
+                        key_id=key_id,
+                        key_hash=key_hash,
+                        name=f"API Key {idx + 1}",
+                        is_active=True,
+                        permissions={"*"},
+                        rate_limit=100
+                    )
+            logger.info(f"Loaded {len(additional_keys.split(','))} additional API keys")
+
+    @staticmethod
+    def generate_api_key() -> str:
+        """
+        Generate a secure API key
+        Format: mcp_<32-char-hex>
+        """
+        random_bytes = secrets.token_bytes(32)
+        key_hex = random_bytes.hex()
+        return f"mcp_{key_hex}"
+
+    @staticmethod
+    def _hash_key(key: str) -> str:
+        """Hash an API key using SHA-256"""
+        return hashlib.sha256(key.encode()).hexdigest()
+
+    def create_key(
+        self,
+        name: str,
+        tenant_id: Optional[str] = None,
+        expires_in_days: Optional[int] = None,
+        permissions: Set[str] = None,
+        rate_limit: int = 100
+    ) -> Tuple[str, APIKey]:
+        """
+        Create a new API key
+
+        Returns:
+            Tuple of (plain_key, api_key_object)
+        """
+        plain_key = self.generate_api_key()
+        key_hash = self._hash_key(plain_key)
+
+        expires_at = None
+        if expires_in_days:
+            expires_at = datetime.utcnow() + timedelta(days=expires_in_days)
+
+        api_key = APIKey(
+            key_id=f"key_{len(self.keys) + 1}",
+            key_hash=key_hash,
+            name=name,
+            tenant_id=tenant_id,
+            expires_at=expires_at,
+            permissions=permissions or {"*"},
+            rate_limit=rate_limit
+        )
+
+        self.keys[key_hash] = api_key
+        logger.info(f"Created new API key: {api_key.key_id} for {name}")
+
+        return plain_key, api_key
+
+    def validate_key(self, plain_key: str) -> Optional[APIKey]:
+        """
+        Validate an API key
+
+        Returns:
+            APIKey object if valid, None otherwise
+        """
+        if not plain_key:
+            return None
+
+        key_hash = self._hash_key(plain_key)
+        api_key = self.keys.get(key_hash)
+
+        if not api_key:
+            logger.warning("Invalid API key provided")
+            return None
+
+        if not api_key.is_valid():
+            logger.warning(f"Expired or inactive API key: {api_key.key_id}")
+            return None
+
+        return api_key
+
+    def revoke_key(self, key_hash: str):
+        """Revoke an API key"""
+        if key_hash in self.keys:
+            self.keys[key_hash].is_active = False
+            logger.info(f"Revoked API key: {self.keys[key_hash].key_id}")
+
+    def list_keys(self) -> list[APIKey]:
+        """List all API keys"""
+        return list(self.keys.values())
+
+
+class APIKeyAuthMiddleware:
+    """
+    aiohttp middleware for API key authentication
+    """
+
+    def __init__(self, key_manager: APIKeyManager, exempt_paths: Set[str] = None):
+        self.key_manager = key_manager
+        self.exempt_paths = exempt_paths or {"/health", "/metrics"}
+        logger.info("API Key Auth Middleware initialized")
+
+    @web.middleware
+    async def middleware(self, request: web.Request, handler):
+        """Middleware handler"""
+
+        # Skip authentication for exempt paths
+        if request.path in self.exempt_paths:
+            return await handler(request)
+
+        # Extract API key from request
+        api_key = self._extract_api_key(request)
+
+        if not api_key:
+            logger.warning(f"No API key provided for {request.path}")
+            return web.json_response(
+                {"error": "Authentication required", "message": "API key missing"},
+                status=401
+            )
+
+        # Validate API key
+        key_obj = self.key_manager.validate_key(api_key)
+
+        if not key_obj:
+            logger.warning(f"Invalid API key for {request.path}")
+            return web.json_response(
+                {"error": "Authentication failed", "message": "Invalid or expired API key"},
+                status=401
+            )
+
+        # Check permissions (if needed)
+        # TODO: Implement permission checking based on request path
+
+        # Attach key info to request for downstream use
+        request["api_key"] = key_obj
+        request["tenant_id"] = key_obj.tenant_id
+
+        logger.debug(f"Authenticated request: {request.path} with key {key_obj.key_id}")
+
+        return await handler(request)
+
+    def _extract_api_key(self, request: web.Request) -> Optional[str]:
+        """
+        Extract API key from request
+
+        Supports:
+        - X-API-Key header
+        - Authorization: Bearer <key> header
+        - api_key query parameter
+        """
+        # Try X-API-Key header
+        api_key = request.headers.get("X-API-Key")
+        if api_key:
+            return api_key
+
+        # Try Authorization: Bearer header
+        auth_header = request.headers.get("Authorization")
+        if auth_header and auth_header.startswith("Bearer "):
+            return auth_header[7:]  # Remove "Bearer " prefix
+
+        # Try query parameter (less secure, should be avoided in production)
+        api_key = request.query.get("api_key")
+        if api_key:
+            logger.warning("API key provided via query parameter (insecure)")
+            return api_key
+
+        return None
+
+
+class RequestSigningAuth:
+    """
+    Request signing authentication using HMAC
+    More secure than API keys alone
+    """
+
+    def __init__(self, secret_key: Optional[str] = None):
+        self.secret_key = secret_key or os.getenv("MCP_SECRET_KEY", "")
+        if not self.secret_key:
+            logger.warning("No secret key provided for request signing")
+
+    def sign_request(self, method: str, path: str, body: str, timestamp: str) -> str:
+        """
+        Sign a request using HMAC-SHA256
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            path: Request path
+            body: Request body (JSON string)
+            timestamp: ISO timestamp
+
+        Returns:
+            HMAC signature (hex string)
+        """
+        message = f"{method}|{path}|{body}|{timestamp}"
+        signature = hmac.new(
+            self.secret_key.encode(),
+            message.encode(),
+            hashlib.sha256
+        ).hexdigest()
+        return signature
+
+    def verify_signature(
+        self,
+        method: str,
+        path: str,
+        body: str,
+        timestamp: str,
+        signature: str
+    ) -> bool:
+        """
+        Verify request signature
+
+        Returns:
+            True if signature is valid, False otherwise
+        """
+        # Check timestamp (prevent replay attacks)
+        try:
+            request_time = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+            time_diff = abs((datetime.utcnow() - request_time).total_seconds())
+
+            # Reject requests older than 5 minutes
+            if time_diff > 300:
+                logger.warning(f"Request timestamp too old: {time_diff}s")
+                return False
+        except Exception as e:
+            logger.error(f"Invalid timestamp format: {e}")
+            return False
+
+        # Verify signature
+        expected_signature = self.sign_request(method, path, body, timestamp)
+        return hmac.compare_digest(expected_signature, signature)
+
+    @web.middleware
+    async def middleware(self, request: web.Request, handler):
+        """Middleware for request signing verification"""
+
+        # Skip health check and metrics
+        if request.path in {"/health", "/metrics"}:
+            return await handler(request)
+
+        # Extract signature components
+        signature = request.headers.get("X-Signature")
+        timestamp = request.headers.get("X-Timestamp")
+
+        if not signature or not timestamp:
+            return web.json_response(
+                {"error": "Missing signature or timestamp"},
+                status=401
+            )
+
+        # Get request body
+        body = ""
+        if request.can_read_body:
+            body_bytes = await request.read()
+            body = body_bytes.decode()
+
+        # Verify signature
+        if not self.verify_signature(
+            request.method,
+            request.path,
+            body,
+            timestamp,
+            signature
+        ):
+            logger.warning(f"Invalid signature for {request.path}")
+            return web.json_response(
+                {"error": "Invalid signature"},
+                status=401
+            )
+
+        return await handler(request)
+
+
+# Global key manager instance
+_key_manager: Optional[APIKeyManager] = None
+
+
+def get_key_manager() -> APIKeyManager:
+    """Get or create the global API key manager"""
+    global _key_manager
+    if _key_manager is None:
+        _key_manager = APIKeyManager()
+    return _key_manager

mcp/auth/rate_limiter.py

@@ -0,0 +1,317 @@
+"""
+Enterprise Rate Limiting for MCP Servers
+
+Features:
+- Token bucket algorithm for smooth rate limiting
+- Per-client rate limiting
+- Global rate limiting
+- Different limits for different endpoints
+- Distributed rate limiting with Redis (optional)
+"""
+import time
+import logging
+from typing import Dict, Optional
+from collections import defaultdict
+from dataclasses import dataclass, field
+from aiohttp import web
+import asyncio
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TokenBucket:
+    """Token bucket for rate limiting"""
+    capacity: int  # Maximum tokens
+    refill_rate: float  # Tokens per second
+    tokens: float = field(default=0)
+    last_refill: float = field(default_factory=time.time)
+
+    def __post_init__(self):
+        self.tokens = self.capacity
+
+    def _refill(self):
+        """Refill tokens based on time elapsed"""
+        now = time.time()
+        elapsed = now - self.last_refill
+
+        # Add tokens based on refill rate
+        self.tokens = min(
+            self.capacity,
+            self.tokens + (elapsed * self.refill_rate)
+        )
+        self.last_refill = now
+
+    def consume(self, tokens: int = 1) -> bool:
+        """
+        Try to consume tokens
+
+        Returns:
+            True if tokens were available, False otherwise
+        """
+        self._refill()
+
+        if self.tokens >= tokens:
+            self.tokens -= tokens
+            return True
+
+        return False
+
+    def get_wait_time(self, tokens: int = 1) -> float:
+        """
+        Get time to wait until tokens are available
+
+        Returns:
+            Seconds to wait
+        """
+        self._refill()
+
+        if self.tokens >= tokens:
+            return 0.0
+
+        tokens_needed = tokens - self.tokens
+        return tokens_needed / self.refill_rate
+
+
+class RateLimiter:
+    """
+    In-memory rate limiter with token bucket algorithm
+    """
+
+    def __init__(self):
+        # Client-specific buckets
+        self.client_buckets: Dict[str, TokenBucket] = {}
+
+        # Global bucket for all requests
+        self.global_bucket: Optional[TokenBucket] = None
+
+        # Endpoint-specific limits
+        self.endpoint_limits: Dict[str, Dict] = {
+            "/rpc": {"capacity": 100, "refill_rate": 10.0},  # 100 requests, 10/sec refill
+            "default": {"capacity": 50, "refill_rate": 5.0}  # Default for other endpoints
+        }
+
+        # Global rate limit (disabled by default)
+        # self.global_bucket = TokenBucket(capacity=1000, refill_rate=100.0)
+
+        # Cleanup task
+        self._cleanup_task = None
+        logger.info("Rate limiter initialized")
+
+    def _get_client_id(self, request: web.Request) -> str:
+        """
+        Get client identifier for rate limiting
+
+        Uses (in order):
+        1. API key
+        2. IP address
+        """
+        # Try API key first
+        if "api_key" in request and hasattr(request["api_key"], "key_id"):
+            return f"key:{request['api_key'].key_id}"
+
+        # Fall back to IP address
+        peername = request.transport.get_extra_info('peername')
+        if peername:
+            return f"ip:{peername[0]}"
+
+        return "unknown"
+
+    def _get_endpoint_limits(self, path: str) -> Dict:
+        """Get rate limits for endpoint"""
+        return self.endpoint_limits.get(path, self.endpoint_limits["default"])
+
+    def _get_or_create_bucket(self, client_id: str, path: str) -> TokenBucket:
+        """Get or create token bucket for client"""
+        bucket_key = f"{client_id}:{path}"
+
+        if bucket_key not in self.client_buckets:
+            limits = self._get_endpoint_limits(path)
+            self.client_buckets[bucket_key] = TokenBucket(
+                capacity=limits["capacity"],
+                refill_rate=limits["refill_rate"]
+            )
+
+        return self.client_buckets[bucket_key]
+
+    async def check_rate_limit(
+        self,
+        request: web.Request,
+        tokens: int = 1
+    ) -> tuple[bool, Optional[float]]:
+        """
+        Check if request is within rate limit
+
+        Returns:
+            Tuple of (allowed, retry_after_seconds)
+        """
+        client_id = self._get_client_id(request)
+        path = request.path
+
+        # Check global rate limit first (if enabled)
+        if self.global_bucket:
+            if not self.global_bucket.consume(tokens):
+                wait_time = self.global_bucket.get_wait_time(tokens)
+                logger.warning(f"Global rate limit exceeded, retry after {wait_time:.2f}s")
+                return False, wait_time
+
+        # Check client-specific rate limit
+        bucket = self._get_or_create_bucket(client_id, path)
+
+        if not bucket.consume(tokens):
+            wait_time = bucket.get_wait_time(tokens)
+            logger.warning(f"Rate limit exceeded for {client_id} on {path}, retry after {wait_time:.2f}s")
+            return False, wait_time
+
+        return True, None
+
+    async def start_cleanup_task(self):
+        """Start background cleanup task"""
+        if self._cleanup_task is None:
+            self._cleanup_task = asyncio.create_task(self._cleanup_loop())
+            logger.info("Rate limiter cleanup task started")
+
+    async def _cleanup_loop(self):
+        """Periodically clean up old buckets"""
+        while True:
+            await asyncio.sleep(300)  # Every 5 minutes
+
+            # Remove buckets that haven't been used recently
+            cutoff_time = time.time() - 600  # 10 minutes
+            removed = 0
+
+            for key in list(self.client_buckets.keys()):
+                bucket = self.client_buckets[key]
+                if bucket.last_refill < cutoff_time:
+                    del self.client_buckets[key]
+                    removed += 1
+
+            if removed > 0:
+                logger.info(f"Cleaned up {removed} unused rate limit buckets")
+
+
+class RateLimitMiddleware:
+    """aiohttp middleware for rate limiting"""
+
+    def __init__(self, rate_limiter: RateLimiter, exempt_paths: set[str] = None):
+        self.rate_limiter = rate_limiter
+        self.exempt_paths = exempt_paths or {"/health", "/metrics"}
+        logger.info("Rate limit middleware initialized")
+
+    @web.middleware
+    async def middleware(self, request: web.Request, handler):
+        """Middleware handler"""
+
+        # Skip rate limiting for exempt paths
+        if request.path in self.exempt_paths:
+            return await handler(request)
+
+        # Check rate limit
+        allowed, retry_after = await self.rate_limiter.check_rate_limit(request)
+
+        if not allowed:
+            return web.json_response(
+                {
+                    "error": "Rate limit exceeded",
+                    "message": f"Too many requests. Please retry after {retry_after:.2f} seconds.",
+                    "retry_after": retry_after
+                },
+                status=429,
+                headers={"Retry-After": str(int(retry_after) + 1)}
+            )
+
+        # Add rate limit headers
+        response = await handler(request)
+
+        # TODO: Add X-RateLimit-* headers
+        # response.headers["X-RateLimit-Limit"] = "100"
+        # response.headers["X-RateLimit-Remaining"] = "95"
+
+        return response
+
+
+class RedisRateLimiter:
+    """
+    Distributed rate limiter using Redis
+    Suitable for multi-instance deployments
+    """
+
+    def __init__(self, redis_client=None):
+        """
+        Initialize with Redis client
+
+        Args:
+            redis_client: redis.asyncio.Redis client
+        """
+        self.redis = redis_client
+        logger.info("Redis rate limiter initialized" if redis_client else "Redis rate limiter (disabled)")
+
+    async def check_rate_limit(
+        self,
+        key: str,
+        limit: int,
+        window_seconds: int
+    ) -> tuple[bool, Optional[int]]:
+        """
+        Check rate limit using Redis
+
+        Uses sliding window algorithm with Redis sorted sets
+
+        Returns:
+            Tuple of (allowed, retry_after_seconds)
+        """
+        if not self.redis:
+            # If Redis is not available, allow all requests
+            return True, None
+
+        now = time.time()
+        window_start = now - window_seconds
+
+        try:
+            # Redis pipeline for atomic operations
+            pipe = self.redis.pipeline()
+
+            # Remove old entries
+            pipe.zremrangebyscore(key, 0, window_start)
+
+            # Count current requests
+            pipe.zcard(key)
+
+            # Add current request
+            pipe.zadd(key, {str(now): now})
+
+            # Set expiry
+            pipe.expire(key, window_seconds)
+
+            results = await pipe.execute()
+
+            count = results[1]  # Result from ZCARD
+
+            if count < limit:
+                return True, None
+            else:
+                # Calculate retry time
+                oldest_entries = await self.redis.zrange(key, 0, 0, withscores=True)
+                if oldest_entries:
+                    oldest_time = oldest_entries[0][1]
+                    retry_after = int(oldest_time + window_seconds - now) + 1
+                    return False, retry_after
+
+                return False, window_seconds
+
+        except Exception as e:
+            logger.error(f"Redis rate limit error: {e}")
+            # On error, allow request (fail open)
+            return True, None
+
+
+# Global rate limiter instance
+_rate_limiter: Optional[RateLimiter] = None
+
+
+def get_rate_limiter() -> RateLimiter:
+    """Get or create the global rate limiter"""
+    global _rate_limiter
+    if _rate_limiter is None:
+        _rate_limiter = RateLimiter()
+    return _rate_limiter

mcp/database/__init__.py

@@ -0,0 +1,72 @@
+"""
+Enterprise-Grade Database Layer for CX AI Agent
+
+Provides:
+- SQLAlchemy ORM models with async support
+- Repository pattern for clean data access
+- Connection pooling and transaction management
+- Multi-tenancy support
+- Audit logging
+- Database-backed MCP store service
+"""
+
+from .models import (
+    Base,
+    Company,
+    Prospect,
+    Contact,
+    Fact,
+    Activity,
+    Suppression,
+    Handoff,
+    AuditLog
+)
+
+from .engine import (
+    DatabaseManager,
+    get_db_manager,
+    get_session,
+    init_database,
+    close_database
+)
+
+from .repositories import (
+    CompanyRepository,
+    ProspectRepository,
+    ContactRepository,
+    FactRepository,
+    ActivityRepository,
+    SuppressionRepository,
+    HandoffRepository
+)
+
+from .store_service import DatabaseStoreService
+
+__all__ = [
+    # Models
+    'Base',
+    'Company',
+    'Prospect',
+    'Contact',
+    'Fact',
+    'Activity',
+    'Suppression',
+    'Handoff',
+    'AuditLog',
+    # Engine
+    'DatabaseManager',
+    'get_db_manager',
+    'get_session',
+    'init_database',
+    'close_database',
+    # Repositories
+    'CompanyRepository',
+    'ProspectRepository',
+    'ContactRepository',
+    'FactRepository',
+    'ActivityRepository',
+    'SuppressionRepository',
+    'HandoffRepository',
+    # Services
+    'DatabaseStoreService',
+]

mcp/database/engine.py

@@ -0,0 +1,242 @@
+"""
+Enterprise-Grade Database Engine with Connection Pooling and Async Support
+"""
+import os
+import logging
+from typing import Optional, AsyncGenerator
+from contextlib import asynccontextmanager
+from sqlalchemy.ext.asyncio import (
+    create_async_engine,
+    AsyncSession,
+    AsyncEngine,
+    async_sessionmaker
+)
+from sqlalchemy.pool import NullPool, QueuePool
+from sqlalchemy import event, text
+
+from .models import Base
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseConfig:
+    """Database configuration with environment variable support"""
+
+    def __init__(self):
+        # Database URL (supports SQLite, PostgreSQL, MySQL)
+        self.database_url = os.getenv(
+            "DATABASE_URL",
+            "sqlite+aiosqlite:///./data/cx_agent.db"
+        )
+
+        # Convert postgres:// to postgresql:// for SQLAlchemy
+        if self.database_url.startswith("postgres://"):
+            self.database_url = self.database_url.replace(
+                "postgres://", "postgresql+asyncpg://", 1
+            )
+
+        # Connection pool settings
+        self.pool_size = int(os.getenv("DB_POOL_SIZE", "20"))
+        self.max_overflow = int(os.getenv("DB_MAX_OVERFLOW", "10"))
+        self.pool_timeout = int(os.getenv("DB_POOL_TIMEOUT", "30"))
+        self.pool_recycle = int(os.getenv("DB_POOL_RECYCLE", "3600"))
+        self.pool_pre_ping = os.getenv("DB_POOL_PRE_PING", "true").lower() == "true"
+
+        # Echo SQL for debugging
+        self.echo = os.getenv("DB_ECHO", "false").lower() == "true"
+
+        # Enable SQLite WAL mode for better concurrency
+        self.enable_wal = os.getenv("SQLITE_WAL", "true").lower() == "true"
+
+    def is_sqlite(self) -> bool:
+        """Check if using SQLite"""
+        return "sqlite" in self.database_url
+
+    def is_postgres(self) -> bool:
+        """Check if using PostgreSQL"""
+        return "postgresql" in self.database_url
+
+
+class DatabaseManager:
+    """Singleton database manager with connection pooling"""
+
+    _instance: Optional["DatabaseManager"] = None
+    _engine: Optional[AsyncEngine] = None
+    _session_factory: Optional[async_sessionmaker[AsyncSession]] = None
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if self._engine is None:
+            self._initialize()
+
+    def _initialize(self):
+        """Initialize database engine and session factory"""
+        config = DatabaseConfig()
+
+        # Engine kwargs
+        engine_kwargs = {
+            "echo": config.echo,
+            "future": True,
+        }
+
+        # Configure connection pool based on database type
+        if config.is_sqlite():
+            # SQLite specific settings
+            logger.info(f"Initializing SQLite database: {config.database_url}")
+            engine_kwargs.update({
+                "poolclass": NullPool,  # SQLite doesn't need pooling in the same way
+                "connect_args": {
+                    "check_same_thread": False,
+                    "timeout": 30,
+                }
+            })
+
+            # Enable WAL mode for better concurrency
+            if config.enable_wal:
+                engine_kwargs["connect_args"]["pragmas"] = {
+                    "journal_mode": "WAL",
+                    "synchronous": "NORMAL",
+                    "cache_size": -64000,  # 64MB cache
+                    "foreign_keys": 1,
+                    "busy_timeout": 5000,
+                }
+
+        else:
+            # PostgreSQL/MySQL settings
+            logger.info(f"Initializing database: {config.database_url}")
+            engine_kwargs.update({
+                "poolclass": QueuePool,
+                "pool_size": config.pool_size,
+                "max_overflow": config.max_overflow,
+                "pool_timeout": config.pool_timeout,
+                "pool_recycle": config.pool_recycle,
+                "pool_pre_ping": config.pool_pre_ping,
+            })
+
+        # Create async engine
+        self._engine = create_async_engine(
+            config.database_url,
+            **engine_kwargs
+        )
+
+        # Create session factory
+        self._session_factory = async_sessionmaker(
+            self._engine,
+            class_=AsyncSession,
+            expire_on_commit=False,
+            autocommit=False,
+            autoflush=False
+        )
+
+        # Register event listeners
+        self._register_event_listeners()
+
+        logger.info("Database engine initialized successfully")
+
+    def _register_event_listeners(self):
+        """Register SQLAlchemy event listeners"""
+
+        @event.listens_for(self._engine.sync_engine, "connect")
+        def receive_connect(dbapi_conn, connection_record):
+            """Event listener for new connections"""
+            logger.debug("New database connection established")
+
+        @event.listens_for(self._engine.sync_engine, "close")
+        def receive_close(dbapi_conn, connection_record):
+            """Event listener for closed connections"""
+            logger.debug("Database connection closed")
+
+    @property
+    def engine(self) -> AsyncEngine:
+        """Get the database engine"""
+        if self._engine is None:
+            raise RuntimeError("Database engine not initialized")
+        return self._engine
+
+    @property
+    def session_factory(self) -> async_sessionmaker[AsyncSession]:
+        """Get the session factory"""
+        if self._session_factory is None:
+            raise RuntimeError("Session factory not initialized")
+        return self._session_factory
+
+    async def create_tables(self):
+        """Create all database tables"""
+        logger.info("Creating database tables...")
+        async with self._engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+        logger.info("Database tables created successfully")
+
+    async def drop_tables(self):
+        """Drop all database tables (use with caution!)"""
+        logger.warning("Dropping all database tables...")
+        async with self._engine.begin() as conn:
+            await conn.run_sync(Base.metadata.drop_all)
+        logger.info("Database tables dropped")
+
+    async def health_check(self) -> bool:
+        """Check database health"""
+        try:
+            async with self.get_session() as session:
+                await session.execute(text("SELECT 1"))
+                return True
+        except Exception as e:
+            logger.error(f"Database health check failed: {e}")
+            return False
+
+    @asynccontextmanager
+    async def get_session(self) -> AsyncGenerator[AsyncSession, None]:
+        """Get a database session with automatic cleanup"""
+        session = self.session_factory()
+        try:
+            yield session
+            await session.commit()
+        except Exception as e:
+            await session.rollback()
+            logger.error(f"Database session error: {e}")
+            raise
+        finally:
+            await session.close()
+
+    async def close(self):
+        """Close database engine and connections"""
+        if self._engine is not None:
+            await self._engine.dispose()
+            logger.info("Database engine closed")
+
+
+# Global database manager instance
+_db_manager: Optional[DatabaseManager] = None
+
+
+def get_db_manager() -> DatabaseManager:
+    """Get or create the global database manager instance"""
+    global _db_manager
+    if _db_manager is None:
+        _db_manager = DatabaseManager()
+    return _db_manager
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    """Convenience function to get a database session"""
+    db_manager = get_db_manager()
+    async with db_manager.get_session() as session:
+        yield session
+
+
+async def init_database():
+    """Initialize database (create tables if needed)"""
+    db_manager = get_db_manager()
+    await db_manager.create_tables()
+    logger.info("Database initialized")
+
+
+async def close_database():
+    """Close database connections"""
+    db_manager = get_db_manager()
+    await db_manager.close()
+    logger.info("Database closed")

mcp/database/migrate.py

@@ -0,0 +1,107 @@
+"""
+Database Migration Management Script
+Provides helper functions for managing database migrations with Alembic
+"""
+import os
+import sys
+import logging
+from pathlib import Path
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from alembic.config import Config
+from alembic import command
+
+logger = logging.getLogger(__name__)
+
+
+def get_alembic_config() -> Config:
+    """Get Alembic configuration"""
+    # Path to alembic.ini
+    alembic_ini = Path(__file__).parent.parent.parent / "alembic.ini"
+
+    if not alembic_ini.exists():
+        raise FileNotFoundError(f"alembic.ini not found at {alembic_ini}")
+
+    config = Config(str(alembic_ini))
+    return config
+
+
+def create_migration(message: str):
+    """Create a new migration"""
+    config = get_alembic_config()
+    command.revision(config, message=message, autogenerate=True)
+    logger.info(f"Created migration: {message}")
+
+
+def upgrade_database(revision: str = "head"):
+    """Upgrade database to a revision"""
+    config = get_alembic_config()
+    command.upgrade(config, revision)
+    logger.info(f"Upgraded database to {revision}")
+
+
+def downgrade_database(revision: str):
+    """Downgrade database to a revision"""
+    config = get_alembic_config()
+    command.downgrade(config, revision)
+    logger.info(f"Downgraded database to {revision}")
+
+
+def show_current_revision():
+    """Show current database revision"""
+    config = get_alembic_config()
+    command.current(config)
+
+
+def show_migration_history():
+    """Show migration history"""
+    config = get_alembic_config()
+    command.history(config)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Database Migration Management")
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    # Create migration
+    create_parser = subparsers.add_parser("create", help="Create a new migration")
+    create_parser.add_argument("message", help="Migration message")
+
+    # Upgrade database
+    upgrade_parser = subparsers.add_parser("upgrade", help="Upgrade database")
+    upgrade_parser.add_argument(
+        "--revision",
+        default="head",
+        help="Revision to upgrade to (default: head)"
+    )
+
+    # Downgrade database
+    downgrade_parser = subparsers.add_parser("downgrade", help="Downgrade database")
+    downgrade_parser.add_argument("revision", help="Revision to downgrade to")
+
+    # Show current revision
+    subparsers.add_parser("current", help="Show current database revision")
+
+    # Show history
+    subparsers.add_parser("history", help="Show migration history")
+
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO)
+
+    if args.command == "create":
+        create_migration(args.message)
+    elif args.command == "upgrade":
+        upgrade_database(args.revision)
+    elif args.command == "downgrade":
+        downgrade_database(args.revision)
+    elif args.command == "current":
+        show_current_revision()
+    elif args.command == "history":
+        show_migration_history()
+    else:
+        parser.print_help()