@qvac/sdk 0.18.2 → 0.19.0

package/dist/scripts/contract/constants-registry.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+/**
+ * Every public constant `enum` from the SDK surface that downstream (non-JS)
+ * client generators should get as a real, named type instead of a
+ * hardcoded string/number. `build-contract.ts` merges each of these
+ * directly into `schema.json`'s `$defs` (same `z.toJSONSchema` call, same
+ * generator run as every request/response type), tagged with an
+ * `x-enum-varnames` hint so datamodel-code-generator preserves the
+ * original key names instead of slugging them from the bare value — plain
+ * JSON Schema `enum:` only carries values, not names, so without that hint
+ * `PluginId`/`Verbosity` (whose keys aren't derivable from their values)
+ * would lose their names entirely.
+ *
+ * A constant only reaches other languages if it's registered here. See
+ * `.cursor/rules/sdk/public-constants-contract.mdc`: any new public
+ * constant meant for downstream SDKs must be a `z.enum(...)` added here,
+ * not just a bare `export const` in its own schema file — otherwise it
+ * silently never leaves JS.
+ *
+ * Scoped to name→value maps (`z.enum`) only. A standalone scalar constant
+ * (e.g. `VLA_DEFAULT_IMAGE_SIZE`) has no natural JSON Schema representation
+ * as a plain value — a `const`-only schema generates an awkward
+ * `RootModel[Literal[...]]` wrapper class in Python, not a usable
+ * constant — so scalars aren't covered by this registry.
+ */
+export declare const constantsRegistry: {
+    readonly ModelType: z.ZodEnum<{
+        readonly llamacppCompletion: "llamacpp-completion";
+        readonly whispercppTranscription: "whispercpp-transcription";
+        readonly bciWhispercppTranscription: "bci-whispercpp-transcription";
+        readonly llamacppEmbedding: "llamacpp-embedding";
+        readonly nmtcppTranslation: "nmtcpp-translation";
+        readonly onnxTts: "onnx-tts";
+        readonly ttsGgml: "tts-ggml";
+        readonly parakeetTranscription: "parakeet-transcription";
+        readonly ggmlOcr: "ggml-ocr";
+        readonly sdcppGeneration: "sdcpp-generation";
+        readonly audiogenGgml: "audiogen-ggml";
+        readonly ggmlVla: "ggml-vla";
+        readonly ggmlClassification: "ggml-classification";
+    }>;
+    readonly Verbosity: z.ZodEnum<{
+        readonly ERROR: 0;
+        readonly WARN: 1;
+        readonly INFO: 2;
+        readonly DEBUG: 3;
+    }>;
+    readonly PluginId: z.ZodEnum<{
+        readonly LLM: "@qvac/sdk/llamacpp-completion/plugin";
+        readonly EMBEDDING: "@qvac/sdk/llamacpp-embedding/plugin";
+        readonly WHISPER: "@qvac/sdk/whispercpp-transcription/plugin";
+        readonly BCI: "@qvac/sdk/bci-whispercpp-transcription/plugin";
+        readonly NMT: "@qvac/sdk/nmtcpp-translation/plugin";
+        readonly TTS: "@qvac/sdk/tts-ggml/plugin";
+        readonly OCR: "@qvac/sdk/ggml-ocr/plugin";
+        readonly DIFFUSION: "@qvac/sdk/sdcpp-generation/plugin";
+        readonly AUDIOGEN: "@qvac/sdk/audiogen-ggml/plugin";
+        readonly VLA: "@qvac/sdk/ggml-vla/plugin";
+        readonly CLASSIFICATION: "@qvac/sdk/ggml-classification/plugin";
+    }>;
+    readonly SupportedAudioFormat: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsPace: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsCosyvoice3Emotion: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsCosyvoice3InstructDialect: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsCosyvoice3InstructVolume: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsCosyvoice3InstructStyle: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly AudioGenEngine: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly AudioGenTaskType: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+};
+//# sourceMappingURL=constants-registry.d.ts.map

