Start here: Supafone Voice Watcher

The Watcher is the core of Supafone Labs: a second AI runs beside the realtime agent, observes the live conversation off the latency-critical audio path, and silently corrects the agent when it detects tool failures, unsafe claims, language changes, missed intent, or a broken workflow. If the Watcher has nothing useful to add—or cannot respond in time—the call continues unchanged.

It is enabled by default in both SDKs:

from supafone_labs import Supafone

supafone = Supafone(api_key="sl_live_...", voice_watcher=True)

import { Supafone } from "supafone-labs";

const supafone = new Supafone({
  apiKey: process.env.SUPAFONE_TOKEN!,
  voiceWatcher: true,
});

Already running Vapi, Retell, Ultravox, OpenAI Realtime, LiveKit, Pipecat, or another stack? Keep it. Feed provider events into the Watcher and deliver its canonical silent directive through the matching adapter.

Read this first: Voice Watcher framework · production problems it solves · framework support · programmable directives · live voice catalog · adversarial QA · MCP setup

import supafone_labs

brain = supafone_labs.supercharge(my_agent)   # that's the whole integration

import { Supafone } from "supafone-labs";

const supafone = new Supafone({ apiKey: process.env.SUPAFONE_TOKEN! });

const agent = await supafone.labs.agents.createInboundWithNumber({
  agentKey: "northline-intake",
  name: "Northline intake",
  assistantName: "Maya",
  description: "Answer new inquiries, understand the request, and book the right next step.",
  websiteUrl: "https://northline.example",
  number: { search: { areaCode: "415" } },
  labs: { enabled: true, model: "gemma" },
});

The TypeScript package is also the canonical client for the Supafone hosted agent API at https://api.supafone.ai/api/v1/labs. The default path buys and routes Supafone-managed numbers, so developers do not need to create Twilio, Ultravox, Cartesia, Inworld, ElevenLabs, or Deepgram accounts just to ship an agent. BYOK remains available when a team already owns those provider accounts.

Describe the job once

Agent Factory now turns that description into the complete prompt and staged call plan that the runtime actually executes. Developers do not need a second Haiku/Anthropic key, and customers do not have to accept a black-box prompt:

const plan = await supafone.generateCallStages({
  name: "Warm lead caller",
  description: "Call consented leads, understand fit, and book a demo without pressure.",
  direction: "outbound",
  stageCount: 5,
});

// Preview, edit, approve, or version ordinary JSON.
console.log(plan.call_stages);

The practical advantage is simple: less prompt plumbing for the developer and a calmer, more consistent conversation for the customer. Stages remember where the call is, tool claims require real tool confirmation, outbound opt-outs are explicit, and the safe template keeps creation available if the hosted planner is temporarily unavailable.

The core product: a model-agnostic supervisor

Supafone Labs is built around one defining capability:

1. Primary — Voice Watcher model supervisor: attach the Supafone second mind to a hosted agent or an agent you already run. It watches empathy and operational patterns across turns—intent, urgency, emotion, language, workflow progress, tool truth, and outcomes—then sends a silent corrective directive through the provider's native control channel only when it can improve the call.
2. Secondary — Agent Factory delivery path: create complete inbound, outbound, web, and campaign agents from one Supafone API key with the same supervisor already attached. This managed path removes provisioning work; it does not define or constrain the Watcher framework.

The supervisor is model agnostic by construction. Provider adapters normalize each stack into one call-state contract and compile one abstract directive back into the provider's supported control channel. The speaking model, supervisor model, carrier, STT, and TTS can therefore evolve independently.

Managed is the default. BYOK is available when the customer already owns provider accounts or needs provider-specific controls. Keep the BYOK lanes separate:

Those lanes can be mixed. A team can use Supafone-managed telephony with BYOK TTS, or BYOK Twilio/Telnyx with the managed Labs watcher, or bring the full stack and only use Supafone for self-healing supervision and logs.

Why this exists

A voice agent is one mind on a stopwatch. To sound human it must answer in well under a second — which means the model that talks can never afford to think. And everything that decides whether a call succeeds is thinking: reading distress in a caller's voice, noticing they just switched to Spanish, catching the agent about to promise something the API failed to do, remembering that this firm never quotes fees on the phone. The latency budget forbids all of it. That's not a prompt-engineering problem; it's an architecture problem.

Humans solved this decades ago. Every great call floor has a supervisor with a headset — listening to the call, saying nothing to the customer, sliding a note across the desk: "she's scared, slow down", "stop — don't quote the fee", "the booking didn't go through, don't say it did." The agent keeps talking; the note changes the call. Nobody expects the person speaking to also be the person supervising. Yet that's exactly what we ask of every voice agent shipped today.

