@qvac/sdk 0.14.1 → 0.16.0

package/dist/examples/tts/chatterbox.js

@@ -1,5 +1,5 @@
-import { loadModel, textToSpeech, unloadModel, TTS_T3_TURBO_EN_CHATTERBOX_Q8_0, TTS_S3GEN_EN_CHATTERBOX, } from "@qvac/sdk";
-import { createWav, playAudio, int16ArrayToBuffer, createWavHeader, } from "./utils.js";
+import { loadModel, textToSpeech, unloadModel, TTS_T3_TURBO_EN_CHATTERBOX_Q8_0, TTS_S3GEN_EN_CHATTERBOX } from '@qvac/sdk';
+import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
 // Chatterbox TTS (GGML): voice cloning with optional reference audio.
 // Uses registry model constants — downloads automatically from QVAC Registry.
 // Usage: node chatterbox.ts [referenceAudioSrc]
@@ -9,49 +9,49 @@ try {
     const modelId = await loadModel({
         modelSrc: TTS_T3_TURBO_EN_CHATTERBOX_Q8_0,
         modelConfig: {
-            ttsEngine: "chatterbox",
-            language: "en",
+            ttsEngine: 'chatterbox',
+            language: 'en',
             s3genModelSrc: TTS_S3GEN_EN_CHATTERBOX.src,
             streamChunkTokens: 25,
             streamFirstChunkTokens: 10,
             cfmSteps: 1,
             threads: 8,
-            ...(referenceAudioSrc ? { referenceAudioSrc } : {}),
+            ...(referenceAudioSrc ? { referenceAudioSrc } : {})
         },
         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");
-        },
+                process.stderr.write('\n');
+        }
     });
     console.log(`▸ Model loaded: ${modelId}`);
-    console.log("▸ Testing Text-to-Speech...");
+    console.log('▸ Testing Text-to-Speech...');
     const result = textToSpeech({
         modelId,
         text: `QVAC SDK is the canonical entry point to QVAC. Written in TypeScript, it provides all QVAC capabilities through a unified interface while also abstracting away the complexity of running your application in a JS environment other than Bare. Supported JS environments include Bare, Node.js, Expo and Bun.`,
-        inputType: "text",
-        stream: false,
+        inputType: 'text',
+        stream: false
     });
     const audioBuffer = await result.buffer;
     console.log(`▸ TTS complete. Total bytes: ${audioBuffer.length}`);
-    console.log("▸ Saving audio to file...");
-    createWav(audioBuffer, CHATTERBOX_SAMPLE_RATE, "tts-output.wav");
-    console.log("▸ Audio saved to tts-output.wav");
-    console.log("▸ Playing audio...");
+    console.log('▸ Saving audio to file...');
+    createWav(audioBuffer, CHATTERBOX_SAMPLE_RATE, 'tts-output.wav');
+    console.log('▸ Audio saved to tts-output.wav');
+    console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
     const wavBuffer = Buffer.concat([
         createWavHeader(audioData.length, CHATTERBOX_SAMPLE_RATE),
-        audioData,
+        audioData
     ]);
     playAudio(wavBuffer);
-    console.log("▸ Audio playback complete");
+    console.log('▸ Audio playback complete');
     await unloadModel({ modelId });
-    console.log("▸ Model unloaded");
+    console.log('▸ Model unloaded');
     process.exit(0);
 }
 catch (error) {
-    console.error("✖", error);
+    console.error('✖', error);
     process.exit(1);
 }

package/dist/examples/tts/llm-to-tts-streaming.js

@@ -12,8 +12,8 @@
  * Usage:
  *   bun run examples/tts/llm-to-tts-streaming.ts
  */
