# Caller Enrichment: Automatic Pre-Call Context for Emergency Dispatch

## Overview

The Caller Enrichment module builds a comprehensive context profile for each incoming emergency call before the AI dispatcher speaks its first word. Within a 450-millisecond window at call start, the system runs five independent lookups in parallel: caller identity and medical history, prior call activity, premise hazards at known addresses, active incidents at those locations, and linked utility account details. The results are injected directly into the AI dispatcher's context, enabling immediate informed responses rather than having to ask callers to repeat basic information they may have already provided in previous calls.

Caller enrichment is particularly valuable for repeat callers, vulnerable individuals with known medical conditions, and addresses with documented hazards, where prior knowledge directly affects triage priority and responder safety briefings.

```mermaid
sequenceDiagram
    participant T as Telephony
    participant V as Voice AI Worker
    participant E as Caller Enrichment Service
    participant DB as PostgreSQL

    T->>V: Incoming call (caller number, call_id)
    V->>E: enrich_caller(phone_number) - 450ms budget
    par Concurrent lookups
        E->>DB: Fetch caller profile (opt-in check)
        E->>DB: Count prior calls (30-day window)
        E->>DB: Load premise hazards (known addresses)
        E->>DB: Find open incidents (known addresses)
        E->>DB: Look up utility account (if applicable)
    end
    E->>V: CallerEnrichmentResult (all available data)
    V->>V: Inject KNOWN CALLER CONTEXT into system prompt
    V->>T: AI dispatcher begins call with enriched context
```

## Key Features

- **Parallel Five-Way Lookup**: Caller profile, prior calls, premise hazards, open incidents, and utility accounts are fetched concurrently within a hard 450ms budget, ensuring enrichment never delays call answer time
- **Caller Profile Resolution**: Looks up registered name, known addresses, medical flags (conditions, medications, mobility restrictions), and emergency contact details for callers who have opted in to pre-registration
- **30-Day Prior Call History**: Retrieves the count of calls from the same number and a summary of the most recent call, giving dispatchers immediate awareness of frequent callers or evolving situations
- **Premise Hazard Loading**: For any address associated with the caller, retrieves active hazard records sorted by severity, including structural hazards, chemical storage, violent history flags, and access restrictions relevant to responding units
- **Active Incident Correlation**: Checks whether any open incidents are already linked to the caller's known addresses, enabling dispatchers to connect a new call to an ongoing operation rather than creating a duplicate incident
- **Utility Account Context**: For utility service calls, retrieves account number, customer name, service address, account status, and outstanding balance, eliminating the need for callers to repeat account details during emergencies
- **System Prompt Injection**: All enriched data is formatted as a structured KNOWN CALLER CONTEXT block appended to the AI dispatcher's initial prompt, ensuring the information is available from the opening exchange
- **Opt-In Enforcement**: Medical flags and emergency contacts are only surfaced when the caller has explicitly opted in to data sharing; all other enrichment uses operationally registered data only
- **Graceful Degradation**: Each of the five lookups is independently fault-tolerant; a timeout or database error on one lookup does not block or delay the others

## Use Cases

### Repeat Caller Recognition
A caller who has contacted emergency services multiple times about an ongoing domestic situation is immediately recognised. The dispatcher sees the prior call count, a summary of the last interaction, and any open incidents at the address, enabling continuity without interrogating the caller.

### Medical Emergency Pre-Brief
For a caller registered with known cardiac history, the enrichment block surfaces their medical flags and emergency contacts before the dispatcher has asked a single question, allowing medically relevant questions to begin immediately.

### Hazardous Premises Awareness
When a call originates from an address with a known chemical storage flag or violent history record, the hazard data is surfaced to the dispatcher and can be included in the responder brief before units are deployed.

### Utility Service Emergencies
A customer calling about a gas leak is automatically matched to their utility account. The dispatcher can confirm service address and account status without diverting the conversation, keeping focus on the safety assessment.

### Duplicate Incident Prevention
If an active incident is already logged at the caller's known address, the dispatcher is immediately aware and can assess whether the new call relates to the same event or represents an escalation, reducing duplicate incident creation.

## How It Works

The Voice AI session handler invokes caller enrichment automatically at call start. All five database lookups run in parallel and must complete within 450ms. Results are assembled into a structured context block and injected into the AI dispatcher's system prompt before the call is answered. Each individual lookup fails independently without blocking the others, so partial enrichment is always better than delayed enrichment.

## Integration

Caller Enrichment is invoked automatically at call start by the Voice AI session handler. It reads from the caller profiles, prior calls, premise hazards, incidents, and utility accounts tables, all of which are populated through their respective domain modules (PSAP Profile Management, Premises Intelligence, Incident Management, and Utility Customer Management). No enrichment data is persisted to the call record at this stage; the injected context is live at call start and is reflected in the AI's transcribed conversation. Post-call summaries and incident records capture the outcome independently.

## Compliance

- Caller profile data is accessed only for numbers with active opt-in consent records
- Medical and emergency contact information is gated behind explicit data-sharing consent
- All enrichment lookups are scoped to the answering organisation's tenant, preventing cross-agency data access
- Audit events are recorded for each enriched field accessed, supporting post-incident review and data access transparency requirements

**Last Reviewed:** 2026-04-14
**Last Updated:** 2026-04-14