# CX AI Agent - Enterprise Edition Deployment Guide

## 🎉 What's New in Enterprise Edition

The enterprise edition transforms the simple pipeline demo into a **full-featured CX automation platform** with:

### ✅ Core Features Implemented

1. **Campaign Management**
   - Create and manage multiple campaigns
   - Track campaign progress through all stages
   - Real-time metrics and analytics
   - Campaign status tracking (Draft, Active, Paused, Completed)

2. **Contact Database**
   - SQLite database with full CRUD operations
   - Advanced contact scoring (fit, engagement, intent, overall)
   - Contact lifecycle management (Lead → MQL → SQL → Opportunity → Customer)
   - Company relationship tracking

3. **Email Sequences**
   - Pre-built sequence templates (Cold Outreach 3-touch)
   - Multi-step email automation
   - Variable substitution ({{company_name}}, {{first_name}}, etc.)
   - Email activity tracking (sent, opened, clicked, replied)

4. **Enterprise UI/UX**
   - Professional multi-tab navigation (Dashboard, Campaigns, Contacts, Sequences, Analytics)
   - Real-time metric cards
   - Activity feed with live updates
   - Sortable, filterable data tables
   - Status badges and progress bars
   - Empty states with call-to-actions

5. **Analytics & Tracking**
   - Dashboard with key metrics
   - Campaign performance tracking
   - Contact engagement scoring
   - Activity timeline
   - Meeting scheduling and tracking

6. **Database Schema**
   - 12 comprehensive tables
   - Companies, Contacts, Campaigns
   - Email Sequences, Activities
   - Meetings, A/B Tests
   - Analytics Snapshots
   - Settings and Templates

---

## 🚀 Quick Start

### 1. Install Dependencies

```bash
pip install -r requirements_gradio.txt
```

New dependencies added:
- `sqlalchemy>=2.0.0` - ORM and database management
- `alembic>=1.13.0` - Database migrations (future use)

### 2. Set Up Environment

```bash
# Copy example environment file
cp .env.example .env

# Edit .env and add required keys:
# - HF_API_TOKEN (Hugging Face for LLM)
# - SERPER_API_KEY (for web search)
```

### 3. Run Enterprise Edition

```bash
# Run the new enterprise application
python app_enterprise.py

# Or run the original simple pipeline
python app.py
```

The enterprise edition will:
- Automatically create `./data/cx_agent.db` (SQLite database)
- Initialize database schema on first run
- Load default settings and sequence templates
- Start on `http://0.0.0.0:7860`

---

## 📊 Using the Enterprise Edition

### Dashboard View

The **Dashboard** shows:
- **Metric Cards**: Total campaigns, active campaigns, contacts, upcoming meetings
- **Activity Feed**: Real-time updates of all agent activities
- **Quick Stats**: At-a-glance performance metrics

### Campaigns View

**Create a Campaign:**
1. Click "+ New Campaign"
2. Enter campaign name (e.g., "Q1 SaaS Outreach")
3. Add description
4. Enter target companies (comma-separated: "Shopify, Stripe, Zendesk")
5. Click "Create & Launch Campaign"

**What Happens:**
- Creates campaign in database
- Runs the 8-agent pipeline (Hunter → Enricher → Contactor → Scorer → Writer → Compliance → Sequencer → Curator)
- Discovers company info via Serper API
- Enriches contacts with web data
- Stores all contacts in database
- Links contacts to campaign
- Updates campaign metrics in real-time

**Campaign Table Shows:**
- Campaign name and description
- Status badge (Active, Draft, Paused, Completed)
- Contacts discovered
- Contacted count vs. goal
- Response count
- Meetings booked
- Progress bar
- Creation date

### Contacts View