-import { completion, loadModel, textToSpeechStream, unloadModel, LLAMA_3_2_1B_INST_Q4_0, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0, } from "@qvac/sdk";
-import { createWav, playPcmInt16Chunk } from "./utils.js";
+import { completion, loadModel, textToSpeechStream, unloadModel, LLAMA_3_2_1B_INST_Q4_0, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0 } from '@qvac/sdk';
+import { createWav, playPcmInt16Chunk } from './utils.js';
 const SUPERTONIC_SAMPLE_RATE = 44100;
 /**
  * Drop angle-bracket spans (e.g. `<think>…</think>`, `<|foo|>`) even when split across tokens,
@@ -22,20 +22,20 @@ const SUPERTONIC_SAMPLE_RATE = 44100;
 function createAngleBracketAndStarFilter() {
     let inAngle = false;
     return function filterChunk(chunk) {
-        let out = "";
+        let out = '';
         for (let i = 0; i < chunk.length; i++) {
             const c = chunk[i];
             if (inAngle) {
-                if (c === ">") {
+                if (c === '>') {
                     inAngle = false;
                 }
                 continue;
             }
-            if (c === "<") {
+            if (c === '<') {
                 inAngle = true;
                 continue;
             }
-            if (c === "*") {
+            if (c === '*') {
                 continue;
             }
             out += c;
@@ -61,49 +61,49 @@ try {
     const llmModelId = await loadModel({
         modelSrc: LLAMA_3_2_1B_INST_Q4_0,
         modelConfig: {
-            ctx_size: 2048,
+            ctx_size: 2048
         },
         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");
-        },
+                process.stderr.write('\n');
+        }
     });
     console.log(`▸ LLM ready: ${llmModelId}`);
-    console.log("▸ Loading Supertonic TTS (registry)…");
+    console.log('▸ Loading Supertonic TTS (registry)…');
     const ttsModelId = await loadModel({
         modelSrc: TTS_MULTILINGUAL_SUPERTONIC3_Q8_0,
         modelConfig: {
-            ttsEngine: "supertonic",
-            language: "en",
-            voice: "F1",
+            ttsEngine: 'supertonic',
+            language: 'en',
+            voice: 'F1',
             ttsSpeed: 1.05,
-            ttsNumInferenceSteps: 10,
+            ttsNumInferenceSteps: 10
         },
         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");
-        },
+                process.stderr.write('\n');
+        }
     });
     console.log(`▸ TTS ready: ${ttsModelId}`);
-    const prompt = "What is a constellation?";
+    const prompt = 'What is a constellation?';
     console.log(`▸ User: ${prompt}`);
-    console.log("▸ Assistant (streaming):");
+    console.log('▸ Assistant (streaming):');
     const result = completion({
         modelId: llmModelId,
-        history: [{ role: "user", content: prompt }],
-        stream: true,
+        history: [{ role: 'user', content: prompt }],
+        stream: true
     });
     const combinedPcm = [];
     const ttsSession = await textToSpeechStream({
         modelId: ttsModelId,
-        inputType: "text",
-        accumulateSentences: true,
+        inputType: 'text',
+        accumulateSentences: true
     });
     let phraseIndex = 0;
     const filterChunk = createAngleBracketAndStarFilter();
@@ -112,10 +112,10 @@ try {
             if (m.buffer.length > 0) {
                 appendPcmSamples(combinedPcm, m.buffer);
                 phraseIndex += 1;
-                const preview = typeof m.sentenceChunk === "string"
-                    ? m.sentenceChunk.replace(/\s+/g, " ").trim().slice(0, 72)
-                    : "";
-                console.log(`\n▸ [TTS phrase ${phraseIndex}] ${m.buffer.length} samples${preview ? ` — "${preview}${preview.length >= 72 ? "..." : ""}"` : ""}`);
+                const preview = typeof m.sentenceChunk === 'string'
+                    ? m.sentenceChunk.replace(/\s+/g, ' ').trim().slice(0, 72)
+                    : '';
+                console.log(`\n▸ [TTS phrase ${phraseIndex}] ${m.buffer.length} samples${preview ? ` — "${preview}${preview.length >= 72 ? '...' : ''}"` : ''}`);
                 await playPcmInt16Chunk(m.buffer, SUPERTONIC_SAMPLE_RATE);
             }
         }
@@ -131,17 +131,17 @@ try {
     await drainPcm;
     const stats = await result.stats;
     if (stats) {
-        console.log("\n▸ LLM stats:", stats);
+        console.log('\n▸ LLM stats:', stats);
     }
-    const outWav = "llm-to-tts-streaming-output.wav";
+    const outWav = 'llm-to-tts-streaming-output.wav';
     console.log(`\n▸ Writing ${combinedPcm.length} samples to ${outWav} (full utterance; phrases were already played above).`);
     createWav(combinedPcm, SUPERTONIC_SAMPLE_RATE, outWav);
     await unloadModel({ modelId: llmModelId, clearStorage: false });
     await unloadModel({ modelId: ttsModelId, clearStorage: false });
-    console.log("▸ Models unloaded.");
+    console.log('▸ Models unloaded.');
     process.exit(0);
 }
 catch (error) {
-    console.error("✖", error);
+    console.error('✖', error);
     process.exit(1);
 }

package/dist/examples/tts/supertonic-enhanced.d.ts

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

package/dist/examples/tts/supertonic-enhanced.js

@@ -0,0 +1,57 @@
+import { loadModel, textToSpeech, unloadModel, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0, TTS_DENOISER_LAVASR_FP16, TTS_ENHANCER_LAVASR_FP16 } from '@qvac/sdk';
+import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
+// Supertonic 3 TTS (GGML) with LavaSR post-processing: the denoiser cleans the
+// synthesized signal first, then the enhancer bandwidth-extends it to 48 kHz.
+// Supplying the enhancer GGUF is what enables enhancement — there is no on/off
+// flag — and it forces the output to 48 kHz regardless of the engine's native
+// rate.
+const ENHANCED_SAMPLE_RATE = 48000;
+try {
+    const modelId = await loadModel({
+        modelSrc: TTS_MULTILINGUAL_SUPERTONIC3_Q8_0,
+        modelConfig: {
+            ttsEngine: 'supertonic',
+            language: 'en',
+            voice: 'F1',
+            // Denoiser runs first (rate-preserving)…
+            lavasrDenoiserModelSrc: TTS_DENOISER_LAVASR_FP16.src,
+            // …then the enhancer bandwidth-extends to 48 kHz.
+            lavasrEnhancerModelSrc: TTS_ENHANCER_LAVASR_FP16.src
+        },
+        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: ${modelId}`);
+    console.log('▸ Testing Text-to-Speech (LavaSR denoiser + enhancer)...');
+    const result = textToSpeech({
+        modelId,
+        text: `QVAC SDK is the canonical entry point to QVAC. Written in TypeScript, it provides all QVAC capabilities through a unified interface while also abstracting away the complexity of running your application in a JS environment other than Bare. Supported JS environments include Bare, Node.js, Expo and Bun.`,
+        inputType: 'text',
+        stream: false
+    });
+    const audioBuffer = await result.buffer;
+    console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
+    console.log('▸ Saving audio to file...');
+    createWav(audioBuffer, ENHANCED_SAMPLE_RATE, 'supertonic-enhanced-output.wav');
+    console.log('▸ Audio saved to supertonic-enhanced-output.wav');
+    console.log('▸ Playing audio...');
+    const audioData = int16ArrayToBuffer(audioBuffer);
+    const wavBuffer = Buffer.concat([
+        createWavHeader(audioData.length, ENHANCED_SAMPLE_RATE),
+        audioData
+    ]);
+    playAudio(wavBuffer);
+    console.log('▸ Audio playback complete');
+    await unloadModel({ modelId });
+    console.log('▸ Model unloaded');
+    process.exit(0);
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/tts/supertonic-multilingual.js

@@ -1,51 +1,51 @@
-import { loadModel, textToSpeech, unloadModel, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0, } from "@qvac/sdk";
-import { createWav, playAudio, int16ArrayToBuffer, createWavHeader, } from "./utils.js";
+import { loadModel, textToSpeech, unloadModel, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0 } from '@qvac/sdk';
+import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
 // Supertonic 3 TTS (GGML): multilingual synthesis across 31 languages.
 const SUPERTONIC_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
         modelSrc: TTS_MULTILINGUAL_SUPERTONIC3_Q8_0,
         modelConfig: {
-            ttsEngine: "supertonic",
-            language: "es",
-            voice: "F1",
+            ttsEngine: 'supertonic',
+            language: 'es',
+            voice: 'F1',
             ttsSpeed: 1.05,
-            ttsNumInferenceSteps: 5,
+            ttsNumInferenceSteps: 5
         },
         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");
-        },
+                process.stderr.write('\n');
+        }
     });
     console.log(`▸ Model loaded: ${modelId}`);
-    console.log("▸ Testing Text-to-Speech...");
+    console.log('▸ Testing Text-to-Speech...');
     const result = textToSpeech({
         modelId,
         text: `Hola mundo. Esta es una demostración de síntesis de voz con Supertonic en español.`,
-        inputType: "text",
-        stream: false,
+        inputType: 'text',
+        stream: false
     });
     const audioBuffer = await result.buffer;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
-    console.log("▸ Saving audio to file...");
-    createWav(audioBuffer, SUPERTONIC_SAMPLE_RATE, "supertonic-multilingual-output.wav");
-    console.log("▸ Audio saved to supertonic-multilingual-output.wav");
-    console.log("▸ Playing audio...");
+    console.log('▸ Saving audio to file...');
+    createWav(audioBuffer, SUPERTONIC_SAMPLE_RATE, 'supertonic-multilingual-output.wav');
+    console.log('▸ Audio saved to supertonic-multilingual-output.wav');
+    console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
     const wavBuffer = Buffer.concat([
         createWavHeader(audioData.length, SUPERTONIC_SAMPLE_RATE),
-        audioData,
+        audioData
     ]);
     playAudio(wavBuffer);
-    console.log("▸ Audio playback complete");
+    console.log('▸ Audio playback complete');
     await unloadModel({ modelId });
-    console.log("▸ Model unloaded");
+    console.log('▸ Model unloaded');
     process.exit(0);
 }
 catch (error) {
-    console.error("✖", error);
+    console.error('✖', error);
     process.exit(1);
 }

package/dist/examples/tts/supertonic.js

@@ -1,5 +1,5 @@
-import { loadModel, textToSpeech, unloadModel, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0, } from "@qvac/sdk";
-import { createWav, playAudio, int16ArrayToBuffer, createWavHeader, } from "./utils.js";
+import { loadModel, textToSpeech, unloadModel, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0 } from '@qvac/sdk';
+import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
 // Supertonic 3 TTS (GGML): fast multilingual synthesis with baked-in voices.
 // Uses registry model constants — downloads automatically from QVAC Registry.
 const SUPERTONIC_SAMPLE_RATE = 44100;
@@ -7,9 +7,9 @@ try {
     const modelId = await loadModel({
         modelSrc: TTS_MULTILINGUAL_SUPERTONIC3_Q8_0,
         modelConfig: {
-            ttsEngine: "supertonic",
-            language: "en",
-            voice: "F1",
+            ttsEngine: 'supertonic',
+            language: 'en',
+            voice: 'F1',
             ttsSpeed: 1.05,
             ttsNumInferenceSteps: 5
         },
@@ -18,35 +18,35 @@ try {
             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");
-        },
+                process.stderr.write('\n');
+        }
     });
     console.log(`▸ Model loaded: ${modelId}`);
-    console.log("▸ Testing Text-to-Speech...");
+    console.log('▸ Testing Text-to-Speech...');
     const result = textToSpeech({
         modelId,
         text: `QVAC SDK is the canonical entry point to QVAC. Written in TypeScript, it provides all QVAC capabilities through a unified interface while also abstracting away the complexity of running your application in a JS environment other than Bare. Supported JS environments include Bare, Node.js, Expo and Bun.`,
-        inputType: "text",
-        stream: false,
+        inputType: 'text',
+        stream: false
     });
     const audioBuffer = await result.buffer;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
-    console.log("▸ Saving audio to file...");
-    createWav(audioBuffer, SUPERTONIC_SAMPLE_RATE, "supertonic-output.wav");
-    console.log("▸ Audio saved to supertonic-output.wav");
-    console.log("▸ Playing audio...");
+    console.log('▸ Saving audio to file...');
+    createWav(audioBuffer, SUPERTONIC_SAMPLE_RATE, 'supertonic-output.wav');
+    console.log('▸ Audio saved to supertonic-output.wav');
+    console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
     const wavBuffer = Buffer.concat([
         createWavHeader(audioData.length, SUPERTONIC_SAMPLE_RATE),
-        audioData,
+        audioData
     ]);
     playAudio(wavBuffer);
-    console.log("▸ Audio playback complete");
+    console.log('▸ Audio playback complete');
     await unloadModel({ modelId });
-    console.log("▸ Model unloaded");
+    console.log('▸ Model unloaded');
     process.exit(0);
 }
 catch (error) {
-    console.error("✖", error);
+    console.error('✖', error);
     process.exit(1);
 }

package/dist/examples/tts/utils.js

@@ -1,18 +1,18 @@
-import { writeFileSync, unlinkSync } from "fs";
-import { spawn, spawnSync } from "child_process";
-import { platform, tmpdir } from "os";
-import { join } from "path";
+import { writeFileSync, unlinkSync } from 'fs';
+import { spawn, spawnSync } from 'child_process';
+import { platform, tmpdir } from 'os';
+import { join } from 'path';
 /**
  * Create WAV header for 16-bit PCM audio
  */
 export function createWavHeader(dataLength, sampleRate) {
     const header = Buffer.alloc(44);
     // RIFF header
-    header.write("RIFF", 0);
+    header.write('RIFF', 0);
     header.writeUInt32LE(36 + dataLength, 4);
-    header.write("WAVE", 8);
+    header.write('WAVE', 8);
     // fmt chunk
-    header.write("fmt ", 12);
+    header.write('fmt ', 12);
     header.writeUInt32LE(16, 16); // fmt chunk size
     header.writeUInt16LE(1, 20); // PCM format
     header.writeUInt16LE(1, 22); // mono
@@ -21,7 +21,7 @@ export function createWavHeader(dataLength, sampleRate) {
     header.writeUInt16LE(2, 32); // block align
     header.writeUInt16LE(16, 34); // bits per sample
     // data chunk
-    header.write("data", 36);
+    header.write('data', 36);
     header.writeUInt32LE(dataLength, 40);
     return header;
 }
@@ -74,28 +74,28 @@ export function playPcmInt16Chunk(samples, sampleRate) {
     let audioPlayer;
     let args;
     switch (currentPlatform) {
-        case "darwin":
-            audioPlayer = "afplay";
+        case 'darwin':
+            audioPlayer = 'afplay';
             args = [tempFile];
             break;
-        case "linux":
-            audioPlayer = "aplay";
+        case 'linux':
+            audioPlayer = 'aplay';
             args = [tempFile];
             break;
-        case "win32":
-            audioPlayer = "powershell";
+        case 'win32':
+            audioPlayer = 'powershell';
             args = [
-                "-Command",
-                `Add-Type -AssemblyName presentationCore; (New-Object Media.SoundPlayer).LoadStream([System.IO.File]::ReadAllBytes('${tempFile}')).PlaySync()`,
+                '-Command',
+                `Add-Type -AssemblyName presentationCore; (New-Object Media.SoundPlayer).LoadStream([System.IO.File]::ReadAllBytes('${tempFile}')).PlaySync()`
             ];
             break;
         default:
-            audioPlayer = "aplay";
+            audioPlayer = 'aplay';
             args = [tempFile];
     }
     return new Promise(function (resolve, reject) {
-        const proc = spawn(audioPlayer, args, { stdio: "ignore" });
-        proc.on("error", function (err) {
+        const proc = spawn(audioPlayer, args, { stdio: 'ignore' });
+        proc.on('error', function (err) {
             try {
                 unlinkSync(tempFile);
             }
@@ -104,7 +104,7 @@ export function playPcmInt16Chunk(samples, sampleRate) {
             }
             reject(err);
         });
-        proc.on("close", function (code) {
+        proc.on('close', function (code) {
             try {
                 unlinkSync(tempFile);
             }
@@ -121,22 +121,14 @@ export function playPcmInt16Chunk(samples, sampleRate) {
     });
 }
 export function playAudio(audioBuffer) {
-    const result = spawnSync("ffplay", [
-        "-hide_banner",
-        "-loglevel",
-        "error",
-        "-autoexit",
-        "-nodisp",
-        "-i",
-        "pipe:0",
-    ], {
+    const result = spawnSync('ffplay', ['-hide_banner', '-loglevel', 'error', '-autoexit', '-nodisp', '-i', 'pipe:0'], {
         input: audioBuffer,
-        stdio: ["pipe", "inherit", "inherit"],
+        stdio: ['pipe', 'inherit', 'inherit']
     });
     if (result.error) {
         const code = result.error.code;
-        if (code === "ENOENT") {
-            throw new Error("ffplay not found on PATH. Install ffmpeg (ffplay ships with it) and retry.");
+        if (code === 'ENOENT') {
+            throw new Error('ffplay not found on PATH. Install ffmpeg (ffplay ships with it) and retry.');
         }
         throw new Error(`ffplay failed: ${result.error.message}`);
     }

package/dist/examples/vla-groot.d.ts

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

package/dist/examples/vla-groot.js

@@ -0,0 +1,118 @@
+/**
+ * NVIDIA GR00T N1.7-3B (vision-language-action) example using the QVAC SDK.
+ *
+ * Loads the GR00T-N1.7-3B LIBERO GGUF model, runs a single inference pass with
+ * synthetic inputs, and prints the produced action chunk + per-stage timings.
+ *
+ * GR00T differs from SmolVLA / π₀.₅ in the ways the SDK surfaces via
+ * `vlaHparams()`:
+ *   - `imageInputMode: 'patches'` — each `images` entry is a pre-patchified
+ *     buffer of `hparams.imagePatchElems` floats, NOT a `3·w·h` pixel plane.
+ *     A real consumer runs the model's own vision patch-embed over each camera
+ *     frame; here we feed synthetic patch buffers of the right length.
+ *   - `stateInputMode: 'continuous'` — the robot state is projected by an
+ *     in-model linear layer; pad it to `hparams.maxStateDim` with `vlaPadState`.
+ *   - `noise` is REQUIRED. GR00T is a flow-matching model that does not sample
+ *     its own prior; a missing `noise` is rejected as INVALID_INPUT.
+ *
+ * The prompt must place one contiguous run of `MERGED_TOKENS_PER_IMAGE`
+ * image-placeholder tokens per camera. A real consumer produces this by
+ * tokenising the instruction with the Qwen3-VL tokenizer, which inserts the
+ * image tokens; we lay it out by hand for the smoke.
+ *
+ * Usage:
+ *   bun examples/vla-groot.ts [path-to-groot.gguf]
+ *
+ * By default the example pulls the registry-baked GR00T-LIBERO GGUF (~3.76 GB)
+ * on first run and caches it locally. Pass an absolute path on the command line
+ * to override and load a local GGUF instead.
+ */
+import { close, loadModel, GROOT_Q8_VF16, unloadModel, vla, vlaHparams, vlaPadState } from '@qvac/sdk';
+// LIBERO GR00T prompt layout (Qwen3-VL tokenizer). GR00T reports
+// `hparams.tokenizerMaxLength === 0` — it does not surface a tokenizer length,
+// so the prompt length is fixed by the model: 2 cameras × 64 merged image
+// tokens (256 patches, 2×2 merge) = 128 image tokens, plus text, = 148 total.
+// A real consumer gets these from the tokenizer; the smoke hard-codes them.
+const IMAGE_TOKEN_ID = 151655;
+const MERGED_TOKENS_PER_IMAGE = 64;
+const PROMPT_LENGTH = 148;
+const TEXT_TOKEN_ID = 1000;
+const modelSrcOverride = process.argv[2];
+const modelSrc = modelSrcOverride ?? GROOT_Q8_VF16;
+try {
+    console.log('▸ Loading GR00T (N1.7-3B LIBERO) model...');
+    const modelId = await loadModel({
+        modelSrc,
+        modelType: 'ggml-vla',
+        modelConfig: { backend: 'cpu' },
+        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');
+        }
+    });
+    if (typeof modelSrc !== 'string')
+        process.stderr.write('\n');
+    console.log(`▸ Model loaded: ${modelId}`);
+    const { hparams, backendName } = await vlaHparams({ modelId });
+    console.log(`▸ Backend: ${backendName ?? '(unknown)'}`);
+    console.log('▸ Hparams:', hparams);
+    const patchElems = hparams.imagePatchElems;
+    if (hparams.imageInputMode !== 'patches' || patchElems == null) {
+        throw new Error(`expected a patch-input model (imageInputMode 'patches' + imagePatchElems); ` +
+            `got imageInputMode=${hparams.imageInputMode}`);
+    }
+    const numCameras = hparams.numCameras ?? 2;
+    // Patch-input model: each camera is a pre-patchified buffer of exactly
+    // `imagePatchElems` floats. A real consumer fills these from the model's
+    // vision patch-embed over the camera frame; we use small synthetic values.
+    const images = Array.from({ length: numCameras }, () => new Float32Array(patchElems).fill(0.02));
+    // Continuous-state model: pad the robot state to `maxStateDim`.
+    const state = vlaPadState([0, 0, 0, 0, 0, 0], hparams.maxStateDim);
+    // GR00T requires the noise prior (flow-matching; it is not sampled in-model).
+    const noise = new Float32Array(hparams.chunkSize * hparams.maxActionDim);
+    // Prompt: one run of `MERGED_TOKENS_PER_IMAGE` image tokens per camera, each
+    // followed by a text separator, padded out to the fixed `PROMPT_LENGTH`.
+    const tokens = new Int32Array(PROMPT_LENGTH);
+    let w = 0;
+    for (let cam = 0; cam < numCameras; cam++) {
+        for (let k = 0; k < MERGED_TOKENS_PER_IMAGE && w < tokens.length; k++) {
+            tokens[w++] = IMAGE_TOKEN_ID;
+        }
+        if (w < tokens.length)
+            tokens[w++] = TEXT_TOKEN_ID + cam;
+    }
+    for (; w < tokens.length; w++)
+        tokens[w] = TEXT_TOKEN_ID + w;
+    const mask = new Uint8Array(PROMPT_LENGTH).fill(1);
+    console.log('▸ Running VLA inference...');
+    const { actions, actionDim, chunkSize, stats } = await vla({
+        modelId,
+        images,
+        // Patch inputs ignore imgWidth/imgHeight, but the request schema requires
+        // positive integers; pass the model's vision image size.
+        imgWidth: hparams.visionImageSize,
+        imgHeight: hparams.visionImageSize,
+        state,
+        tokens,
+        mask,
+        noise
+    });
+    console.log(`▸ Got ${chunkSize} action steps of dim ${actionDim}.`);
+    console.log(Array.from(actions.subarray(0, actionDim)));
+    if (stats) {
+        console.log(`▸ Timing: vision=${stats.vision_ms?.toFixed(0)}ms ` +
+            `ode=${stats.ode_ms?.toFixed(0)}ms ` +
+            `total=${stats.total_ms?.toFixed(0)}ms`);
+    }
+    await unloadModel({ modelId, clearStorage: false });
+    console.log('▸ Model unloaded.');
+    process.exit(0);
+}
+catch (error) {
+    console.error('✖', error);
+    await close();
+    process.exit(1);
+}