package/dist/scripts/contract/constants-registry.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { ModelType, VERBOSITY, SUPPORTED_AUDIO_FORMATS, AUDIOGEN_ENGINES, AUDIOGEN_TASK_TYPES, TTS_PACES, TTS_COSYVOICE3_EMOTIONS, TTS_COSYVOICE3_INSTRUCT_DIALECTS, TTS_COSYVOICE3_INSTRUCT_VOLUMES, TTS_COSYVOICE3_INSTRUCT_STYLES } from '@qvac/inference/surface';
+import { PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_BCI, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, PLUGIN_AUDIOGEN, PLUGIN_VLA, PLUGIN_CLASSIFICATION } from '../../src/plugin-ids.js';
+// Uppercases each vocabulary value into an identifier-safe varname (e.g.
+// 'slow' -> 'SLOW', 'cover-nofsq' -> 'COVER_NOFSQ'), mirroring the
+// SupportedAudioFormat derivation so names can't drift from the single
+// source-of-truth array.
+function enumFromVocabulary(values) {
+    return z.enum(Object.fromEntries(values.map((value) => [value.toUpperCase().replace(/-/g, '_'), value])));
+}
+/**
+ * Every public constant `enum` from the SDK surface that downstream (non-JS)
+ * client generators should get as a real, named type instead of a
+ * hardcoded string/number. `build-contract.ts` merges each of these
+ * directly into `schema.json`'s `$defs` (same `z.toJSONSchema` call, same
+ * generator run as every request/response type), tagged with an
+ * `x-enum-varnames` hint so datamodel-code-generator preserves the
+ * original key names instead of slugging them from the bare value — plain
+ * JSON Schema `enum:` only carries values, not names, so without that hint
+ * `PluginId`/`Verbosity` (whose keys aren't derivable from their values)
+ * would lose their names entirely.
+ *
+ * A constant only reaches other languages if it's registered here. See
+ * `.cursor/rules/sdk/public-constants-contract.mdc`: any new public
+ * constant meant for downstream SDKs must be a `z.enum(...)` added here,
+ * not just a bare `export const` in its own schema file — otherwise it
+ * silently never leaves JS.
+ *
+ * Scoped to name→value maps (`z.enum`) only. A standalone scalar constant
+ * (e.g. `VLA_DEFAULT_IMAGE_SIZE`) has no natural JSON Schema representation
+ * as a plain value — a `const`-only schema generates an awkward
+ * `RootModel[Literal[...]]` wrapper class in Python, not a usable
+ * constant — so scalars aren't covered by this registry.
+ */
+export const constantsRegistry = {
+    ModelType: z.enum(ModelType),
+    Verbosity: z.enum(VERBOSITY),
+    PluginId: z.enum({
+        LLM: PLUGIN_LLM,
+        EMBEDDING: PLUGIN_EMBEDDING,
+        WHISPER: PLUGIN_WHISPER,
+        BCI: PLUGIN_BCI,
+        NMT: PLUGIN_NMT,
+        TTS: PLUGIN_TTS,
+        OCR: PLUGIN_OCR,
+        DIFFUSION: PLUGIN_DIFFUSION,
+        AUDIOGEN: PLUGIN_AUDIOGEN,
+        VLA: PLUGIN_VLA,
+        CLASSIFICATION: PLUGIN_CLASSIFICATION
+    }),
+    // Derived from SUPPORTED_AUDIO_FORMATS itself (e.g. '.mp3' -> 'MP3') rather
+    // than a hand-written record, so the varnames can't drift from the one
+    // source of truth every other consumer of SUPPORTED_AUDIO_FORMATS shares.
+    SupportedAudioFormat: z.enum(Object.fromEntries(SUPPORTED_AUDIO_FORMATS.map((ext) => [ext.slice(1).toUpperCase(), ext]))),
+    TtsPace: enumFromVocabulary(TTS_PACES),
+    TtsCosyvoice3Emotion: enumFromVocabulary(TTS_COSYVOICE3_EMOTIONS),
+    TtsCosyvoice3InstructDialect: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_DIALECTS),
+    TtsCosyvoice3InstructVolume: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_VOLUMES),
+    TtsCosyvoice3InstructStyle: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_STYLES),
+    AudioGenEngine: enumFromVocabulary(AUDIOGEN_ENGINES),
+    AudioGenTaskType: enumFromVocabulary(AUDIOGEN_TASK_TYPES)
+};