**Features:**
- **Search**: Find contacts by name, email, or company
- **Filter**: By status (New, Contacted, Responded, Meeting Scheduled)
- **Sortable Table**: Name, Company, Title, Status, Score, Date Added
- **Scoring**: Visual score indicator (0.0 - 1.0)
  - Green (0.7+): High fit
  - Yellow (0.4-0.7): Medium fit
  - Red (<0.4): Low fit

**Contact Statuses:**
- `new` - Just discovered
- `contacted` - Email sent
- `responded` - Reply received
- `meeting_scheduled` - Meeting booked
- `qualified` - Passed qualification
- `lost` - Not interested/no response
- `customer` - Converted to customer

### Sequences View

Currently shows "Coming Soon" placeholder. Full email sequence builder will include:
- Drag-and-drop sequence editor
- Email templates with variables
- A/B testing
- Send time optimization
- Performance tracking

### Analytics View

Currently shows "Coming Soon" placeholder. Full analytics dashboard will include:
- Charts and graphs (Plotly integration)
- Campaign ROI tracking
- Cohort analysis
- Funnel visualization
- Export to CSV/PDF

---

## 🗄️ Database Structure

### Key Tables

**Companies** (id, name, domain, industry, size, location, pain_points)
- Stores all target companies
- Linked to contacts

**Contacts** (id, company_id, first_name, last_name, email, job_title, scores, status)
- All discovered prospects
- Scoring: fit_score, engagement_score, intent_score, overall_score
- Lifecycle tracking

**Campaigns** (id, name, description, status, goals, metrics)
- Campaign definitions and tracking
- Progress metrics (discovered, enriched, contacted, responded, meetings)

**CampaignContacts** (id, campaign_id, contact_id, stage)
- Many-to-many relationship
- Tracks which contacts are in which campaigns
- Stage tracking (discovery → enrichment → scoring → outreach → responded → meeting → closed)

**Sequences** (id, name, category, is_template)
- Email sequence definitions
- Pre-built templates

**SequenceEmails** (id, sequence_id, step_number, wait_days, subject, body)
- Individual emails in a sequence
- Automated sending logic

**EmailActivities** (id, contact_id, campaign_id, type, occurred_at)
- Track all email interactions
- Types: sent, delivered, opened, clicked, replied, bounced, unsubscribed

**Meetings** (id, contact_id, campaign_id, scheduled_at, status, outcome)
- Meeting scheduling and tracking
- Outcomes: interested, not_interested, needs_follow_up, closed_won

**Activities** (id, contact_id, campaign_id, type, description, occurred_at)
- General activity log
- Agent actions and system events

**Settings** (key, value, description)
- Application configuration
- Company details for email footers
- Email sending limits
- Feature flags

---

## 🔧 Configuration

### Database Path

Default: `./data/cx_agent.db`

Change via environment variable:
```bash
export DATABASE_PATH=/custom/path/to/database.db
```

### Default Settings

Automatically created on first run:
- `company_name`: "Your Company"
- `company_address`: "123 Main St, City, State 12345"
- `sender_name`: "Sales Team"
- `sender_email`: "hello@example.com"
- `daily_email_limit`: 1000
- `enable_tracking`: True

Modify in database:
```python
from database.manager import get_db_manager
from models.database import Setting

db = get_db_manager()
with db.get_session() as session:
    setting = session.query(Setting).filter_by(key='company_name').first()
    setting.value = 'My Company Inc.'
    session.commit()
```

---

## 📈 Roadmap: What's Next

### Phase 2 (Next Sprint)
- [ ] Complete Email Sequence Builder UI
- [ ] Add A/B testing functionality
- [ ] Implement meeting scheduling integration
- [ ] Real-time notifications

### Phase 3
- [ ] Analytics Dashboard with charts
- [ ] Export campaigns to CSV/Excel
- [ ] Email report scheduling
- [ ] Custom report builder

### Phase 4
- [ ] Sentiment analysis on replies
- [ ] Smart reply suggestions
- [ ] Conversation intelligence
- [ ] Automated workflows (triggers)

