# Voice Commands - 0.1% Plan

## Overview
Transform voice commands from a standalone gadget into a context-aware, hands-free assistant that knows exactly what you're doing and acts instantly.

**Status:** COMPLETE
**Priority:** #2
**Target:** Missing → 0.1%

---

## 0.1% Vision

**The best sales CRM voice system would:**
- Know which lead you're looking at — no need to say their name
- Let you bark quick commands: "Mark hot", "Skip", "Call next"
- Work during live calls without interrupting transcription
- Handle natural language: "Call them back Thursday" = schedule callback

**User Experience:**
```
[Looking at Sarah's card]
User: "Mark hot"
System: ✓ Sarah marked as hot

[On a call with Mike]
User: "Callback tomorrow 2pm"
System: ✓ Callback scheduled for Mike, tomorrow 2pm

[In call list]
User: "Skip"
System: [Swipes to next lead]
```

---

## Solution Design

### Core Principle: Context Injection
Pass `currentLeadId` to every voice command. Backend defaults to that lead.

### Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                     FRONTEND                                 │
├─────────────────────────────────────────────────────────────┤
│  VoiceAssistant.jsx                                         │
│  ├── Receives currentLead prop from parent                  │
│  ├── Passes leadId to API                                   │
│  └── Handles action callbacks (skip, navigate)              │
│                                                             │
│  CallList.jsx                                               │
│  └── Passes currentLead + callbacks to VoiceAssistant       │
│                                                             │
│  LiveCopilot.jsx                                            │
│  └── Detects command prefix, routes to voice-command API    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     BACKEND                                  │
├─────────────────────────────────────────────────────────────┤
│  parseVoiceCommand() - src/services/ai.js                   │
│  ├── NEW fast-path patterns for quick actions               │
│  └── Context-aware GPT prompt (knows leadId)                │
│                                                             │
│  voice-command endpoint - src/routes/ai.js                  │
│  ├── Accepts leadId parameter                               │
│  ├── NEW handlers: mark_tier, skip_lead, send_followup      │
│  └── Returns actionType for frontend callbacks              │
└─────────────────────────────────────────────────────────────┘
```

---

## New Fast-Path Patterns

### Quick Actions (no lead name needed)

| Pattern | Intent | Action |
|---------|--------|--------|
| `mark (this\|them\|lead)? (hot\|warm\|cold)` | mark_tier | Update lead tier |
| `mark (as\|them)? (engaged\|converted\|lost)` | mark_status | Update lead status |
| `skip( this( one)?)?` | skip_lead | Trigger skip callback |
| `(call\|dial) (next\|this one)` | call_lead | Trigger call callback |
| `send (a )?(follow-?up\|quick (text\|sms))` | send_followup | Open SMS composer |
| `(add )?note:? (.+)` | add_note | Add note to current lead |
| `callback (tomorrow\|monday\|tuesday\|...\|in \d+ days?)( at \d+)?` | schedule_callback | Create callback |

### Natural Language Expansions

| User Might Say | Normalized Intent |
|----------------|-------------------|
| "he's hot" | mark_tier: hot |
| "this one's engaged" | mark_status: engaged |
| "next" | skip_lead |
| "call them back thursday" | schedule_callback: thursday |
| "remind me tomorrow" | schedule_callback: tomorrow |
| "note they're interested in residential" | add_note |

---

## API Changes

### POST /api/ai/voice-command (Enhanced)

**Request:**
```json
{
  "transcript": "mark hot",
  "leadId": "uuid-of-current-lead",  // NEW: context injection
  "userEmail": "tony@rateright.com.au",
  "mode": "normal"  // or "in_call" for LiveCopilot
}
```

**Response:**
```json
{
  "success": true,
  "parsed": {
    "intent": "mark_tier",
    "confidence": 1.0,
    "data": { "tier": "hot" },
    "confirmation": "Marked as hot"
  },
  "actionResult": {
    "updated": true,
    "leadId": "uuid",
    "newTier": "hot"
  },
  "frontendAction": "none"  // or "skip", "call", "open_sms"
}
```

### New `frontendAction` Values

| Action | Frontend Behavior |
|--------|-------------------|
| `none` | Just show confirmation |
| `skip` | Trigger skip to next lead |
| `call` | Trigger call initiation |
| `open_sms` | Open SMS composer modal |
| `refresh` | Refresh lead data |

---

## Implementation Steps

### Step 1: Add Quick Action Patterns ✅ DONE
**File:** `src/services/ai.js`

Add fast-path regex patterns before GPT fallback:
- [x] mark_tier patterns
- [x] mark_status patterns
- [x] skip_lead patterns
- [x] call_lead patterns
- [x] send_followup patterns
- [x] note patterns
- [x] callback patterns with day/time parsing
- [x] parseCallbackTime() helper function

### Step 2: Add API Handlers ✅ DONE
**File:** `src/routes/ai.js`

Add handlers for new intents:
- [x] mark_tier - Update lead score to tier threshold
- [x] skip_lead - Return frontendAction: "skip"
- [x] call_lead - Return frontendAction: "call"
- [x] send_followup - Return frontendAction: "open_sms"
- [x] Modify add_note to use leadId parameter
- [x] Modify schedule_callback to use leadId parameter
- [x] Added getTargetLead() helper for context-aware commands
- [x] Response now includes frontendAction field

### Step 3: Pass Context from CallList ✅ DONE
**File:** `admin/src/pages/CallList.jsx`

- [x] Import VoiceAssistant component
- [x] Pass currentLead to VoiceAssistant component
- [x] Pass action callbacks (onSkip, onCall, onOpenSms, onRefresh)

### Step 4: Update VoiceAssistant Component ✅ DONE
**File:** `admin/src/components/VoiceAssistant.jsx`

- [x] Accept currentLead prop
- [x] Accept action callbacks (onSkip, onCall, onOpenSms, onRefresh)
- [x] Pass leadId to API
- [x] Handle frontendAction in response
- [x] Execute callbacks based on action type
- [x] Show context indicator: "Commands for: [Lead Name]"
- [x] Updated example commands with quick actions
- [x] Intent-specific result styling (colors for different actions)

### Step 5: Add In-Call Command Mode to LiveCopilot ✅ DONE
**File:** `admin/src/components/LiveCopilot.jsx`

- [x] Add COMMAND_PREFIXES patterns (hey system, command:, note:, mark, callback, skip)
- [x] Add commandResult and processingCommand state
- [x] Add detectAndProcessCommand() function
- [x] Route detected commands to voice-command API
- [x] Show command processing indicator (purple pulsing)
- [x] Show command confirmation in UI (green toast)
- [x] Call detection in both Deepgram and Web Speech handlers

### Step 6: Test All Commands
**Build deployed to production**

Test checklist (manual verification):
- [x] Build deployed to production
- [ ] Test "mark hot" on call list → Lead score changes to 75
- [ ] Test "skip" → UI navigates to next lead
- [ ] Test "callback tomorrow" → Callback created for next day
- [ ] Test "note: interested in residential" → Note added to lead
- [ ] Test "send follow-up" → SMS composer opens
- [ ] Test "call this one" → Call initiates
- [ ] In LiveCopilot: "Hey system, mark hot" → Command processed
- [ ] In LiveCopilot: "Note: budget is 50k" → Note added
- [ ] Context indicator shows lead name in VoiceAssistant header

### Step 7: Documentation ✅ DONE
- [x] Update SYSTEM-INTEL.md (Voice commands → 0.1%, priority queue checked)
- [x] Update voice-commands-plan.md (marked complete)
- [x] Add build history entry
- [ ] Update CODEBASE_MAP.md

---

## Files to Modify

| File | Changes |
|------|---------|
| `src/services/ai.js` | Add 8 new fast-path patterns |
| `src/routes/ai.js` | Add mark_tier, skip_lead, call_lead, send_followup handlers |
| `admin/src/pages/CallList.jsx` | Pass context + callbacks to VoiceAssistant |
| `admin/src/components/VoiceAssistant.jsx` | Accept props, handle frontendAction |
| `admin/src/components/LiveCopilot.jsx` | Add command prefix detection |

---

## Day/Time Parsing for Callbacks

Simple parsing for callback scheduling:

| Input | Parsed Date |
|-------|-------------|
| "tomorrow" | +1 day |
| "monday", "tuesday", etc. | Next occurrence of that day |
| "in 2 days" | +2 days |
| "next week" | +7 days |
| "at 2pm", "at 14:00" | Set time (default 9am if not specified) |

```javascript
// Example: "callback thursday at 2pm"
// → scheduled_at: next Thursday, 14:00 AEST
```

---

## Score/Tier Thresholds

When marking tier, set score to threshold:

| Command | Score Set To |
|---------|--------------|
| "mark hot" | 75 |
| "mark warm" | 55 |
| "mark cold" | 15 |

---

## In-Call Command Detection

For LiveCopilot, detect command prefix to avoid confusion with conversation:

**Trigger phrases:**
- "Hey system..."
- "Command..."
- "Note..."

**Example flow:**
```
[LiveCopilot transcribing call]
User says: "Hey system, callback tomorrow 2pm"
[System detects "hey system" prefix]
[Routes "callback tomorrow 2pm" to voice-command API]
[Shows confirmation: "Callback scheduled for tomorrow 2pm"]
[Resumes normal transcription]
```

---

## Success Criteria

1. **Zero-name commands** - "Mark hot" works without saying lead name
2. **Sub-500ms response** - Fast-path patterns respond instantly
3. **Natural language** - "Call them back Thursday" just works
4. **In-call friendly** - Can schedule callbacks during LiveCopilot calls
5. **Skip works** - Voice command actually swipes to next lead

---

## Testing Scenarios

| Scenario | Voice Command | Expected Result |
|----------|---------------|-----------------|
| On Sarah's card | "Mark hot" | Sarah's score → 75, confirmation shown |
| On call list | "Skip" | Swipes to next lead |
| On Mike's card | "Callback tomorrow" | Callback created for Mike, tomorrow 9am |
| On call list | "Call next" | Initiates call with current lead |
| In LiveCopilot | "Hey system, note interested in resi" | Note added, transcription continues |
| On any card | "Note: budget is 50k" | Note "budget is 50k" added to lead |

---

**Ready for Phase 3: Execute**

Build order:
1. Fast-path patterns in ai.js
2. API handlers in routes/ai.js
3. CallList context passing
4. VoiceAssistant props + callbacks
5. LiveCopilot command mode
6. Test all scenarios
7. Document