package/dist/scripts/contract/method-shapes.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Call shape of every RPC method, keyed by the request `type` literal.
+ *
+ * This is a contract-tooling input: `scripts/export-contract.ts` loads it
+ * under Node to pair each wire method with its call shape (reply / stream /
+ * duplex) in the generated manifest. It stays free of engine imports so the
+ * export runs under Node, where core's native `bare-*` modules cannot load.
+ */
+export declare const methodShapes: {
+    readonly assessModelFit: "reply";
+    readonly audioGenStream: "stream";
+    readonly batchCompletionStream: "stream";
+    readonly bciTranscribe: "stream";
+    readonly bciTranscribeStream: "duplex";
+    readonly cancel: "reply";
+    readonly classify: "stream";
+    readonly completionOrchestrate: "duplex";
+    readonly completionStream: "stream";
+    readonly deleteCache: "reply";
+    readonly diffusionStream: "stream";
+    readonly downloadAsset: "reply";
+    readonly embed: "reply";
+    readonly finetune: "reply";
+    readonly getLoadedModelInfo: "reply";
+    readonly getModelInfo: "reply";
+    readonly getSystemResources: "reply";
+    readonly heartbeat: "reply";
+    readonly loadModel: "reply";
+    readonly loggingStream: "stream";
+    readonly modelRegistryGetModel: "reply";
+    readonly modelRegistryList: "reply";
+    readonly modelRegistrySearch: "reply";
+    readonly ocrStream: "stream";
+    readonly pluginInvoke: "reply";
+    readonly pluginInvokeStream: "stream";
+    readonly rag: "reply";
+    readonly resume: "reply";
+    readonly state: "reply";
+    readonly suspend: "reply";
+    readonly textToSpeech: "stream";
+    readonly textToSpeechStream: "duplex";
+    readonly transcribe: "stream";
+    readonly transcribeStream: "duplex";
+    readonly translate: "stream";
+    readonly unloadModel: "reply";
+    readonly upscaleStream: "stream";
+    readonly videoStream: "stream";
+    readonly worldSceneStream: "stream";
+    readonly worldStepStream: "stream";
+};
+export type MethodName = keyof typeof methodShapes;
+export type MethodCallShape = (typeof methodShapes)[MethodName];
+//# sourceMappingURL=method-shapes.d.ts.map

package/dist/scripts/contract/method-shapes.js

@@ -0,0 +1,50 @@
+/**
+ * Call shape of every RPC method, keyed by the request `type` literal.
+ *
+ * This is a contract-tooling input: `scripts/export-contract.ts` loads it
+ * under Node to pair each wire method with its call shape (reply / stream /
+ * duplex) in the generated manifest. It stays free of engine imports so the
+ * export runs under Node, where core's native `bare-*` modules cannot load.
+ */
+export const methodShapes = {
+    assessModelFit: 'reply',
+    audioGenStream: 'stream',
+    batchCompletionStream: 'stream',
+    bciTranscribe: 'stream',
+    bciTranscribeStream: 'duplex',
+    cancel: 'reply',
+    classify: 'stream',
+    completionOrchestrate: 'duplex',
+    completionStream: 'stream',
+    deleteCache: 'reply',
+    diffusionStream: 'stream',
+    downloadAsset: 'reply',
+    embed: 'reply',
+    finetune: 'reply',
+    getLoadedModelInfo: 'reply',
+    getModelInfo: 'reply',
+    getSystemResources: 'reply',
+    heartbeat: 'reply',
+    loadModel: 'reply',
+    loggingStream: 'stream',
+    modelRegistryGetModel: 'reply',
+    modelRegistryList: 'reply',
+    modelRegistrySearch: 'reply',
+    ocrStream: 'stream',
+    pluginInvoke: 'reply',
+    pluginInvokeStream: 'stream',
+    rag: 'reply',
+    resume: 'reply',
+    state: 'reply',
+    suspend: 'reply',
+    textToSpeech: 'stream',
+    textToSpeechStream: 'duplex',
+    transcribe: 'stream',
+    transcribeStream: 'duplex',
+    translate: 'stream',
+    unloadModel: 'reply',
+    upscaleStream: 'stream',
+    videoStream: 'stream',
+    worldSceneStream: 'stream',
+    worldStepStream: 'stream'
+};

