DispatchAI

Real-time emergency call triage powered by AI. DispatchAI ingests live phone calls via Telnyx, streams audio through parallel NLP and audio analysis agents, and produces a ranked priority queue to help dispatchers act on the most critical calls first.

---

How it works

Telnyx webhook → /api/v1/call/incoming
       ↓
Telephony layer starts audio stream → /ws
       ↓
agents.pipeline (audio track + NLP track run in parallel)
       ↓
merger produces a CallPacket (transcript, intent, distress score, hazards)
       ↓
ranking.service scores and queues the call
       ↓
Dashboard polls GET /api/v1/queue

---

Project structure

app/
├── agents/          # Streaming pipeline — audio & NLP analysis tracks
├── api/
│   ├── http/        # REST endpoints (health, queue)
│   └── ws/          # WebSocket handler for live audio frames
├── core/            # Config, logging, observability
├── ranking/         # Priority scoring and queue service
├── schemas/         # Pydantic models (CallPacket, queue, telephony)
├── services/        # Third-party provider boundaries (STT, LLM, emotion)
├── telephony/       # Telnyx client, webhooks, commands
├── ui/static/       # Dashboard frontend
├── utils/           # Shared helpers (IDs, time, errors)
└── workers/         # Background task workers
data/
docs/                # Architecture, packet schema, runbook
scripts/             # Dev startup, packet export, call replay
tests/               # Unit, integration, e2e

---

Quickstart

1. Clone and set up the environment

git clone https://github.com/oseni99/dispatchai.git
cd dispatchai
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

2. Configure environment variables

cp .env.example .env

Then edit .env:

Variable	Description
TELNYX_API_KEY	Telnyx REST API key
NGROK_AUTHTOKEN	ngrok auth token (for persistent tunnels)
PORT	uvicorn port (default 8000)

3. Start the dev server + ngrok

./scripts/dev_start.sh

This starts uvicorn and ngrok together. The ops/ngrok.yml config exposes two tunnels — one for /api and one for /ws. Public URLs are written to ops/urls.txt for quick reference.

---

API overview

Method	Path	Description
GET	/health	Health check
POST	/api/v1/call/incoming	Telnyx webhook — starts a call session
GET	/api/v1/queue	Returns the current ranked triage queue
WS	/ws	Audio frame stream from Telnyx

---

CallPacket schema

Each processed call produces a CallPacket:

{
  "call_id": "string",
  "timestamp": "ISO8601",
  "meta": { "from": "+1555...", "to": "+1555..." },
  "nlp": {
    "transcript": "...",
    "intent": "...",
    "summary": "..."
  },
  "audio": {
    "distress_score": 0.92,
    "hazards": ["fire", "unconscious person"]
  },
  "ranking": {
    "priority": 1,
    "reason": "High distress + life-threatening hazard detected"
  }
}

See docs/packet_schema.md for full details.

---

Docs

• Architecture
• Packet schema
• Runbook
• Ops tasks