@pyai/sdk 0.2.0 → 0.2.2

package/README.md

@@ -1,18 +1,19 @@
 # @pyai/sdk
 
-Official TypeScript/JavaScript SDK for [PyAI](https://pyai.com) — the all-in-one
+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)** — 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`
+- **[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`
+- **[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`
 
 The contract is `https://api.pyai.com/openapi.json`. This SDK wraps it
 ergonomically with typed errors, automatic retries, and a realtime helper.
@@ -31,13 +32,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
+// 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
@@ -51,22 +52,61 @@ const job = await pyai.transcriptionJobs.create(
 const done = await pyai.transcriptionJobs.get(job.job_id);
 ```
 
+## Use with MCP (AI coding agents)
+
+Building this SDK *with* an AI coding agent (Cursor, Claude Code, Codex)? Add the
+PyAI **MCP server** ([`@pyai/mcp`](https://www.npmjs.com/package/@pyai/mcp)) so
+the agent can mint a free key and call PyAI as tools, no endpoint guessing, no
+human setup step:
+
+```jsonc
+// .cursor/mcp.json  ·  or:  claude mcp add pyai -- npx -y @pyai/mcp
+{ "mcpServers": { "pyai": { "command": "npx", "args": ["-y", "@pyai/mcp"] } } }
+```
+
+With no key set, the server exposes `create_sandbox_key`, calls it, and adopts
+the minted key for the session, then `get_started`, `list_voices`,
+`synthesize_speech`, and the transcription tools work immediately. Full setup +
+a runnable client: the [`mcp-quickstart`](https://github.com/atomsai/pyai-examples/tree/main/mcp-quickstart)
+example.
+
 ## 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),
+});
+
+omni.sendAudio(pcm16Chunk); // stream caller audio continuously (server-side VAD)
+omni.sendDtmf("5");
+omni.close();
+```
 
-// Or build the pieces yourself for a custom WS library:
-const url = pyai.realtimeURL({ product: "omni", agentId: "agent_123" });
-const proto = pyai.realtimeSubprotocol();
+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. `connectRealtime`
-> targets it by default (`product: "omni"`); `product: "flow"` uses
-> `/v1/realtime`. The older `/v2/omni/chat` URL is deprecated but still works.
+> 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)
 
@@ -108,15 +148,14 @@ In Node, pass a WebSocket implementation if there's no global one:
 
 ## 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
+`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",
+  voice: "stock_emma_en_gb",
   response_format: "g711_ulaw", // -> audio/basic, forced 8 kHz
 });
 // base64-encode `ulaw` straight into a Twilio media frame.
@@ -133,7 +172,7 @@ const ulaw = await pyai.audio.speech({
 | `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
+`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`.
@@ -142,6 +181,48 @@ always 8 kHz). The set is typed (`SpeechFormat`) and exported as `SPEECH_FORMATS
 > for the full before/after: ~120 lines of resampler + μ-law replaced by one
 > param, with Node (`@pyai/twilio`), Python, and raw-curl snippets.
 
+## AMD (answering-machine detection)
+
+Already on Twilio? The usual path is **one line of TwiML** pointing the call's
+media at PyAI, no SDK needed. The `answered_by_twilio` field maps to Twilio's
+exact `AnsweredBy` enum, so your routing logic doesn't change:
+
+```xml
+<Response><Connect>
+  <Stream url="wss://api.pyai.com/v1/amd/stream">
+    <Parameter name="api_key" value="YOUR_PYAI_KEY"/>
+    <Parameter name="aggressiveness" value="0.25"/>
+    <Parameter name="webhook" value="https://you/amd-events"/>
+  </Stream>
+</Connect></Response>
+```
+
+(The key rides a `<Parameter>` because Twilio strips query strings from the
+`<Stream>` URL; PyAI verifies it from the `start` frame before processing any
+audio.)
+
+From code, set the operating point and read decisions back:
+
+```ts
+// One aggressiveness dial: near 0 = human-safe, near 1 = fire "machine" fast.
+await pyai.amd.config.set({ aggressiveness: 0.25, webhookUrl: "https://you/amd-events" });
+
+const { data: decisions } = await pyai.amd.calls.list({ sessionLabel: "sales" });
+const decision = await pyai.amd.calls.get("C_123");
+// decision.answered_by = "human" | "voicemail" | "screening" | "sit_invalid" | ...
+// decision.answered_by_twilio = "human" | "machine_start" | ...  (Twilio parity)
+// decision.reason = "machine phrase: 'leave a message' @1.2s"
+
+// Server-side helper if you fork the media yourself (Twilio Media Streams wire):
+const stream = pyai.amd.stream({
+  aggressiveness: 0.25,
+  onDecision: (d) => console.log(d.answered_by, d.decision_ms, d.reason),
+});
+```
+
+Billed per **answered** call, first 5,000 answered calls/month free, then
+$0.004/call; free when bundled with PyAI telephony/Omni.
+
 ## More APIs: clones, telephony, trace
 
 ```ts
