# VAPI Dynamic Context Injection Specification

## Overview
This specification outlines how to implement dynamic context injection for Rivet's VAPI voice assistant, enabling real-time personalization based on current business data when calls are received.

## 1. How assistant-request Webhook Works

### Trigger
The `assistant-request` webhook fires when:
- An inbound call arrives on a VAPI phone number that doesn't have a static `assistantId` configured
- VAPI needs to dynamically determine which assistant configuration to use for the call

### Timing Constraints
- **CRITICAL**: Must respond within **7.5 seconds** end-to-end
- This is a hard limit enforced by telephony providers (15-second cap total, VAPI reserves ~7.5s for setup)
- Not configurable - plan for fast response times

### Webhook Payload
```json
{
  "message": {
    "type": "assistant-request",
    "call": {
      "id": "call-id",
      "phoneNumber": "+61238205443",
      "customer": {
        "number": "+61412345678"
      },
      "timestamp": "2026-02-06T10:51:00Z"
    }
  }
}
```

### Response Options

#### Option 1: Return Existing Assistant ID
```json
{
  "assistantId": "existing-assistant-id"
}
```

#### Option 2: Create Transient Assistant (Recommended for Dynamic Context)
```json
{
  "assistant": {
    "firstMessage": "Hey Michael! I've got your priorities ready — want to review today's leads?",
    "model": {
      "provider": "openai",
      "model": "gpt-4o",
      "messages": [
        {
          "role": "system",
          "content": "You are Rivet, COO of RateRight... [DYNAMIC CONTEXT HERE]"
        }
      ]
    }
  }
}
```

#### Option 3: Transfer Call
```json
{
  "destination": {
    "type": "number",
    "number": "+61426246472"
  }
}
```

## 2. What Context to Inject

### Priority 1: Essential Context (Always Include)
1. **Today's TODOs and Priorities**
   - Top 3 tasks for today
   - Any urgent deadlines or meetings
   - Key follow-ups needed

2. **Recent Memory/Events (Last 24-48h)**
   - Yesterday's completed actions
   - Recent decisions or insights
   - Current work in progress

3. **Active Leads Status**
   - New leads since yesterday
   - Hot prospects requiring follow-up
   - Pipeline movement (deals won/lost)

### Priority 2: Contextual Enhancement (Include if Fast)
1. **Current Work Blocks**
   - Active projects/tasks in progress
   - Any blockers or issues
   - Next steps on key initiatives

2. **Calendar Context**
   - Upcoming meetings in next 4 hours
   - Any preparation needed
   - Travel time if applicable

### Context Format for Voice
- **Keep it concise**: Phone calls need brief, digestible context
- **Use bullet points**: Easy for AI to parse and reference
- **Prioritize actionability**: Focus on what needs to be done
- **Time-aware**: Include relative time references ("today", "yesterday", "this morning")

Example context format:
```
[Context for Rivet - {{date}} {{time}}]

Today's Priorities:
- Review 3 new leads from Growth Engine
- Follow up on yesterday's RateRight product decisions
- Check instant matching spec progress

Recent Activity:
- Yesterday: Killed payment protection insurance (legal risk)
- Yesterday: Decided on $50 flat fee model (no escrow)
- Current: Spec agent finalizing instant matching

Active Leads:
- 2 new construction contractor inquiries
- 1 agency partnership discussion pending
- Pipeline value: $2,400 (48 potential hires)
```

## 3. Context Sources and Fast Fetching

### File-Based Sources (Fastest - <500ms)
1. **Daily Memory Files**
   - Path: `/home/ccuser/rateright-growth/rivet/memory/YYYY-MM-DD.md`
   - Contains today's log entries
   - Pre-parsed for quick extraction

2. **Weekly Work Log**
   - Path: `/home/ccuser/rateright-growth/rivet/memory/work-log/YYYY-W##.md`
   - Current week progress tracking

3. **Memory Summary**
   - Path: `/home/ccuser/rateright-growth/rivet/MEMORY.md`
   - Curated long-term context

