@qvac/sdk 0.17.1 → 0.18.0

package/dist/client/api/transcribe.js

@@ -121,12 +121,39 @@ function buildTranscribeStreamRequest(params) {
  * to surface strings or segments; `sessionName` is only used to label the
  * "already iterated" error so callers see the correct session type.
  */
-async function createTranscribeStreamSession(params, options, process, sessionName) {
+export async function createTranscribeStreamSession(params, options, process, sessionName, duplexFactory = duplex) {
     const request = buildTranscribeStreamRequest(params);
-    const { requestStream, responseStream } = await duplex(request, options);
-    const responses = parseLines(responseStream, process);
+    const { requestStream, responseStream } = await duplexFactory(request, options);
+    let statsSettled = false;
+    let resolveStatsPromise = () => { };
+    let rejectStatsPromise = () => { };
+    const stats = new Promise((resolve, reject) => {
+        resolveStatsPromise = resolve;
+        rejectStatsPromise = reject;
+    });
+    stats.catch(() => { });
+    function resolveStats(value) {
+        if (statsSettled)
+            return;
+        statsSettled = true;
+        resolveStatsPromise(value);
+    }
+    function rejectStats(error) {
+        if (statsSettled)
+            return;
+        statsSettled = true;
+        rejectStatsPromise(error);
+    }
+    function resolveEmptyStats() {
+        resolveStats(undefined);
+    }
+    function processResponse(line) {
+        return process(line, resolveStats);
+    }
+    const responses = parseLines(responseStream, processResponse, resolveEmptyStats, rejectStats);
     let consumed = false;
     return {
+        stats,
         write(audioChunk) {
             requestStream.write(audioChunk);
         },
@@ -134,6 +161,7 @@ async function createTranscribeStreamSession(params, options, process, sessionNa
             requestStream.end();
         },
         destroy() {
+            resolveStats(undefined);
             requestStream.destroy();
             responseStream.destroy();
         },
@@ -154,32 +182,41 @@ function transcribeStreamDuplexMetadata(params, options) {
 }
 function transcribeStreamDuplexConversation(params, options) {
     const wantsMetadata = params.metadata === true;
-    return createTranscribeStreamSession(params, options, (line) => processLineConversation(line, wantsMetadata), 'TranscribeStreamConversationSession');
+    return createTranscribeStreamSession(params, options, (line, onStats) => processLineConversation(line, wantsMetadata, onStats), 'TranscribeStreamConversationSession');
 }
 /**
  * Line-delimited parser: reads newline-separated frames from a duplex
  * response stream, passes each non-empty line through `process`, and yields
  * whatever values it returns. `null` from `process` terminates the stream.
  */
-async function* parseLines(responseStream, process) {
+async function* parseLines(responseStream, process, onClose, onError) {
     let buf = '';
-    for await (const chunk of responseStream) {
-        buf += chunk.toString();
-        const lines = buf.split('\n');
-        buf = lines.pop() || '';
-        for (const line of lines) {
-            const result = process(line);
-            if (result === null)
-                return;
-            if (result !== undefined)
+    try {
+        for await (const chunk of responseStream) {
+            buf += chunk.toString();
+            const lines = buf.split('\n');
+            buf = lines.pop() || '';
+            for (const line of lines) {
+                const result = process(line);
+                if (result === null)
+                    return;
+                if (result !== undefined)
+                    yield result;
+            }
+        }
+        // Process any residual data after stream ends
+        if (buf.trim()) {
+            const result = process(buf);
+            if (result !== null && result !== undefined)
                 yield result;
         }
     }
-    // Process any residual data after stream ends
-    if (buf.trim()) {
-        const result = process(buf);
-        if (result !== null && result !== undefined)
-            yield result;
+    catch (error) {
+        onError(error);
+        throw error;
+    }
+    finally {
+        onClose();
     }
 }
 function parseResponseLine(line) {
@@ -204,23 +241,25 @@ function parseResponseLine(line) {
  * `undefined` for frames the caller should skip, or the value extracted from
  * the frame.
  */
-function processWith(line, extract) {
+function processWith(line, extract, onStats) {
     const response = parseResponseLine(line);
     if (response === null)
         return undefined;
     if (response.error)
         throw new TranscriptionFailedError(response.error);
-    if (response.done)
+    if (response.done) {
+        onStats(response.stats);
         return null;
+    }
     return extract(response);
 }
-function processLine(line) {
-    return processWith(line, (response) => (response.text?.trim() ? response.text : undefined));
+export function processLine(line, onStats) {
+    return processWith(line, (response) => (response.text?.trim() ? response.text : undefined), onStats);
 }
-function processLineMetadata(line) {
-    return processWith(line, (response) => response.segment);
+function processLineMetadata(line, onStats) {
+    return processWith(line, (response) => response.segment, onStats);
 }
-function processLineConversation(line, wantsMetadata) {
+function processLineConversation(line, wantsMetadata, onStats) {
     return processWith(line, (response) => {
         if (response.vad) {
             return {
@@ -252,5 +291,5 @@ function processLineConversation(line, wantsMetadata) {
             return { type: 'text', text: response.text };
         }
         return undefined;
-    });
+    }, onStats);
 }

package/dist/client/api/translate.d.ts

@@ -44,5 +44,6 @@ export declare function translate(params: TranslateClientParams, options?: RPCOp
     tokenStream: AsyncGenerator<string>;
     stats: Promise<TranslationStats | undefined>;
     text: Promise<string>;
+    requestId: string;
 };
 //# sourceMappingURL=translate.d.ts.map

package/dist/client/api/translate.js

@@ -1,4 +1,5 @@
 import { stream as streamRpc } from '../../client/rpc/rpc-client.js';
+import { generateClientRequestId } from '../../client/api/client-request-id.js';
 import { translateResponseSchema } from '../../schemas/index.js';
 /**
  * Translates text from one language to another using a specified translation model.
@@ -42,13 +43,17 @@ import { translateResponseSchema } from '../../schemas/index.js';
  * ```
  */
 export function translate(params, options) {
+    // Stable identity generated client-side so `cancel({ requestId })` works the
+    // moment we return, before the first round-trip. Surfaced on the handle.
+    const requestId = generateClientRequestId();
     // Source-language auto-detection lives in the worker now
     // (server/bare/ops/translate.ts): `from` is passed through when present and
     // resolved server-side when absent, so every language binding shares one
     // detector instead of each shipping its own.
     const request = {
         type: 'translate',
-        ...params
+        ...params,
+        requestId
     };
     let stats;
     let statsResolver = () => { };
@@ -57,24 +62,32 @@ export function translate(params, options) {
     });
     if (params.stream) {
         const tokenStream = (async function* () {
-            for await (const response of streamRpc(request, options)) {
-                if (response.type === 'translate') {
-                    const streamResponse = translateResponseSchema.parse(response);
-                    if (!streamResponse.done) {
-                        yield streamResponse.token;
-                    }
-                    else {
-                        stats = streamResponse.stats;
-                        statsResolver(stats);
+            try {
+                for await (const response of streamRpc(request, options)) {
+                    if (response.type === 'translate') {
+                        const streamResponse = translateResponseSchema.parse(response);
+                        if (!streamResponse.done) {
+                            yield streamResponse.token;
+                        }
+                        else {
+                            stats = streamResponse.stats;
+                            statsResolver(stats);
+                        }
                     }
                 }
             }
+            finally {
+                // Settle stats even if the stream ended early (cancel) or errored, so
+                // `await handle.stats` can't hang. Idempotent if already resolved.
+                statsResolver(stats);
+            }
         })();
         const textPromise = Promise.resolve('');
         return {
             tokenStream,
             text: textPromise,
-            stats: statsPromise
+            stats: statsPromise,
+            requestId
         };
     }
     else {
@@ -83,22 +96,30 @@ export function translate(params, options) {
         })();
         const textPromise = (async () => {
             let buffer = '';
-            for await (const response of streamRpc(request, options)) {
-                if (response.type === 'translate') {
-                    const streamResponse = translateResponseSchema.parse(response);
-                    buffer += streamResponse.token;
-                    if (streamResponse.done) {
-                        stats = streamResponse.stats;
-                        statsResolver(stats);
+            try {
+                for await (const response of streamRpc(request, options)) {
+                    if (response.type === 'translate') {
+                        const streamResponse = translateResponseSchema.parse(response);
+                        buffer += streamResponse.token;
+                        if (streamResponse.done) {
+                            stats = streamResponse.stats;
+                            statsResolver(stats);
+                        }
                     }
                 }
             }
+            finally {
+                // Settle stats even if the stream ended early (cancel) or errored, so
+                // `await handle.stats` can't hang. Idempotent if already resolved.
+                statsResolver(stats);
+            }
             return buffer;
         })();
         return {
             tokenStream,
             text: textPromise,
-            stats: statsPromise
+            stats: statsPromise,
+            requestId
         };
     }
 }

package/dist/client/api/vla.d.ts

@@ -1,4 +1,4 @@
-import { type VlaClientRunParams, type VlaClientRunResult, type VlaHparams } from '../../schemas/index.js';
+import { type VlaClientRunParams, type VlaClientRunResult, type VlaEmbodimentSelection, type VlaHparams } from '../../schemas/index.js';
 /**
  * Run VLA inference on a loaded model (SmolVLA, π₀.₅, or GR00T) and return the
  * produced action chunk plus per-stage timings.
@@ -70,4 +70,45 @@ export declare function vlaHparams(params: {
     hparams: VlaHparams;
     backendName: string | null;
 }>;
+/**
+ * Switch a loaded multi-embodiment GR00T model to another embodiment shipped
+ * in the same GGUF — no reload, only that embodiment's weight rows are re-read.
+ *
+ * The returned hparams follow the newly active embodiment: re-read
+ * `numCameras` (and re-size buffers if needed) before the next `vla()` call.
+ * `selectedEmbodimentTag` / `selectedEmbodimentCatId` report what was
+ * resolved. Selecting by `catId` reports that id's canonical tag, which may
+ * differ from the alias used to select — the id is the stable identity.
+ *
+ * Rejects (leaving the current embodiment active) for a non-GR00T or
+ * single-embodiment model, an unknown tag or `cat_id`, one not stored in the
+ * GGUF, an embodiment with no known camera count and no `numCameras`
+ * override, or while an inference response is still pending — await the
+ * in-flight `vla()` call first.
+ *
+ * @param params.modelId - Identifier of the loaded VLA model.
+ * @param params.embodiment - The embodiment to activate: a tag string, a
+ *   numeric `cat_id` (0..31), or `{ tag | catId, numCameras }` where
+ *   `numCameras` overrides the camera count stored in the GGUF.
+ * @returns The refreshed model hparams after the switch.
+ *
+ * @example
+ * ```typescript
+ * import { loadModel, vlaSetEmbodiment, vlaHparams } from "@qvac/sdk";
+ *
+ * const modelId = await loadModel({
+ *   modelSrc: "/path/to/groot-multi.gguf",
+ *   modelType: "vla",
+ *   modelConfig: { embodiment: "libero_sim" }, // initial selection at load
+ * });
+ * const { hparams } = await vlaSetEmbodiment({ modelId, embodiment: "real_droid" });
+ * console.log(hparams.selectedEmbodimentTag, hparams.numCameras);
+ * ```
+ */
+export declare function vlaSetEmbodiment(params: {
+    modelId: string;
+    embodiment: VlaEmbodimentSelection;
+}): Promise<{
+    hparams: VlaHparams;
+}>;
 //# sourceMappingURL=vla.d.ts.map

package/dist/client/api/vla.js

@@ -1,8 +1,9 @@
-import { vlaHparamsResponseSchema, vlaRunResponseSchema } from '../../schemas/index.js';
+import { vlaHparamsResponseSchema, vlaRunResponseSchema, vlaSetEmbodimentResponseSchema } from '../../schemas/index.js';
 import { decodeBase64, encodeBase64 } from '../../utils/encoding.js';
 import { invokePlugin } from './invoke-plugin.js';
 const VLA_RUN_HANDLER = 'vlaRun';
 const VLA_HPARAMS_HANDLER = 'vlaHparams';
+const VLA_SET_EMBODIMENT_HANDLER = 'vlaSetEmbodiment';
 function bytesOf(arr) {
     return new Uint8Array(arr.buffer, arr.byteOffset, arr.byteLength);
 }
@@ -115,3 +116,51 @@ export async function vlaHparams(params) {
     });
     return vlaHparamsResponseSchema.parse(result);
 }
+/**
+ * Switch a loaded multi-embodiment GR00T model to another embodiment shipped
+ * in the same GGUF — no reload, only that embodiment's weight rows are re-read.
+ *
+ * The returned hparams follow the newly active embodiment: re-read
+ * `numCameras` (and re-size buffers if needed) before the next `vla()` call.
+ * `selectedEmbodimentTag` / `selectedEmbodimentCatId` report what was
+ * resolved. Selecting by `catId` reports that id's canonical tag, which may
+ * differ from the alias used to select — the id is the stable identity.
+ *
+ * Rejects (leaving the current embodiment active) for a non-GR00T or
+ * single-embodiment model, an unknown tag or `cat_id`, one not stored in the
+ * GGUF, an embodiment with no known camera count and no `numCameras`
+ * override, or while an inference response is still pending — await the
+ * in-flight `vla()` call first.
+ *
+ * @param params.modelId - Identifier of the loaded VLA model.
+ * @param params.embodiment - The embodiment to activate: a tag string, a
+ *   numeric `cat_id` (0..31), or `{ tag | catId, numCameras }` where
+ *   `numCameras` overrides the camera count stored in the GGUF.
+ * @returns The refreshed model hparams after the switch.
+ *
+ * @example
+ * ```typescript
+ * import { loadModel, vlaSetEmbodiment, vlaHparams } from "@qvac/sdk";
+ *
+ * const modelId = await loadModel({
+ *   modelSrc: "/path/to/groot-multi.gguf",
+ *   modelType: "vla",
+ *   modelConfig: { embodiment: "libero_sim" }, // initial selection at load
+ * });
+ * const { hparams } = await vlaSetEmbodiment({ modelId, embodiment: "real_droid" });
+ * console.log(hparams.selectedEmbodimentTag, hparams.numCameras);
+ * ```
+ */
+export async function vlaSetEmbodiment(params) {
+    const wireRequest = {
+        type: 'vlaSetEmbodiment',
+        modelId: params.modelId,
+        embodiment: params.embodiment
+    };
+    const result = await invokePlugin({
+        modelId: params.modelId,
+        handler: VLA_SET_EMBODIMENT_HANDLER,
+        params: wireRequest
+    });
+    return vlaSetEmbodimentResponseSchema.parse(result);
+}

package/dist/commands/bundle/entry-gen.d.ts

@@ -1,2 +1,6 @@
 export declare function generateWorkerEntry(pluginSpecifiers: string[], sdkName: string, resolveImport?: (specifier: string) => string): string;
+export declare function generateWorkerEntries(pluginSpecifiers: string[], sdkName: string, resolveBundleImport: (specifier: string) => string): {
+    runtimeEntry: string;
+    bundleEntry: string;
+};
 //# sourceMappingURL=entry-gen.d.ts.map

package/dist/commands/bundle/entry-gen.js

@@ -46,3 +46,9 @@ if (hasRPCConfig) {
 }
 `;
 }
+export function generateWorkerEntries(pluginSpecifiers, sdkName, resolveBundleImport) {
+    return {
+        runtimeEntry: generateWorkerEntry(pluginSpecifiers, sdkName),
+        bundleEntry: generateWorkerEntry(pluginSpecifiers, sdkName, resolveBundleImport)
+    };
+}

package/dist/commands/bundle/index.js

@@ -6,7 +6,7 @@ import { CONFIG_CANDIDATES, resolveConfigForProject } from '../../client/config-
 import { getClientLogger } from '../../logging/index.js';
 import { BareImportsMapNotFoundError } from '../../utils/errors-client.js';
 import { resolvePluginSpecifiers, parseBuiltinSpecifier } from '../../commands/bundle/plugins.js';
-import { generateWorkerEntry } from '../../commands/bundle/entry-gen.js';
+import { generateWorkerEntries } from '../../commands/bundle/entry-gen.js';
 import { runBarePack } from '../../commands/bundle/bare-pack.js';
 import { generateAddonsManifest } from '../../commands/bundle/manifest.js';
 import { createSdkImportResolver } from '../../commands/bundle/resolve-sdk-import.js';
@@ -63,6 +63,7 @@ export async function bundleSdk(options = {}) {
     const projectRoot = options.projectRoot ?? process.cwd();
     const outputDir = path.join(projectRoot, 'qvac');
     const entryPath = path.join(outputDir, 'worker.entry.mjs');
+    const bundleEntryPath = path.join(outputDir, 'worker.bundle.entry.mjs');
     const bundlePath = path.join(outputDir, 'worker.bundle.js');
     const logger = createCommandLogger(options);
     logger.info('🔧 QVAC SDK Worker Bundler\n');
@@ -93,8 +94,8 @@ export async function bundleSdk(options = {}) {
     await fsp.mkdir(outputDir, { recursive: true });
     logger.info('\n📝 Generating worker entry...');
     const resolveSdkImport = createSdkImportResolver(sdkPath, sdkName);
-    const workerEntry = generateWorkerEntry(pluginSpecifiers, sdkName, resolveSdkImport);
-    await fsp.writeFile(entryPath, workerEntry, 'utf8');
+    const { runtimeEntry, bundleEntry } = generateWorkerEntries(pluginSpecifiers, sdkName, resolveSdkImport);
+    await fsp.writeFile(entryPath, runtimeEntry, 'utf8');
     logger.info(`   Created: ${path.relative(projectRoot, entryPath)}`);
     logger.info(`   Using: ${path.relative(projectRoot, importsMapPath)}`);
     logger.info('\n🔨 Bundling with bare-pack...');
@@ -102,15 +103,21 @@ export async function bundleSdk(options = {}) {
     if (deferModules.length > 0) {
         logger.debug(`   Deferred: ${deferModules.join(', ')}`);
     }
-    await runBarePack({
-        entryPath,
-        outputPath: bundlePath,
-        hosts,
-        importsMapPath,
-        deferModules,
-        quiet: options.quiet === true,
-        logger
-    });
+    try {
+        await fsp.writeFile(bundleEntryPath, bundleEntry, 'utf8');
+        await runBarePack({
+            entryPath: bundleEntryPath,
+            outputPath: bundlePath,
+            hosts,
+            importsMapPath,
+            deferModules,
+            quiet: options.quiet === true,
+            logger
+        });
+    }
+    finally {
+        await fsp.rm(bundleEntryPath, { force: true });
+    }
     const stats = await fsp.stat(bundlePath);
     const sizeKB = (stats.size / 1024).toFixed(1);
     logger.info(`\n✅ Bundle created: ${path.relative(projectRoot, bundlePath)}`);

package/dist/examples/asr/parakeet-indic-conformer-filesystem.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=parakeet-indic-conformer-filesystem.d.ts.map

package/dist/examples/asr/parakeet-indic-conformer-filesystem.js

@@ -0,0 +1,52 @@
+/**
+ * Indic Conformer CTC transcription from a WAV file.
+ *
+ * Usage:
+ *   bun run examples/asr/parakeet-indic-conformer-filesystem.ts <wav-file> <language> [gguf]
+ *
+ * Loads a single GGUF checkpoint (`PARAKEET_INDIC_CONFORMER_CTC_Q8_0` by
+ * default) and transcribes with the batch `transcribe` API. `language` is
+ * required (e.g. `hi`, `ta`) because Indic Conformer CTC masks the vocab
+ * with `parakeet.ctc.lang_*` ranges. English Parakeet CTC ignores this field.
+ *
+ * Audio should be 16 kHz mono PCM in a WAV container.
+ */
+import { loadModel, unloadModel, transcribe, PARAKEET_INDIC_CONFORMER_CTC_Q8_0 } from '@qvac/sdk';
+const args = process.argv.slice(2);
+if (!args[0] || !args[1]) {
+    console.error('Usage: bun run examples/asr/parakeet-indic-conformer-filesystem.ts ' +
+        '<wav-file> <language> [indic-conformer-gguf]');
+    console.error('\nExample: ... filesystem.ts speech.wav hi');
+    console.error('If the model path is omitted, defaults to the registry model.');
+    process.exit(1);
+}
+const audioFilePath = args[0];
+const language = args[1];
+const parakeetModelSrc = args[2] ?? PARAKEET_INDIC_CONFORMER_CTC_Q8_0;
+try {
+    console.log('▸ Loading Indic Conformer CTC model...');
+    const modelId = await loadModel({
+        modelSrc: parakeetModelSrc,
+        modelType: 'parakeet-transcription',
+        modelConfig: { language },
+        onProgress: (p) => {
+            const mb = (n) => (n / 1e6).toFixed(1);
+            const line = `▸ Downloading ${p.percentage.toFixed(0)}% (${mb(p.downloaded)}/${mb(p.total)} MB)`;
+            process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
+            if (p.percentage >= 100)
+                process.stderr.write('\n');
+        }
+    });
+    console.log(`▸ Indic Conformer CTC model loaded with ID: ${modelId}`);
+    console.log(`▸ Language: ${language}`);
+    console.log('▸ Transcribing audio...');
+    const text = await transcribe({ modelId, audioChunk: audioFilePath });
+    console.log(text);
+    console.log('▸ Unloading model...');
+    await unloadModel({ modelId });
+    console.log('▸ Done');
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/audiogen/generate-cover.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=generate-cover.d.ts.map

package/dist/examples/audiogen/generate-cover.js

@@ -0,0 +1,100 @@
+import { writeFileSync } from 'node:fs';
+import { AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0, AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M, AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0, AUDIOGEN_VAE_BF16, audioGen, loadModel, unloadModel } from '@qvac/sdk';
+// Re-render an existing song with a new caption (ACE-Step "cover-nofsq"),
+// optionally conditioning the timbre on a second reference clip.
+//
+// Usage:
+//   bun examples/audiogen/generate-cover.ts <source.wav|mp3|...> "orchestral arrangement" [reference.wav] [output.wav]
+//
+// Both audio inputs are file paths: the SDK decodes them (any FFmpeg-decodable
+// format) to the 48 kHz stereo float PCM the engine expects. Pass raw
+// interleaved stereo 48 kHz Float32 LE PCM as a Buffer instead when the audio
+// is already in memory.
+const sourcePath = process.argv[2];
+const caption = process.argv[3] ?? 'Orchestral arrangement with dramatic strings';
+const referencePath = process.argv[4];
+const outputPath = process.argv[5] ?? 'audiogen-cover.wav';
+if (!sourcePath) {
+    console.error('Usage: bun examples/audiogen/generate-cover.ts <source-audio> "<caption>" [reference-audio] [output.wav]');
+    process.exit(1);
+}
+let modelId;
+try {
+    console.log('▸ Loading ACE-Step AudioGen models...');
+    modelId = await loadModel({
+        modelType: 'audiogen',
+        modelConfig: {
+            textEncModelSrc: AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0,
+            lmModelSrc: AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0,
+            ditModelSrc: AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M,
+            vaeModelSrc: AUDIOGEN_VAE_BF16,
+            useGPU: true
+        }
+    });
+    console.log(`▸ Model loaded: ${modelId}`);
+    console.log(`▸ Covering ${sourcePath} as: ${caption}`);
+    const run = audioGen({
+        modelId,
+        caption,
+        lyrics: '[Instrumental]',
+        taskType: 'cover-nofsq',
+        sourceAudio: sourcePath,
+        ...(referencePath !== undefined && { referenceAudio: referencePath }),
+        // cover-nofsq keeps the full source context; coverNoiseStrength blends the
+        // initial noise toward the source latent (0 = pure noise, 1 ≈ source).
+        audioCoverStrength: 1,
+        coverNoiseStrength: 0.75,
+        seed: 22886
+    });
+    console.log(`▸ requestId: ${run.requestId}`);
+    for await (const progress of run.progressStream) {
+        console.log(`▸ ${progress.stage}: ${progress.step}/${progress.total}`);
+    }
+    const [audio, stats] = await Promise.all([run.audio, run.stats]);
+    writeFileSync(outputPath, createWav(audio.pcm, audio.sampleRate, audio.channels, audio.bitsPerSample));
+    if (stats)
+        console.log(`▸ Stats: ${JSON.stringify(stats)}`);
+    console.log(`▸ Saved ${outputPath}`);
+    await unloadModel({ modelId });
+    modelId = undefined;
+    process.exit(0);
+}
+catch (error) {
+    if (modelId !== undefined) {
+        try {
+            await unloadModel({ modelId });
+        }
+        catch {
+            // Preserve the generation error as the primary failure.
+        }
+    }
+    console.error('✖', error);
+    process.exit(1);
+}
+function createWav(pcm, sampleRate, channels, bitsPerSample) {
+    const header = new ArrayBuffer(44);
+    const view = new DataView(header);
+    const blockAlign = channels * (bitsPerSample / 8);
+    writeAscii(view, 0, 'RIFF');
+    view.setUint32(4, 36 + pcm.byteLength, true);
+    writeAscii(view, 8, 'WAVE');
+    writeAscii(view, 12, 'fmt ');
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true);
+    view.setUint16(22, channels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, sampleRate * blockAlign, true);
+    view.setUint16(32, blockAlign, true);
+    view.setUint16(34, bitsPerSample, true);
+    writeAscii(view, 36, 'data');
+    view.setUint32(40, pcm.byteLength, true);
+    const wav = new Uint8Array(44 + pcm.byteLength);
+    wav.set(new Uint8Array(header));
+    wav.set(pcm, 44);
+    return wav;
+}
+function writeAscii(view, offset, value) {
+    for (let index = 0; index < value.length; index++) {
+        view.setUint8(offset + index, value.charCodeAt(index));
+    }
+}

package/dist/examples/llamacpp-fallback.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llamacpp-fallback.d.ts.map

package/dist/examples/llamacpp-fallback.js

@@ -0,0 +1,34 @@
+import { completion, loadModel, unloadModel, LLAMA_3_2_1B_INST_Q4_0 } from '@qvac/sdk';
+// A catalog model loads from the registry by default. On networks where the
+// registry is unreachable, pass `fallbackSrc` — an HTTP URL or a local file
+// path — to load the same model from an alternate source. The bytes are
+// validated against the catalog model's checksum before use.
+const fallbackUrl = process.argv[2] ||
+    'https://huggingface.co/bartowski/Llama-3.2-1B-Instruct-GGUF/resolve/main/Llama-3.2-1B-Instruct-Q4_0.gguf';
+console.log(`▸ Loading ${LLAMA_3_2_1B_INST_Q4_0.name} (fallback: ${fallbackUrl})`);
+try {
+    const modelId = await loadModel({
+        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
+        fallbackSrc: fallbackUrl,
+        onProgress: (p) => {
+            const mb = (n) => (n / 1e6).toFixed(1);
+            const line = `▸ Downloading ${p.percentage.toFixed(0)}% (${mb(p.downloaded)}/${mb(p.total)} MB)`;
+            process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
+            if (p.percentage >= 100)
+                process.stderr.write('\n');
+        }
+    });
+    console.log(`▸ Model loaded successfully! Model ID: ${modelId}`);
+    const history = [{ role: 'user', content: 'Explain quantum computing in 3 key points' }];
+    console.log('\n▸ AI Response:');
+    const result = completion({ modelId, history, stream: true });
+    for await (const token of result.tokenStream) {
+        process.stdout.write(token);
+    }
+    console.log('\n\n▸ Completed!');
+    await unloadModel({ modelId, clearStorage: false });
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}