synthiaresearch 0.0.2 → 0.0.3

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 export declare const DEFAULT_BASE_URL = "https://synthia-research--synthia-api-web.modal.run";
+/** Audio input for overloaded surfaces: raw bytes or a path to an audio file. */
+export type AudioInput = Uint8Array | string;
 /** One traced tool invocation made by the agent while answering a probe. */
 export interface ToolCall {
     name: string;
@@ -44,8 +46,11 @@ export declare class ToolSandbox {
 export interface TranscriptTurn {
     role: string;
     content: string;
+    /** Set on voiced turns (voice-enabled accounts); fetch via
+     * Rollouts.turnAudio. */
+    audio_url?: string | null;
 }
-export type RolloutAgent = (transcript: TranscriptTurn[], sandbox: ToolSandbox) => string | Promise<string>;
+export type RolloutAgent = (transcript: TranscriptTurn[], sandbox: ToolSandbox) => string | AudioInput | Promise<string | AudioInput>;
 declare class Http {
     private baseUrl;
     headers: Record<string, string>;
@@ -55,6 +60,8 @@ declare class Http {
     constructor(baseUrl: string, headers: Record<string, string>);
     get(path: string, params?: Record<string, string | number>): Promise<any>;
     post(path: string, body?: unknown): Promise<any>;
+    /** Binary GET (audio artifacts). */
+    getBytes(path: string): Promise<Uint8Array>;
     /** Un-gated request returning the raw Response (used by the handshake). */
     raw(method: string, path: string, body?: unknown, params?: Record<string, string | number>): Promise<Response>;
 }
@@ -119,11 +126,18 @@ export declare class GenerationJob {
 export declare class Seeds {
     #private;
     constructor(http: Http);
-    /** Upload seed material (documents, tool schemas, policies, traces...). */
+    /**
+     * Upload seed material (documents, tool schemas, policies, traces...).
+     *
+     * Overloaded on `content`: an object is ingested as-is (text pipeline);
+     * raw bytes or a path to an audio file (.wav/.mp3/...) is uploaded and
+     * transcribed server-side (voice-enabled accounts only) — the transcript
+     * becomes the seed content.
+     */
     ingest(opts: {
         kind: string;
         source: string;
-        content: Record<string, unknown>;
+        content: Record<string, unknown> | AudioInput;
         version?: string;
         metadata?: Record<string, unknown>;
     }): Promise<any>;
@@ -171,6 +185,9 @@ export interface PrepareResult {
     reason: string;
     successRate: number | null;
     qualityCheckId: string | null;
+    /** Running render handles when prepare({voice: true}) pre-voiced the
+     * scenarios. */
+    voiceRenders?: VoiceRender[];
 }
 /**
  * An async evaluation of finished rollouts: per rollout, the server
@@ -192,9 +209,45 @@ export declare class QualityCheck {
      */
     rollouts(): Promise<any[]>;
 }
+/**
+ * An async voice render: a scenario (LLM-authored script) or a rollout
+ * transcript, voiced with ElevenLabs — N takes spliced into one mixed WAV
+ * with per-turn provenance. Requires a voice-enabled customer config.
+ */
+export declare class VoiceRender {
+    #private;
+    id: string;
+    status: string;
+    scenario_id: string | null;
+    rollout_id: string | null;
+    params: Record<string, unknown>;
+    duration_ms: number | null;
+    wpm: number | null;
+    provenance: any[] | null;
+    error: string | null;
+    constructor(data: any, http: Http);
+    /** Poll until the render finishes; verbose prints server telemetry
+     * (per-TTS-call latencies, take/mix progress). */
+    wait(opts?: WaitOptions): Promise<VoiceRender>;
+    /** The mixed conversation WAV. */
+    audio(): Promise<Uint8Array>;
+    /** Write the mixed conversation WAV to `path`; returns it. */
+    saveAudio(path: string): Promise<string>;
+}
+export interface VoiceOptions {
+    takes?: number;
+    engine?: "v2" | "v3";
+    annotate?: boolean;
+    phoneFx?: boolean;
+    roomTone?: boolean;
+    wpmRange?: [number, number];
+    voiceOverrides?: Record<string, string>;
+}
 /**
  * One finished rollout: the conversation a scenario produced, plus every
  * tool call the agent made along the way (each tagged with its turn_idx).
+ * voice_render is attached (already running) when the account's config has
+ * voice.auto — await .wait()/.saveAudio() on it if you want the WAV.
  */
 export interface RolloutResult {
     rollout_id: string;
@@ -203,6 +256,7 @@ export interface RolloutResult {
     turns: number;
     transcript: TranscriptTurn[];
     tool_events: any[];
+    voice_render?: VoiceRender | null;
 }
 export interface RunOptions {
     maxTurns?: number;
@@ -210,12 +264,21 @@ export interface RunOptions {
 }
 export declare class Rollouts {
     #private;
-    constructor(http: Http, sessionId?: string | null);
+    constructor(http: Http, sessionId?: string | null, voiceAuto?: boolean);
     /**
      * A stored rollout's full captured state: status, seed, transcript,
      * tool events, and sandbox.
      */
     get(rolloutId: string): Promise<any>;
+    /**
+     * Voice a finished rollout: the transcript maps to a script
+     * deterministically (words verbatim; `annotate` may add delivery tags
+     * only), then N takes are rendered and spliced into one mixed WAV.
+     * Requires a voice-enabled customer config (throws otherwise).
+     */
+    voice(rollout: RolloutResult | string, opts?: VoiceOptions): Promise<VoiceRender>;
+    /** One voiced turn's WAV (turns with an audio_url only). */
+    turnAudio(rolloutId: string, idx: number): Promise<Uint8Array>;
     /**
      * Play a dataset's scenarios against `agent` (most recent dataset when
      * none is given).
@@ -250,6 +313,12 @@ export interface PrepareOptions {
     minSuccessRate?: number;
     maxSuccessRate?: number;
     verbose?: boolean;
+    /** Additionally voice every scenario in the prepared dataset (an LLM
+     * authors each script, then a takes=1 render) — explicit opt-in because
+     * it spends per row; handles come back still-running on
+     * PrepareResult.voiceRenders. voice.auto accounts don't need this:
+     * their rollouts voice themselves. */
+    voice?: boolean;
 }
 /**
  * Client entry point.
@@ -270,11 +339,26 @@ export declare class Synthia {
     sessionName: string;
     sessionId: string | null;
     invocationId: string | null;
+    /** Voice mode, mirrored from the account's customer config by the
+     * session handshake: enabled unlocks the voice surfaces; auto makes
+     * rollouts voice themselves. Zero client-side flags — flipping a
+     * customer's config flips their SDK. */
+    voiceEnabled: boolean;
+    voiceAuto: boolean;
     seeds: Seeds;
     userModels: UserModels;
     datasets: Datasets;
     rollouts: Rollouts;
     constructor(options?: SynthiaOptions);
+    /**
+     * Voice one scenario (an LLM authors the full two-sided script) or one
+     * finished rollout (deterministic transcript transform). Exactly one
+     * source id. Requires a voice-enabled customer config.
+     */
+    voiceRender(opts: VoiceOptions & {
+        scenarioId?: string;
+        rolloutId?: string;
+    }): Promise<VoiceRender>;
     /**
      * Probe + generate only when needed; otherwise reuse the latest dataset.
      *

package/dist/client.js

@@ -1,7 +1,41 @@
 import { createHash, randomUUID } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, resolve } from "node:path";
 export const DEFAULT_BASE_URL = "https://synthia-research--synthia-api-web.modal.run";
-const SDK_VERSION = "0.0.1";
+const SDK_VERSION = "0.0.3"; // keep in lockstep with package.json
+// File suffixes treated as audio where inputs are overloaded (seeds.ingest
+// content, rollout agent replies).
+const AUDIO_SUFFIXES = new Set([".wav", ".mp3", ".m4a", ".ogg", ".flac", ".webm"]);
+/**
+ * base64 audio when `value` is audio — raw bytes, or a string path ending in
+ * an audio suffix — else null. The runtime half of the input overloads.
+ */
+function asAudioB64(value) {
+    if (value instanceof Uint8Array)
+        return Buffer.from(value).toString("base64");
+    if (typeof value === "string" && AUDIO_SUFFIXES.has(extname(value).toLowerCase())) {
+        return readFileSync(value).toString("base64");
+    }
+    return null;
+}
+/**
+ * 403 on a voice surface means the account's config doesn't enable voice —
+ * rethrow something actionable instead of a bare status error.
+ */
+function translateVoice403(e) {
+    if (e instanceof HttpError && e.status === 403) {
+        let detail = "voice is not enabled for this account";
+        try {
+            detail = JSON.parse(e.body).detail ?? detail;
+        }
+        catch {
+            /* keep default */
+        }
+        return new Error(`${detail} — voice is enabled per customer config; ask your Synthia ` +
+            "contact to turn it on for your organization");
+    }
+    return e;
+}
 // Launcher argv[1] stems that don't identify a script (REPLs, runners).
 const INTERACTIVE_STEMS = new Set(["", "node", "npx", "tsx", "ts-node"]);
 /**
@@ -118,6 +152,14 @@ class Http {
             throw new HttpError(r.status, await r.text(), "POST", path);
         return r.json();
     }
+    /** Binary GET (audio artifacts). */
+    async getBytes(path) {
+        await this.ready;
+        const r = await this.raw("GET", path);
+        if (!r.ok)
+            throw new HttpError(r.status, await r.text(), "GET", path);
+        return new Uint8Array(await r.arrayBuffer());
+    }
     /** Un-gated request returning the raw Response (used by the handshake). */
     async raw(method, path, body, params) {
         const url = new URL(this.baseUrl + path);
@@ -291,8 +333,32 @@ export class Seeds {
     constructor(http) {
         this.#http = http;
     }
-    /** Upload seed material (documents, tool schemas, policies, traces...). */
+    /**
+     * Upload seed material (documents, tool schemas, policies, traces...).
+     *
+     * Overloaded on `content`: an object is ingested as-is (text pipeline);
+     * raw bytes or a path to an audio file (.wav/.mp3/...) is uploaded and
+     * transcribed server-side (voice-enabled accounts only) — the transcript
+     * becomes the seed content.
+     */
     async ingest(opts) {
+        const audioB64 = asAudioB64(opts.content);
+        if (audioB64 !== null) {
+            const filename = typeof opts.content === "string" ? basename(opts.content) : null;
+            try {
+                return await this.#http.post("/v1/seeds", {
+                    kind: opts.kind,
+                    source: opts.source,
+                    audio_b64: audioB64,
+                    audio_filename: filename,
+                    version: opts.version ?? "1",
+                    metadata: opts.metadata ?? {},
+                });
+            }
+            catch (e) {
+                throw translateVoice403(e);
+            }
+        }
         return this.#http.post("/v1/seeds", {
             kind: opts.kind,
             source: opts.source,
@@ -425,12 +491,92 @@ export class QualityCheck {
         return body.data;
     }
 }
+/**
+ * An async voice render: a scenario (LLM-authored script) or a rollout
+ * transcript, voiced with ElevenLabs — N takes spliced into one mixed WAV
+ * with per-turn provenance. Requires a voice-enabled customer config.
+ */
+export class VoiceRender {
+    id;
+    status;
+    scenario_id;
+    rollout_id;
+    params;
+    duration_ms;
+    wpm;
+    provenance;
+    error;
+    #http;
+    constructor(data, http) {
+        this.id = data.id;
+        this.status = data.status;
+        this.scenario_id = data.scenario_id;
+        this.rollout_id = data.rollout_id;
+        this.params = data.params;
+        this.duration_ms = data.duration_ms;
+        this.wpm = data.wpm;
+        this.provenance = data.provenance;
+        this.error = data.error;
+        this.#http = http;
+    }
+    /** Poll until the render finishes; verbose prints server telemetry
+     * (per-TTS-call latencies, take/mix progress). */
+    async wait(opts = {}) {
+        const { pollInterval = 2, timeout = 1800, verbose = false } = opts;
+        const events = new EventStream(this.#http, `/v1/voice-renders/${this.id}/events`, verbose);
+        const deadline = Date.now() + timeout * 1000;
+        while (this.status === "running") {
+            if (Date.now() > deadline) {
+                throw new Error(`voice render ${this.id} still running after ${timeout}s`);
+            }
+            await sleep(pollInterval * 1000);
+            const data = await this.#http.get(`/v1/voice-renders/${this.id}`);
+            this.status = data.status;
+            this.params = data.params;
+            this.duration_ms = data.duration_ms;
+            this.wpm = data.wpm;
+            this.provenance = data.provenance;
+            this.error = data.error;
+            await events.pump();
+        }
+        await events.pump(); // catch events written after the final status poll
+        if (this.status !== "succeeded") {
+            throw new Error(`voice render ${this.id} failed: ${this.error}`);
+        }
+        return this;
+    }
+    /** The mixed conversation WAV. */
+    async audio() {
+        try {
+            return await this.#http.getBytes(`/v1/voice-renders/${this.id}/audio`);
+        }
+        catch (e) {
+            throw translateVoice403(e);
+        }
+    }
+    /** Write the mixed conversation WAV to `path`; returns it. */
+    async saveAudio(path) {
+        writeFileSync(path, await this.audio());
+        return path;
+    }
+}
+async function createVoiceRender(http, body) {
+    const clean = Object.fromEntries(Object.entries(body).filter(([, v]) => v !== undefined && v !== null));
+    try {
+        return new VoiceRender(await http.post("/v1/voice-renders", clean), http);
+    }
+    catch (e) {
+        throw translateVoice403(e);
+    }
+}
 export class Rollouts {
     #http;
     #sessionId;
-    constructor(http, sessionId = null) {
+    #voiceAuto;
+    constructor(http, sessionId = null, voiceAuto = false) {
         this.#http = http;
         this.#sessionId = sessionId;
+        this.#voiceAuto = voiceAuto;
     }
     /**
      * A stored rollout's full captured state: status, seed, transcript,
@@ -439,6 +585,34 @@ export class Rollouts {
     async get(rolloutId) {
         return this.#http.get(`/v1/rollouts/${rolloutId}`);
     }
+    /**
+     * Voice a finished rollout: the transcript maps to a script
+     * deterministically (words verbatim; `annotate` may add delivery tags
+     * only), then N takes are rendered and spliced into one mixed WAV.
+     * Requires a voice-enabled customer config (throws otherwise).
+     */
+    async voice(rollout, opts = {}) {
+        const rolloutId = typeof rollout === "string" ? rollout : rollout.rollout_id;
+        return createVoiceRender(this.#http, {
+            rollout_id: rolloutId,
+            takes: opts.takes ?? 1,
+            engine: opts.engine,
+            annotate: opts.annotate ?? false,
+            phone_fx: opts.phoneFx ?? false,
+            room_tone: opts.roomTone ?? false,
+            wpm_range: opts.wpmRange,
+            voice_overrides: opts.voiceOverrides,
+        });
+    }
+    /** One voiced turn's WAV (turns with an audio_url only). */
+    async turnAudio(rolloutId, idx) {
+        try {
+            return await this.#http.getBytes(`/v1/rollouts/${rolloutId}/turns/${idx}/audio`);
+        }
+        catch (e) {
+            throw translateVoice403(e);
+        }
+    }
     /**
      * Play a dataset's scenarios against `agent` (most recent dataset when
      * none is given).
@@ -491,6 +665,21 @@ export class Rollouts {
             }
         };
         await Promise.all(Array.from({ length: Math.min(concurrency, rows.length) }, worker));
+        if (this.#voiceAuto) {
+            // voice.auto accounts: every completed rollout gets a takes=1 mixed
+            // render, kicked here and attached still-running — audio is ready
+            // server-side whether or not anyone awaits it.
+            for (const result of results) {
+                if (result.status === "completed") {
+                    try {
+                        result.voice_render = await this.voice(result, { takes: 1 });
+                    }
+                    catch {
+                        /* rendering is a bonus; results stand alone */
+                    }
+                }
+            }
+        }
         return results;
     }
     /**
@@ -516,10 +705,23 @@ export class Rollouts {
         while (session.status === "running") {
             const sandbox = ToolSandbox.fromConfig(session.sandbox);
             const reply = await agent(session.transcript, sandbox);
-            session = await this.#http.post(`/v1/rollouts/${session.id}/turns`, {
-                reply,
-                tool_calls: sandbox.events,
-            });
+            const audioB64 = asAudioB64(reply);
+            const body = { tool_calls: sandbox.events };
+            if (audioB64 !== null) {
+                // The agent replied with audio — the server transcribes it
+                // (voice-enabled accounts) and the transcript drives the simulator.
+                body["reply"] = "";
+                body["audio_b64"] = audioB64;
+            }
+            else {
+                body["reply"] = reply;
+            }
+            try {
+                session = await this.#http.post(`/v1/rollouts/${session.id}/turns`, body);
+            }
+            catch (e) {
+                throw audioB64 !== null ? translateVoice403(e) : e;
+            }
         }
         return {
             rollout_id: session.id,
@@ -549,6 +751,12 @@ export class Synthia {
     sessionName;
     sessionId = null;
     invocationId = null;
+    /** Voice mode, mirrored from the account's customer config by the
+     * session handshake: enabled unlocks the voice surfaces; auto makes
+     * rollouts voice themselves. Zero client-side flags — flipping a
+     * customer's config flips their SDK. */
+    voiceEnabled = false;
+    voiceAuto = false;
     seeds;
     userModels;
     datasets;
@@ -611,9 +819,29 @@ export class Synthia {
         const data = (await r.json());
         this.sessionId = data.sdk_session_id;
         this.invocationId = data.sdk_invocation_id;
+        this.voiceEnabled = data.voice_enabled ?? false;
+        this.voiceAuto = data.voice_auto ?? false;
         this.#http.headers["X-Synthia-Session"] = this.sessionId;
         this.#http.headers["X-Synthia-Invocation"] = this.invocationId;
-        this.rollouts = new Rollouts(this.#http, this.sessionId);
+        this.rollouts = new Rollouts(this.#http, this.sessionId, this.voiceAuto);
+    }
+    /**
+     * Voice one scenario (an LLM authors the full two-sided script) or one
+     * finished rollout (deterministic transcript transform). Exactly one
+     * source id. Requires a voice-enabled customer config.
+     */
+    async voiceRender(opts) {
+        return createVoiceRender(this.#http, {
+            scenario_id: opts.scenarioId,
+            rollout_id: opts.rolloutId,
+            takes: opts.takes ?? 1,
+            engine: opts.engine,
+            annotate: opts.annotate ?? false,
+            phone_fx: opts.phoneFx ?? false,
+            room_tone: opts.roomTone ?? false,
+            wpm_range: opts.wpmRange,
+            voice_overrides: opts.voiceOverrides,
+        });
     }
     /**
      * Probe + generate only when needed; otherwise reuse the latest dataset.
@@ -634,6 +862,16 @@ export class Synthia {
      * scripts/sessions never trigger regeneration here.
      */
     async prepare(agent, opts = {}) {
+        const result = await this.#prepare(agent, opts);
+        if (opts.voice) {
+            result.voiceRenders = [];
+            for (const row of await result.dataset.download()) {
+                result.voiceRenders.push(await this.voiceRender({ scenarioId: row.scenario_id, takes: 1 }));
+            }
+        }
+        return result;
+    }
+    async #prepare(agent, opts) {
         const { count = 20, maxTurns = 10, minSuccessRate = 0.6, maxSuccessRate = 0.9, verbose = false, } = opts;
         await this.#http.ready;
         const existing = await this.datasets.list(this.sessionId ?? undefined); // newest first

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { Synthia, ToolSandbox, Dataset, GenerationJob, ValidationRun, QualityCheck, Seeds, UserModels, Datasets, Rollouts, DEFAULT_BASE_URL, } from "./client.js";
-export type { Agent, AgentReply, PrepareOptions, PrepareResult, RolloutAgent, RolloutResult, RunOptions, SandboxConfig, SynthiaOptions, ToolCall, ToolEvent, TranscriptTurn, UserModel, WaitOptions, } from "./client.js";
+export { Synthia, ToolSandbox, Dataset, GenerationJob, ValidationRun, QualityCheck, Seeds, UserModels, Datasets, Rollouts, VoiceRender, DEFAULT_BASE_URL, } from "./client.js";
+export type { Agent, AgentReply, AudioInput, PrepareOptions, PrepareResult, RolloutAgent, RolloutResult, RunOptions, SandboxConfig, SynthiaOptions, ToolCall, ToolEvent, TranscriptTurn, UserModel, VoiceOptions, WaitOptions, } from "./client.js";

package/dist/index.js

@@ -1 +1 @@
-export { Synthia, ToolSandbox, Dataset, GenerationJob, ValidationRun, QualityCheck, Seeds, UserModels, Datasets, Rollouts, DEFAULT_BASE_URL, } from "./client.js";
+export { Synthia, ToolSandbox, Dataset, GenerationJob, ValidationRun, QualityCheck, Seeds, UserModels, Datasets, Rollouts, VoiceRender, DEFAULT_BASE_URL, } from "./client.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthiaresearch",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "JavaScript/TypeScript SDK for the Synthia API",
   "license": "MIT",
   "type": "module",