### API-Based Sources (Require Caching)
1. **Growth Engine API**
   - Endpoint: `https://rateright-growth-production.up.railway.app/leads/active`
   - Returns active leads with status
   - Cache strategy: Refresh every 15 minutes

2. **Calendar Integration**
   - Google Calendar API for today's events
   - Cache strategy: Refresh every hour

### Implementation Strategy for Speed
```python
# Pseudo-code for fast context assembly
async def get_context():
    # Start all fetches in parallel
    tasks = [
        get_today_memory(),      # Local file - ~50ms
        get_weekly_summary(),    # Local file - ~50ms
        get_cached_leads(),      # Redis cache - ~100ms
        get_cached_calendar()    # Redis cache - ~100ms
    ]
    
    # Wait for all with 2-second timeout
    results = await asyncio.gather(*tasks, return_exceptions=True)
    
    # Format context quickly
    return format_context(results)
```

## 4. Webhook Response Payload Structure

### Minimal Fast Response (<2 seconds)
```json
{
  "assistant": {
    "firstMessage": "Hey! I've got your updates ready.",
    "model": {
      "provider": "openai",
      "model": "gpt-4o",
      "messages": [
        {
          "role": "system",
          "content": "You are Rivet, COO of RateRight...\n\n[CONTEXT] Today's priorities: 3 new leads, spec review needed. Yesterday: decided on $50 flat fee."
        }
      ]
    }
  }
}
```

### Full Context Response (If time permits)
```json
{
  "assistant": {
    "firstMessage": "Hey Michael! Good {{time_of_day}}. I've got {{num_leads}} new leads and {{num_tasks}} priorities today. Ready to dive in?",
    "model": {
      "provider": "openai", 
      "model": "gpt-4o",
      "messages": [
        {
          "role": "system",
          "content": "You are Rivet, COO of RateRight...\n\n{{full_context}}\n\nCurrent time: {{now}}\nRemember: Keep responses short for phone calls."
        }
      ]
    },
    "variableValues": {
      "time_of_day": "morning",
      "num_leads": "3",
      "num_tasks": "5",
      "full_context": "[Full formatted context here]"
    }
  }
}
```

## 5. Implementation Plan

### Phase 1: Basic Context (Week 1)
1. Set up webhook endpoint to receive VAPI calls
2. Implement file-based context reading (daily memory)
3. Create minimal assistant response with basic context
4. Test with 7.5-second timeout compliance

### Phase 2: Enhanced Context (Week 2)
1. Add Growth Engine API integration with caching
2. Implement calendar context fetching
3. Create context formatting templates
4. Add error handling and fallback responses

### Phase 3: Optimization (Week 3)
1. Implement parallel data fetching
2. Add Redis caching for API responses
3. Optimize context size for voice interactions
4. Add monitoring and logging

### Phase 4: Advanced Features (Week 4)
1. Implement context personalization based on caller
2. Add context history for continuity
3. Create context preview for testing
4. Add analytics on context usage

### Technical Requirements
- **Infrastructure**: Webhook server close to US-West-2 (VAPI's region)
- **Caching**: Redis for API response caching
- **Monitoring**: Response time tracking (<2s target)
- **Error Handling**: Graceful degradation if context fetch fails

### Security Considerations
- Validate webhook signatures from VAPI
- Store API keys securely (environment variables)
- Implement rate limiting on webhook endpoint
- Sanitize context data before injection

## Testing Strategy
1. **Unit Tests**: Context fetching and formatting
2. **Integration Tests**: Full webhook flow with VAPI
3. **Load Tests**: Multiple concurrent calls
4. **Timeout Tests**: Ensure <7.5s response under load

## Success Metrics
- Response time: <2 seconds (target), <7.5 seconds (hard limit)
- Context freshness: <15 minutes for leads, <1 hour for calendar
- Error rate: <1% of calls
- User satisfaction: Context feels relevant and helpful