@qvac/sdk 0.19.0 → 0.20.0

package/dist/examples/kv-cache-cleanup.js

@@ -69,13 +69,16 @@ try {
     console.log('\n▸ 2. Delete specific model within cache key:');
     console.log('▸    await deleteCache({ kvCacheKey: "my-session", modelId: "model-abc" })');
     console.log('▸    └─ Removes: my-session/model-abc/ (specific model directory)');
-    console.log('\n▸ 3. Delete ALL caches (entire cache folder):');
+    console.log('\n▸ 3. Reclaim automatic caches only (named keys survive):');
+    console.log('▸    await deleteCache({ auto: true })');
+    console.log('▸    └─ Removes: every kvCache:true cache no request is using');
+    console.log('\n▸ 4. Delete ALL caches (entire cache folder):');
     console.log('▸    await deleteCache({ all: true })');
     console.log('▸    └─ Removes: ALL cache files from all sessions and models');
     console.log('\n▸ Use Cases:');
     console.log("▸    - User logout → Delete user's cache key");
     console.log('▸    - Model updated → Delete old model caches');
-    console.log('▸    - Disk space cleanup → Delete old cache keys or all caches');
+    console.log('▸    - Disk space cleanup → Reclaim with { auto: true }');
     console.log('▸    - Privacy → Clear conversation history');
     console.log('▸    - App reset → Delete all caches with { all: true }');
     await unloadModel({ modelId, clearStorage: false });

package/dist/examples/model-fit-ui/server.js

@@ -21,17 +21,20 @@
  *   node dist/examples/model-fit-ui/server.js
  */
 import { createServer } from 'node:http';
-import { readFileSync } from 'node:fs';
-import { assessModelFit, getSystemResources, loadModel, unloadModel, completion, close, QWEN3_600M_INST_Q4, QWEN3_1_7B_INST_Q4, QWEN3_4B_INST_Q4_K_M, QWEN3_8B_INST_Q4_K_M, QWEN3_8_27B_MULTIMODAL_UD_Q8_K_XL } from '@qvac/sdk';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { assessModelFit, getSystemResources, loadModel, unloadModel, completion, close, QWEN3_600M_INST_Q4, QWEN3_1_7B_INST_Q4, QWEN3_4B_INST_Q4_K_M, QWEN3_8B_INST_Q4_K_M, GEMMA4_31B_MULTIMODAL_Q4_K_M } from '@qvac/sdk';
 const PORT = 8712;
-// A ladder ending well past what a laptop has, so one screen shows every
-// verdict. The 27B at Q8 is here to be refused.
+// A ladder ending past what a laptop has, so one screen shows every verdict.
+// The 31B is here to be refused: 18 GiB against a 24 GiB machine leaves the OS
+// no way to satisfy it without paging.
 const CATALOG = [
     QWEN3_600M_INST_Q4,
     QWEN3_1_7B_INST_Q4,
     QWEN3_4B_INST_Q4_K_M,
     QWEN3_8B_INST_Q4_K_M,
-    QWEN3_8_27B_MULTIMODAL_UD_Q8_K_XL
+    GEMMA4_31B_MULTIMODAL_Q4_K_M
 ];
 const PAGE_PATH = new URL('index.html', import.meta.url);
 // Read per request, not once at startup: editing the page and reloading is the
@@ -43,6 +46,18 @@ function page() {
 // `onProgress` is passed, and without it a 29 GiB download, a stall and a dead
 // worker all look identical from the browser: "loading…" forever.
 const progress = new Map();
+// Whether the weights are already on disk, so a Run costs no download. The
+// cache layout is not API, so this matches on file size — enough to label a
+// button, and it errs towards promising a download that may not happen.
+function cachedSizes() {
+    try {
+        const dir = join(homedir(), '.qvac', 'models');
+        return new Set(readdirSync(dir).map((file) => statSync(join(dir, file)).size));
+    }
+    catch {
+        return new Set();
+    }
+}
 function byName(name) {
     const model = CATALOG.find((entry) => entry.name === name);
     if (!model)
@@ -131,7 +146,13 @@ async function run(body) {
             systemUsedBeforeBytes: before,
             systemUsedAfterLoadBytes: afterLoad,
             backendDevice: final.stats?.backendDevice,
-            sample: final.contentText.trim().slice(0, 120)
+            // The engine's own numbers for the run: tokens/s, time to first token,
+            // token counts. Worth showing next to the memory figures.
+            stats: final.stats,
+            // `cacheableAssistantContent` is the same text with <think> blocks
+            // stripped; a reasoning model otherwise leads with its scratchpad.
+            sample: (final.cacheableAssistantContent ?? final.contentText).trim().slice(0, 160) ||
+                '(no plain text — the model returned reasoning only)'
         };
     }
     catch (error) {
@@ -164,7 +185,12 @@ const server = createServer((request, response) => {
         return;
     }
     if (request.method === 'GET' && url === '/api/models') {
-        sendJson(response, 200, CATALOG.map((model) => ({ name: model.name, expectedSize: model.expectedSize })));
+        const sizes = cachedSizes();
+        sendJson(response, 200, CATALOG.map((model) => ({
+            name: model.name,
+            expectedSize: model.expectedSize,
+            cached: sizes.has(model.expectedSize)
+        })));
         return;
     }
     if (request.method === 'POST' && (url === '/api/assess' || url === '/api/run')) {

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

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

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

@@ -0,0 +1,58 @@
+import { createVectorIndex, embed, loadModel, loadVectorIndex, unloadModel, GTE_LARGE_FP16, VectorIndexStorage } from '@qvac/sdk';
+// Retrieval over documents kept in your own store. The SDK holds only the
+// vectors, in a TurboVec index inside the worker; the documents stay in this
+// Map (or any database you choose) and result ids map back to them.
+try {
+    const query = process.argv[2] || 'Which moon has methane rain and lakes?';
+    console.log(`▸ Query: "${query}"`);
+    const documents = new Map([
+        ['1', 'Saturn moon Titan has lakes, clouds, and rain made of liquid methane.'],
+        ['2', 'Solar panels convert sunlight into electricity using photovoltaic cells.'],
+        ['3', 'Honeybees communicate the location of flowers through a waggle dance.'],
+        ['4', 'The Pacific Ocean is the largest and deepest ocean on Earth.']
+    ]);
+    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');
+        }
+    });
+    console.log('▸ Embedding documents...');
+    const { embedding: vectors } = await embed({ modelId, text: [...documents.values()] });
+    console.log('▸ Building the vector index...');
+    const index = await createVectorIndex({
+        dim: vectors[0].length,
+        storage: VectorIndexStorage.TURBOVEC_Q4
+    });
+    await index.add({ ids: [...documents.keys()], vectors });
+    console.log(`▸ Indexed ${index.length} vectors of dimension ${index.dim}`);
+    console.log('▸ Searching...');
+    const { embedding: queryVector } = await embed({ modelId, text: query });
+    const hits = await index.search({ query: queryVector, k: 2 });
+    console.log('▸ Top matches:');
+    for (const hit of hits) {
+        console.log(`  score=${hit.score.toFixed(4)} id=${hit.id}: ${documents.get(hit.id)}`);
+    }
+    // Snapshots persist the vectors only. A relative path resolves under the
+    // QVAC data directory; pass an absolute path to store it elsewhere.
+    const snapshotPath = 'examples/rag-turbovec.qvi';
+    const { path: writtenPath } = await index.write({ path: snapshotPath });
+    await index.dispose();
+    console.log(`▸ Snapshot written to ${writtenPath}`);
+    const reloaded = await loadVectorIndex({ path: snapshotPath });
+    const [reloadedBest] = await reloaded.search({ query: queryVector, k: 1 });
+    await reloaded.dispose();
+    if (!reloadedBest || reloadedBest.id !== hits[0]?.id) {
+        throw new Error(`Reloaded index returned id=${reloadedBest?.id} but the original returned id=${hits[0]?.id}`);
+    }
+    console.log(`▸ Reloaded index agrees: best match id=${reloadedBest.id}`);
+    await unloadModel({ modelId });
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/tts/audio8.js

@@ -4,6 +4,8 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // primary modelSrc is the LM GGUF; the codec decoder loads via modelConfig.
 // For zero-shot voice cloning also pass audio8CodecEncoderModelSrc plus
 // referenceAudioSrc/referenceText (a recording and its exact transcript).
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const AUDIO8_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
@@ -32,16 +34,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? AUDIO8_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, AUDIO8_SAMPLE_RATE, 'audio8-output.wav');
+    createWav(audioBuffer, sampleRate, 'audio8-output.wav');
     console.log('▸ Audio saved to audio8-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, AUDIO8_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

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

@@ -5,6 +5,7 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // enhancement — there is no on/off flag — and it forces the output to 48 kHz.
 // Usage: node chatterbox-enhanced.ts [referenceAudioSrc]
 const [referenceAudioSrc] = process.argv.slice(2);
+// Only a fallback; the engine reports the rate it actually produced.
 const ENHANCED_SAMPLE_RATE = 48000;
 try {
     const modelId = await loadModel({
@@ -33,16 +34,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? ENHANCED_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, ENHANCED_SAMPLE_RATE, 'chatterbox-enhanced-output.wav');
+    createWav(audioBuffer, sampleRate, 'chatterbox-enhanced-output.wav');
     console.log('▸ Audio saved to chatterbox-enhanced-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, ENHANCED_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

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

@@ -2,6 +2,8 @@ import { loadModel, textToSpeech, unloadModel, TTS_T3_MULTILINGUAL_CHATTERBOX_Q4
 import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
 // Chatterbox multilingual TTS (GGML): Japanese synthesis with MeCab/IPAdic.
 // Uses registry model constants — downloads automatically from QVAC Registry.
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const CHATTERBOX_SAMPLE_RATE = 24000;
 const OUTPUT_FILE = 'chatterbox-multilingual-output.wav';
 try {
@@ -32,16 +34,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? CHATTERBOX_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, CHATTERBOX_SAMPLE_RATE, OUTPUT_FILE);
+    createWav(audioBuffer, sampleRate, OUTPUT_FILE);
     console.log(`▸ Audio saved to ${OUTPUT_FILE}`);
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, CHATTERBOX_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

package/dist/examples/tts/chatterbox.js

@@ -4,6 +4,8 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // Uses registry model constants — downloads automatically from QVAC Registry.
 // Usage: node chatterbox.ts [referenceAudioSrc]
 const [referenceAudioSrc] = process.argv.slice(2);
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const CHATTERBOX_SAMPLE_RATE = 24000;
 try {
     const modelId = await loadModel({
@@ -35,16 +37,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? CHATTERBOX_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total bytes: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, CHATTERBOX_SAMPLE_RATE, 'tts-output.wav');
+    createWav(audioBuffer, sampleRate, '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
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

package/dist/examples/tts/cosyvoice3.js

@@ -4,6 +4,8 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // synthesis (emotion, pace, or instruct). The LLM GGUF's registry companion
 // set downloads the flow/HiFT models, baked voice and tokenizer alongside it.
 // Native output is 24 kHz.
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const COSYVOICE3_SAMPLE_RATE = 24000;
 try {
     const modelId = await loadModel({
@@ -30,16 +32,14 @@ try {
         emotion: 'happy'
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? COSYVOICE3_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, COSYVOICE3_SAMPLE_RATE, 'cosyvoice3-output.wav');
+    createWav(audioBuffer, sampleRate, 'cosyvoice3-output.wav');
     console.log('▸ Audio saved to cosyvoice3-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, COSYVOICE3_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

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

@@ -14,6 +14,9 @@
  */
 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';
+// Only a fallback, for the case where no frame ever reports a rate: each
+// audio frame carries the rate the engine actually produced, and
+// `outputSampleRate` can move it off this default.
 const SUPERTONIC_SAMPLE_RATE = 44100;
 /**
  * Drop angle-bracket spans (e.g. `<think>…</think>`, `<|foo|>`) even when split across tokens,
@@ -107,16 +110,23 @@ try {
     });
     let phraseIndex = 0;
     const filterChunk = createAngleBracketAndStarFilter();
+    // Playback and the WAV header both follow what the engine reports rather
+    // than the engine's documented default, so a configured `outputSampleRate`
+    // cannot leave the audio playing back at the wrong speed.
+    let sampleRate = SUPERTONIC_SAMPLE_RATE;
     const drainPcm = (async () => {
         for await (const m of ttsSession) {
             if (m.buffer.length > 0) {
+                if (m.sampleRate !== undefined) {
+                    sampleRate = m.sampleRate;
+                }
                 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 ? '...' : ''}"` : ''}`);
-                await playPcmInt16Chunk(m.buffer, SUPERTONIC_SAMPLE_RATE);
+                await playPcmInt16Chunk(m.buffer, sampleRate);
             }
         }
     })();
@@ -135,7 +145,7 @@ try {
     }
     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);
+    createWav(combinedPcm, sampleRate, outWav);
     await unloadModel({ modelId: llmModelId, clearStorage: false });
     await unloadModel({ modelId: ttsModelId, clearStorage: false });
     console.log('▸ Models unloaded.');

package/dist/examples/tts/parler.js

@@ -2,6 +2,8 @@ import { loadModel, textToSpeech, unloadModel, TTS_MINI_V1_EN_PARLER_TTS_Q8_0 }
 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.
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const PARLER_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
@@ -29,16 +31,14 @@ try {
         emotion: 'happy'
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? PARLER_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, PARLER_SAMPLE_RATE, 'parler-output.wav');
+    createWav(audioBuffer, sampleRate, '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
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

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

@@ -5,6 +5,7 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // 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.
+// Only a fallback; the engine reports the rate it actually produced.
 const ENHANCED_SAMPLE_RATE = 48000;
 try {
     const modelId = await loadModel({
@@ -35,16 +36,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? ENHANCED_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, ENHANCED_SAMPLE_RATE, 'supertonic-enhanced-output.wav');
+    createWav(audioBuffer, sampleRate, '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
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

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

@@ -1,6 +1,8 @@
 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.
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const SUPERTONIC_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
@@ -29,16 +31,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? SUPERTONIC_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, SUPERTONIC_SAMPLE_RATE, 'supertonic-multilingual-output.wav');
+    createWav(audioBuffer, sampleRate, '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
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

package/dist/examples/tts/supertonic.js

@@ -2,6 +2,8 @@ import { loadModel, textToSpeech, unloadModel, TTS_MULTILINGUAL_SUPERTONIC3_Q8_0
 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.
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const SUPERTONIC_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
@@ -30,16 +32,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? SUPERTONIC_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, SUPERTONIC_SAMPLE_RATE, 'supertonic-output.wav');
+    createWav(audioBuffer, sampleRate, '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
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

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

@@ -20,7 +20,7 @@ export declare function buildContract(): {
                 condition: string;
                 responseSchema: string;
             };
-            name: "audioGenStream" | "heartbeat" | "loadModel" | "downloadAsset" | "completionStream" | "completionOrchestrate" | "batchCompletionStream" | "unloadModel" | "transcribe" | "transcribeStream" | "bciTranscribe" | "bciTranscribeStream" | "loggingStream" | "embed" | "translate" | "textToSpeech" | "textToSpeechStream" | "cancel" | "finetune" | "rag" | "deleteCache" | "getModelInfo" | "getLoadedModelInfo" | "getSystemResources" | "assessModelFit" | "ocrStream" | "diffusionStream" | "videoStream" | "upscaleStream" | "worldSceneStream" | "worldStepStream" | "resume" | "pluginInvoke" | "pluginInvokeStream" | "modelRegistryList" | "modelRegistrySearch" | "modelRegistryGetModel" | "suspend" | "state" | "classify";
+            name: "audioGenStream" | "audioEditStream" | "audioUnderstand" | "heartbeat" | "loadModel" | "downloadAsset" | "completionStream" | "completionOrchestrate" | "batchCompletionStream" | "unloadModel" | "transcribe" | "transcribeStream" | "bciTranscribe" | "bciTranscribeStream" | "loggingStream" | "embed" | "translate" | "textToSpeech" | "textToSpeechStream" | "cancel" | "finetune" | "rag" | "vectorIndex" | "deleteCache" | "getModelInfo" | "getLoadedModelInfo" | "getSystemResources" | "assessModelFit" | "ocrStream" | "diffusionStream" | "videoStream" | "upscaleStream" | "worldSceneStream" | "worldStepStream" | "resume" | "pluginInvoke" | "pluginInvokeStream" | "modelRegistryList" | "modelRegistrySearch" | "modelRegistryGetModel" | "suspend" | "state" | "classify";
             callShape: "duplex" | "request-reply" | "server-stream";
             requestSchema: string;
             responseSchema: string;

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

@@ -61,9 +61,24 @@ export declare const constantsRegistry: {
     readonly SupportedAudioFormat: z.ZodEnum<{
         [k: string]: string;
     }>;
+    readonly TtsEngine: z.ZodEnum<{
+        [k: string]: string;
+    }>;
     readonly TtsPace: z.ZodEnum<{
         [k: string]: string;
     }>;
+    readonly TtsParlerEmotion: z.ZodEnum<{
+        [k: string]: "command" | "anger" | "narration" | "conversation" | "disgust" | "fear" | "happy" | "neutral" | "proper noun" | "news" | "sad" | "surprise";
+    }>;
+    readonly TtsSentenceDelimiterPreset: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsChatterboxLanguage: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly TtsSupertonicLanguage: z.ZodEnum<{
+        [k: string]: string;
+    }>;
     readonly TtsCosyvoice3Emotion: z.ZodEnum<{
         [k: string]: string;
     }>;
@@ -82,5 +97,21 @@ export declare const constantsRegistry: {
     readonly AudioGenTaskType: z.ZodEnum<{
         [k: string]: string;
     }>;
+    readonly AudioGenEditOperation: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly AudioGenRepaintMode: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly AudioGenTrack: z.ZodEnum<{
+        [k: string]: string;
+    }>;
+    readonly VectorIndexStorage: z.ZodEnum<{
+        readonly F32: "f32";
+        readonly Q8: "q8";
+        readonly Q4: "q4";
+        readonly TURBOVEC_Q4: "turbovec-q4";
+        readonly TURBOVEC_Q2: "turbovec-q2";
+    }>;
 };
 //# sourceMappingURL=constants-registry.d.ts.map

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ModelType, VERBOSITY, SUPPORTED_AUDIO_FORMATS, AUDIOGEN_ENGINES, AUDIOGEN_TASK_TYPES, TTS_PACES, TTS_COSYVOICE3_EMOTIONS, TTS_COSYVOICE3_INSTRUCT_DIALECTS, TTS_COSYVOICE3_INSTRUCT_VOLUMES, TTS_COSYVOICE3_INSTRUCT_STYLES } from '@qvac/inference/surface';
+import { ModelType, VERBOSITY, SUPPORTED_AUDIO_FORMATS, AUDIOGEN_ENGINES, AUDIOGEN_TASK_TYPES, AUDIOGEN_EDIT_OPERATIONS, AUDIOGEN_REPAINT_MODES, AUDIOGEN_TRACKS, TTS_ENGINES, TTS_PACES, TTS_PARLER_EMOTIONS, TTS_SENTENCE_DELIMITER_PRESETS, TTS_CHATTERBOX_LANGUAGES, TTS_SUPERTONIC_LANGUAGES, TTS_COSYVOICE3_EMOTIONS, TTS_COSYVOICE3_INSTRUCT_DIALECTS, TTS_COSYVOICE3_INSTRUCT_VOLUMES, TTS_COSYVOICE3_INSTRUCT_STYLES, VectorIndexStorage } from '@qvac/inference/surface';
 import { PLUGIN_LLM, PLUGIN_EMBEDDING, PLUGIN_WHISPER, PLUGIN_BCI, PLUGIN_NMT, PLUGIN_TTS, PLUGIN_OCR, PLUGIN_DIFFUSION, PLUGIN_AUDIOGEN, PLUGIN_VLA, PLUGIN_CLASSIFICATION } from '../../src/plugin-ids.js';
 // Uppercases each vocabulary value into an identifier-safe varname (e.g.
 // 'slow' -> 'SLOW', 'cover-nofsq' -> 'COVER_NOFSQ'), mirroring the
@@ -52,11 +52,22 @@ export const constantsRegistry = {
     // than a hand-written record, so the varnames can't drift from the one
     // source of truth every other consumer of SUPPORTED_AUDIO_FORMATS shares.
     SupportedAudioFormat: z.enum(Object.fromEntries(SUPPORTED_AUDIO_FORMATS.map((ext) => [ext.slice(1).toUpperCase(), ext]))),
+    TtsEngine: enumFromVocabulary(TTS_ENGINES),
     TtsPace: enumFromVocabulary(TTS_PACES),
+    // 'proper noun' carries a space; enumFromVocabulary only rewrites '-', so
+    // map it explicitly to keep the varname identifier-safe.
+    TtsParlerEmotion: z.enum(Object.fromEntries(TTS_PARLER_EMOTIONS.map((value) => [value.toUpperCase().replace(/[\s-]/g, '_'), value]))),
+    TtsSentenceDelimiterPreset: enumFromVocabulary(TTS_SENTENCE_DELIMITER_PRESETS),
+    TtsChatterboxLanguage: enumFromVocabulary(TTS_CHATTERBOX_LANGUAGES),
+    TtsSupertonicLanguage: enumFromVocabulary(TTS_SUPERTONIC_LANGUAGES),
     TtsCosyvoice3Emotion: enumFromVocabulary(TTS_COSYVOICE3_EMOTIONS),
     TtsCosyvoice3InstructDialect: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_DIALECTS),
     TtsCosyvoice3InstructVolume: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_VOLUMES),
     TtsCosyvoice3InstructStyle: enumFromVocabulary(TTS_COSYVOICE3_INSTRUCT_STYLES),
     AudioGenEngine: enumFromVocabulary(AUDIOGEN_ENGINES),
-    AudioGenTaskType: enumFromVocabulary(AUDIOGEN_TASK_TYPES)
+    AudioGenTaskType: enumFromVocabulary(AUDIOGEN_TASK_TYPES),
+    AudioGenEditOperation: enumFromVocabulary(AUDIOGEN_EDIT_OPERATIONS),
+    AudioGenRepaintMode: enumFromVocabulary(AUDIOGEN_REPAINT_MODES),
+    AudioGenTrack: enumFromVocabulary(AUDIOGEN_TRACKS),
+    VectorIndexStorage: z.enum(VectorIndexStorage)
 };

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

@@ -8,7 +8,9 @@
  */
 export declare const methodShapes: {
     readonly assessModelFit: "reply";
+    readonly audioEditStream: "stream";
     readonly audioGenStream: "stream";
+    readonly audioUnderstand: "stream";
     readonly batchCompletionStream: "stream";
     readonly bciTranscribe: "stream";
     readonly bciTranscribeStream: "duplex";
@@ -44,6 +46,7 @@ export declare const methodShapes: {
     readonly translate: "stream";
     readonly unloadModel: "reply";
     readonly upscaleStream: "stream";
+    readonly vectorIndex: "reply";
     readonly videoStream: "stream";
     readonly worldSceneStream: "stream";
     readonly worldStepStream: "stream";

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

@@ -8,7 +8,9 @@
  */
 export const methodShapes = {
     assessModelFit: 'reply',
+    audioEditStream: 'stream',
     audioGenStream: 'stream',
+    audioUnderstand: 'stream',
     batchCompletionStream: 'stream',
     bciTranscribe: 'stream',
     bciTranscribeStream: 'duplex',
@@ -44,6 +46,7 @@ export const methodShapes = {
     translate: 'stream',
     unloadModel: 'reply',
     upscaleStream: 'stream',
+    vectorIndex: 'reply',
     videoStream: 'stream',
     worldSceneStream: 'stream',
     worldStepStream: 'stream'

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

@@ -29,8 +29,10 @@ export async function assessModelFit(input) {
         verdict: response.verdict,
         basis: response.basis,
         execution: response.execution,
+        ...(response.evidence && { evidence: response.evidence }),
         ...(response.budget && { budget: response.budget }),
         ...(response.estimate && { estimate: response.estimate }),
+        ...(response.floorBytes !== undefined && { floorBytes: response.floorBytes }),
         models: response.models,
         reasons: response.reasons,
         assumptions: response.assumptions

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

@@ -0,0 +1,36 @@
+import type { AudioEditClientParams, AudioGenResult } from '@qvac/inference/surface';
+/**
+ * Edits a source recording with a loaded ACE-Step AudioGen model: an ordered
+ * pipeline of `flow-edit` and `repaint` operations, executed in array order.
+ *
+ * @param params - Loaded model ID, the source audio, the ordered `operations`, and an optional `seed`.
+ * @param params.sourceAudio - The recording to edit: a file path (decoded server-side) or raw
+ *   interleaved stereo 48 kHz Float32 LE PCM bytes in `[-1, 1]`.
+ * @param params.operations - `flow-edit` re-conditions the whole clip from a `from` prompt to a
+ *   `to` prompt over an optional `nMin`/`nMax` diffusion window (turbo DiT variants only);
+ *   `repaint` regenerates the `start`..`end` range (seconds) against a new `caption`, keeping the
+ *   rest of the clip. Operations may repeat or mix.
+ * @param params.seed - Seeds the first operation; each following operation uses `seed + index`.
+ * @returns The same run shape as `audioGen()`: a synchronous request ID, generation progress stream, PCM audio promise, stats promise, and diagnostics promise.
+ *
+ * @example
+ * ```typescript
+ * const run = audioEdit({
+ *   modelId,
+ *   sourceAudio: "/path/to/song.wav",
+ *   operations: [
+ *     {
+ *       type: "flow-edit",
+ *       from: { caption: "original pop song", lyrics: originalLyrics },
+ *       to: { caption: "guitar pop-rock", lyrics: newLyrics },
+ *     },
+ *     { type: "repaint", caption: "analog synth solo", start: 10, end: 20, mode: "balanced" },
+ *   ],
+ *   seed: 22883,
+ * });
+ * stopButton.onclick = () => cancel({ requestId: run.requestId });
+ * const { pcm, sampleRate, channels, bitsPerSample } = await run.audio;
+ * ```
+ */
+export declare function audioEdit(params: AudioEditClientParams): AudioGenResult;
+//# sourceMappingURL=audio-edit.d.ts.map