package/dist/scripts/contract/plugin-contract.d.ts

@@ -1,4 +1,4 @@
-import type { QvacPlugin } from '../../schemas/index.js';
+import type { QvacPlugin } from '@qvac/inference/surface';
 export interface PluginHandlerContract {
     name: string;
     streaming: boolean;

package/dist/scripts/contract/plugin-contract.js

@@ -1,4 +1,4 @@
-import { toWireJsonSchema } from '../../scripts/contract/build-contract.js';
+import { toWireJsonSchema } from './build-contract.js';
 /**
  * Wire contract of one registered plugin: JSON Schema per handler, in the
  * same wire shape the built-in contract export uses (requests as input

package/dist/scripts/enforce-inference-peer-dependencies.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=enforce-inference-peer-dependencies.d.ts.map

package/dist/scripts/enforce-inference-peer-dependencies.js

@@ -0,0 +1,39 @@
+// @qvac/inference peerDependencies is the source of truth for addon version
+// ranges. The SDK should use the same version ranges as inference for addons.
+// For every addon p in inference's peerDependencies, this script validates if:
+//   - inference's devDependencies.p == inference's peerDependencies.p,
+//   - SDK's dependencies.p == inference's peerDependencies.p.
+// That is, inference's devDependencies and SDK's dependencies match inference's peerDependencies.
+import { readFileSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const sdkDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const inferenceDir = resolve(sdkDir, '..', 'inference');
+function readManifest(dir) {
+    return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+}
+const inferencePkg = readManifest(inferenceDir);
+const sdkPkg = readManifest(sdkDir);
+const peers = inferencePkg.peerDependencies ?? {};
+const inferenceDev = inferencePkg.devDependencies ?? {};
+const sdkDeps = sdkPkg.dependencies ?? {};
+const drifts = [];
+for (const [name, peer] of Object.entries(peers)) {
+    const dev = inferenceDev[name];
+    const dep = sdkDeps[name];
+    const mismatches = [];
+    if (dep !== peer)
+        mismatches.push(dep === undefined ? 'SDK is missing it' : `SDK has ${dep}`);
+    if (dev !== peer) {
+        mismatches.push(dev === undefined
+            ? 'inference devDependencies is missing it'
+            : `inference devDependencies has ${dev}`);
+    }
+    if (mismatches.length > 0) {
+        drifts.push(`${name}: inference has it as ${peer} in peerDependencies, but ${mismatches.join(' and ')}.`);
+    }
+}
+if (drifts.length > 0) {
+    console.error(`${drifts.join('\n')}\n\nPlease ensure the SDK dependencies and inference devDependencies use the same addon versions as inference's peerDependencies.`);
+    process.exit(1);
+}

package/dist/scripts/export-contract.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
-import { contractDir, renderContractFiles } from '../scripts/contract/build-contract.js';
+import { contractDir, renderContractFiles } from './contract/build-contract.js';
 const checkOnly = process.argv.includes('--check');
 const files = await renderContractFiles();
 await mkdir(contractDir, { recursive: true });

package/dist/scripts/export-plugin-contract.js

@@ -1,6 +1,6 @@
 import { writeFile } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
-import { buildPluginContract } from '../scripts/contract/plugin-contract.js';
+import { buildPluginContract } from './contract/plugin-contract.js';
 // Usage: tsx scripts/export-plugin-contract.ts <plugin-module> <out.json>
 // The plugin module's default export must be a definePlugin(...) value.
 const [modulePath, outPath] = process.argv.slice(2);

package/dist/scripts/run-unit-tests.js

@@ -3,12 +3,17 @@ import { join, dirname } from 'path';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const testDir = join(__dirname, '..', 'test', 'unit');
+const testDir = join(__dirname, '..', 'test');
+// The Bare suite (test/bare) and its build output (test/dist) run via
+// `test:bare`, so the Bun/Node unit runner skips them.
+const SKIP_DIRS = new Set(['bare', 'dist']);
 function collectTestFiles(dir) {
     const files = [];
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
         const fullPath = join(dir, entry.name);
         if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name))
+                continue;
             files.push(...collectTestFiles(fullPath));
         }
         else if (entry.isFile() && entry.name.endsWith('.test.ts')) {

package/dist/src/client/api/assess-model-fit.d.ts

@@ -0,0 +1,17 @@
+import { type AssessModelFitInput, type AssessModelFitResult } from '@qvac/inference/surface';
+/**
+ * Assesses, before anything is downloaded, whether the given models are likely
+ * to fit in this device's memory.
+ *
+ * Advisory only: it does not download weights, run a native fit probe, block
+ * `loadModel`, reserve memory, or make a performance claim. `unknown` is a real
+ * answer — it means the available evidence does not support a verdict either
+ * way, and callers should treat it as "cannot say", not "no".
+ *
+ * @param input - Candidates with their intended workloads, the declared
+ *   execution mode, and the headroom policy.
+ * @returns Per-model and combined verdicts, with the budget and bounds they came
+ *   from, plus every assumption that was made.
+ */
+export declare function assessModelFit(input: AssessModelFitInput): Promise<AssessModelFitResult>;
+//# sourceMappingURL=assess-model-fit.d.ts.map

package/dist/src/client/api/assess-model-fit.js

@@ -0,0 +1,38 @@
+import { assessModelFitInputSchema } from '@qvac/inference/surface';
+import { send } from '../rpc/rpc-client.js';
+import { InvalidResponseError } from '../../utils/errors-client.js';
+/**
+ * Assesses, before anything is downloaded, whether the given models are likely
+ * to fit in this device's memory.
+ *
+ * Advisory only: it does not download weights, run a native fit probe, block
+ * `loadModel`, reserve memory, or make a performance claim. `unknown` is a real
+ * answer — it means the available evidence does not support a verdict either
+ * way, and callers should treat it as "cannot say", not "no".
+ *
+ * @param input - Candidates with their intended workloads, the declared
+ *   execution mode, and the headroom policy.
+ * @returns Per-model and combined verdicts, with the budget and bounds they came
+ *   from, plus every assumption that was made.
+ */
+export async function assessModelFit(input) {
+    const parsed = assessModelFitInputSchema.parse(input);
+    const request = { type: 'assessModelFit', ...parsed };
+    const response = await send(request);
+    if (response.type !== 'assessModelFit') {
+        throw new InvalidResponseError('assessModelFit');
+    }
+    // Rebuilt field by field rather than by rest-destructuring the discriminant,
+    // matching the other client wrappers and keeping optionals absent rather than
+    // explicitly undefined.
+    return {
+        verdict: response.verdict,
+        basis: response.basis,
+        execution: response.execution,
+        ...(response.budget && { budget: response.budget }),
+        ...(response.estimate && { estimate: response.estimate }),
+        models: response.models,
+        reasons: response.reasons,
+        assumptions: response.assumptions
+    };
+}

package/dist/src/client/api/audio-gen-result.d.ts

@@ -0,0 +1,4 @@
+import { type AudioGenClientParams, type AudioGenResult, type AudioGenStreamRequest } from '@qvac/inference/surface';
+export type AudioGenStreamFactory = (request: AudioGenStreamRequest) => AsyncGenerator<unknown>;
+export declare function createAudioGenResult(params: AudioGenClientParams, streamFactory: AudioGenStreamFactory): AudioGenResult;
+//# sourceMappingURL=audio-gen-result.d.ts.map

package/dist/src/client/api/audio-gen-result.js

@@ -0,0 +1,143 @@
+import { audioGenClientParamsSchema, audioGenStreamResponseSchema } from '@qvac/inference/surface';
+import { parseClientInput } from '../parse-input.js';
+import { generateClientRequestId } from './client-request-id.js';
+import { decodeBase64 } from '../../utils/encoding.js';
+import { InvalidResponseError } from '../../utils/errors-client.js';
+import { InferenceCancelledError } from '../../utils/errors-server.js';
+function concatenateChunks(chunks) {
+    const totalLength = chunks.reduce((total, chunk) => total + chunk.length, 0);
+    const pcm = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        pcm.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return pcm;
+}
+export function createAudioGenResult(params, streamFactory) {
+    const parsed = parseClientInput(audioGenClientParamsSchema, params);
+    const requestId = generateClientRequestId();
+    const request = {
+        ...parsed,
+        type: 'audioGenStream',
+        requestId
+    };
+    const progressQueue = [];
+    const pcmChunks = [];
+    let sampleRate;
+    let channels;
+    let bitsPerSample;
+    let progressDone = false;
+    let progressError;
+    let progressResolve;
+    let resolveAudio = () => { };
+    let rejectAudio = () => { };
+    const audio = new Promise((resolve, reject) => {
+        resolveAudio = resolve;
+        rejectAudio = reject;
+    });
+    audio.catch(() => { });
+    let resolveStats = () => { };
+    let rejectStats = () => { };
+    const stats = new Promise((resolve, reject) => {
+        resolveStats = resolve;
+        rejectStats = reject;
+    });
+    stats.catch(() => { });
+    let resolveDiagnostics = () => { };
+    let rejectDiagnostics = () => { };
+    const diagnostics = new Promise((resolve, reject) => {
+        resolveDiagnostics = resolve;
+        rejectDiagnostics = reject;
+    });
+    diagnostics.catch(() => { });
+    function notifyProgress() {
+        progressResolve?.();
+        progressResolve = undefined;
+    }
+    async function processResponses() {
+        let receivedDone = false;
+        try {
+            for await (const response of streamFactory(request)) {
+                if (!response ||
+                    typeof response !== 'object' ||
+                    !('type' in response) ||
+                    response.type !== 'audioGenStream') {
+                    continue;
+                }
+                const chunk = audioGenStreamResponseSchema.parse(response);
+                if (chunk.progress) {
+                    progressQueue.push(chunk.progress);
+                    notifyProgress();
+                }
+                if (chunk.data !== undefined) {
+                    pcmChunks.push(decodeBase64(chunk.data));
+                    sampleRate = chunk.sampleRate;
+                    channels = chunk.channels;
+                    bitsPerSample = chunk.bitsPerSample;
+                }
+                if (chunk.done) {
+                    receivedDone = true;
+                    if (chunk.stopReason === 'cancelled') {
+                        const error = new InferenceCancelledError(requestId);
+                        rejectAudio(error);
+                        rejectStats(error);
+                        rejectDiagnostics(error);
+                        break;
+                    }
+                    if (sampleRate === undefined || channels === undefined || bitsPerSample === undefined) {
+                        throw new InvalidResponseError('audioGenStream audio chunk');
+                    }
+                    resolveAudio({
+                        pcm: concatenateChunks(pcmChunks),
+                        sampleRate,
+                        channels,
+                        bitsPerSample
+                    });
+                    resolveStats(chunk.stats);
+                    resolveDiagnostics(chunk.diagnostics);
+                    break;
+                }
+            }
+            if (!receivedDone) {
+                throw new InvalidResponseError('audioGenStream terminal response');
+            }
+        }
+        catch (error) {
+            progressError =
+                error instanceof Error ? error : new InvalidResponseError('audioGenStream', error);
+            rejectAudio(progressError);
+            rejectStats(progressError);
+            rejectDiagnostics(progressError);
+        }
+        finally {
+            progressDone = true;
+            notifyProgress();
+        }
+    }
+    async function* progressStream() {
+        while (true) {
+            const tick = progressQueue.shift();
+            if (tick) {
+                yield tick;
+                continue;
+            }
+            if (progressDone) {
+                if (progressError !== undefined)
+                    throw progressError;
+                return;
+            }
+            await new Promise((resolve) => {
+                progressResolve = resolve;
+            });
+        }
+    }
+    void processResponses();
+    return {
+        requestId,
+        progressStream: progressStream(),
+        audio,
+        stats,
+        diagnostics
+    };
+}

package/dist/src/client/api/audio-gen.d.ts

@@ -0,0 +1,66 @@
+import type { AudioGenClientParams, AudioGenResult } from '@qvac/inference/surface';
+/**
+ * Generates PCM audio using a loaded AudioGen model.
+ *
+ * @param params - Loaded model ID, required caption, and optional lyrics, musical controls, duration, and seed.
+ * @param params.maxFrames - MiniMax semantic-frame cap; mutually exclusive with `duration`.
+ * @param params.inferenceSteps - MiniMax flow steps for this run.
+ * @param params.cfgScale - MiniMax flow classifier-free guidance scale for this run.
+ * @param params.referenceAudio - Optional timbre reference: a file path (decoded server-side)
+ *   or raw interleaved stereo 48 kHz Float32 LE PCM bytes.
+ * @param params.sourceAudio - Source audio to re-render (same forms as `referenceAudio`);
+ *   required when `taskType` is `"cover-nofsq"`.
+ * @param params.taskType - `"text2music"` (default) or `"cover-nofsq"`.
+ * @param params.audioCoverStrength - Source-context strength for cover tasks (0..1).
+ * @param params.coverNoiseStrength - Initial source/noise blend for cover tasks (0..1).
+ * @returns A run with a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise describing the backend the run resolved to.
+ *
+ * @example
+ * ```typescript
+ * const modelId = await loadModel({
+ *   modelType: "audiogen",
+ *   modelConfig: {
+ *     textEncModelSrc,
+ *     lmModelSrc,
+ *     ditModelSrc,
+ *     vaeModelSrc,
+ *   },
+ * });
+ * const run = audioGen({ modelId, caption: "ambient electronic music", duration: 10 });
+ * stopButton.onclick = () => cancel({ requestId: run.requestId });
+ * for await (const progress of run.progressStream) {
+ *   console.log(progress.stage, progress.step, progress.total);
+ * }
+ * const { pcm, sampleRate, channels, bitsPerSample } = await run.audio;
+ * const stats = await run.stats;
+ *
+ * // MiniMax-Music3 uses a local LM and synthesis GGUF pair:
+ * const minimaxId = await loadModel({
+ *   modelType: "audiogen",
+ *   modelConfig: {
+ *     engine: "minimax",
+ *     lmModelSrc: "/models/mm3-lm-q8.gguf",
+ *     synthModelSrc: "/models/mm3-synth-q8.gguf",
+ *   },
+ * });
+ * const minimaxRun = audioGen({
+ *   modelId: minimaxId,
+ *   caption: "warm cinematic piano",
+ *   maxFrames: 250,
+ *   inferenceSteps: 12,
+ *   cfgScale: 1.8,
+ * });
+ *
+ * // Re-render an existing song with a new caption (cover) and a timbre reference:
+ * const cover = audioGen({
+ *   modelId,
+ *   caption: "orchestral arrangement with dramatic strings",
+ *   taskType: "cover-nofsq",
+ *   sourceAudio: "/path/to/source.wav",
+ *   referenceAudio: "/path/to/reference.mp3",
+ *   coverNoiseStrength: 0.75,
+ * });
+ * ```
+ */
+export declare function audioGen(params: AudioGenClientParams): AudioGenResult;
+//# sourceMappingURL=audio-gen.d.ts.map