Supafone Labs is the supervisor. A second, slower mind that runs beside the call instead of inside its latency budget: it taps every turn, maintains a live belief state — who's calling, what they want, how they feel, what language they're speaking — and slides its note across the desk through your platform's native silent channel. The caller never hears it. The agent reads it mid-call.

Why silent injection, not a better prompt? Because prompts are frozen at call-start and calls are alive. The moment that matters — the caller starts crying, the summary contradicts the tool result, the language flips — is by definition the moment your prompt didn't anticipate.

Why every platform? Because teams switch voice stacks constantly, and the coaching layer is exactly the part you can't afford to rewrite. One canonical contract in, one whisper out, compiled to whatever you run this quarter.

Why open source with a cloud? Because a system that whispers into your calls must be inspectable — every directive is in the audit log, and the whole brain is MIT. The cloud exists for one reason: one key that runs the models, the voices, and the transcription is more convenient than five vendor accounts.

And when the second mind fails? Nothing happens. It runs behind a timeout, off the hot path; a stalled oracle yields no note and the call proceeds exactly as it would have without us. Degrade-safety is tested, not promised.

Every platform, one whisper

Vapi	Retell AI	ElevenLabs	Ultravox	GPT-Realtime	Grok Voice	Deepgram
Bland	Pipecat	LiveKit	Cartesia	Inworld	Claude	Twilio
Telnyx	SignalWire	Vonage	Plivo	Jambonz	FreeSWITCH	Asterisk

Get started in 60 seconds

1 — Get a key (5 free minutes, no card):

curl -X POST https://api.labs.supafone.ai/v1/signup \
  -H "Content-Type: application/json" -d '{"email": "you@company.com"}'
# -> { "key": "sl_live_…", "free_minutes": 5.0 }   (also emailed to you)

export SUPAFONE_LABS_API_KEY=sl_live_…

2 — Install and supercharge:

pip install supafone-labs[all]

import supafone_labs

brain = supafone_labs.supercharge(my_agent, scenario="legal_intake")
result = await brain.observe(raw_event)     # feed your platform's events
# result.actions -> the compiled native whisper (or [] if the oracle is quiet)

Want every finished call automatically labeled? Construct the brain with post_call_analysis=True and each session end is classified against your objective — achieved/missed, per-criterion verdicts, failure reasons — with the enriched report filed for the optimizer:

from supafone_labs import SupafoneLabs

brain = SupafoneLabs(agent=my_agent, post_call_analysis=True)
# ...calls happen...
brain.analysis("session-123")   # -> {"achieved": True, "criteria": {...}, "failure_reasons": []}
brain.last_analysis             # labels for the most recently classified call

With the key set, the oracle, TTS, and live multilingual STT all run on Supafone Labs' hosted infrastructure. Without it, everything runs on your own vendor keys — or fully offline on deterministic fakes. Same code, all three modes.

3 — Watch it work in the console: your balance, usage, and an auditable log of every instruction your second mind whispered.

Hosted Supafone agents

Use supafone-labs when you want Supafone to host the whole agent:

const inbound = await supafone.labs.agents.createInboundWithNumber({
  agentKey: "northline-intake",
  name: "Northline intake",
  assistantName: "Maya",
  websiteUrl: "https://northline.example",
  number: { search: { areaCode: "415" } },
  tools: { callRouting: true, scheduling: true, sms: true, voicemail: true },
  labs: { enabled: true, model: "gemma" },
});

const outbound = await supafone.labs.agents.createOutboundWithNumber({
  agentKey: "northline-sales",
  name: "Northline sales team",
  number: { search: { areaCode: "415" } },
  labs: { enabled: true, model: "gemma" },
});

What Supafone handles in the default path:

• Supafone-managed phone number search, purchase, assignment, and routing.
• Managed voice provider accounts for Cartesia, Inworld, ElevenLabs-compatible, Ultravox, and Deepgram-backed paths.
• Multistage inbound and outbound presets instead of one flat prompt.
• Built-in tools for routing, scheduling, SMS, email, voicemail, knowledge, escalation, transcripts, recordings, and summaries.
• Supafone Pro live watcher/call coach.

BYOK is advanced, not required:

await supafone.labs.telephony.configure({
  mode: "byok",
  provider: "twilio",
  credentials: {
    accountSid: process.env.TWILIO_ACCOUNT_SID!,
    authToken: process.env.TWILIO_AUTH_TOKEN!,
    fromNumber: "+14155550123",
  },
});

The MCP server — run Supafone in natural language

mcp/supafone_mcp.py is a dependency-light MCP (Model Context Protocol) stdio server. Point Claude Desktop, Claude Code, or any MCP client at it and the whole platform becomes conversational — no code required:

"Create a win-back campaign with my Northline agent, add these five leads, launch it, and show me the calls as they happen."

Claude builds the campaign, launches real calls, and replies with links to the developer portal (app.supafone.ai/app/developer) where you watch the calls live — in-flight calls surface with a growing transcript as the conversation happens.

