@pyai/sdk 0.2.2 → 0.3.1

package/README.md

@@ -8,10 +8,10 @@ dependencies; runs in the browser and Node 18+.
 ## PyAI products
 
 - **[Hear](https://pyai.com/models/hear)**, Lightning-fast, telephony-native **speech-to-text**. Whisper-compatible transcription tuned for real phone-call audio, with live streaming partials so your app reacts mid-sentence, plus async batch transcription for big archives. `POST /v1/audio/transcriptions`
-- **[Speak](https://pyai.com/models/speak)**, Ultra-realistic **text-to-speech** that starts speaking in tens of milliseconds. Stream lifelike, expressive voices, choose from 36 studio-quality presets, or clone any voice instantly, for free. `POST /v1/audio/speech`
+- **[Speak](https://pyai.com/models/speak)**, Ultra-realistic **text-to-speech** that starts speaking in tens of milliseconds. Stream lifelike, expressive voices, choose from 144 stock voices, or clone any voice instantly, for free. `POST /v1/audio/speech`
 - **[Omni](https://pyai.com/models/omni)** _(flagship)_, One **API for a complete, end-to-end voice AI agent**. A single WebSocket where your agent listens, thinks, and speaks, grounded in your knowledge bases and tools, with human-like turn-taking and instant barge-in, no STT, LLM, or TTS to stitch together yourself. `wss://api.pyai.com/v1/omni`
 - **[Trace](https://pyai.com/models/trace)** _(flagship)_, The **compliance API that keeps your AI agents safe**. Trace automatically checks every call for HIPAA, TCPA, and PII risks (plus your own brand-voice rules), flags the exact rule broken, redacts sensitive data, and seals each call with a tamper-evident audit trail, so a risky conversation never slips through. `GET /v1/trace/interactions`
-- **[Cue](https://pyai.com/models/cue)**, Realtime **turn detection + knowledge-grounded context** for your own stack. Bring your own LLM and voice; Cue nails the hard part, knowing the instant a speaker finishes and surfacing the right context. `wss://api.pyai.com/v1/audio/transcriptions/stream`
+- **Cue**, reserved turn-detection and grounding fields on Hear streaming. Grounding is not active on the serving route yet.
 - **[AMD](https://pyai.com/models/amd)**, **Answering-machine detection** that tells your dialer who or what answered, human, voicemail, IVR, iPhone/Google screening, dead number, fax, in a fraction of Twilio's dead-air dwell, with the reason. A one-line-TwiML Twilio Media Streams drop-in; billed per answered call (first 5,000/month free). `wss://api.pyai.com/v1/amd/stream`
 - **[Telephony](https://pyai.com/models/telephony)**, Instant **managed phone numbers** for your voice agents. Provision a US number and route live calls straight into an Omni agent, no carrier contracts, no telephony glue. `POST /v1/telephony/numbers`
 
@@ -93,6 +93,16 @@ omni.sendDtmf("5");
 omni.close();
 ```
 
+Live `0x02` transcript bodies are plain UTF-8 caller-text deltas, not JSON.
+`onTranscript` receives the normalized
+`{ event:"transcript", role:"user", text, final:false, mode:"delta" }` shape.
+Coalesce successive deltas for the current caller turn. Bounded direct JSON
+bodies remain accepted for older bridges.
+
+`rate` configures caller input. A `rate: 16000` session still receives 24 kHz
+agent audio; `rate: 8000` receives 8 kHz. Read `hello.audio_out` before playback.
+Omni has no commit frame—keep streaming silence during caller pauses.
+
 From the browser, mint an ephemeral token server-side with
 `pyai.omni.createSession({ allowedOrigins })` and pass it as `token` so the page
 never holds a secret key:
@@ -101,31 +111,37 @@ never holds a secret key:
 const omni = pyai.omni.connect({ token: session.token, configure: { voice_id, persona } });
 ```
 
-> Omni uses the native `wss://api.pyai.com/v1/omni` surface and is **zero-state**
->, no agent to create, `sessionLabel` is an optional opaque tag (never
-> required). Need the raw socket? `pyai.realtimeURL({ product: "omni" })` +
-> `pyai.realtimeSubprotocol()` (or `pyai.connectRealtime()`) still work;
-> `product: "flow"` uses `/v1/realtime`. The older `/v2/omni/chat` URL and the
-> `agentId` option are deprecated but still work.
+> Omni connects only to `wss://api.pyai.com/v1/omni` and is **zero-state**, no
+> agent to create. `sessionLabel` is an optional opaque tag (never required).
+> Need the raw socket? Use `pyai.realtimeURL({ sessionLabel })` with
+> `pyai.realtimeSubprotocol()` (or `pyai.connectRealtime()`).
+> The raw URL helper accepts canonical `format`, `rate`, and `api_key` query
+> parameters; retired connect aliases, model selectors, and token query names
+> throw instead of being translated.
 
-## Streaming speech-to-text (Hear / Cue)
+## Streaming speech-to-text (Hear)
 
 `transcriptions.stream()` hides the WebSocket frame protocol behind callbacks.
-It opens `wss://api.pyai.com/v1/audio/transcriptions/stream` (key carried as the
+It opens `wss://api.pyai.com/v1/audio/transcriptions/stream?protocol=pyai-hear-v1` (key carried as the
 WS subprotocol, so it works in the browser), routes the wire frames to
-`onPartial`/`onFinal`/`onError`, and gives you `sendAudio`, `commit()`, and
-`close()`:
+`onConfigAck`/`onPartial`/`onFinal`/`onError`, and gives you `sendAudio`,
+`configureEndpointing()`, `commit()`, and `close()`:
 
 ```ts
 const hear = pyai.audio.transcriptions.stream({
   sampleRate: 16000,
+  endpointingMs: 800, // minimum trailing pause; may wait up to max(800, 1500) ms
+  onConfigAck: (ack) => {
+    if (ack.warnings.length) throw new Error(JSON.stringify(ack.warnings));
+  },
   onPartial: (f) => console.log("…", f.text),
-  onFinal: (f) => console.log("✓", f.text, `(${f.audio_ms}ms)`),
+  onFinal: (f) => console.log("✓", f.text, f.endpoint_reason),
   onError: (e) => console.error(e),
 });
 
-micChunks.on("data", (pcm16) => hear.sendAudio(pcm16)); // binary frames
-vad.on("end", () => hear.commit());                     // force-finalize an utterance
+micChunks.on("data", (pcm16) => hear.sendAudio(pcm16)); // keep sending silence through pauses
+hear.configureEndpointing(950);                         // update without reconnecting
+vad.on("end", () => hear.commit());                     // optional forced final
 // hear.close() also flushes a final for any buffered audio
 ```
 
@@ -163,8 +179,8 @@ const ulaw = await pyai.audio.speech({
 
 | `response_format` | sample rates (Hz) | Content-Type |
 |---|---|---|
-| `mp3` (default) | 8000 / 16000 / 24000 / 48000 | `audio/mpeg` |
-| `wav` | 8000 / 16000 / 24000 / 48000 | `audio/wav` |
+| `wav` (default) | 8000 / 16000 / 24000 / 48000 | `audio/wav` |
+| `mp3` | 8000 / 16000 / 24000 / 48000 | `audio/mpeg` |
 | `opus` | 8000 / 16000 / 24000 / 48000 | `audio/ogg` |
 | `aac` | 8000 / 16000 / 24000 / 48000 | `audio/aac` |
 | `flac` | 8000 / 16000 / 24000 / 48000 | `audio/flac` |
@@ -175,7 +191,7 @@ const ulaw = await pyai.audio.speech({
 `sample_rate` is optional, omit it for the engine's native 24 kHz (`g711_*` is
 always 8 kHz). The set is typed (`SpeechFormat`) and exported as `SPEECH_FORMATS`
 / `SPEECH_SAMPLE_RATES` for dropdowns and validation. Any other value is a
-`400 unsupported_format`; omit `response_format` for the default `mp3`.
+`400 unsupported_format`; omit `response_format` for the default `wav`.
 
 > See [`examples/speak-telephony-formats`](../../examples/speak-telephony-formats)
 > for the full before/after: ~120 lines of resampler + μ-law replaced by one
@@ -292,7 +308,7 @@ Speak→Hear round-trip, and prints remediation hints for any failure:
 ```bash
 export PYAI_API_KEY=pyai_test_...
 npx pyai doctor
-# PASS  key (/v1/me), env=test; 3 scope(s): hear:transcribe, voice:synthesize, hear:stream
+# PASS  key (/v1/me), env=test; 3 scope(s): hear:transcribe, speak:synthesize, hear:stream
 # PASS  models.list, 12 models
 # PASS  voices.list, 38 voices
 # PASS  speak→hear round-trip, synth 45210 bytes → "the quick brown fox…"

package/dist/index.d.ts

@@ -24,6 +24,9 @@ export declare class PyAIError extends Error {
     constructor(status: number, message: string, code?: string, type?: string, requestId?: string);
 }
 export interface Voice {
+    /** Canonical catalog identifier returned by GET /v1/voices. */
+    voice_id: string;
+    /** SDK compatibility alias, always equal to voice_id. */
     id: string;
     name?: string;
     gender?: string;
@@ -49,13 +52,13 @@ export interface TranscriptionJob {
  * Output container/codec for `audio.speech`. This is the **exact** set the
  * server accepts on `POST /v1/audio/speech`, any other value is rejected with
  * `400 unsupported_format`. The default (when `response_format` is omitted) is
- * `mp3`. Omit `sample_rate` for the engine's native 24 kHz (`g711_*` is always
+ * `wav`. Omit `sample_rate` for the engine's native 24 kHz (`g711_*` is always
  * 8 kHz).
  *
  * | format | rates (Hz) | Content-Type |
  * |---|---|---|
- * | `mp3` (default) | 8000/16000/24000/48000 | `audio/mpeg` |
- * | `wav` | 8000/16000/24000/48000 | `audio/wav` |
+ * | `wav` (default) | 8000/16000/24000/48000 | `audio/wav` |
+ * | `mp3` | 8000/16000/24000/48000 | `audio/mpeg` |
  * | `opus` | 8000/16000/24000/48000 | `audio/ogg` |
  * | `aac` | 8000/16000/24000/48000 | `audio/aac` |
  * | `flac` | 8000/16000/24000/48000 | `audio/flac` |
@@ -73,14 +76,16 @@ export declare const SPEECH_FORMATS: readonly ["wav", "mp3", "opus", "aac", "fla
 /** Sample rates (Hz) the server accepts for `audio.speech` (`g711_*` is always 8 kHz). */
 export declare const SPEECH_SAMPLE_RATES: readonly [8000, 16000, 24000, 48000];
 export type SpeechSampleRate = (typeof SPEECH_SAMPLE_RATES)[number];
+/** Canonical Speak model plus the intentional OpenAI drop-in aliases. */
+export type SpeakModel = "pyai-speak" | "tts-1" | "tts-1-hd";
 export interface SpeechParams {
     input: string;
     voice?: string;
-    model?: string;
+    model?: SpeakModel;
     /**
      * Output container/codec, resampled+encoded server-side. One of
      * {@link SpeechFormat}, anything else is a `400 unsupported_format`. Omit for
-     * the default of `mp3`.
+     * the default of `wav`.
      *
      * `g711_ulaw`/`g711_alaw` return raw 8 kHz mono G.711, the bytes Twilio/SIP
      * media streams expect, so you can hand the response straight to a telephony
@@ -97,15 +102,14 @@ export interface SpeechParams {
      * telephony pipelines, most often with `response_format: "pcm"`.
      */
     sample_rate?: SpeechSampleRate;
+    /** Reserved; currently returns `400 unsupported_parameter` when provided. */
     speed?: number;
     /**
-     * Deterministic sampling seed for reproducible eval runs. Forward-compatible:
-     * honored once the engine supports it (otherwise ignored server-side), so it's
-     * always safe to send.
+     * Reserved; currently returns `400 unsupported_parameter` when provided.
      */
     seed?: number;
     /**
-     * Sampling temperature (lower = more deterministic). Forward-compatible, * honored once the engine supports it, otherwise ignored.
+     * Reserved; currently returns `400 unsupported_parameter` when provided.
      */
     temperature?: number;
 }
@@ -119,8 +123,6 @@ export interface CreateJobParams {
     webhook_url?: string;
 }
 export interface RealtimeOptions {
-    /** "omni" (agentic voice) or "flow" (legacy voice duplex). Default "omni". */
-    product?: "omni" | "flow";
     /**
      * Optional opaque tag echoed to your `kb_endpoint` and recorded on the call.
      * Omni is zero-state: the session is authorized by the key's org, so there is
@@ -128,12 +130,10 @@ export interface RealtimeOptions {
      */
     sessionLabel?: string;
     /**
-     * @deprecated Use {@link sessionLabel}. Kept for back-compat, emitted as the
-     * `agent_id` query alias, which the gateway still accepts. Ignored if
-     * `sessionLabel` is set.
+     * Extra canonical query params (`format`, `rate`, or the intentional
+     * server-side `api_key` auth option). Retired connect aliases and model/token
+     * selectors are rejected.
      */
-    agentId?: string;
-    /** Extra query params (e.g. format, rate). */
     query?: Record<string, string>;
 }
 /** Parameters for minting an ephemeral browser Omni session token (server-side). */
@@ -167,6 +167,8 @@ export interface OmniSession {
 }
 /** Frame `type`s emitted by the Hear streaming-STT WebSocket. */
 export declare const HearFrameType: {
+    /** Applied endpointing configuration and validation warnings. */
+    readonly ConfigAck: "config_ack";
     /** Eager live hypothesis for the current utterance. */
     readonly Partial: "partial";
     /** Partial whose prefix has stabilized (won't be revised). */
@@ -202,7 +204,7 @@ export declare const ErrorCode: {
     readonly Unauthorized: "unauthorized";
     readonly Forbidden: "forbidden";
     readonly OriginNotAllowed: "origin_not_allowed";
-    readonly InvalidAgentId: "invalid_agent_id";
+    readonly InvalidSessionLabel: "invalid_session_label";
     readonly CreditExhausted: "credit_exhausted";
     readonly KeyBudgetExceeded: "key_budget_exceeded";
     readonly InsufficientQuota: "insufficient_quota";
@@ -219,6 +221,22 @@ export interface HearGroundingPassage {
     content: string;
     score: number;
 }
+/** One endpointing validation result echoed in a `config_ack` frame. */
+export interface HearConfigWarning {
+    field: string;
+    value: unknown;
+    effective?: number;
+    reason: "clamped_to_range" | "not_a_number" | "unknown_config_field" | (string & {});
+}
+/** Applied endpointing settings after connect-time or mid-session config. */
+export interface HearConfigAckFrame {
+    type: "config_ack";
+    endpointing_ms: number;
+    effective_floor_ms: number;
+    effective_ceiling_ms: number;
+    score_interval_ms: number;
+    warnings: HearConfigWarning[];
+}
 /** Live hypothesis frame (`partial` / `partial_stable`). */
 export interface HearPartialFrame {
     type: "partial" | "partial_stable";
@@ -232,6 +250,7 @@ export interface HearPartialFrame {
     t_ms: number;
 }
 /** Finalized-utterance frame (`speech_final` / `final`). */
+export type HearEndpointReason = "peak_te_early" | "silence_backstop" | "commit" | (string & {});
 export interface HearFinalFrame {
     type: "speech_final" | "final";
     text: string;
@@ -239,6 +258,8 @@ export interface HearFinalFrame {
     t_ms: number;
     /** Active-speech length of the utterance (the billed signal), ms. */
     audio_ms: number;
+    /** Why the utterance ended. Log this when tuning automatic endpointing. */
+    endpoint_reason: HearEndpointReason;
     /** Present only with Cue grounding enabled (top KB passages). */
     grounding?: HearGroundingPassage[];
 }
@@ -250,7 +271,7 @@ export interface HearUsageFrame {
     type: "usage";
     /** `hear` for plain streaming, `cue` when grounding was enabled. */
     product: "hear" | "cue";
-    /** The billed meter (`hear.requests` or `cue.minutes`). */
+    /** The billed meter (`hear.minutes` or `cue.minutes`). */
     meter: string;
     /** Summed active-speech audio billed for the session, in seconds. */
     audio_seconds: number;
@@ -263,7 +284,7 @@ export interface HearErrorFrame {
     code?: string;
     message: string;
 }
-export type HearFrame = HearPartialFrame | HearFinalFrame | HearUsageFrame | HearErrorFrame;
+export type HearFrame = HearConfigAckFrame | HearPartialFrame | HearFinalFrame | HearUsageFrame | HearErrorFrame;
 /**
  * Minimal structural WebSocket, matches both the browser/Node global
  * `WebSocket` and the `ws` package, and lets tests inject a mock.
@@ -286,8 +307,12 @@ export type WebSocketCtor = new (url: string, protocols?: string | string[]) =>
 export interface HearStreamOptions {
     /** Streaming STT model. Server default `pyai-hear`. */
     model?: string;
-    /** ISO-639-1 hint, e.g. "en". */
-    language?: string;
+    /**
+     * Hear is English-only. Set `"en"` explicitly; omission also means English
+     * and does not enable language detection. Other values receive
+     * `400 unsupported_language`.
+     */
+    language?: "en";
     /** Input PCM sample rate in Hz. Default 16000 server-side. */
     sampleRate?: number;
     /** Audio frame encoding. Default "pcm16". */
@@ -301,16 +326,14 @@ export interface HearStreamOptions {
      */
     numerals?: boolean;
     /**
-     * Turn-segmentation tuning: trailing-pause (ms, 50-2000) that ends an
-     * utterance. Forwards `?endpointing_ms=`, clamped + honored once the engine
-     * supports it; a no-op when omitted. Drive end-of-turn yourself with
-     * {@link HearStream.commit} for full control today.
+     * Minimum trailing-pause length before an utterance may end (50-5000 ms).
+     * Turn detection may wait longer, bounded at `max(endpointingMs, 1500)`.
+     * The server confirms the applied value through `onConfigAck`.
      */
     endpointingMs?: number;
     /**
-     * Enable Cue knowledge-base grounding: sends `{type:"config",grounding:true}`
-     * on open, after which `speech_final`/`final` frames carry a `grounding`
-     * array. Bills a single `cue.minutes` line instead of the Hear rate.
+     * Reserved Cue grounding configuration. Grounding is not active on the
+     * serving Hear stream; do not rely on grounding frames or Cue metering yet.
      */
     grounding?: boolean;
     /** Cue: number of KB passages to retrieve per turn (1-20, default 3). */
@@ -322,8 +345,11 @@ export interface HearStreamOptions {
     groundingTimeoutMs?: number;
     /** Extra query params merged onto the connect URL. */
     query?: Record<string, string>;
-    /** Fired once the socket opens (after the optional grounding config). */
+    /** Fired once the socket opens. */
     onOpen?: () => void;
+    /** Fired after connect-time or mid-session endpointing config. Assert that
+     * `warnings` is empty before relying on the requested floor. */
+    onConfigAck?: (frame: HearConfigAckFrame) => void;
     /** Fired on `partial` / `partial_stable`. */
     onPartial?: (frame: HearPartialFrame) => void;
     /** Fired on `speech_final` / `final`. */
@@ -340,8 +366,10 @@ export interface HearStreamOptions {
 /**
  * A live Hear streaming-STT session. Hides the frame protocol: stream audio
  * with {@link HearStream.sendAudio}, get `onPartial`/`onFinal`/`onError`
- * callbacks, force-finalize with {@link HearStream.commit}, and flush+close
- * with {@link HearStream.close}. Construct via `pyai.audio.transcriptions.stream()`.
+ * callbacks, update the silence floor with
+ * {@link HearStream.configureEndpointing}, force-finalize with
+ * {@link HearStream.commit}, and flush+close with {@link HearStream.close}.
+ * Construct via `pyai.audio.transcriptions.stream()`.
  */
 export declare class HearStream {
     private readonly ws;
@@ -351,6 +379,8 @@ export declare class HearStream {
     private handleMessage;
     /** Send a chunk of audio (PCM16 or opus per `encoding`). */
     sendAudio(chunk: ArrayBufferLike | ArrayBufferView | Blob): void;
+    /** Change the minimum trailing-pause floor without reconnecting. */
+    configureEndpointing(endpointingMs: number): void;
     /** Force-finalize the current utterance (e.g. on VAD end-of-turn). */
     commit(): void;
     /** Close the socket; the server flushes a final for any buffered audio. */
@@ -420,6 +450,21 @@ export interface OmniServerFrame {
     event: string;
     [k: string]: unknown;
 }
+/** Canonical, sanitized transcript delivered by the native Omni demux.
+ * The live wire sends caller text deltas; the JSON fields are SDK-owned
+ * normalization so applications don't have to special-case the byte payload. */
+export interface OmniTranscriptFrame extends OmniServerFrame {
+    event: "transcript";
+    role: "user" | "assistant";
+    text: string;
+    final: boolean;
+    /** Live text frames append; legacy JSON frames replace unless they use `delta`. */
+    mode: "delta" | "replace";
+    /** Optional ordering hint on legacy JSON frames. */
+    sequence?: number;
+}
+/** Normalize the live UTF-8 `0x02` text body and bounded legacy JSON bodies. */
+export declare function normalizeOmniTranscriptBody(bytes: Uint8Array): OmniTranscriptFrame | null;
 /** A binary agent-audio chunk delivered to {@link OmniConnectOptions.onAudio}. */
 export type OmniAudioChunk = ArrayBuffer | ArrayBufferView | Blob;
 export interface OmniToolDef {
@@ -430,7 +475,7 @@ export interface OmniToolDef {
     endpoint?: string;
 }
 export interface OmniToolCallFrame {
-    type: "tool_call";
+    event: "tool_call";
     call_id: string;
     name: string;
     arguments?: Record<string, unknown>;
@@ -455,7 +500,7 @@ export interface OmniConfigure {
     /**
      * Session language, end to end (recognition, reasoning, voice). Also
      * settable on the agent profile (`language` on `POST /v1/agents`), which
-     * applies automatically when connecting with `session_label={agent_id}`;
+     * applies automatically when `session_label` is the saved profile id;
      * an inline value here wins for the session. Default `en`. Fail-safe: an
      * unknown/not-yet-enabled language falls back to `en` (the `configured`
      * ack carries `language_active` + `language_fallback: true`), the call
@@ -477,7 +522,11 @@ export interface OmniConnectOptions {
      * so a page never holds a secret key.
      */
     token?: string;
-    /** Connect-URL sample rate: 24000 browser, 16000 wideband telephony, 8000 G.711/Twilio. */
+    /**
+     * Caller-input sample rate. `24000` and `16000` sessions receive agent audio
+     * at 24 kHz; `8000` sessions receive 8 kHz. Read `hello.audio_out` rather than
+     * assuming output matches this value.
+     */
     rate?: 24000 | 16000 | 8000;
     /** Connect-URL audio format. Default `pcm16`. */
     format?: "pcm16";
@@ -500,7 +549,7 @@ export interface OmniConnectOptions {
     onSessionStarted?: (frame: OmniServerFrame) => void;
     /** Fired on `turn` boundaries. */
     onTurn?: (frame: OmniServerFrame) => void;
-    /** Fired on `transcript` text frames. */
+    /** Fired for each normalized caller-transcript delta (`0x02` plain UTF-8 live). */
     onTranscript?: (frame: OmniServerFrame) => void;
     /** Fired on `barge_in` / `flush` (user interrupted). */
     onBargeIn?: (frame: OmniServerFrame) => void;
@@ -539,6 +588,8 @@ export declare class OmniConnection {
     private closed;
     /** Serializes async Blob reads in {@link sendAudio} so frames stay ordered. */
     private blobTail;
+    /** Serializes inbound Blob decoding so browser frames stay ordered. */
+    private inboundTail;
     constructor(url: string, subprotocol: string, opts: OmniConnectOptions);
     private handleMessage;
     private dispatchFrame;
@@ -841,8 +892,13 @@ export interface RecapCallTriggerInput {
     customer_name?: string;
     crm_fields?: Record<string, unknown>;
 }
-/** PyAI's richer answered-by vocabulary (superset of Twilio's enum). */
-export type AmdAnsweredBy = "human" | "voicemail" | "live_voicemail" | "screening" | "ivr" | "human_gatekeeper" | "sit_invalid" | "fax" | "silence" | "unknown";
+/**
+ * The answered-by vocabulary on stored call records and the
+ * `amd.call.completed` webhook: the routing classes plus the machine subtypes.
+ */
+export type AmdAnsweredBy = "human" | "machine" | "voicemail" | "screening" | "ivr" | "music" | "sit_invalid" | "unknown";
+/** The routing classes pushed on the mid-call wire event (`event: "amd"`). */
+export type AmdWireAnsweredBy = "human" | "machine" | "sit_invalid" | "unknown";
 /** Twilio's `AnsweredBy` enum, echoed for drop-in migration parity. */
 export type AmdTwilioAnsweredBy = "human" | "machine_start" | "machine_end_beep" | "machine_end_silence" | "machine_end_other" | "fax" | "unknown";
 export interface AmdConfigInput {
@@ -880,11 +936,16 @@ export interface AmdCall extends AmdCallSummary {
     meta?: Record<string, unknown> | null;
     error?: string | null;
 }
-/** A mid-call AMD decision event pushed on the stream (and to the webhook). */
+/**
+ * A mid-call AMD decision event pushed on the stream (and to the per-call
+ * TwiML `webhook`). Carries the coarse routing class; the machine subtype
+ * (`voicemail`/`ivr`/`screening`/`music`) is on the stored call record
+ * (`AmdCall`) and the `amd.call.completed` webhook instead.
+ */
 export interface AmdDecisionEvent {
     event?: "amd";
     call_id?: string;
-    answered_by?: AmdAnsweredBy;
+    answered_by?: AmdWireAnsweredBy;
     answered_by_twilio?: string | null;
     confidence?: number | null;
     decision_ms?: number | null;
@@ -954,7 +1015,11 @@ export declare class PyAI {
                 file: Blob;
                 filename?: string;
                 model?: string;
-                language?: string;
+                /**
+                 * Hear is English-only. Omission means English, not auto-detect; other
+                 * values receive `400 unsupported_language`.
+                 */
+                language?: "en";
                 response_format?: "json" | "text" | "verbose_json";
                 /**
                  * Deterministic seed for reproducible eval runs. Forward-compatible:
@@ -994,7 +1059,7 @@ export declare class PyAI {
     clones: {
         /** List the org's cloned voices. */
         list: () => Promise<ListResponse<Voice>>;
-        /** Enroll a custom voice from reference audio (>= ~10s). Scope `voice:clone`. */
+        /** Enroll a custom voice from reference audio (>= ~10s). Scope `speak:clone`. */
         create: (params: {
             name: string;
             file: Blob;
@@ -1006,7 +1071,7 @@ export declare class PyAI {
          * when the id isn't found.
          */
         get: (id: string) => Promise<Voice>;
-        /** Delete a cloned voice (tenant-isolated). Scope `voice:clone`. */
+        /** Delete a cloned voice (tenant-isolated). Scope `speak:clone`. */
         delete: (id: string) => Promise<void>;
     };
     telephony: {
@@ -1151,7 +1216,7 @@ export declare class PyAI {
          */
         connect: (opts?: OmniConnectOptions) => OmniConnection;
     };
-    /** Build the realtime WebSocket URL for the chosen product. */
+    /** Build the canonical Omni WebSocket URL. */
     realtimeURL(opts?: RealtimeOptions): string;
     /** The subprotocol that carries the key on a WS upgrade (browser-safe auth). */
     realtimeSubprotocol(): string;