@pyai/sdk 0.1.1 → 0.2.0

package/README.md

@@ -1,17 +1,18 @@
 # @pyai/sdk
 
-Official TypeScript/JavaScript SDK for [PyAI](https://pyai.com) — the voice-AI
-platform for speech-to-text, text-to-speech, realtime voice agents, and
-automated call compliance. Zero dependencies; runs in the browser and Node 18+.
+Official TypeScript/JavaScript SDK for [PyAI](https://pyai.com) — the all-in-one
+voice AI platform: lightning-fast speech-to-text, ultra-realistic text-to-speech,
+end-to-end realtime voice agents, and automatic call compliance. Zero
+dependencies; runs in the browser and Node 18+.
 
 ## PyAI products
 
-- **[Hear](https://pyai.com/models/hear)** — Speech-to-text tuned for telephony (8 kHz), with streaming partials and a half-price async batch tier; OpenAI-compatible. `POST /v1/audio/transcriptions`
-- **[Speak](https://pyai.com/models/speak)** — Low-latency streaming text-to-speech (~32–98 ms to first byte) with 36 stock voices and free instant voice cloning. `POST /v1/audio/speech`
-- **[Omni](https://pyai.com/models/omni)** _(flagship)_ — End-to-end realtime voice agents over a single WebSocket: listens, thinks, and speaks — grounded in your knowledge bases and tools, with natural turn-taking and barge-in. `wss://api.pyai.com/v1/omni`
-- **[Trace](https://pyai.com/models/trace)** _(flagship)_ — Automated compliance & QA on every call: scores each call against rule packs (TCPA, HIPAA, PII, brand-voice), with findings that cite the rule, auto-redaction, and a tamper-evident audit hash. `GET /v1/trace/interactions`
-- **[Cue](https://pyai.com/models/cue)** — Turn detection + retrieved knowledge-base context for bring-your-own-LLM/voice pipelines, billed as one per-minute meter. `wss://api.pyai.com/v1/audio/transcriptions/stream`
-- **[Telephony](https://pyai.com/models/telephony)** — Managed US phone numbers routed straight to your Omni agents, no separate carrier contract. `POST /v1/telephony/numbers`
+- **[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`
+- **[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`
+- **[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`
 
 The contract is `https://api.pyai.com/openapi.json`. This SDK wraps it
 ergonomically with typed errors, automatic retries, and a realtime helper.
@@ -67,6 +68,118 @@ const proto = pyai.realtimeSubprotocol();
 > targets it by default (`product: "omni"`); `product: "flow"` uses
 > `/v1/realtime`. The older `/v2/omni/chat` URL is deprecated but still works.
 
+## Streaming speech-to-text (Hear / Cue)
+
+`transcriptions.stream()` hides the WebSocket frame protocol behind callbacks.
+It opens `wss://api.pyai.com/v1/audio/transcriptions/stream` (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()`:
+
+```ts
+const hear = pyai.audio.transcriptions.stream({
+  sampleRate: 16000,
+  onPartial: (f) => console.log("…", f.text),
+  onFinal: (f) => console.log("✓", f.text, `(${f.audio_ms}ms)`),
+  onError: (e) => console.error(e),
+});
+
+micChunks.on("data", (pcm16) => hear.sendAudio(pcm16)); // binary frames
+vad.on("end", () => hear.commit());                     // force-finalize an utterance
+// hear.close() also flushes a final for any buffered audio
+```
+
+Frame `type`s, WS close codes, and error `code`s are exported as named
+constants so you never hardcode a magic string:
+
+```ts
+import { HearFrameType, WSCloseCode, ErrorCode } from "@pyai/sdk";
+HearFrameType.SpeechFinal; // "speech_final"
+WSCloseCode.OverCapacity;  // 4429
+ErrorCode.CreditExhausted; // "credit_exhausted"
+```
+
+Set `grounding: true` to turn the stream into **Cue** (turn detection + KB
+context): the SDK sends the grounding config on open and `final`/`speech_final`
+frames then carry a `grounding` array of top KB passages.
+
+In Node, pass a WebSocket implementation if there's no global one:
+`transcriptions.stream({ webSocket: (await import("ws")).WebSocket })`.
+
+## Speak audio formats (incl. telephony G.711)
+
+`audio.speech` encodes server-side into any of eight formats via `response_format`
+— the audio comes back already in the shape you need, so telephony callers can
+drop the hand-rolled resampler + μ-law encoder entirely:
+
+```ts
+// Twilio/SIP-ready in one param: raw 8 kHz mono μ-law, no client-side DSP.
+const ulaw = await pyai.audio.speech({
+  input: "Your appointment is confirmed.",
+  voice: "stock_sarah_style2",
+  response_format: "g711_ulaw", // -> audio/basic, forced 8 kHz
+});
+// base64-encode `ulaw` straight into a Twilio media frame.
+```
+
+| `response_format` | sample rates (Hz) | Content-Type |
+|---|---|---|
+| `mp3` (default) | 8000 / 16000 / 24000 / 48000 | `audio/mpeg` |
+| `wav` | 8000 / 16000 / 24000 / 48000 | `audio/wav` |
+| `opus` | 8000 / 16000 / 24000 / 48000 | `audio/ogg` |
+| `aac` | 8000 / 16000 / 24000 / 48000 | `audio/aac` |
+| `flac` | 8000 / 16000 / 24000 / 48000 | `audio/flac` |
+| `pcm` (raw int16 LE, no header) | 8000 / 16000 / 24000 / 48000 | `audio/pcm` |
+| `g711_ulaw` | 8000 (forced) | `audio/basic` |
+| `g711_alaw` | 8000 (forced) | `audio/basic` |
+
+`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`.
+
+> See [`examples/speak-telephony-formats`](../../examples/speak-telephony-formats)
+> for the full before/after: ~120 lines of resampler + μ-law replaced by one
+> param, with Node (`@pyai/twilio`), Python, and raw-curl snippets.
+
+## More APIs: clones, telephony, trace
+
+```ts
+// Voice clones (Speak)
+const { data: clones } = await pyai.clones.list();
+const clone = await pyai.clones.create({ name: "Brand VO", file: refAudioBlob });
+await pyai.clones.delete(clone.id);
+
+// Managed phone numbers (Telephony)
+const { data: avail } = await pyai.telephony.numbers.available({ areaCode: "415" });
+const num = await pyai.telephony.numbers.buy({ phone_number: avail[0]!.phone_number, agent_id: "agent_123" });
+await pyai.telephony.numbers.assign(num.id, "agent_123");
+await pyai.telephony.numbers.release(num.id);
+
+// Compliance (Trace)
+const { data: calls } = await pyai.trace.interactions.list({ verdict: "FAIL" });
+const detail = await pyai.trace.interactions.get(calls[0]!.id);
+await pyai.trace.config.set({ agent_id: "agent_123", enabled: true });
+const exposure = await pyai.trace.exposure(30);
+
+// Per-call eval scorecard (timeline + quality metrics). These are additive and
+// forward-compatible — present once the engine emits them, so reading them is
+// always safe (the timeline reader returns [] until then).
+const timeline = await pyai.trace.callTimeline(detail.id); // TraceTimelineTurn[]
+const quality = detail.quality_metrics;                    // { wer?, ttfb_ms?, turn_p95_ms?, vaqi?, … }
+```
+
+## Reproducible runs (evals)
+
+`audio.speech` and `audio.transcriptions.create` take optional `seed` and
+`temperature` for deterministic eval runs. They're forward-compatible — honored
+once the engine supports them and otherwise ignored — so it's always safe to send:
+
+```ts
+await pyai.audio.speech({ input: "Hello", voice: "stock_sarah_style2", seed: 42, temperature: 0 });
+await pyai.audio.transcriptions.create({ file: wavBlob, seed: 42 });
+```
+
 ## Errors
 
 Failures throw `PyAIError` with a stable `code` (branch on it, not the message):
@@ -90,16 +203,21 @@ Common codes: `unauthorized`, `forbidden`, `credit_exhausted`,
 
 ## CLI (`pyai`)
 
-Installing the package also provides a `pyai` command — a smoke tester that
-proves your key, the endpoint, and audio synthesis in one shot:
+Installing the package also provides a `pyai` command. `pyai doctor` runs a
+deeper diagnosis — it introspects your key/scopes via `GET /v1/me` (skipped
+gracefully if the route isn't deployed yet), checks endpoint liveness, runs a
+Speak→Hear round-trip, and prints remediation hints for any failure:
 
 ```bash
 export PYAI_API_KEY=pyai_test_...
-npx pyai smoke
+npx pyai doctor
+# PASS  key (/v1/me)  — env=test; 3 scope(s): hear:transcribe, voice:synthesize, hear:stream
 # PASS  models.list  — 12 models
 # PASS  voices.list  — 38 voices
-# PASS  audio.speech — 45210 bytes of audio
-# All checks passed. Your key, the endpoint, and audio synthesis work.
+# PASS  speak→hear round-trip  — synth 45210 bytes → "the quick brown fox…"
+# Diagnosis: healthy. Key, endpoint, and a Speak→Hear round-trip all work.
+
+npx pyai smoke   # lighter: models + voices + speak
 ```
 
 Other commands:

package/dist/cli.d.ts

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 /**
- * pyai — CLI smoke tester for the PyAI API: proves your key, the endpoint,
- * and audio synthesis in one command.
+ * pyai — CLI for the PyAI API: proves your key, the endpoint, and audio in one
+ * command (`smoke`) or runs a deeper diagnosis with remediation hints (`doctor`).
  *
  * Commands:
+ *   pyai doctor                         diagnose key/scopes + endpoint + Speak→Hear round-trip
  *   pyai smoke                          run models+voices+speak and report PASS/FAIL
  *   pyai models                         list models
  *   pyai voices [--gender g --region r] list voices

package/dist/cli.js

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
 /**
- * pyai — CLI smoke tester for the PyAI API: proves your key, the endpoint,
- * and audio synthesis in one command.
+ * pyai — CLI for the PyAI API: proves your key, the endpoint, and audio in one
+ * command (`smoke`) or runs a deeper diagnosis with remediation hints (`doctor`).
  *
  * Commands:
+ *   pyai doctor                         diagnose key/scopes + endpoint + Speak→Hear round-trip
  *   pyai smoke                          run models+voices+speak and report PASS/FAIL
  *   pyai models                         list models
  *   pyai voices [--gender g --region r] list voices
@@ -57,6 +58,7 @@ function fail(msg) {
 const USAGE = `pyai — PyAI API CLI
 
 Usage:
+  pyai doctor                             diagnose key/scopes + endpoint + Speak→Hear round-trip
   pyai smoke                              run a key/endpoint/audio smoke test
   pyai models                             list models
   pyai voices [--gender g] [--region r]   list voices
@@ -135,10 +137,113 @@ async function cmdSmoke(flags) {
     if (!allOk)
         process.exit(1);
 }
+/** Turn an error into an actionable, code-first remediation hint. */
+function remediation(err) {
+    if (!(err instanceof PyAIError))
+        return err?.message ?? String(err);
+    switch (err.code) {
+        case "unauthorized":
+            return "Invalid or missing key — check PYAI_API_KEY (a pyai_test_ or pyai_live_ key).";
+        case "forbidden":
+            return "Key is missing a required scope — add it to the key in the console.";
+        case "origin_not_allowed":
+            return "Publishable token origin not allow-listed — fix the allowed origins.";
+        case "credit_exhausted":
+            return "Out of prepaid credit — add credit, or use a pyai_test_ sandbox key.";
+        case "key_budget_exceeded":
+            return "Per-key monthly budget hit — raise the budget in the console.";
+        case "insufficient_quota":
+            return "Plan quota exhausted — upgrade your plan.";
+        case "rate_limit_exceeded":
+            return "Rate limited — back off and retry (honor Retry-After).";
+        case "concurrency_limit_exceeded":
+            return "Too many concurrent sessions — retry shortly.";
+        case "daily_cap_exceeded":
+            return "Daily cap reached — wait until it resets.";
+        default:
+            break;
+    }
+    switch (err.status) {
+        case 401:
+            return "Invalid or missing key — check PYAI_API_KEY.";
+        case 403:
+            return "Forbidden — the key likely lacks the required scope.";
+        case 404:
+            return "Not found — check PYAI_BASE_URL and the route.";
+        case 429:
+            return "Rate/concurrency limited — back off and retry.";
+        default:
+            return err.message;
+    }
+}
+async function doctorCheck(checks, name, fn) {
+    try {
+        checks.push({ name, status: "PASS", detail: await fn() });
+    }
+    catch (err) {
+        const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}`.trim() : err.message;
+        checks.push({ name, status: "FAIL", detail, hint: remediation(err) });
+    }
+}
+/** Deeper than smoke: key/scopes, endpoint liveness, and a Speak→Hear round-trip. */
+async function cmdDoctor(flags) {
+    const pyai = client(flags);
+    const checks = [];
+    // (a) Key validity + scopes via GET /v1/me. The route is new, so a 404 means
+    // "not deployed here yet" — skip it rather than failing the whole doctor.
+    try {
+        const me = await pyai.me();
+        const scopes = Array.isArray(me.scopes) ? me.scopes : [];
+        const env = me.environment ?? me.env ?? "unknown";
+        checks.push({
+            name: "key (/v1/me)",
+            status: "PASS",
+            detail: `env=${env}; ${scopes.length} scope(s)${scopes.length ? `: ${scopes.join(", ")}` : ""}`,
+        });
+    }
+    catch (err) {
+        if (err instanceof PyAIError && err.status === 404) {
+            checks.push({ name: "key (/v1/me)", status: "SKIP", detail: "introspection route not on this deployment" });
+        }
+        else {
+            const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""}`.trim() : err.message;
+            checks.push({ name: "key (/v1/me)", status: "FAIL", detail, hint: remediation(err) });
+        }
+    }
+    // (b) Endpoint liveness.
+    await doctorCheck(checks, "models.list", async () => `${(await pyai.models.list()).data.length} models`);
+    await doctorCheck(checks, "voices.list", async () => `${(await pyai.voices.list()).data.length} voices`);
+    // (c) Speak -> Hear round-trip: synthesize a sentence, then transcribe it.
+    await doctorCheck(checks, "speak→hear round-trip", async () => {
+        const audio = await pyai.audio.speech({ input: "The quick brown fox jumps over the lazy dog." });
+        const bytes = Buffer.from(audio).byteLength;
+        const blob = new Blob([audio], { type: "audio/wav" });
+        const tr = await pyai.audio.transcriptions.create({ file: blob, filename: "doctor.wav" });
+        const text = (tr.text ?? "").trim();
+        if (!text)
+            throw new Error(`synthesized ${bytes} bytes but transcription came back empty`);
+        return `synth ${bytes} bytes → "${text.length > 60 ? `${text.slice(0, 60)}…` : text}"`;
+    });
+    for (const c of checks) {
+        out(`${c.status.padEnd(4)}  ${c.name}  — ${c.detail}`);
+        if (c.hint)
+            out(`        ↳ ${c.hint}`);
+    }
+    const failed = checks.filter((c) => c.status === "FAIL");
+    if (failed.length === 0) {
+        out("\nDiagnosis: healthy. Key, endpoint, and a Speak→Hear round-trip all work.");
+    }
+    else {
+        out(`\nDiagnosis: ${failed.length} check(s) failed — see the remediation hints above.`);
+        process.exit(1);
+    }
+}
 async function main() {
     const flags = parseArgs(process.argv.slice(2));
     const cmd = flags._[0];
     switch (cmd) {
+        case "doctor":
+            return cmdDoctor(flags);
         case "smoke":
             return cmdSmoke(flags);
         case "models":