@@ -163,7 +244,7 @@ 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
+// 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?, … }
@@ -172,11 +253,11 @@ const quality = detail.quality_metrics;                    // { wer?, ttfb_ms?,
 ## 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:
+`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.speech({ input: "Hello", voice: "stock_emma_en_gb", seed: 42, temperature: 0 });
 await pyai.audio.transcriptions.create({ file: wavBlob, seed: 42 });
 ```
 
@@ -191,7 +272,7 @@ try {
   await pyai.audio.speech({ input: "hi" });
 } catch (err) {
   if (err instanceof PyAIError && err.code === "credit_exhausted") {
-    // out of prepaid credit — add credit or use a sandbox key
+    // out of prepaid credit, add credit or use a sandbox key
   }
 }
 ```
@@ -204,17 +285,17 @@ Common codes: `unauthorized`, `forbidden`, `credit_exhausted`,
 ## CLI (`pyai`)
 
 Installing the package also provides a `pyai` command. `pyai doctor` runs a
-deeper diagnosis — it introspects your key/scopes via `GET /v1/me` (skipped
+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 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  speak→hear round-trip  — synth 45210 bytes → "the quick brown fox…"
+# 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  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
@@ -225,7 +306,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,17 +1,18 @@
 #!/usr/bin/env node
 /**
- * pyai — CLI for the PyAI API: proves your key, the endpoint, and audio in one
+ * 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 smoke [--tolerate-upstream]    run models+voices+speak and report PASS/FAIL
+ *                                       (--tolerate-upstream: transient 5xx/429 → WARN, not FAIL)
  *   pyai models                         list models
  *   pyai voices [--gender g --region r] list voices
  *   pyai speak --text T [--voice V] [--out f.wav]
  *   pyai transcribe --url U [--diarize] [--poll]
  *
  * Auth: PYAI_API_KEY env (or --api-key). Base URL: PYAI_BASE_URL (or --base-url).
- * Zero deps — uses the bundled SDK.
+ * Zero deps, uses the bundled SDK.
  */
 export {};

package/dist/cli.js

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 /**
- * pyai — CLI for the PyAI API: proves your key, the endpoint, and audio in one
+ * 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 smoke [--tolerate-upstream]    run models+voices+speak and report PASS/FAIL
+ *                                       (--tolerate-upstream: transient 5xx/429 → WARN, not FAIL)
  *   pyai models                         list models
  *   pyai voices [--gender g --region r] list voices
  *   pyai speak --text T [--voice V] [--out f.wav]
  *   pyai transcribe --url U [--diarize] [--poll]
  *
  * Auth: PYAI_API_KEY env (or --api-key). Base URL: PYAI_BASE_URL (or --base-url).
- * Zero deps — uses the bundled SDK.
+ * Zero deps, uses the bundled SDK.
  */
 import { writeFile } from "node:fs/promises";
 import PyAI, { PyAIError } from "./index.js";
@@ -55,11 +56,12 @@ function fail(msg) {
     process.stderr.write(`pyai: ${msg}\n`);
     process.exit(1);
 }
-const USAGE = `pyai — PyAI API CLI
+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 smoke [--tolerate-upstream]        run a key/endpoint/audio smoke test
+                                          (--tolerate-upstream: transient 5xx/429 warn, don't fail)
   pyai models                             list models
   pyai voices [--gender g] [--region r]   list voices
   pyai speak --text T [--voice V] [--out f.wav]
@@ -105,17 +107,54 @@ async function cmdTranscribe(flags) {
     }
     out(`job ${job.job_id} still running after polling; check later.`);
 }