### Phase 5
- [ ] CRM integrations (Salesforce, HubSpot)
- [ ] Webhook/API for custom integrations
- [ ] Team collaboration features
- [ ] Advanced permission system

---

## 🐛 Troubleshooting

### Database Issues

**Error: "Unable to open database file"**
```bash
# Create data directory
mkdir -p ./data
chmod 755 ./data
```

**Reset Database:**
```bash
# Delete existing database
rm ./data/cx_agent.db

# Restart application - will recreate with fresh schema
python app_enterprise.py
```

### Application Not Loading

**Check Dependencies:**
```bash
pip install -r requirements_gradio.txt
```

**Check Ports:**
```bash
# Default port 7860
# If in use, application will show error
# Kill process using port:
lsof -ti:7860 | xargs kill -9
```

### Serper API Errors

**401 Unauthorized:**
- Check `SERPER_API_KEY` in `.env`
- Verify key at https://serper.dev/

**429 Rate Limit:**
- Free tier: 2,500 searches/month
- Check usage at https://serper.dev/dashboard
- Upgrade plan or set `SKIP_WEB_SEARCH=true`

---

## 💡 Tips & Best Practices

### Campaign Management

1. **Start Small**: Test with 2-3 companies first
2. **Set Realistic Goals**: Estimate 5-10 contacts per company
3. **Monitor Progress**: Check dashboard daily
4. **Iterate**: Pause, adjust, and relaunch campaigns

### Contact Quality

1. **Review Scores**: Focus on contacts with score > 0.7
2. **Update Manually**: Add notes and tags
3. **Track Engagement**: Monitor email opens and clicks
4. **Follow Up**: Schedule meetings for hot leads

### Email Sequences

1. **Use Templates**: Start with "Cold Outreach - 3 Touch"
2. **Personalize**: Use variables ({{company_name}}, {{first_name}})
3. **A/B Test**: Try different subject lines
4. **Optimize Timing**: Test send times for best open rates

---

## 📚 API Reference

### Database Manager

```python
from database.manager import get_db_manager

db = get_db_manager()

# Get session
with db.get_session() as session:
    contacts = session.query(Contact).all()
    # Session auto-commits on success
    # Auto-rollback on exception
```

### Models

```python
from models.database import Contact, Campaign, Company

# Create contact
contact = Contact(
    first_name="John",
    last_name="Doe",
    email="john@example.com",
    job_title="VP of Sales",
    fit_score=0.85
)

# Query
high_score_contacts = session.query(Contact).filter(
    Contact.overall_score > 0.7
).all()
```

---

## 🎯 Success Metrics

Track these KPIs in your enterprise deployment:

- **Discovery Rate**: Contacts discovered per campaign
- **Enrichment Rate**: % of contacts successfully enriched
- **Response Rate**: % of emails that get replies
- **Meeting Rate**: % of contacts that book meetings
- **Conversion Rate**: % of meetings that convert to opportunities
- **Pipeline Value**: Total value of opportunities generated

Target Benchmarks:
- Discovery: 5-10 contacts/company
- Enrichment: >90%
- Response Rate: 10-20%
- Meeting Rate: 5-10%
- Conversion Rate: 20-30%

---

## 🔐 Security & Compliance

### Data Privacy

- All data stored locally in SQLite
- No external data sharing
- Contact suppression support
- GDPR-friendly (local storage)

### Email Compliance

- CAN-SPAM footer included
- Unsubscribe link required
- Physical address in footer
- Suppression list checking

### Best Practices

- Never store sensitive PII without encryption
- Regular database backups
- Secure API keys in environment variables
- Monitor for data breaches

---

## 📞 Support

For issues or questions:
- Check this deployment guide
- Review `ENTERPRISE_UPGRADE_PLAN.md`
- Check application logs
- Open GitHub issue

---

**Built with ❤️ for Enterprise CX Teams**

**Version**: 2.0.0-enterprise
**Last Updated**: 2025-01-15