SDK Installation#

Supafone Labs publishes a Python package and an unscoped TypeScript package. The current release is 0.4.13 for both PyPI and npm.

Python#

pip install supafone-labs

Recommended full install for hosted cloud, HTTP, STT, and server helpers:

pip install "supafone-labs[all]"

Minimal usage:

import supafone_labs

brain = supafone_labs.supercharge(my_agent)

Explicit usage:

from supafone_labs import SupafoneLabs

brain = SupafoneLabs(
    provider="ultravox",
    llm="hosted",
    agent_label="intake",
)

Environment:

export SUPAFONE_LABS_API_KEY=sl_live_...

If no Labs key is present, use BYO provider keys such as ANTHROPIC_API_KEY, OPENAI_API_KEY, XAI_API_KEY, or local fake providers for tests.

Oracle provider and controls#

labs.enabled: true attaches the model-agnostic supervisor. A Supafone sl_... key uses the hosted Oracle; BYOK can use Anthropic, OpenAI, xAI/Grok, or an explicitly constructed OpenAI-compatible provider. The speaking agent and supervisor providers are independent.

from supafone_labs import SupafoneLabs
from supafone_labs.config import Settings

watcher = SupafoneLabs(
    provider="ultravox",       # speaking-agent adapter
    llm="anthropic",           # supervisor provider
    oracle_model="claude-haiku-4-5-20251001",
    config=Settings(
        confidence_threshold=0.65,
        oracle_timeout_seconds=5.0,
    ),
    oracle_instructions="Prioritize empathy, tool truth, and the next required intake step.",
    scenario="intake",
    mode="apply",
    telemetry=True,
    post_call_analysis=True,
)

For raw hosted completions, both SDKs expose model, max_tokens/ maxTokens, and temperature. whisper() additionally accepts operator guardrails. The full watcher also accepts custom belief/directive prompts, an injection adapter, telemetry and post-call controls, and an agent_label for optimization history.

TypeScript#

npm i supafone-labs

ESM:

import { Supafone } from "supafone-labs";

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

CommonJS:

const { Supafone } = require("supafone-labs");

Hosted-agent usage — since 0.4.4 a lone sl_ key cross-fills every credential lane (labs, hosted-agent, and account) automatically:

const supafone = new Supafone({
  apiKey: process.env.SUPAFONE_TOKEN!, // sl_live_... — one key, both APIs
});

Explicit per-surface keys are still supported when you want them scoped:

const supafone = new Supafone({
  apiKey: process.env.SUPAFONE_LABS_API_KEY!,
  supafoneApiKey: process.env.SUPAFONE_API_KEY!,
  supafoneApiBaseUrl: "https://api.supafone.ai",
});

The package works in Node 18+ and browsers using native fetch. Live STT needs a global WebSocket; on older Node versions, pass a WebSocket implementation.

Hosted Agent Factory creation can also opt into same-call language and voice routing. See Live Language and Voice Routing for the shared TypeScript, Python, REST, and MCP contract.

import WebSocket from "ws";

const live = supafone.liveTranscribe({
  WebSocketImpl: WebSocket,
  language: "multi",
  onResult: (r) => console.log(r.transcript)
});

Universal Phone Tester#

Both SDKs expose the real provider-neutral phone grader. The target can run on Vapi, Retell, Bland, OpenAI Realtime, Grok, LiveKit, or a custom runtime, and can use any carrier reachable over PSTN.

Python:

from supafone_labs import Supafone

sf = Supafone()  # SUPAFONE_TOKEN=sl_live_...
started = sf.tester.grade_agent(
    to_number="+14155550100",
    scenario="price_probe",
    ai_provider="gpt_realtime",
    telephony_provider="twilio",
    authorized=True,
)
finished = sf.tester.wait(started["session_id"])
print(finished["verdict"], finished["transcript"])

TypeScript:

const started = await supafone.tester.gradeAgent({
  toNumber: "+14155550100",
  scenario: "price_probe",
  aiProvider: "vapi",
  telephonyProvider: "telnyx",
  authorized: true,
});
const finished = await supafone.tester.wait(started.session_id);

This places a real call and spends tester credits. Both SDKs reject missing authorization and malformed E.164 numbers before dialing.

Browser WebRTC calls#

Version 0.4.10 adds first-class browser-session creation without buying or dialing a phone number:

const started = await supafone.startWebRtcCall({ agentId: "agent-123" });
console.log(started.browser_session.join_url);

started = supafone.start_webrtc_call(agent_id="agent-123")
print(started["browser_session"]["join_url"])

See Browser WebRTC Calls for React integration, security boundaries, transport details, and transfer limitations.

Stripe-hosted billing handoff#

Version 0.4.11 adds plan, credit-pack, and managed-number Checkout links to both SDKs and the MCP server. Clients receive a public checkout_url; Stripe card entry and entitlement verification remain in Supafone's private services. See Pricing and Credits for the full flow.

Hosted call planning and complete REST parity#

Version 0.4.13 turns one plain-language description into a validated, reviewable 3–8 stage plan through REST, Python, TypeScript, or MCP. Agent creation installs the generated or developer-edited plan in the executable runtime. It also completes hosted discovery, runtime, call, recording, and transcript route parity across the public clients.

Outbound campaigns#

The same account-authenticated clients create, launch, monitor, pause, and round-trip call campaigns as YAML. See Outbound Call Campaigns for the complete TypeScript and Python lifecycle.

Package Names#

View raw Markdown