@qvac/sdk 0.16.0 → 0.17.1

package/dist/examples/{transcription → asr}/whispercpp-filesystem-streaming.js

@@ -2,7 +2,7 @@
  * Test script: pipes a WAV file through transcribeStream to verify
  * the bidirectional streaming + addon processing works end-to-end.
  *
- * Usage: bun run examples/transcription/whispercpp-filesystem-streaming.ts
+ * Usage: bun run examples/asr/whispercpp-filesystem-streaming.ts
  *
  * Uses FFmpeg to convert the WAV to raw f32le and streams chunks
  * through the duplex RPC session to the whisper addon.

package/dist/examples/{transcription → asr}/whispercpp-filesystem.js

@@ -2,7 +2,7 @@ import { loadModel, unloadModel, transcribe, WHISPER_TINY } from '@qvac/sdk';
 // Parse command line arguments
 const args = process.argv.slice(2);
 if (!args[0]) {
-    console.error('Usage: bun run examples/whispercpp-filesystem.ts <wav-file-path>');
+    console.error('Usage: bun run examples/asr/whispercpp-filesystem.ts <wav-file-path>');
     process.exit(1);
 }
 const audioFilePath = args[0];

package/dist/examples/{transcription → asr}/whispercpp-microphone-conversation.js

@@ -18,7 +18,7 @@
  */
 import { loadModel, unloadModel, transcribeStream, WHISPER_TINY, VAD_SILERO_5_1_2 } from '@qvac/sdk';
 import { spawnSync } from 'child_process';
-import { startMicrophone } from '../audio/mic-input';
+import { startMicrophone } from '../audio/mic-input.js';
 const SAMPLE_RATE = 16000;
 try {
     const r = spawnSync('ffmpeg', ['-version'], { stdio: 'ignore' });

package/dist/examples/{transcription → asr}/whispercpp-microphone-record.js

@@ -1,7 +1,7 @@
 /**
  * Microphone → Whisper streaming transcription with native VAD.
  *
- * Usage: bun run examples/transcription/whispercpp-microphone-record.ts
+ * Usage: bun run examples/asr/whispercpp-microphone-record.ts
  *
  * Speak into your mic; transcriptions appear automatically when you pause.
  * Press Ctrl+C to quit.
@@ -10,7 +10,7 @@
  */
 import { loadModel, unloadModel, transcribeStream, WHISPER_TINY, VAD_SILERO_5_1_2 } from '@qvac/sdk';
 import { spawnSync } from 'child_process';
-import { startMicrophone } from '../audio/mic-input';
+import { startMicrophone } from '../audio/mic-input.js';
 const SAMPLE_RATE = 16000;
 // ── Main ──
 try {

package/dist/examples/{transcription → asr}/whispercpp-prompt.js

@@ -2,7 +2,7 @@
  * Whisper transcription with prompt example.
  *
  * Usage:
- *   bun examples/transcription/whispercpp-prompt.ts
+ *   bun examples/asr/whispercpp-prompt.ts
  *
  * This example requires a test audio file (default: examples/audio/sample-16khz.wav).
  * Sample audio files are available in the QVAC source repository, but not included in the published npm package.

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

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

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

@@ -0,0 +1,112 @@
+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';
+// Usage:
+//   bun examples/audiogen/generate-music.ts "lo-fi hip hop, mellow piano" output.wav
+const caption = process.argv[2] ?? 'Lo-fi hip hop with mellow piano, soft drums, and a warm bass line';
+const outputPath = process.argv[3] ?? 'audiogen-output.wav';
+let modelId;
+const lastLoggedPercentageByDownload = new Map();
+const completedDownloads = new Set();
+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,
+            inferenceSteps: 8
+        },
+        onProgress: (progress) => {
+            const mb = (bytes) => (bytes / 1e6).toFixed(1);
+            const label = getDownloadLabel(progress.downloadKey);
+            const line = `▸ Downloading ${label}: ${progress.percentage.toFixed(0)}% ` +
+                `(${mb(progress.downloaded)}/${mb(progress.total)} MB)`;
+            if (process.stderr.isTTY) {
+                process.stderr.write(`\r${line}`);
+                if (progress.percentage >= 100 && !completedDownloads.has(progress.downloadKey)) {
+                    completedDownloads.add(progress.downloadKey);
+                    process.stderr.write('\n');
+                }
+                return;
+            }
+            const percentageBucket = Math.floor(progress.percentage / 5) * 5;
+            const lastLogged = lastLoggedPercentageByDownload.get(progress.downloadKey);
+            const isNewCompletion = progress.percentage >= 100 && lastLogged !== 100;
+            if (lastLogged === undefined || percentageBucket > lastLogged || isNewCompletion) {
+                lastLoggedPercentageByDownload.set(progress.downloadKey, percentageBucket);
+                process.stderr.write(`${line}\n`);
+            }
+        }
+    });
+    console.log(`▸ Model loaded: ${modelId}`);
+    console.log(`▸ Generating: ${caption}`);
+    const run = audioGen({
+        modelId,
+        caption,
+        lyrics: '[Instrumental]',
+        seed: 42,
+        duration: 10
+    });
+    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]);
+    const wav = createWav(audio.pcm, audio.sampleRate, audio.channels, audio.bitsPerSample);
+    writeFileSync(outputPath, wav);
+    const samplesPerChannel = audio.pcm.byteLength / (audio.bitsPerSample / 8) / audio.channels;
+    console.log(`▸ Generated ${samplesPerChannel} samples per channel at ` +
+        `${audio.sampleRate} Hz (${audio.channels} channels)`);
+    if (stats)
+        console.log(`▸ Stats: ${JSON.stringify(stats)}`);
+    console.log(`▸ Saved ${outputPath}`);
+    await unloadModel({ modelId });
+    modelId = undefined;
+    console.log('▸ Model unloaded');
+    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 getDownloadLabel(downloadKey) {
+    return downloadKey.split('/').pop() ?? downloadKey;
+}
+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/cache-management.js

@@ -1,5 +1,5 @@
 import { WHISPER_TINY } from '../models/registry/index.js';
-import { downloadAsset, getModelInfo, loadModel, unloadModel } from '..';
+import { downloadAsset, getModelInfo, loadModel, unloadModel } from '../index.js';
 const printModelStatus = (info, label) => {
     console.log(`\n▸ ${label}`);
     console.log(`▸ Model Name: ${info.name}`);

package/dist/examples/config-reload.js

@@ -1,4 +1,4 @@
-import { WHISPER_TINY, loadModel, transcribe, unloadModel } from '../index';
+import { WHISPER_TINY, loadModel, transcribe, unloadModel } from '../index.js';
 // Parse command line arguments
 const args = process.argv.slice(2);
 if (!args[0]) {

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/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.js

@@ -8,8 +8,9 @@
  * `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.
+ *     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
@@ -66,8 +67,9 @@ try {
     }
     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.
+    // `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);

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. ' +