@qvac/sdk 0.15.0 → 0.17.0

package/dist/examples/diffusion-txt2vid-ltx.js

@@ -0,0 +1,92 @@
+import { loadModel, unloadModel, video } from '@qvac/sdk';
+import fs from 'fs';
+import path from 'path';
+// Text-to-video (+ synchronized audio) with LTX-2. Unlike Wan, LTX-2 uses a
+// Gemma text encoder (llmModelSrc), a video VAE (vaeModelSrc), a set of
+// text-embedding connectors (embeddingsConnectorsModelSrc — this is what
+// selects the LTX-2 layout), and an optional audio VAE (audioVaeModelSrc)
+// that produces a 48 kHz audio track muxed into the output AVI.
+//
+// This example needs powerful hardware: LTX-2.3 is a ~21B model, budget at
+// least 20+ GB of video / unified memory.
+//
+// No LTX-2 model constants ship in the SDK registry, so the model sources
+// default to public HuggingFace URLs (the SDK downloads http(s) sources
+// directly). Pass your own paths / URLs via argv to override.
+const HF = 'https://huggingface.co';
+const diffusionModelSrc = process.argv[2] ||
+    `${HF}/QuantStack/LTX-2.3-GGUF/resolve/main/LTX-2.3-distilled-1.1/LTX-2.3-22B-distilled-1.1-Q5_K_M.gguf`;
+const llmModelSrc = process.argv[3] || `${HF}/unsloth/gemma-3-12b-it-GGUF/resolve/main/gemma-3-12b-it-UD-Q4_K_XL.gguf`;
+const vaeModelSrc = process.argv[4] ||
+    `${HF}/unsloth/LTX-2.3-GGUF/resolve/main/vae/ltx-2.3-22b-distilled_video_vae.safetensors`;
+const audioVaeModelSrc = process.argv[5] ||
+    `${HF}/unsloth/LTX-2.3-GGUF/resolve/main/vae/ltx-2.3-22b-distilled_audio_vae.safetensors`;
+const embeddingsConnectorsModelSrc = process.argv[6] ||
+    `${HF}/unsloth/LTX-2.3-GGUF/resolve/main/text_encoders/ltx-2.3-22b-distilled_embeddings_connectors.safetensors`;
+const prompt = process.argv[7] || 'a claymation cat playing jazz on a piano';
+const outputDir = process.argv[8] || '.';
+try {
+    console.log('▸ Loading LTX-2 model (diffusion + Gemma + video VAE + audio VAE + connectors)...');
+    const modelId = await loadModel({
+        modelSrc: diffusionModelSrc,
+        modelType: 'sdcpp-generation',
+        modelConfig: {
+            mode: 'video',
+            device: 'gpu',
+            threads: 4,
+            // Supplying embeddingsConnectorsModelSrc selects the LTX-2 layout.
+            llmModelSrc,
+            vaeModelSrc,
+            audioVaeModelSrc,
+            embeddingsConnectorsModelSrc,
+            diffusion_fa: true,
+            vae_tiling: true
+        },
+        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(`\n▸ Generating video for: "${prompt}"`);
+    const { progressStream, outputs, stats } = video({
+        modelId,
+        mode: 'txt2vid',
+        prompt,
+        negative_prompt: 'blurry, low quality, static, jittery, watermark, distorted audio',
+        // LTX-2 requires width/height as multiples of 32.
+        width: 512,
+        height: 320,
+        // LTX-2 requires (8*k + 1) frames, max 257. At 24 fps: 25≈1s, 121≈5s, 241≈10s.
+        video_frames: 121,
+        fps: 24,
+        // Distilled variants run in 4-8 steps with cfg ~1.0; the full --dev model
+        // wants steps >= 20 and cfg ~7.0.
+        steps: 10,
+        cfg_scale: 1.0,
+        seed: 42,
+        // Tile the video VAE decode along the time axis to cap peak VRAM on long
+        // / HD clips (LTX-2 only).
+        temporal_tiling: true
+    });
+    for await (const { step, totalSteps } of progressStream) {
+        console.log(`▸ step ${step}/${totalSteps}`);
+    }
+    const buffers = await outputs;
+    for (let i = 0; i < buffers.length; i++) {
+        const outputPath = path.join(outputDir, `ltx_t2v_${i}.avi`);
+        fs.writeFileSync(outputPath, buffers[i]);
+        console.log(`▸ Saved ${outputPath} (play in VLC to hear the muxed audio track)`);
+    }
+    console.log('\n▸ Stats:', await stats);
+    await unloadModel({ modelId, clearStorage: false });
+    console.log('▸ Done.');
+    process.exit(0);
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/diffusion-txt2vid-wan22.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=diffusion-txt2vid-wan22.d.ts.map

package/dist/examples/diffusion-txt2vid-wan22.js

@@ -0,0 +1,96 @@
+import { loadModel, unloadModel, video, WAN2_2_TI2V_5B_Q5_K_S, UMT5_XXL_FP16, WAN_2_2_COMFYUI_REPACKAGED_VAE } from '@qvac/sdk';
+import fs from 'fs';
+import path from 'path';
+// Text-to-video with Wan 2.2 TI2V-5B Turbo (Q5_K_S). Like Wan 2.1 this is a
+// split layout — diffusion model + UMT5-XXL text encoder + VAE — but it needs
+// the Wan 2.2 VAE specifically: its 16x spatial compression is what gives
+// TI2V its 32-pixel grid, and the Wan 2.1 VAE is not interchangeable.
+//
+// TI2V-5B is a single-expert model. The high_noise_* / moe_boundary fields
+// belong to the two-expert Wan 2.2 A14B layout and are rejected here.
+//
+// Budget at least 16 GB of video memory or 20 GB of unified memory. The
+// artifacts total roughly 16.4 GB, dominated by the fp16 text encoder.
+//
+// The text encoder is byte-identical to the Wan 2.1 repackage, so both
+// generations share the one UMT5_XXL_FP16 registry entry.
+const diffusionModelSrc = process.argv[2] || WAN2_2_TI2V_5B_Q5_K_S;
+const t5XxlModelSrc = process.argv[3] || UMT5_XXL_FP16;
+const vaeModelSrc = process.argv[4] || WAN_2_2_COMFYUI_REPACKAGED_VAE;
+// Prompt tip: Turbo responds well to explicit camera and lighting direction.
+// Describe continuous motion rather than a pose, or the clip reads as a still.
+const prompt = process.argv[5] ||
+    'A single white porcelain espresso cup on a dark walnut table beside a sunlit window, ' +
+        'delicate steam curling upward, slow circular camera move, warm morning light, ' +
+        'sharp ceramic texture, realistic continuous motion';
+const outputDir = process.argv[6] || '.';
+try {
+    console.log('▸ Loading Wan 2.2 TI2V-5B Turbo model (diffusion + UMT5-XXL + Wan 2.2 VAE)...');
+    const modelId = await loadModel({
+        modelSrc: diffusionModelSrc,
+        modelType: 'sdcpp-generation',
+        modelConfig: {
+            mode: 'video',
+            device: 'gpu',
+            threads: 4,
+            t5XxlModelSrc,
+            vaeModelSrc,
+            diffusion_fa: true,
+            offload_to_cpu: true,
+            vae_tiling: true
+        },
+        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(`\n▸ Generating video for: "${prompt}"`);
+    const { progressStream, outputs, stats } = video({
+        modelId,
+        mode: 'txt2vid',
+        prompt,
+        negative_prompt: 'flickering, temporal jitter, morphing, duplicated subject, warped geometry, ' +
+            'distorted anatomy, blurry details, low resolution, text, watermark, logo',
+        // TI2V-5B requires width and height to be multiples of 32 — stricter than
+        // the multiple of 16 the schema enforces for Wan generally. Native
+        // validation derives this from the loaded GGUF, so a non-conforming size
+        // fails at generation time rather than at load.
+        // Turbo was trained on this 720p, 24 fps, five-second shape; 640x352 with
+        // 49 frames is a much cheaper way to smoke-test the pipeline.
+        width: 1280,
+        height: 704,
+        // Frame count must satisfy (4*k + 1), k >= 1. At 24 fps: 49 ≈ 2s,
+        // 121 ≈ 5s (the trained length).
+        video_frames: 121,
+        fps: 24,
+        // Turbo is distilled for very short schedules: 4 steps with guidance
+        // effectively disabled. The non-distilled TI2V-5B wants steps >= 30 and
+        // cfg ~5.0 instead.
+        steps: 4,
+        cfg_scale: 1.0,
+        flow_shift: 5.0,
+        seed: 42,
+        vae_tiling: true
+    });
+    for await (const { step, totalSteps } of progressStream) {
+        console.log(`▸ step ${step}/${totalSteps}`);
+    }
+    const buffers = await outputs;
+    for (let i = 0; i < buffers.length; i++) {
+        const outputPath = path.join(outputDir, `wan22_ti2v_t2v_${i}.avi`);
+        fs.writeFileSync(outputPath, buffers[i]);
+        console.log(`▸ Saved ${outputPath}`);
+    }
+    console.log('\n▸ Stats:', await stats);
+    await unloadModel({ modelId, clearStorage: false });
+    console.log('▸ Done.');
+    process.exit(0);
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/logging-streaming.js

@@ -46,7 +46,11 @@ try {
     const result = completion({
         modelId: llmModelId,
         history: messages,
-        stream: true
+        stream: true,
+        // Bound the generation: at temp 0.7 a 1B model can ignore "to 5" and ramble
+        // past ctx_size (2048) into a context overflow. This demo only needs enough
+        // tokens to show logs streaming.
+        generationParams: { predict: 512 }
     });
     const { embedding } = await embed({
         modelId: embedModelId,

package/dist/examples/quickstart.bare.js

@@ -3,7 +3,7 @@
 // then register the plugins this example uses via `plugins([...])`.
 import bareProcess from 'bare-process';
 import { plugins, LLAMA_3_2_1B_INST_Q4_0 } from '@qvac/sdk';
-import { llmPlugin } from '@qvac/sdk/llamacpp-completion/plugin.js';
+import { llmPlugin } from '@qvac/sdk/llamacpp-completion/plugin';
 globalThis.process = bareProcess;
 const { loadModel, completion, unloadModel } = plugins([llmPlugin]);
 // From here it is the same as the Node quickstart.

package/dist/examples/rag/rag-mongodb.d.ts

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

package/dist/examples/rag/rag-mongodb.js

@@ -0,0 +1,180 @@
+import { embed, loadModel, unloadModel, GTE_LARGE_FP16 } from '@qvac/sdk';
+import { MongoClient } from 'mongodb';
+const INDEX_NAME = 'documents_vector_index';
+const MONGODB_SETUP_INSTRUCTIONS = `
+▸ This example needs a MongoDB deployment with Atlas Vector Search.
+
+One way to get one is to run it in Docker:
+
+   docker run -p 27017:27017 --name atlas-local mongodb/mongodb-atlas-local
+
+For more details, visit: https://www.mongodb.com/docs/atlas/cli/current/atlas-cli-deploy-docker/
+`;
+async function initializeMongoClient() {
+    // Replace with your own deployment's connection string if it is not the Docker one
+    // https://www.mongodb.com/docs/manual/reference/connection-string/
+    const client = new MongoClient('mongodb://localhost:27017/?directConnection=true');
+    try {
+        await client.connect();
+        await client.db('admin').command({ ping: 1 });
+        console.log('▸ Connected to MongoDB server');
+        return client;
+    }
+    catch {
+        console.error('✖ Failed to connect to MongoDB server');
+        console.error('▸ Please ensure the server is running on localhost:27017');
+        console.error(MONGODB_SETUP_INSTRUCTIONS);
+        process.exit(1);
+    }
+}
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+try {
+    // Get query and category from command line or use defaults
+    const query = process.argv[2] || 'machine learning algorithms';
+    const category = process.argv[3] || 'ai';
+    console.log(`▸ Query: "${query}" (category: "${category}")`);
+    const client = await initializeMongoClient();
+    const collection = client.db('qvac').collection('documents');
+    const modelId = await loadModel({
+        modelSrc: GTE_LARGE_FP16,
+        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');
+        }
+    });
+    // Sample corpus, each document tagged with a category to filter on
+    const samples = [
+        {
+            id: 1,
+            category: 'ai',
+            text: 'Machine learning is a subset of artificial intelligence that focuses on algorithms that can learn and make predictions from data without being explicitly programmed for every task.'
+        },
+        {
+            id: 2,
+            category: 'ai',
+            text: 'Deep learning uses neural networks with multiple layers to process and learn from complex data patterns, enabling breakthroughs in image recognition and natural language processing.'
+        },
+        {
+            id: 3,
+            category: 'ai',
+            text: 'Natural language processing combines computational linguistics with machine learning to help computers understand, interpret, and generate human language in a meaningful way.'
+        },
+        {
+            id: 4,
+            category: 'ai',
+            text: 'Computer vision enables machines to interpret and understand visual information from the world, using techniques like image classification, object detection, and facial recognition.'
+        },
+        {
+            id: 5,
+            category: 'computing',
+            text: 'Quantum computing leverages quantum mechanical phenomena to process information in fundamentally different ways than classical computers, potentially solving certain problems exponentially faster.'
+        },
+        {
+            id: 6,
+            category: 'security',
+            text: 'Blockchain technology creates decentralized, immutable ledgers that enable secure peer-to-peer transactions without requiring a central authority or intermediary.'
+        },
+        {
+            id: 7,
+            category: 'computing',
+            text: 'Cloud computing delivers computing services over the internet, allowing users to access resources like storage, processing power, and applications on-demand from anywhere.'
+        },
+        {
+            id: 8,
+            category: 'security',
+            text: 'Cybersecurity protects digital systems, networks, and data from malicious attacks, unauthorized access, and various forms of cyber threats through multiple layers of defense.'
+        }
+    ];
+    // (Re)create the collection
+    try {
+        await collection.drop();
+    }
+    catch (e) {
+        console.warn(`▸ Collection didn't exist, no need to drop: ${String(e)}`);
+    }
+    // Embed and store documents
+    console.log('▸ Embedding documents...');
+    const documents = [];
+    for (const sample of samples) {
+        const { embedding } = await embed({ modelId, text: sample.text });
+        documents.push({
+            id: sample.id,
+            category: sample.category,
+            text: sample.text,
+            embedding
+        });
+    }
+    await collection.insertMany(documents);
+    // numDimensions is fixed at index creation and must match the model: GTE Large is 1024
+    console.log('▸ Creating vector search index...');
+    await collection.createSearchIndex({
+        name: INDEX_NAME,
+        type: 'vectorSearch',
+        definition: {
+            fields: [
+                {
+                    type: 'vector',
+                    path: 'embedding',
+                    numDimensions: 1024,
+                    similarity: 'cosine'
+                },
+                // A field must be indexed as a filter to be usable in a $vectorSearch filter
+                {
+                    type: 'filter',
+                    path: 'category'
+                }
+            ]
+        }
+    });
+    // Index builds are asynchronous; querying too early returns no matches
+    for (let attempt = 0; attempt < 60; attempt++) {
+        const [index] = (await collection.listSearchIndexes(INDEX_NAME).toArray());
+        if (index?.queryable)
+            break;
+        if (attempt === 59)
+            throw new Error(`Index ${INDEX_NAME} did not become queryable`);
+        await wait(1000);
+    }
+    console.log('▸ Searching for similar documents...');
+    const { embedding: queryEmbedding } = await embed({ modelId, text: query });
+    const results = await collection
+        .aggregate([
+        {
+            $vectorSearch: {
+                index: INDEX_NAME,
+                path: 'embedding',
+                queryVector: queryEmbedding,
+                filter: { category: { $eq: category } },
+                numCandidates: 100,
+                limit: 3
+            }
+        },
+        {
+            $project: {
+                _id: 0,
+                id: 1,
+                category: 1,
+                text: 1,
+                score: { $meta: 'vectorSearchScore' }
+            }
+        }
+    ])
+        .toArray();
+    console.log('▸ Top 3 most similar documents:');
+    results.forEach((result, index) => {
+        console.log(`${index + 1}. (Score: ${result.score.toFixed(4)}, Category: ${result.category})`);
+        console.log(`   ${result.text}`);
+        console.log();
+    });
+    await unloadModel({ modelId });
+    await client.close();
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/tools/llamacpp-tools-auto-dialect.d.ts

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

package/dist/examples/tools/llamacpp-tools-auto-dialect.js

@@ -0,0 +1,77 @@
+/**
+ * Tool-calling example with automatic dialect detection.
+ *
+ * The SDK infers the tool-call format from the model name/path. It supports
+ * model families such as Qwen3.5/3.6, Gemma4, GPT-OSS, DeepSeek V3.2/V4, and
+ * LFM without requiring a toolDialect override.
+ *
+ * Usage:
+ *   bun run bare:example dist/examples/tools/llamacpp-tools-auto-dialect.js <model-src>
+ */
+import { completion, loadModel, unloadModel } from '@qvac/sdk';
+import { tools, mockExecute } from './shared.js';
+const modelSrc = process.argv[2];
+if (!modelSrc) {
+    console.error('✖ Missing model source: pass a tool-capable GGUF path or URL');
+    process.exit(1);
+}
+let modelId;
+try {
+    modelId = await loadModel({
+        modelSrc,
+        modelType: 'llamacpp-completion',
+        modelConfig: { ctx_size: 4096, tools: true },
+        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}`);
+    const history = [
+        {
+            role: 'system',
+            content: 'You are a helpful assistant that can call tools to look up weather and horoscopes.'
+        },
+        {
+            role: 'user',
+            content: "What's the weather in Tokyo and my horoscope for Aquarius?"
+        }
+    ];
+    const result = completion({ modelId, history, stream: true, tools });
+    const tokensTask = (async () => {
+        for await (const token of result.tokenStream) {
+            process.stdout.write(token);
+        }
+    })();
+    const toolsTask = (async () => {
+        for await (const evt of result.toolCallStream) {
+            if (evt.type === 'toolCall') {
+                console.log(`\n▸ ${evt.call.name}(${JSON.stringify(evt.call.arguments)})`);
+            }
+        }
+    })();
+    await Promise.all([tokensTask, toolsTask]);
+    const toolCalls = await result.toolCalls;
+    console.log('\n\n▸ Final tool calls:');
+    if (toolCalls.length > 0) {
+        for (const call of toolCalls) {
+            console.log(`▸ ${call.name}(${JSON.stringify(call.arguments)})`);
+            const toolResult = mockExecute(call.name, call.arguments);
+            console.log(`▸ result: ${toolResult}`);
+        }
+    }
+    else {
+        console.log('▸ (none)');
+    }
+    await unloadModel({ modelId, clearStorage: false });
+    process.exit(0);
+}
+catch (error) {
+    console.error('✖', error);
+    if (modelId)
+        await unloadModel({ modelId, clearStorage: false }).catch(() => { });
+    process.exit(1);
+}

package/dist/examples/tts/parler.d.ts

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

package/dist/examples/tts/parler.js

@@ -0,0 +1,51 @@
+import { loadModel, textToSpeech, unloadModel, TTS_MINI_V1_EN_PARLER_TTS_Q8_0 } from '@qvac/sdk';
+import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
+// Parler-TTS (GGML): description-conditioned speech with per-call voice controls.
+// Uses the registry-hosted Mini v1 Q8_0 model and its native 44.1 kHz output.
+const PARLER_SAMPLE_RATE = 44100;
+try {
+    const modelId = await loadModel({
+        modelSrc: TTS_MINI_V1_EN_PARLER_TTS_Q8_0,
+        modelConfig: {
+            ttsEngine: 'parler',
+            voice: 'Laura',
+            seed: 42
+        },
+        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 Parler Text-to-Speech...');
+    const result = textToSpeech({
+        modelId,
+        text: 'Hey, how are you doing today?',
+        inputType: 'text',
+        stream: false,
+        emotion: 'happy'
+    });
+    const audioBuffer = await result.buffer;
+    console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
+    console.log('▸ Saving audio to file...');
+    createWav(audioBuffer, PARLER_SAMPLE_RATE, 'parler-output.wav');
+    console.log('▸ Audio saved to parler-output.wav');
+    console.log('▸ Playing audio...');
+    const audioData = int16ArrayToBuffer(audioBuffer);
+    const wavBuffer = Buffer.concat([
+        createWavHeader(audioData.length, PARLER_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/vla-groot.d.ts

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

package/dist/examples/vla-groot.js

@@ -0,0 +1,120 @@
+/**
+ * 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 patchifies each camera frame the way `Gr00tPolicy` does
+ *     (the model's learned patch-embed runs inside the addon); 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 patchifies each camera frame the
+    // way `Gr00tPolicy` does (the model's learned patch-embed runs inside the
+    // addon); 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);
+}

package/dist/examples/voice-assistant/voice-assistant.js

@@ -12,8 +12,8 @@
  */
 import { loadModel, unloadModel, transcribeStream, completion, textToSpeech, WHISPER_TINY, VAD_SILERO_5_1_2, LLAMA_3_2_1B_INST_Q4_0, TTS_EN_SUPERTONIC_Q8_0 } from '@qvac/sdk';
 import { spawnSync } from 'child_process';
-import { startMicrophone } from '../audio/mic-input';
-import { createWavHeader, int16ArrayToBuffer, playAudio } from '../tts/utils';
+import { startMicrophone } from '../audio/mic-input.js';
+import { createWavHeader, int16ArrayToBuffer, playAudio } from '../tts/utils.js';
 const MIC_SAMPLE_RATE = 16000;
 const TTS_SAMPLE_RATE = 44100;
 const SYSTEM_PROMPT = 'You are a concise, friendly voice assistant. Keep responses under two sentences. ' +