CATS MCP Server

# CATS Intelligence Agent System ## AI-Powered ATS Organization, Tagging, and Workflow Automation **Version**: 1.0.0 **Date**: October 28, 2025 **Status**: Design Phase --- ## Executive Summary Build an **agentic AI system** that analyzes, organizes, and optimizes your entire CATS ATS database (~4,000 candidates) using: - **Your existing CATS MCP server** (163 tools across 17 toolsets) ✅ - **AI Tech Stack 1 plugins** (FastAPI + Next.js + Supabase + Mem0 + Claude Agent SDK) - **Layered, dry-run approach** for safe, intelligent database organization - **Production deployment** with full audit trails and rollback capability **Key Innovation**: Agent operates in **staging mode** first, showing you exactly what it plans to do before making any changes to CATS. --- ## System Architecture ### Tech Stack ``` ┌─────────────────────────────────────────────────────────────┐ │ Frontend Layer │ │ Next.js 15 + shadcn/ui + Vercel AI SDK │ │ - Dashboard for agent recommendations │ │ - Approval workflows (approve/reject staging changes) │ │ - Real-time progress tracking │ │ - Visualization of organization strategy │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Agent Orchestration Layer │ │ Claude Agent SDK + Mem0 │ │ - CATS Intelligence Agent (master orchestrator) │ │ - Subagents: Analyzer, Tagger, Organizer, Email Generator │ │ - Memory: Track decisions, patterns, user preferences │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Backend API Layer │ │ FastAPI + Python 3.12 │ │ - Agent endpoints (/api/analyze, /api/stage, /api/commit) │ │ - CATS MCP client (server_all_tools.py wrapper) │ │ - Staging database operations │ │ - Audit logging and rollback │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Data & Memory Layer │ │ Supabase (PostgreSQL + pgvector) │ │ - Staging tables (mirrored CATS schema) │ │ - Agent memory (Mem0 persistence) │ │ - Audit logs (all decisions + reasoning) │ │ - Vector search (candidate similarity, job matching) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ CATS API Integration │ │ CATS MCP Server (server_all_tools.py) │ │ - 163 tools across 17 toolsets │ │ - Rate limiting (1500 req/hr, exponential backoff) │ │ - Full CRUD for candidates, jobs, companies, etc. │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Agent Architecture ### Master Agent: CATS Intelligence Coordinator **Role**: Orchestrates all subagents, manages staging workflow, coordinates with user **Capabilities**: - Full access to all 163 CATS MCP tools - Mem0 memory for learning preferences - Multi-stage workflow management - Approval gate coordination ### Subagent 1: Database Analyzer **Role**: Deep analysis of entire CATS database **Tasks**: 1. Fetch all candidates (paginated, 50 at a time to avoid context limits) 2. Analyze skills, experience, locations, job history 3. Identify patterns, duplicates, incomplete records 4. Score candidates by completeness and relevance 5. Identify missing tags, incorrect categorizations 6. Build candidate similarity matrix (for grouping) **Output**: Comprehensive database health report with recommendations ### Subagent 2: Smart Tagger **Role**: Intelligent tag generation and application **Tasks**: 1. Analyze candidate resumes and profiles 2. Extract skills, technologies, industries, seniority levels 3. Generate tag hierarchy (primary skills → secondary skills → soft skills) 4. Map to existing CATS tags or propose new tags 5. Create tag application plan (which tags for which candidates) **Output**: Tag strategy document with reasoning for each tag assignment ### Subagent 3: Pipeline Organizer **Role**: Optimize candidate placement in pipelines **Tasks**: 1. Analyze active jobs and pipeline stages 2. Match candidates to jobs based on skills, experience, location 3. Recommend pipeline stage based on candidate status 4. Identify stale candidates (needs follow-up) 5. Suggest priority candidates for each job **Output**: Pipeline organization plan with candidate-to-job mappings ### Subagent 4: Communication Orchestrator **Role**: End-to-end communication management (outbound + inbound) **Tasks**: 1. **Outbound Communication**: - Generate personalized email templates (cold outreach, follow-ups, job pitches) - Schedule email sequences with optimal timing - Track email delivery status (via external email service) - Manage SMS campaigns (via external SMS provider - CATS has no SMS API) 2. **Inbound Response Handling**: - Monitor email inbox for candidate replies (via email webhook) - Parse reply sentiment and intent (interested, not interested, needs more info) - Extract key information (availability, salary expectations, questions) - Auto-update CATS candidate record with response data - Trigger next action (schedule interview, send info, mark as uninterested) 3. **Multi-Channel Routing**: - Email responses → CATS activities via API - SMS responses → Secondary routing system (webhook → Supabase → CATS sync) - Track all conversations across channels in unified timeline **Output**: Communication plans + automated response handling + CATS activity logging --- ## Communication Architecture ### Challenge: CATS SMS Limitations **Problem**: CATS has built-in SMS functionality but **NO API endpoints** for: - Sending SMS via API - Receiving SMS webhooks - Tracking SMS delivery status **Solution**: Hybrid communication system with external providers ### Email Flow (Full Integration) ``` ┌─────────────────────────────────────────────────────────────┐ │ Email Outbound │ │ │ │ Agent → Email Template → SendGrid/Resend API → Candidate │ │ (personalized) (tracking enabled) │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ Email Inbound │ │ │ │ Candidate Reply → SendGrid Webhook → FastAPI /webhook/email│ │ ↓ │ │ AI Agent analyzes reply (Claude) │ │ ↓ │ │ Extract: sentiment, intent, next_action │ │ ↓ │ │ Update CATS via MCP: Add activity + Update pipeline │ └─────────────────────────────────────────────────────────────┘ ``` ### SMS Flow (External Routing) ``` ┌─────────────────────────────────────────────────────────────┐ │ SMS Outbound │ │ │ │ Agent → SMS Template → Twilio API → Candidate │ │ (personalized) (tracking) │ │ │ │ Note: Bypasses CATS (no SMS API), but logs activity │ └─────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────┐ │ SMS Inbound │ │ │ │ Candidate Reply → Twilio Webhook → FastAPI /webhook/sms │ │ ↓ │ │ Store in Supabase (sms_messages table) │ │ ↓ │ │ AI Agent analyzes reply (Claude) │ │ ↓ │ │ Extract: sentiment, intent, next_action │ │ ↓ │ │ Sync to CATS: Create activity manually via MCP │ │ (CATS API has activities endpoint for notes/calls) │ └─────────────────────────────────────────────────────────────┘ ``` ### Unified Communication Timeline All messages (email + SMS) stored in Supabase, synced to CATS as activities: ```sql -- Communication Log (all channels) CREATE TABLE communication_log ( id BIGSERIAL PRIMARY KEY, candidate_id BIGINT, channel TEXT, -- 'email' or 'sms' direction TEXT, -- 'outbound' or 'inbound' message_body TEXT, metadata JSONB, -- provider_id, delivery_status, tracking_data sent_at TIMESTAMPTZ, -- AI Analysis (for inbound messages) ai_sentiment TEXT, -- 'positive', 'neutral', 'negative' ai_intent TEXT, -- 'interested', 'not_interested', 'needs_info' ai_next_action TEXT, -- 'schedule_interview', 'send_job_details', 'mark_unqualified' ai_extracted_data JSONB, -- salary_expectations, availability, questions -- CATS Sync synced_to_cats BOOLEAN DEFAULT FALSE, cats_activity_id BIGINT, -- CATS activity record ID synced_at TIMESTAMPTZ ); -- Email-specific tracking CREATE TABLE email_tracking ( id BIGSERIAL PRIMARY KEY, communication_log_id BIGINT REFERENCES communication_log(id), email_provider TEXT, -- 'sendgrid', 'resend' provider_message_id TEXT, opened BOOLEAN DEFAULT FALSE, clicked BOOLEAN DEFAULT FALSE, bounced BOOLEAN DEFAULT FALSE, unsubscribed BOOLEAN DEFAULT FALSE, tracking_data JSONB ); -- SMS-specific tracking CREATE TABLE sms_tracking ( id BIGSERIAL PRIMARY KEY, communication_log_id BIGINT REFERENCES communication_log(id), sms_provider TEXT, -- 'twilio' provider_message_sid TEXT, delivery_status TEXT, -- 'queued', 'sent', 'delivered', 'failed' error_code TEXT, tracking_data JSONB ); ``` --- ## Workflow: Layered Dry-Run Approach ### Layer 1: Analysis (Read-Only) **Duration**: 30-60 minutes (depending on database size) **Process**: 1. Agent fetches ALL data from CATS (candidates, jobs, companies, pipelines, tags) 2. Stores in Supabase staging database 3. Runs comprehensive analysis 4. Generates insights: - Database health score (completeness, quality) - Tag coverage analysis - Pipeline optimization opportunities - Duplicate detection - Missing information gaps **Output**: Analysis report visible in dashboard **User Action**: Review analysis, no approval needed ### Layer 2: Strategy (Dry-Run Planning) **Duration**: 15-30 minutes **Process**: 1. Agent generates detailed action plan: - Which candidates to tag (with which tags + reasoning) - Which candidates to move (to which pipelines + why) - Which candidates need follow-up (with suggested emails) - Which records to merge/update 2. Creates simulated result preview (what database will look like after changes) 3. Calculates impact score (how much better organization will be) **Output**: Staging plan with visualizations **User Action**: **APPROVE or REJECT** entire plan or individual changes ### Layer 3: Staging (Simulated Execution) **Duration**: 5-15 minutes **Process**: 1. Agent applies approved changes to **Supabase staging database** (NOT CATS yet) 2. User can browse simulated CATS database 3. Run test queries: "Show me all Python developers in pipeline X" 4. Verify organization looks correct 5. Agent generates final commit plan with exact API calls **Output**: Fully staged database ready for commit **User Action**: **FINAL APPROVAL** to commit to CATS ### Layer 4: Execution (Live Commit) **Duration**: 10-30 minutes (depending on change volume) **Process**: 1. Agent commits approved changes to CATS via MCP tools 2. Respects rate limits (1500 req/hr, batches intelligently) 3. Logs every API call with timestamp, response, success/failure 4. Provides real-time progress updates 5. Automatic rollback on errors (reverts to pre-execution state) **Output**: Live CATS database updated + complete audit log **User Action**: Monitor progress, receive completion notification --- ## Database Schema (Supabase) ### Staging Tables (Mirror CATS Schema) ```sql -- Candidates (staging copy from CATS) CREATE TABLE staging_candidates ( id BIGINT PRIMARY KEY, first_name TEXT, last_name TEXT, email TEXT, phone TEXT, resume_text TEXT, skills JSONB, experience_years INTEGER, location TEXT, metadata JSONB, synced_at TIMESTAMPTZ DEFAULT NOW() ); -- Jobs (staging copy) CREATE TABLE staging_jobs ( id BIGINT PRIMARY KEY, title TEXT, description TEXT, requirements JSONB, location TEXT, salary_range JSONB, metadata JSONB, synced_at TIMESTAMPTZ DEFAULT NOW() ); -- Pipeline Assignments (staging) CREATE TABLE staging_pipeline_assignments ( id BIGSERIAL PRIMARY KEY, candidate_id BIGINT REFERENCES staging_candidates(id), job_id BIGINT REFERENCES staging_jobs(id), pipeline_stage TEXT, assigned_at TIMESTAMPTZ DEFAULT NOW(), reasoning TEXT -- WHY agent placed candidate here ); -- Tag Assignments (staging) CREATE TABLE staging_tag_assignments ( id BIGSERIAL PRIMARY KEY, candidate_id BIGINT REFERENCES staging_candidates(id), tag_name TEXT, tag_category TEXT, -- skill, industry, seniority, etc. assigned_at TIMESTAMPTZ DEFAULT NOW(), reasoning TEXT -- WHY agent applied this tag ); ``` ### Agent Memory Tables (Mem0 Integration) ```sql -- Agent Decisions (learning from user approvals/rejections) CREATE TABLE agent_decisions ( id BIGSERIAL PRIMARY KEY, decision_type TEXT, -- tag_assignment, pipeline_move, email_template context JSONB, -- What information led to decision action JSONB, -- What action was proposed user_approved BOOLEAN, user_feedback TEXT, created_at TIMESTAMPTZ DEFAULT NOW() ); -- User Preferences (learned over time) CREATE TABLE user_preferences ( id BIGSERIAL PRIMARY KEY, preference_key TEXT UNIQUE, -- e.g., "tag_threshold_confidence" preference_value JSONB, learned_from TEXT, -- Which decision/feedback led to this updated_at TIMESTAMPTZ DEFAULT NOW() ); ``` ### Audit & Rollback Tables ```sql -- Execution Log (every CATS API call) CREATE TABLE execution_log ( id BIGSERIAL PRIMARY KEY, execution_batch_id UUID, -- Groups all changes in one commit api_endpoint TEXT, http_method TEXT, request_payload JSONB, response_payload JSONB, success BOOLEAN, executed_at TIMESTAMPTZ DEFAULT NOW() ); -- Rollback Points (snapshots before execution) CREATE TABLE rollback_snapshots ( id BIGSERIAL PRIMARY KEY, batch_id UUID, cats_state JSONB, -- Complete state before changes created_at TIMESTAMPTZ DEFAULT NOW() ); ``` ### Vector Search (Candidate Similarity) ```sql -- Enable pgvector CREATE EXTENSION IF NOT EXISTS vector; -- Candidate Embeddings (for semantic search and grouping) CREATE TABLE candidate_embeddings ( id BIGSERIAL PRIMARY KEY, candidate_id BIGINT REFERENCES staging_candidates(id), embedding vector(1536), -- OpenAI ada-002 or similar embedding_model TEXT, created_at TIMESTAMPTZ DEFAULT NOW() ); -- Index for fast similarity search CREATE INDEX ON candidate_embeddings USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100); ``` --- ## API Endpoints (FastAPI) ### Analysis Endpoints ```python POST /api/analysis/start # Trigger full database analysis # Returns: analysis_job_id GET /api/analysis/{job_id}/status # Check analysis progress # Returns: { status, progress_pct, current_step } GET /api/analysis/{job_id}/report # Get analysis results # Returns: comprehensive health report with insights ``` ### Staging Endpoints ```python POST /api/staging/generate-plan # Generate dry-run action plan based on analysis # Body: { analysis_job_id, user_preferences } # Returns: staging_plan_id GET /api/staging/{plan_id}/preview # Preview what database will look like after plan execution # Returns: simulated database state POST /api/staging/{plan_id}/approve # Approve entire plan or specific changes # Body: { approve_all: true } OR { approved_change_ids: [...] } # Returns: { approved_count, ready_for_commit } POST /api/staging/{plan_id}/commit # Execute approved changes to live CATS # Returns: execution_batch_id GET /api/staging/{plan_id}/rollback # Rollback executed changes (emergency only) # Returns: rollback_status ``` ### Agent Endpoints ```python POST /api/agents/tag-candidates # Run Smart Tagger subagent on specific candidates # Body: { candidate_ids: [...], tag_strategy: "auto" } # Returns: tag_assignments with reasoning POST /api/agents/organize-pipelines # Run Pipeline Organizer for specific job(s) # Body: { job_ids: [...], match_threshold: 0.7 } # Returns: pipeline_assignments with match scores POST /api/agents/generate-emails # Generate email templates for candidates # Body: { candidate_ids: [...], email_type: "outreach" } # Returns: personalized_email_templates ``` ### Communication Endpoints ```python # ============= OUTBOUND COMMUNICATION ============= POST /api/communication/send-email # Send personalized email to candidate(s) # Body: { # candidate_ids: [...], # email_template_id: "...", # send_immediately: true, # tracking_enabled: true # } # Returns: { sent_count, message_ids, tracking_urls } POST /api/communication/send-sms # Send SMS to candidate(s) via Twilio # Body: { # candidate_ids: [...], # sms_template_id: "...", # send_immediately: true # } # Returns: { sent_count, message_sids } # Note: Creates CATS activity automatically via MCP POST /api/communication/schedule-sequence # Schedule multi-touch email/SMS sequence # Body: { # candidate_ids: [...], # sequence_type: "cold_outreach_3_touch", # schedule: { # day_0: { channel: "email", template_id: "..." }, # day_3: { channel: "email", template_id: "..." }, # day_7: { channel: "sms", template_id: "..." } # } # } # Returns: { scheduled_count, sequence_id } # ============= INBOUND RESPONSE HANDLING ============= POST /api/webhooks/email # Webhook endpoint for email provider (SendGrid/Resend) # Body: { email_data } from provider # Process: # 1. Parse sender, extract candidate_id from metadata # 2. AI analyzes reply (sentiment, intent, next_action) # 3. Store in communication_log # 4. Update CATS via MCP (add activity, update pipeline) # 5. Trigger automated response if needed # Returns: { status: "processed", cats_updated: true } POST /api/webhooks/sms # Webhook endpoint for SMS provider (Twilio) # Body: { sms_data } from Twilio # Process: # 1. Parse phone number, lookup candidate # 2. AI analyzes reply (sentiment, intent, next_action) # 3. Store in communication_log + sms_tracking # 4. Sync to CATS as activity (via MCP activities endpoint) # 5. Trigger automated response if needed # Returns: { status: "processed", cats_synced: true } # ============= COMMUNICATION HISTORY ============= GET /api/communication/timeline/{candidate_id} # Get unified communication history for candidate # Returns: { # email_threads: [...], # sms_messages: [...], # cats_activities: [...], # synced from CATS # ai_insights: { # engagement_score: 0.85, # response_rate: "high", # best_channel: "email", # optimal_send_time: "10am EST" # } # } GET /api/communication/analytics # Communication performance analytics # Returns: { # email_stats: { sent, opened, clicked, replied }, # sms_stats: { sent, delivered, replied }, # response_patterns: [...], # best_performing_templates: [...] # } ``` --- ## Implementation Plan ### Phase 1: Foundation (Week 1) **Goal**: Set up infrastructure and basic agent **Tasks**: 1. Deploy AI Tech Stack 1: ```bash /ai-tech-stack-1:build-full-stack cats-intelligence ``` 2. Configure CATS MCP server integration in FastAPI backend 3. Set up Supabase schema (staging tables, audit logs) 4. Create basic Next.js dashboard (analysis view only) 5. Build Database Analyzer subagent (read-only mode) **Deliverable**: System can analyze CATS database and show health report ### Phase 2: Staging System (Week 2) **Goal**: Implement dry-run planning and approval workflow **Tasks**: 1. Build Smart Tagger subagent 2. Build Pipeline Organizer subagent 3. Create staging plan generation logic 4. Implement approval UI (approve/reject changes) 5. Add Supabase staging database sync **Deliverable**: System can generate action plans and simulate results ### Phase 3: Execution Engine (Week 3) **Goal**: Safe execution with rollback capability **Tasks**: 1. Build execution engine (commits to CATS via MCP) 2. Implement rate limiting and batching 3. Add audit logging for all API calls 4. Create rollback mechanism 5. Build progress tracking UI **Deliverable**: System can safely execute approved changes ### Phase 4: Communication System (Week 4) **Goal**: Full bidirectional communication with response handling **Tasks**: 1. **Email Integration**: - Set up SendGrid or Resend account + API keys - Configure email webhook endpoint (`/api/webhooks/email`) - Build outbound email sending (`/api/communication/send-email`) - Implement AI reply analysis (sentiment, intent extraction) - Auto-update CATS activities via MCP when replies received 2. **SMS Integration**: - Set up Twilio account + API keys - Configure SMS webhook endpoint (`/api/webhooks/sms`) - Build outbound SMS sending (`/api/communication/send-sms`) - Store SMS messages in Supabase (CATS has no SMS API) - Sync SMS to CATS as activities (manual sync via MCP) 3. **AI Response Handler**: - Claude analyzes inbound messages - Extract: sentiment (positive/neutral/negative), intent (interested/not interested/needs info) - Determine next action (schedule interview, send info, mark unqualified) - Auto-trigger follow-up sequences based on response 4. **Unified Timeline**: - Build communication timeline view (all channels) - Show email threads + SMS + CATS activities in one view - AI-powered engagement scoring per candidate - Communication analytics dashboard **Deliverable**: Complete bidirectional communication system with AI response handling ### Phase 5: Intelligence & Learning (Week 5) **Goal**: Agent learns from communication patterns and user feedback **Tasks**: 1. Integrate Mem0 for decision memory (kept from original plan) 2. Track communication effectiveness: - Which templates get best response rates - Optimal send times per candidate segment - Channel preference learning (email vs SMS) 3. A/B testing framework for email templates 4. Auto-optimize follow-up timing based on response patterns 5. Learn from manual interventions (when user overrides agent suggestions) **Deliverable**: Self-improving communication system that gets smarter over time ### Phase 6: Production Polish (Week 6) **Goal**: Production-ready deployment **Tasks**: 1. Deploy to Vercel (frontend) + Fly.io (backend) 2. Add authentication (Supabase Auth) 3. Implement proper error handling and monitoring 4. Create user documentation 5. Run end-to-end testing on full CATS database 6. Set up monitoring/alerting for webhook failures 7. Implement retry logic for failed email/SMS sends **Deliverable**: Production system ready for daily use --- ## Usage Scenarios ### Scenario 1: "Organize my entire CATS database" **User action**: Click "Run Full Analysis" in dashboard **System workflow**: 1. Database Analyzer fetches all 4,000 candidates (50 at a time) 2. Generates health report: "78% candidates missing tags, 45% in wrong pipelines" 3. Smart Tagger proposes 12,000 tag assignments with reasoning 4. Pipeline Organizer recommends 800 candidate moves 5. User reviews plan, approves 95% of changes 6. System executes in 25 minutes, respecting rate limits 7. Dashboard shows before/after comparison **Result**: Perfectly organized CATS database with audit trail ### Scenario 2: "Find best candidates for new Software Engineer role" **User action**: Paste job description, click "Find Matches" **System workflow**: 1. Agent analyzes job requirements (Python, React, 3+ years) 2. Searches staged database + vector similarity 3. Ranks all candidates by fit score (semantic match) 4. Proposes top 20 candidates for pipeline 5. Generates personalized outreach emails for each 6. User approves top 10, agent adds to pipeline + queues emails **Result**: Best candidates instantly found and contacted ### Scenario 3: "Clean up stale candidates and re-engage" **User action**: Click "Re-engagement Campaign" **System workflow**: 1. Agent finds candidates with no activity in 90+ days 2. Filters for high-quality candidates (strong profiles) 3. Generates re-engagement email templates (personalized) 4. Proposes follow-up schedule (day 1, day 7, day 14) 5. User approves, agent stages email sends 6. Tracks responses and updates pipeline accordingly **Result**: Dormant candidates re-activated with minimal effort ### Scenario 4: "Automated Email Response Handling" (NEW) **User action**: None - fully automated **System workflow**: 1. **Candidate replies to outreach email** ("Yes, I'm interested!") 2. **SendGrid webhook fires** → `/api/webhooks/email` 3. **AI analyzes reply**: - Sentiment: Positive - Intent: Interested - Next action: Schedule screening call 4. **System auto-responds**: - Updates CATS pipeline stage (Interested → Screening) - Adds CATS activity: "Replied positively on [date]" - Sends calendar link: "Great! Here's my calendar..." 5. **User gets notification**: "Candidate John Doe replied - screening scheduled" **Result**: Zero manual work, candidate engaged within 2 minutes ### Scenario 5: "SMS Follow-up with Response Tracking" (NEW) **User action**: Click "Send SMS Follow-ups" for stale candidates **System workflow**: 1. **Agent generates SMS**: "Hi Sarah! Still interested in the React role at [Company]? Reply YES to schedule a call." 2. **Sends via Twilio** (CATS has no SMS API) 3. **Logs in Supabase** communication_log + sms_tracking 4. **Syncs to CATS** as activity: "SMS sent on [date]" 5. **Candidate replies "YES"**: - Twilio webhook → `/api/webhooks/sms` - AI analyzes: Intent = Interested - Updates CATS pipeline + creates activity - Auto-sends calendar link via SMS 6. **User sees update** in unified timeline (SMS + email + CATS activities) **Result**: SMS engagement tracked despite CATS limitation, full audit trail --- ## Advanced Features ### 1. Duplicate Detection & Merging - Agent identifies duplicate candidates (fuzzy name matching, email similarity) - Proposes merge strategy (which record to keep, what data to combine) - User approves, system merges via CATS API ### 2. Skills Extraction from Resumes - Agent parses resume text (stored in CATS) - Extracts skills, technologies, certifications - Auto-tags candidates with extracted skills - Updates candidate profiles with structured data ### 3. Job-Candidate Match Scoring - Vector embeddings for jobs and candidates - Semantic similarity scoring (0.0 - 1.0) - Multi-factor ranking (skills, location, experience, salary) - Automated pipeline placement based on score thresholds ### 4. Intelligent Follow-Up Scheduling - Agent analyzes candidate engagement history - Predicts optimal follow-up timing - Generates contextual follow-up messages - Auto-schedules via CATS tasks/activities ### 5. Compliance & Data Retention - Identifies candidates past retention period (GDPR, CCPA) - Proposes data deletion or anonymization - Audit trail for all compliance actions ### 6. AI-Powered Reply Intelligence (NEW) **Sentiment Analysis**: - Detects positive, neutral, negative responses - Flags urgent replies (e.g., "I have another offer") - Prioritizes high-engagement candidates **Intent Classification**: - `interested` → Auto-send calendar link + update pipeline - `not_interested` → Mark as unqualified, add to "do not contact" - `needs_more_info` → Auto-send job details + company info - `availability_shared` → Extract dates, propose interview slots **Data Extraction**: - Salary expectations: "I'm looking for $120k-140k" - Availability: "I can start in 2 weeks" - Questions: "What's the tech stack?" → Auto-generate answer - Objections: "Too far to commute" → Flag for recruiter review ### 7. Multi-Touch Campaign Orchestration (NEW) **Sequence Templates**: ``` Cold Outreach (5-touch): Day 0: Email - Initial outreach Day 3: Email - Follow-up with job details Day 7: SMS - Quick check-in Day 14: Email - Final value proposition Day 21: Mark as unresponsive (if no reply) Re-engagement (3-touch): Day 0: Email - "Hey, we have new roles!" Day 5: SMS - "Quick question..." Day 10: Email - Last attempt + referral ask Job-Specific (4-touch): Day 0: Email - Personalized pitch with job details Day 2: Email - Company culture + team intro Day 5: SMS - "Thoughts on the role?" Day 10: Email - Final follow-up with urgency ``` **Smart Sequence Logic**: - Pause sequence if candidate replies (move to human handoff) - Skip SMS if candidate prefers email (learned from engagement) - Adjust timing based on response patterns (Mem0 learning) - A/B test different sequences, auto-select winners ### 8. Channel Preference Learning (NEW) **Tracks per candidate**: - Email open rate, click rate, reply rate - SMS delivery rate, reply rate - Preferred response time (morning vs evening) - Response speed (immediate vs 24-hour delay) **Auto-optimizes**: - Use email for candidates who always reply via email - Use SMS for candidates who ignore emails but respond to texts - Send at optimal time (learned from historical responses) - Skip unresponsive channels ### 9. Unified Communication Dashboard (NEW) **Real-time metrics**: - Active conversations (awaiting response) - Response rate by channel (email 23%, SMS 47%) - Average response time (email 12 hours, SMS 2 hours) - Hot leads (positive replies in last 24 hours) - Stalled conversations (no reply in 7+ days) **AI Insights**: - "SMS getting 2x response rate this week" - "Tuesday 10am has highest open rate" - "Template 'Software Engineer - Startup' outperforming by 35%" - "5 candidates awaiting your response (flagged urgent)" --- ## Performance Optimizations ### Context Window Management **Problem**: 4,000 candidates = too much data for single agent context **Solution**: Chunked processing - Fetch candidates in batches of 50 - Process each batch independently - Aggregate results in Supabase - Agent operates on summaries, not raw data ### Rate Limit Handling **CATS API Limit**: 1500 requests/hour **Strategy**: - Batch operations (update 10 candidates per API call where possible) - Exponential backoff on 429 errors (already implemented in MCP server) - Queue system for large operations (spread over hours if needed) - Priority queue (user-approved changes first) ### Caching & Incremental Sync **Problem**: Re-analyzing 4,000 candidates is slow **Solution**: - Cache candidate data in Supabase staging - Incremental sync (only fetch changed records) - Timestamp tracking (last_synced_at) - Agent works on cached data (99% of the time) --- ## Cost Estimates ### Development (6 weeks @ $75/hr avg) - **Phase 1-3**: 120 hours = $9,000 (Foundation + Staging) - **Phase 4**: 60 hours = $4,500 (Communication System) - **Phase 5-6**: 60 hours = $4,500 (Learning + Polish) - **Total Dev**: $18,000 ### Infrastructure (Monthly) - **Vercel**: $20/mo (Pro plan) - **Fly.io**: $15/mo (1GB RAM backend) - **Supabase**: $25/mo (Pro plan with pgvector) - **Anthropic API**: $50-200/mo (Claude Sonnet for agents + reply analysis) - **OpenAI API**: $20-50/mo (embeddings for vector search) - **SendGrid/Resend**: $15-30/mo (email sending + tracking) - **Twilio**: $20-50/mo (SMS sending, varies by volume) - **Total Infra**: ~$195/mo ### ROI Calculation **Time Saved**: - Manual tagging: 10 min/candidate × 4,000 = **667 hours** - Manual pipeline organization: 5 min/candidate = **333 hours** - Email template creation: 15 min/template × 50 templates = **12.5 hours** - **Email reply processing: 3 min/reply × 500 replies/month = 25 hours/month** (NEW) - **SMS management: 2 min/message × 200 messages/month = 6.7 hours/month** (NEW) **Monthly Time Saved** (ongoing): ~32 hours/month = **$2,400/month in labor value** **One-Time Setup Savings**: ~1,012 hours = **$75,000 in labor value** (at $75/hr) **Payback Period**: ~7.5 months (or 1 month if counting one-time savings) **Annual ROI**: $28,800/year savings on $18k investment = **160% ROI** --- ## Next Steps ### Option 1: Full Build (Recommended) Deploy complete AI Tech Stack 1 foundation: ```bash cd ~/Projects /ai-tech-stack-1:build-full-stack cats-intelligence ``` **Includes**: - Next.js 15 frontend (dashboard) - FastAPI backend (agent orchestration) - Supabase database (staging + audit) - Mem0 memory (agent learning) - Claude Agent SDK (subagent coordination) - CATS MCP server integration **Timeline**: 70 minutes for stack deployment + 5 weeks custom development ### Option 2: Proof of Concept (Faster) Build minimal version with just Database Analyzer: ```bash /fastapi-backend:init cats-analyzer /claude-agent-sdk:new-app cats-analyzer-agent ``` **Includes**: - Simple Python script that analyzes CATS database - Generates health report (no UI, just terminal output) - Uses CATS MCP server for data fetching **Timeline**: 1 week development ### Option 3: Manual Integration Test Test CATS MCP server with Claude Code RIGHT NOW: 1. Open project in VS Code with Claude Code extension 2. Configure CATS MCP server in `.mcp.json` 3. Ask Claude Code: "Analyze first 50 candidates in CATS and suggest tags" 4. Verify agent can access CATS data and make intelligent recommendations **Timeline**: 15 minutes --- ## Conclusion You have **all the pieces** needed to build a production-grade CATS Intelligence System: ✅ **CATS MCP Server**: 163 tools, rate limiting, production-ready ✅ **AI Tech Stack 1**: Complete foundation (Next.js + FastAPI + Supabase + Mem0 + Agents) ✅ **Plugins**: FastAPI, Claude Agent SDK, Mem0, Supabase all ready to use ✅ **Architecture**: Layered dry-run approach ensures safety ✅ **ROI**: Saves 1,000+ hours of manual work = $75k value **Recommendation**: Start with **Option 1 (Full Build)** for production system, or **Option 3 (Manual Test)** to validate concept in 15 minutes. --- **Ready to build?** Let me know which option you want to pursue and I'll start the deployment! 🚀