Hook it up (Claude Desktop / Claude Code)

{
  "mcpServers": {
    "supafone": {
      "command": "python3.12",
      "args": ["<repo>/mcp/supafone_mcp.py"],
      "env": {
        "SUPAFONE_TOKEN": "sl_live_..."
      }
    }
  }
}

<repo> is the absolute path to the cloned public supafone-labs repository. After changing this file, fully restart the MCP client so it refreshes tools/list. A correct connection advertises start_call_and_watch; a short models/usage-only list means Claude is still launching a different command.

Two independent auth lanes — set the ones you use:

The server logs in lazily with the email/password and transparently re-logs-in when the token expires — a long Claude session never goes stale.

What Claude can do with it

• Campaigns end to end — create_campaign, apply_campaign_preset (built-in playbooks or your saved custom presets), add_campaign_recipients (consented leads), launch_campaign / pause_campaign, update_campaign (scripts, cadence, settings — including the e-sign document config).
• Real phone calls — start_call_and_watch (or call_from_owned_agent) dials through your configured calling provider, bridges your voice agent onto the line, and returns a secret-free authenticated dashboard link for the live call. list_voice_agents picks the agent.
• Live monitoring — monitor_campaign returns the live funnel, the calls in flight right now, and a listen link per call plus the campaign's developer-portal link; get_call polled during a call follows the live transcript turn by turn.
• E-sign — create_sign_link mints a recipient's tracked tap-to-sign page (inherits the campaign's uploaded PDF + placed signature fields).
• Hosted agents & numbers — create inbound/outbound agents (with number provisioning), search/assign/release numbers, tail Labs logs, preview voices.

Full tool reference: gitbook/mcp-server.md. The same campaign surface is available in code via supafone_labs (PyPI) and supafone-labs (npm) — client.campaigns.*, callFromAgent(), and startWebRtcCall() for browser voice sessions without a phone number.

How it works

                      ┌─────────────────────────────────────────────┐
  your live call ────▶│  TAP        13 platform adapters +          │
  (any platform)      │             Deepgram nova-3 multilingual    │
                      │             STT for audio-only stacks       │
                      ├─────────────────────────────────────────────┤
                      │  THINK      belief state + coaching oracle  │
                      │             (off the latency path, timeout- │
                      │             bounded, degrade-safe)          │
                      ├─────────────────────────────────────────────┤
  silent whisper ◀────│  WHISPER    compiled to the platform's      │
  (native channel)    │             native control — never spoken   │
                      └─────────────────────────────────────────────┘

The Cloud API

One key fronts the whole stack — hosted oracle models, four TTS engines under one voice namespace, and live multilingual transcription. Billed by the minute; every request itemized.

Adversarial QA, built in. POST /v1/qa/suite generates a bespoke test suite from your agent's own objective, plays each scenario as a mock call against your real configuration, and judges every call twice — pass/fail on the scenario's assertion and an SSR grade (the judge picks one of five nominal levels, poorly/ok/good/great/perfectly, mapped deterministically to a score + distribution). POST /v1/qa/run plays every scenario A/B — supervised vs unsupervised — and reports the watcher's measured lift. How this stacks up against Hamming, Coval, Roark, Cekura, and the rest of the 2026 voice-QA field: gitbook/voice-qa-landscape.md.

import httpx

API, KEY = "https://api.labs.supafone.ai", os.environ["SUPAFONE_LABS_API_KEY"]

r = httpx.post(f"{API}/v1/oracle/complete",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"model": "supafone-labs-oracle", "messages": [...]})
directive = r.json()["text"]                     # the silent coaching line

audio = httpx.post(f"{API}/v1/tts",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"voice": "supafone-labs-calm-en", "text": "Right away."}).content

const API = "https://api.labs.supafone.ai";
const auth = { Authorization: `Bearer ${process.env.SUPAFONE_LABS_API_KEY}` };

const { text } = await fetch(`${API}/v1/oracle/complete`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "supafone-labs-oracle", messages: [...] }),
}).then(r => r.json());

// live multilingual STT — language-tagged Results, 10 languages, code-switching
const ws = new WebSocket(`${API.replace("https","wss")}/v1/stt/live` +
  `?api_key=${KEY}&language=multi&encoding=linear16&sample_rate=16000`);

Full reference with every endpoint, WebSocket framing, and error shapes: docs · interactive OpenAPI.

Pricing

Every billed second is itemized in /v1/logs. The live pricing contract is exposed at /v1/pricing and rendered at labs.supafone.ai/pricing.html. BYO vendor keys always win when present — leaving the cloud is deleting one environment variable.

Works with every voice platform

Speech-to-speech models, STT→LLM→TTS pipelines, frameworks, and raw speech engines each get the injection channel they actually have:

