Skip to content

Migration Plan: CampaignBrain Chat (v0.3.5)

Date: December 2024 From: v0.3.4 or earlier To: v0.3.5 (CampaignBrain Chat MVP)

What's New

This release adds CampaignBrain Chat - an AI-powered natural language interface to i360 voter data using Claude (Anthropic API).

New Features

  • /chat - Natural language voter queries ("Find Republicans over 65 in Detroit")
  • Query results can be saved as segments
  • Clarifying questions when queries are ambiguous
  • Suggested queries for new users

New Files

src/api/services/
├── __init__.py
├── cb_data_dictionary.py
├── cb_prompts.py
├── cb_query_engine.py
└── cb_query_ir.py
src/api/routes/cb_chat.py
src/app/templates/cb_chat/index.html

Modified Files

  • requirements.txt - Added anthropic package
  • src/api/config.py - Added ANTHROPIC_API_KEY config
  • src/api/main.py - Registered cb_chat router
  • src/app/main.py - Added /chat route
  • src/app/templates/layout.html - Added Chat to navigation

Pre-Migration Checklist

  • Obtain Anthropic API key from https://console.anthropic.com/
  • Verify tenant manager has access to cbapp repo
  • Note current running version of each tenant
  • Schedule maintenance window (estimated: 5-10 min per tenant)

Migration Steps

1. Update Tenant Manager Configuration

Add to tenant manager's master .env or config:

# Anthropic API key for CampaignBrain Chat
ANTHROPIC_API_KEY=sk-ant-api03-...

This key will be propagated to tenant instances.

2. Update cbapp Repository

On the tenant manager server:

cd /path/to/cbapp-source
git fetch origin
git pull origin main

3. Update Each Tenant Instance

For each deployed tenant:

# Option A: Via tenant manager CLI (if available)
tenant-manager update <tenant-id>

# Option B: Manual update
cd /path/to/tenants/<tenant-id>/cbapp

# Pull latest code
git fetch origin
git pull origin main

# Install new dependencies
source venv/bin/activate
pip install -r requirements.txt

# Add API key to tenant's .env
echo "ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}" >> .env

# Restart services
sudo systemctl restart cbapp-api-<tenant-id>
sudo systemctl restart cbapp-frontend-<tenant-id>

4. Verify Migration

For each tenant:

# Check API health
curl -s http://localhost:<api-port>/api/cb-chat/health | jq

# Expected response:
{
  "status": "healthy",
  "anthropic_configured": true,
  "model": "claude-sonnet-4-20250514",
  "data_dictionary_loaded": true,
  "query_engine_available": true
}

5. Test Chat Functionality

  1. Log into tenant frontend
  2. Navigate to "Chat" in navigation
  3. Try a sample query: "How many voters do we have?"
  4. Verify response includes count
  5. Try "Save as Segment" action

Rollback Plan

If issues occur:

cd /path/to/tenants/<tenant-id>/cbapp

# Revert to previous version
git checkout <previous-commit-hash>

# Restart services
sudo systemctl restart cbapp-api-<tenant-id>
sudo systemctl restart cbapp-frontend-<tenant-id>

Previous stable commit: 6d330c6 (v0.3.4)

Configuration Reference

New Environment Variables

Variable Required Default Description
ANTHROPIC_API_KEY Yes* "" Anthropic API key for Claude
CB_CHAT_MODEL No claude-sonnet-4-20250514 Claude model to use

*Chat feature will show "degraded" status without API key but app will still function.

API Endpoints Added

Endpoint Method Auth Description
/api/cb-chat/message POST JWT Send chat message
/api/cb-chat/health GET None Health check
/api/cb-chat/suggestions GET JWT Get suggested queries

Cost Considerations

CampaignBrain Chat uses Claude Sonnet for queries:

  • Input: ~$3/million tokens
  • Output: ~$15/million tokens
  • Per query: ~$0.01-0.02

Estimated monthly cost for moderate usage (500 queries/month): $5-10

Consider: - Setting up usage alerts in Anthropic console - Implementing rate limiting if needed (not included in MVP)

Troubleshooting

Chat returns "Anthropic API key not configured"

  • Verify ANTHROPIC_API_KEY is set in tenant's .env
  • Restart API service after adding key

Chat returns "i360 database not available"

  • Verify db/i360.db exists in tenant directory
  • Check file permissions
  • Clear browser cache
  • Verify layout.html was updated
  • Restart frontend service

Post-Migration Tasks

  • Update tenant manager deployment scripts to include ANTHROPIC_API_KEY
  • Document chat feature for end users
  • Monitor Anthropic API usage dashboard
  • Collect user feedback on query accuracy

Support

For issues during migration: - Check logs: journalctl -u cbapp-api-<tenant-id> -f - GitHub Issues: https://github.com/Nominate-AI/cbapp/issues