+// Transient upstream conditions: a momentary engine/capacity blip or network
+// hiccup, NOT a key/scope/contract problem. 5xx = engine unhealthy (e.g. Speak
+// "503 service_unavailable"), 429 = rate/capacity, a non-PyAIError = network.
+// These self-heal; the others (401/403/404/400) are real and must fail loudly.
+const TRANSIENT_STATUSES = new Set([429, 500, 502, 503, 504]);
+function isTransient(err) {
+    if (err instanceof PyAIError)
+        return TRANSIENT_STATUSES.has(err.status);
+    return true; // network / timeout / unknown, worth a retry, never a hard fail on its own
+}
+/** Retry `fn` on transient upstream errors with exponential backoff. Real
+ * (non-transient) errors throw immediately, we never paper over a bad key. */
+async function withRetry(fn, attempts = 4, baseMs = 800) {
+    let lastErr;
+    for (let i = 0; i < attempts; i++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isTransient(err) || i === attempts - 1)
+                throw err;
+            await new Promise((r) => setTimeout(r, baseMs * 2 ** i));
+        }
+    }
+    throw lastErr;
+}
 /** The headline: prove key + endpoint + audio in one command. */
 async function cmdSmoke(flags) {
     const pyai = client(flags);
+    // CI/ops opt-in: a transient upstream blip (engine warming, a brief 503,
+    // rate-limit) should not red the build, it isn't the commit's fault. With this
+    // on, such failures are reported as WARN (exit 0); real key/scope/contract
+    // failures still FAIL (exit 1). Off by default so a developer running `pyai
+    // smoke` gets the strict, honest answer.
+    const tolerateUpstream = flags["tolerate-upstream"] === true || process.env.PYAI_SMOKE_TOLERATE_UPSTREAM === "1";
+    // Retry tuning is env-overridable (tests drive it fast; default rides brief blips).
+    const retryAttempts = Number(process.env.PYAI_SMOKE_RETRY_ATTEMPTS ?? 4);
+    const retryBaseMs = Number(process.env.PYAI_SMOKE_RETRY_BASE_MS ?? 800);
     const checks = [];
     const run = async (name, fn) => {
         try {
-            checks.push({ name, ok: true, detail: await fn() });
+            checks.push({ name, status: "PASS", detail: await withRetry(fn, retryAttempts, retryBaseMs) });
         }
         catch (err) {
-            const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}` : err.message;
-            checks.push({ name, ok: false, detail });
+            const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}`.trim() : err.message;
+            const status = isTransient(err) && tolerateUpstream ? "WARN" : "FAIL";
+            checks.push({ name, status, detail });
         }
     };
     await run("models.list", async () => {
@@ -131,11 +170,22 @@ async function cmdSmoke(flags) {
         return `${Buffer.from(audio).byteLength} bytes of audio`;
     });
     for (const c of checks)
-        out(`${c.ok ? "PASS" : "FAIL"}  ${c.name}  — ${c.detail}`);
-    const allOk = checks.every((c) => c.ok);
-    out(allOk ? "\nAll checks passed. Your key, the endpoint, and audio synthesis work." : "\nSome checks failed (see above).");
-    if (!allOk)
+        out(`${c.status}  ${c.name}, ${c.detail}`);
+    const failed = checks.filter((c) => c.status === "FAIL");
+    const warned = checks.filter((c) => c.status === "WARN");
+    // GitHub Actions annotation: a tolerated blip is still surfaced in the run UI.
+    for (const c of warned)
+        out(`::warning title=PyAI smoke transient::${c.name}: ${c.detail}`);
+    if (failed.length === 0 && warned.length === 0) {
+        out("\nAll checks passed. Your key, the endpoint, and audio synthesis work.");
+    }
+    else if (failed.length === 0) {
+        out(`\n${warned.length} transient upstream issue(s) tolerated (self-healing engine blip), not failing the build.`);
+    }
+    else {
+        out("\nSome checks failed (see above).");
         process.exit(1);
+    }
 }
 /** Turn an error into an actionable, code-first remediation hint. */
 function remediation(err) {
@@ -143,35 +193,35 @@ function remediation(err) {
         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).";
+            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.";
+            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.";
+            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.";
+            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.";
+            return "Per-key monthly budget hit, raise the budget in the console.";
         case "insufficient_quota":
-            return "Plan quota exhausted — upgrade your plan.";
+            return "Plan quota exhausted, upgrade your plan.";
         case "rate_limit_exceeded":
-            return "Rate limited — back off and retry (honor Retry-After).";
+            return "Rate limited, back off and retry (honor Retry-After).";
         case "concurrency_limit_exceeded":
-            return "Too many concurrent sessions — retry shortly.";
+            return "Too many concurrent sessions, retry shortly.";
         case "daily_cap_exceeded":
-            return "Daily cap reached — wait until it resets.";
+            return "Daily cap reached, wait until it resets.";
         default:
             break;
     }
     switch (err.status) {
         case 401:
-            return "Invalid or missing key — check PYAI_API_KEY.";
+            return "Invalid or missing key, check PYAI_API_KEY.";
         case 403:
-            return "Forbidden — the key likely lacks the required scope.";
+            return "Forbidden, the key likely lacks the required scope.";
         case 404:
-            return "Not found — check PYAI_BASE_URL and the route.";
+            return "Not found, check PYAI_BASE_URL and the route.";
         case 429:
-            return "Rate/concurrency limited — back off and retry.";
+            return "Rate/concurrency limited, back off and retry.";
         default:
             return err.message;
     }
@@ -190,7 +240,7 @@ 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.
+    // "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 : [];
@@ -225,7 +275,7 @@ async function cmdDoctor(flags) {
         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}`);
+        out(`${c.status.padEnd(4)}  ${c.name}, ${c.detail}`);
         if (c.hint)
             out(`        ↳ ${c.hint}`);
     }
@@ -234,7 +284,7 @@ async function cmdDoctor(flags) {
         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.`);
+        out(`\nDiagnosis: ${failed.length} check(s) failed, see the remediation hints above.`);
         process.exit(1);
     }
 }