@pyai/sdk 0.1.2 → 0.2.1

package/README.md

@@ -31,13 +31,13 @@ import PyAI from "@pyai/sdk";
 const pyai = new PyAI({ apiKey: process.env.PYAI_API_KEY! });
 
 // Text-to-speech
-const audio = await pyai.audio.speech({ input: "Hello from PyAI.", voice: "stock_sarah_style2" });
+const audio = await pyai.audio.speech({ input: "Hello from PyAI.", voice: "stock_emma_en_gb" });
 await Bun.write?.("hello.wav", audio); // or fs.writeFile in Node
 
 // Text-to-speech, streamed — start playing/forwarding at the first chunk
 // (tens of ms) instead of waiting for the whole clip. Use mp3 for smooth
 // progressive playback.
-const stream = await pyai.audio.speechStream({ input: "Hello from PyAI.", voice: "stock_sarah_style2", response_format: "mp3" });
+const stream = await pyai.audio.speechStream({ input: "Hello from PyAI.", voice: "stock_emma_en_gb", response_format: "mp3" });
 for await (const chunk of stream) writeToSpeakerOrResponse(chunk);
 
 // Voices
@@ -53,20 +53,154 @@ const done = await pyai.transcriptionJobs.get(job.job_id);
 
 ## Realtime (Omni)
 
-Keys travel as a WebSocket subprotocol so this works in the browser:
+`omni.connect()` opens an agentic-voice session and hides the wire protocol —
+including its **frame-key asymmetry** (your control frames are keyed on `type`,
+the server's frames are keyed on `event`). It sends a `type`-keyed `configure`
+the instant the socket opens and routes server frames to typed callbacks, so you
+**can't** trip the #1 Omni integration bug (a hand-rolled `{"event":"configure"}`
+is acked but silently dropped, giving you a connected session with zero turns):
 
 ```ts
-const ws = pyai.connectRealtime({ product: "omni", agentId: "agent_123" });
-ws.addEventListener("message", (e) => console.log(e.data));
+// Omni is zero-state: the key's org authorizes the session — nothing to create.
+const omni = pyai.omni.connect({
+  rate: 16000, // 24000 browser · 16000 wideband telephony · 8000 G.711/Twilio
+  configure: { voice_id: "stock_emma_en_gb", persona: "You are a receptionist." },
+  onAudio: (chunk) => speaker.write(chunk), // binary agent audio — play it out
+  onTranscript: (f) => console.log(f.text),
+  onError: (e) => console.error(e),
+});
 
-// Or build the pieces yourself for a custom WS library:
-const url = pyai.realtimeURL({ product: "omni", agentId: "agent_123" });
-const proto = pyai.realtimeSubprotocol();
+omni.sendAudio(pcm16Chunk); // stream caller audio continuously (server-side VAD)
+omni.sendDtmf("5");
+omni.close();
 ```
 
-> Omni uses the native `wss://api.pyai.com/v1/omni` surface. `connectRealtime`
-> targets it by default (`product: "omni"`); `product: "flow"` uses
-> `/v1/realtime`. The older `/v2/omni/chat` URL is deprecated but still works.
+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:
+
+```ts
+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.
+
+## 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_emma_en_gb",
+  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_emma_en_gb", seed: 42, temperature: 0 });
+await pyai.audio.transcriptions.create({ file: wavBlob, seed: 42 });
+```
 
 ## Errors
 
@@ -91,16 +225,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:
@@ -108,7 +247,7 @@ Other commands:
 ```bash
 pyai models
 pyai voices --gender female --region en_us
-pyai speak --text "Hello" --voice stock_sarah_style2 --out hello.wav
+pyai speak --text "Hello" --voice stock_emma_en_gb --out hello.wav
 pyai transcribe --url https://example.com/call.wav --diarize --poll
 ```
 

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":