The release gate covers fourteen public runtimes from provider event through Watcher decision to exact delivery payload. Credentialed probes separately send real controls and wait for provider acceptance; missing credentials skip rather than pass. docs/providers.md has the current contract and test matrix. Telephony is transport-agnostic: Twilio, Telnyx, SignalWire, Vonage, Plivo, LiveKit SIP, Jambonz, FreeSWITCH/Asterisk, and SIPREC forks all feed the same tap (SIP matrix).

Runnable integrations for every permutation live in examples/.

Live multilingual transcription

Callers switch languages mid-sentence; the tap keeps up. Deepgram nova-3 language=multi code-switches live across en/es/fr/de/hi/ru/pt/ja/it/nl, every utterance arrives language-tagged, and the coaching comes back in the caller's language — Spanish callers get Spanish guardrails, silently, mid-call.

from supafone_labs.stt import MultilingualCallTap, recommended_setup

recommended_setup("vapi")                       # -> use Vapi's transcripts, skip the tap
recommended_setup("ultravox", multilingual=True)  # -> tap becomes the language authority

tap = MultilingualCallTap(brain, session_id=call_sid)   # any SIP/audio fork
await tap.feed(track="inbound", payload_b64=frame)

One rule prevents every bad combination: exactly one transcript source per call — recommended_setup() picks it, so you never double-ingest or double-pay. With SUPAFONE_LABS_API_KEY set and no Deepgram account, the tap routes through the hosted proxy automatically.

Pick your model. Write your prompts.

brain = supafone_labs.SupafoneLabs(
    provider="ultravox",
    oracle_model="claude-sonnet-4-6",     # provider auto-inferred (Anthropic/OpenAI/xAI/hosted)
    oracle_instructions="Coach for a bilingual intake desk. Empathy before logistics.",
)

models = await supafone_labs.discover_oracle_models()   # live vendor catalogs, cached hourly

Model routing is prefix-based and the catalogs are fetched from vendor APIs at runtime — a model released tomorrow works today, no package update. The static table in config.py is an offline fallback only.

Built for production

• Degrade-safe by construction — the oracle runs behind a timeout off the hot path; a stalled LLM, a dead STT socket, or a failed TTS backend can never take down the call it's shadowing. The TTS chain fails downward (hosted → your keys → offline audio); the tap no-ops without credentials.
• Auditable — every whispered instruction is in /v1/logs with a timestamp and its exact cost. No black box.
• Tested like infrastructure — 200+ offline tests (every adapter's parse, injection compile, and capability honesty; end-to-end facade runs per provider; billing; tiering) plus live contract checks against Deepgram, Ultravox, ElevenLabs, Cartesia, and Inworld.
• No lock-in — MIT package, MIT gateway. Self-host the whole cloud: cd cloud && uvicorn app:app.

The research behind it

The architecture is an assembly of five peer-reviewed threads — dual-process talker/reasoner agents (DeepMind's Talker-Reasoner), the evidence that models can't reliably self-correct (hence an external supervisor), generator/verifier splits (Cobbe 2021, Lightman 2023, Baker 2025), inference-time multi-model oversight (Sakana AI's AB-MCTS), and feedback-driven prompt optimization (OPRO, DSPy, TextGrad). All 22 citations, verified and annotated: the research page, and the full synthesis — meta-analysis plus the formal runtime treatment — is the whitepaper (PDF) (LaTeX source).

The QA methodology has its own paper: Grading the Call — objective-derived adversarial suites, SSR nominal-scale judging with deterministic score distributions, and supervision-lift A/B testing, situated against the 2025–2026 voice-QA landscape (Coval, Hamming, Roark, Cekura, Bluejay, platform-native suites, τ-bench, VoiceBench) — PDF (LaTeX source).

Repo layout

src/supafone_labs/     the package — facade, oracle, runtime + 14 audited runtimes, tts, stt, tiers
cloud/              Supafone Labs Cloud — the hosted gateway (FastAPI)
landing/            the website (landing, get-key, console, docs)
examples/           one runnable integration per platform + TypeScript client
tests/              200+ offline tests · live contract checks (pytest -m live)
docs/               provider capability matrix + quickstart

Development

make install                  # editable install + dev tools
make test                     # offline suite (live tests skip without keys)
make test-provider-contracts  # 14-runtime event -> Watcher -> exact-action gate
make test-live-injection      # real controls; missing credentials are skips
make lint                     # ruff
cd cloud && uvicorn app:app --reload    # run the gateway locally

Security

Keys are bearer credentials — treat sl_live_… like a password. The gateway stores no call audio; logs keep a 240-char excerpt per request (last 1,000 per key) for your own auditability. Report vulnerabilities via SECURITY.md.

License

MIT © 2026 Sam Savage. Free tier is free forever; the cloud exists because one key that runs everything is more convenient than five vendor accounts.