@qvac/sdk 0.19.0 → 0.20.0

package/dist/examples/advisory-model-fit.js

@@ -0,0 +1,156 @@
+/**
+ * Advisory llama.cpp fit check (QVAC-22629).
+ *
+ * Before a completion or embedding load, the SDK runs `@qvac/model-fit` in one
+ * disposable Bare child and projects whether the exact configuration it is
+ * about to load will fit in device memory.
+ *
+ * The result is ADVISORY. It never blocks a load. `does-not-fit` is logged and
+ * the ordinary load path runs unchanged. Crashes, timeouts, malformed
+ * responses, unsupported configurations, and internal errors all resolve to
+ * "no evidence" and are equally non-blocking. Nothing consumes the verdict
+ * yet — this PR only produces it.
+ *
+ * The verdict is emitted on the SDK server log stream, not to stdout, so this
+ * example subscribes to `loggingStream({ id: SDK_LOG_ID })` and reprints the
+ * `[advisory-fit:…]` lines.
+ *
+ * ---------------------------------------------------------------------------
+ * What fits on this machine (Apple M4 Pro, 24 GiB unified memory)
+ * ---------------------------------------------------------------------------
+ *
+ * Measured with `@qvac/model-fit@0.8.0` (the first release carrying the
+ * qvac-fabric#214 memory-reporting fix) at the default 1024 MiB margin. The
+ * fitter budgets against what the machine can actually keep resident
+ * (total − wired − compressor: 17.4 GiB on this machine at idle), not the raw
+ * RAM figure.
+ *
+ *   PROJECTED TO FIT — all layers on GPU
+ *     Qwen3.5 0.8B  Q4_K_M   0.5 GiB  @   4k ctx
+ *     gpt-oss-20B   Q4_K_M  10.8 GiB  @  32k ctx
+ *     gte-large     fp16     0.6 GiB  (embedding, context pinned to 512)
+ *
+ *   PROJECTED NOT TO FIT — try any of these to see a `does-not-fit` verdict
+ *     gpt-oss-20B   Q4_K_M  10.8 GiB  @ 128k ctx with an f32 KV cache ← below
+ *     Gemma 4 31B   Q4_K_M  18.3 GiB  @   1k ctx   ← the weights alone do not
+ *                                                    fit with gpu_layers: 99
+ *
+ * gpt-oss-20B at 128k context FITS with the default KV cache and DOES NOT FIT
+ * once `cache-type-k`/`cache-type-v` are set to `f32`. Same model, same
+ * context, same machine — the verdict tracks the configuration, not the file
+ * size.
+ *
+ * Two boundaries worth understanding when reading verdicts:
+ *
+ * 1. The verdict answers for a PLACEMENT, not a model. The SDK's schema
+ *    default is `gpu_layers: 99` ("everything on the GPU"), so `does-not-fit`
+ *    means "not at this placement". Omit `gpu_layers` and the fitter is free
+ *    to move layers to the CPU side instead.
+ * 2. A `does-not-fit` configuration can still RUN on macOS when the OS
+ *    compresses and pages hard enough — and a `fits` configuration right at
+ *    the boundary can still fail at first decode under memory pressure.
+ *    Prediction cannot separate those cases from a snapshot; the addon-side
+ *    probe decode (QVAC-24114) is the runtime check that catches the
+ *    remainder. The verdict here is the honest working-set budget, and the
+ *    measured failure modes punish over-committing, so treat `does-not-fit`
+ *    as "expect degradation or decode failure", not "the load will error".
+ */
+import { completion, loadModel, unloadModel, loggingStream, SDK_LOG_ID, QWEN3_5_0_8B_MULTIMODAL_Q4_K_M, GPT_OSS_20B_INST_Q4_K_M } from '@qvac/sdk';
+// The oversized load below is expected to be reported as `does-not-fit` and
+// then attempted anyway, because the check is advisory. It really does try to
+// allocate ~11 GiB, so it stays opt-in.
+const ATTEMPT_OVERSIZED = process.env['QVAC_FIT_DEMO_ATTEMPT_OVERSIZED'] === '1';
+// Reprint the worker's advisory verdicts. They arrive on the SDK server log
+// stream; everything else on that stream is filtered out to keep this readable.
+//
+// Called once per phase rather than once for the process: a subscription
+// currently stops delivering after any `unloadModel`, so a single one would go
+// silent before the second verdict. Resubscribing after the unload works.
+function watchVerdicts() {
+    void (async () => {
+        for await (const log of loggingStream({ id: SDK_LOG_ID })) {
+            if (log.message.includes('[advisory-fit:')) {
+                console.log(`▸ [${log.level.toUpperCase()}] ${log.message}`);
+            }
+        }
+    })().catch(() => {
+        // Stream terminated — normal on shutdown.
+    });
+}
+watchVerdicts();
+try {
+    // 1. A load the fitter projects to fit. The verdict carries the plan it
+    //    projected: resolved context, offloaded layers, and GPU device count.
+    console.log('▸ Loading Qwen3.5 0.8B @ 4k — expected verdict: projected to fit');
+    const smallModelId = await loadModel({
+        modelSrc: QWEN3_5_0_8B_MULTIMODAL_Q4_K_M,
+        modelConfig: { ctx_size: 4096 }
+    });
+    console.log(`▸ Loaded ${smallModelId}\n`);
+    const result = completion({
+        modelId: smallModelId,
+        history: [{ role: 'user', content: 'Say hello in five words.' }],
+        stream: false,
+        generationParams: { predict: 48 }
+    });
+    const final = await result.final;
+    console.log(`▸ Completion still works normally: ${final.contentText.trim().slice(0, 120)}\n`);
+    // Unloaded before the next phase, so the second verdict is measured on an
+    // idle machine and stays comparable to the fixture tables above. Leaving it
+    // loaded would shift the verdict: the check reserves resident weight bytes
+    // through the fit margin, and since model-fit 0.8.0 the fit child also sees
+    // system-wide wired memory.
+    await unloadModel({ modelId: smallModelId, clearStorage: false });
+    watchVerdicts();
+    // 2. A load the fitter projects NOT to fit. The point of this example is that
+    //    the SDK reports the verdict and then loads anyway — the check is
+    //    evidence, not admission control.
+    if (!ATTEMPT_OVERSIZED) {
+        console.log('▸ Skipping the oversized gpt-oss-20B load.');
+        console.log('▸ Set QVAC_FIT_DEMO_ATTEMPT_OVERSIZED=1 to let it run and watch the');
+        console.log('  load proceed past a `does-not-fit` verdict (allocates ~11 GiB).');
+    }
+    else {
+        console.log('▸ Loading gpt-oss-20B @ 128k with an f32 KV cache');
+        console.log('▸ Expected verdict: projected NOT to fit');
+        console.log('▸ The load is attempted regardless. That is the fail-open contract:');
+        console.log('  the verdict is evidence, not admission control.\n');
+        const bigModelId = await loadModel({
+            modelSrc: GPT_OSS_20B_INST_Q4_K_M,
+            modelConfig: {
+                ctx_size: 131072,
+                'cache-type-k': 'f32',
+                'cache-type-v': 'f32'
+            }
+        });
+        console.log(`▸ Load returned ${bigModelId} — the advisory verdict did not block it`);
+        // Loading is not the same as being usable: a model can load and then fail
+        // at decode time. Gemma 4 31B does exactly that on this machine. So run a
+        // real completion and report throughput rather than trusting the load.
+        try {
+            const check = completion({
+                modelId: bigModelId,
+                history: [{ role: 'user', content: 'Name three colours. Answer briefly.' }],
+                stream: false,
+                generationParams: { predict: 40 }
+            });
+            const checkFinal = await check.final;
+            console.log(`▸ ...and it actually runs: ${checkFinal.stats?.tokensPerSecond?.toFixed(1) ?? '?'} tok/s ` +
+                `— the OS compressed and paged its way past the working-set budget`);
+        }
+        catch (inferenceError) {
+            console.log(`▸ ...but it cannot run: ${inferenceError instanceof Error ? inferenceError.message : String(inferenceError)}`);
+            console.log('▸ The verdict was right, and `loadModel` succeeding did not mean usable.');
+        }
+        await unloadModel({ modelId: bigModelId, clearStorage: false });
+    }
+}
+catch (error) {
+    // A failing load here is the native loader's own error, not the fit check.
+    // The check never throws and never converts a verdict into a load failure.
+    console.error('✖', error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+}
+// The log subscription is an open stream and would otherwise keep the process
+// alive after the work is done.
+process.exit(process.exitCode ?? 0);

package/dist/examples/asr/parakeet-nemotron-filesystem.d.ts

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

package/dist/examples/asr/parakeet-nemotron-filesystem.js

@@ -0,0 +1,170 @@
+/**
+ * Parakeet Nemotron transcription from an audio file.
+ *
+ * Usage:
+ *   bun run examples/asr/parakeet-nemotron-filesystem.ts \
+ *     <audio-file> [locale] [nemotron-gguf] [--streaming]
+ *   bun run examples/asr/parakeet-nemotron-filesystem.ts \
+ *     <audio-file> [nemotron-gguf] [--streaming]
+ *
+ * Uses `PARAKEET_NEMOTRON_0_6B_Q4_0` when the model is omitted and `auto` when
+ * the locale is omitted. Pass `--streaming` to stream decoded 16 kHz mono PCM;
+ * otherwise, the input is transcribed in batch mode.
+ */
+import { loadModel, PARAKEET_NEMOTRON_0_6B_Q4_0, transcribe, transcribeStream, unloadModel } from '@qvac/sdk';
+import { spawn } from 'child_process';
+const SAMPLE_RATE = 16000;
+const BYTES_PER_S16_SAMPLE = 2;
+const INPUT_CHUNK_MS = 160;
+const MILLISECONDS_PER_SECOND = 1000;
+const BYTES_PER_MEGABYTE = 1e6;
+const DEFAULT_LOCALE = 'auto';
+const FFMPEG_PROTOCOLS = 'file,pipe';
+const STREAMING_FLAG = '--streaming';
+const EARLY_OUTPUT_END_MESSAGE = 'The transcription stream ended before the decoder input completed';
+const USAGE = 'Usage: bun run examples/asr/parakeet-nemotron-filesystem.ts ' +
+    '<audio-file> [locale] [nemotron-gguf] [--streaming]';
+function parseArguments(args) {
+    const streaming = args.includes(STREAMING_FLAG);
+    const positional = args.filter((argument) => argument !== STREAMING_FLAG);
+    const [audioFilePath, second, third] = positional;
+    const secondIsModel = second !== undefined &&
+        (second.endsWith('.gguf') || second.includes('/') || second.includes('\\'));
+    const locale = secondIsModel ? DEFAULT_LOCALE : (second ?? DEFAULT_LOCALE);
+    const modelSource = secondIsModel ? second : third;
+    return { audioFilePath, locale, modelSource, streaming };
+}
+function requireAudioFilePath(audioFilePath) {
+    if (audioFilePath)
+        return audioFilePath;
+    throw new Error(USAGE);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function calculateChunkBytes() {
+    const samplesPerChunk = Math.floor((INPUT_CHUNK_MS / MILLISECONDS_PER_SECOND) * SAMPLE_RATE);
+    return samplesPerChunk * BYTES_PER_S16_SAMPLE;
+}
+function createDecoder(inputPath) {
+    return spawn('ffmpeg', [
+        '-protocol_whitelist',
+        FFMPEG_PROTOCOLS,
+        '-i',
+        inputPath,
+        '-ar',
+        String(SAMPLE_RATE),
+        '-ac',
+        '1',
+        '-f',
+        's16le',
+        'pipe:1'
+    ], { stdio: ['ignore', 'pipe', 'inherit'] });
+}
+function waitForDecoder(decoder) {
+    return new Promise((resolve) => {
+        decoder.once('error', resolve);
+        decoder.once('close', (code) => {
+            if (code === 0)
+                resolve(null);
+            else
+                resolve(new Error(`ffmpeg exited with code ${code}`));
+        });
+    });
+}
+function stopDecoder(decoder) {
+    if (decoder?.exitCode === null && !decoder.killed)
+        decoder.kill();
+}
+async function printTranscription(session) {
+    for await (const event of session) {
+        if (event.type === 'text' && event.text)
+            process.stdout.write(event.text);
+    }
+}
+async function rejectWhenOutputEnds(output) {
+    await output;
+    throw new Error(EARLY_OUTPUT_END_MESSAGE);
+}
+async function writeAvailableChunks(session, pcm, chunkBytes) {
+    let offset = 0;
+    while (pcm.length - offset >= chunkBytes) {
+        session.write(pcm.subarray(offset, offset + chunkBytes));
+        offset += chunkBytes;
+        await delay(INPUT_CHUNK_MS);
+    }
+    return pcm.subarray(offset);
+}
+async function feedDecoderOutput(session, decoder, chunkBytes) {
+    let incomplete = Buffer.alloc(0);
+    for await (const decoded of decoder.stdout) {
+        const pcm = incomplete.length === 0 ? Buffer.from(decoded) : Buffer.concat([incomplete, decoded]);
+        incomplete = await writeAvailableChunks(session, pcm, chunkBytes);
+    }
+    return incomplete;
+}
+async function runStreaming(modelId, inputPath) {
+    const session = await transcribeStream({ modelId, parakeetStreamingConfig: {} });
+    const output = printTranscription(session);
+    let decoder;
+    let exited;
+    let feeding;
+    try {
+        decoder = createDecoder(inputPath);
+        exited = waitForDecoder(decoder);
+        feeding = feedDecoderOutput(session, decoder, calculateChunkBytes());
+        const incomplete = await Promise.race([feeding, rejectWhenOutputEnds(output)]);
+        const decoderError = await exited;
+        if (decoderError)
+            throw decoderError;
+        if (incomplete.length > 0)
+            session.write(incomplete);
+        session.end();
+        await output;
+        process.stdout.write('\n');
+    }
+    finally {
+        stopDecoder(decoder);
+        session.destroy();
+        await Promise.allSettled([exited, feeding, output]);
+    }
+}
+function printDownloadProgress(progress) {
+    const downloaded = (progress.downloaded / BYTES_PER_MEGABYTE).toFixed(1);
+    const total = (progress.total / BYTES_PER_MEGABYTE).toFixed(1);
+    const percentage = progress.percentage.toFixed(0);
+    const line = `Downloading ${percentage}% (${downloaded}/${total} MB)`;
+    process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
+    if (progress.percentage >= 100)
+        process.stderr.write('\n');
+}
+async function run() {
+    const { audioFilePath, locale, modelSource, streaming } = parseArguments(process.argv.slice(2));
+    const inputPath = requireAudioFilePath(audioFilePath);
+    let modelId = null;
+    try {
+        console.log(`Loading Nemotron with locale ${locale}...`);
+        modelId = await loadModel({
+            modelSrc: modelSource ?? PARAKEET_NEMOTRON_0_6B_Q4_0,
+            modelType: 'parakeet-transcription',
+            modelConfig: { language: locale, streaming },
+            onProgress: printDownloadProgress
+        });
+        if (streaming) {
+            console.log('Streaming with the Nemotron native 320 ms operating point...');
+            await runStreaming(modelId, inputPath);
+        }
+        else {
+            console.log('Transcribing in batch mode...');
+            console.log(await transcribe({ modelId, audioChunk: inputPath }));
+        }
+    }
+    finally {
+        if (modelId)
+            await unloadModel({ modelId });
+    }
+}
+run().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/examples/assess-model-fit.js

@@ -53,7 +53,12 @@ try {
     for (const [index, model] of result.models.entries()) {
         const mark = VERDICT_MARK[model.verdict];
         const size = gib(CANDIDATES[index].expectedSize).padStart(9);
-        const needs = model.estimate ? `needs ${gib(model.estimate.upperBoundBytes)}` : '';
+        // A calibrated row has a two-sided estimate; a computed-only row has the floor.
+        const needs = model.estimate
+            ? `needs ${gib(model.estimate.upperBoundBytes)}`
+            : model.evidence === 'computed-only' && model.floorBytes
+                ? `at least ${gib(model.floorBytes)}`
+                : '';
         console.log(`  ${mark} ${model.name.padEnd(46)} ${size} on disk  ${needs}`);
         // Present on every `unknown`, and worth surfacing: it names what is missing.
         if (model.verdict === 'unknown') {

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

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

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

@@ -0,0 +1,121 @@
+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, audioEdit, loadModel, unloadModel } from '@qvac/sdk';
+// Edit an existing recording with ACE-Step: a Flow-Edit that re-conditions the
+// whole clip from a source prompt to a target prompt, then a Repaint that
+// regenerates one time range against a new prompt. Operations run in order.
+//
+// Usage:
+//   bun examples/audiogen/edit-music.ts <source.wav|mp3|...> "original pop song" "guitar pop-rock" [output.wav]
+//
+// The source must run at least REPAINT_END seconds: the Repaint below asks for
+// a fixed window, and a range past the end of the source is rejected with
+// `repaint.start must be within the source duration`.
+//
+// The source is a file path: the SDK decodes it (any FFmpeg-decodable format)
+// to the 48 kHz stereo float PCM the engine expects. Pass raw interleaved
+// stereo 48 kHz Float32 LE PCM in [-1, 1] as a Buffer instead when the audio
+// is already in memory — for example the `pcm` of an earlier `audioGen()` run,
+// converted from Int16 to Float32.
+// Repaint window, in seconds from the start of the source.
+const REPAINT_START = 10;
+const REPAINT_END = 20;
+const sourcePath = process.argv[2];
+const fromCaption = process.argv[3] ?? 'Original pop song';
+const toCaption = process.argv[4] ?? 'Guitar pop-rock';
+const outputPath = process.argv[5] ?? 'audiogen-edit.wav';
+if (!sourcePath) {
+    console.error('Usage: bun examples/audiogen/edit-music.ts <source-audio> "<from caption>" "<to caption>" [output.wav]');
+    process.exit(1);
+}
+let modelId;
+try {
+    console.log('▸ Loading ACE-Step AudioGen models...');
+    modelId = await loadModel({
+        modelType: 'audiogen',
+        modelConfig: {
+            textEncModelSrc: AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0,
+            lmModelSrc: AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0,
+            // Flow-Edit needs a turbo DiT variant; Repaint works on every variant.
+            ditModelSrc: AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M,
+            vaeModelSrc: AUDIOGEN_VAE_BF16,
+            useGPU: true
+        }
+    });
+    console.log(`▸ Model loaded: ${modelId}`);
+    console.log(`▸ Editing ${sourcePath}: "${fromCaption}" -> "${toCaption}"`);
+    const run = audioEdit({
+        modelId,
+        sourceAudio: sourcePath,
+        operations: [
+            {
+                type: 'flow-edit',
+                from: { caption: fromCaption },
+                to: { caption: toCaption }
+            },
+            {
+                // Regenerate the repaint window as a synth solo; the rest is kept.
+                type: 'repaint',
+                caption: 'analog synth solo',
+                lyrics: '[Instrumental]',
+                start: REPAINT_START,
+                end: REPAINT_END,
+                mode: 'balanced',
+                strength: 0.5
+            }
+        ],
+        // Seeds the first operation; each following operation uses seed + index.
+        seed: 22883
+    });
+    console.log(`▸ requestId: ${run.requestId}`);
+    for await (const progress of run.progressStream) {
+        const value = progress.total > 0 ? `${progress.step}/${progress.total}` : `${progress.step} (indeterminate)`;
+        console.log(`▸ ${progress.stage}: ${value}`);
+    }
+    const [audio, stats] = await Promise.all([run.audio, run.stats]);
+    writeFileSync(outputPath, createWav(audio.pcm, audio.sampleRate, audio.channels, audio.bitsPerSample));
+    if (stats)
+        console.log(`▸ Stats: ${JSON.stringify(stats)}`);
+    console.log(`▸ Saved ${outputPath}`);
+    await unloadModel({ modelId });
+    modelId = undefined;
+    process.exit(0);
+}
+catch (error) {
+    if (modelId !== undefined) {
+        try {
+            await unloadModel({ modelId });
+        }
+        catch {
+            // Preserve the edit error as the primary failure.
+        }
+    }
+    console.error('✖', error);
+    process.exit(1);
+}
+function createWav(pcm, sampleRate, channels, bitsPerSample) {
+    const header = new ArrayBuffer(44);
+    const view = new DataView(header);
+    const blockAlign = channels * (bitsPerSample / 8);
+    writeAscii(view, 0, 'RIFF');
+    view.setUint32(4, 36 + pcm.byteLength, true);
+    writeAscii(view, 8, 'WAVE');
+    writeAscii(view, 12, 'fmt ');
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true);
+    view.setUint16(22, channels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, sampleRate * blockAlign, true);
+    view.setUint16(32, blockAlign, true);
+    view.setUint16(34, bitsPerSample, true);
+    writeAscii(view, 36, 'data');
+    view.setUint32(40, pcm.byteLength, true);
+    const wav = new Uint8Array(44 + pcm.byteLength);
+    wav.set(new Uint8Array(header));
+    wav.set(pcm, 44);
+    return wav;
+}
+function writeAscii(view, offset, value) {
+    for (let index = 0; index < value.length; index++) {
+        view.setUint8(offset + index, value.charCodeAt(index));
+    }
+}

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

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

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

@@ -0,0 +1,73 @@
+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, audioUnderstand, loadModel, unloadModel } from '@qvac/sdk';
+// Describe an existing recording with ACE-Step's reverse pipeline: the engine
+// encodes the audio, recovers its FSQ semantic codes, and the LM reports a
+// caption and the clip's musical metadata.
+//
+// Usage:
+//   bun examples/audiogen/understand-music.ts <source.wav|mp3|...> [language hint]
+//
+// The source is a file path: the SDK decodes it (any FFmpeg-decodable format)
+// to the 48 kHz stereo float PCM the engine expects. Pass raw interleaved
+// stereo 48 kHz Float32 LE PCM in [-1, 1] as a Buffer instead when the audio
+// is already in memory.
+const sourcePath = process.argv[2];
+const vocalLanguage = process.argv[3];
+if (!sourcePath) {
+    console.error('Usage: bun examples/audiogen/understand-music.ts <source-audio> [language]');
+    process.exit(1);
+}
+let modelId;
+try {
+    console.log('▸ Loading ACE-Step AudioGen models...');
+    modelId = await loadModel({
+        modelType: 'audiogen',
+        modelConfig: {
+            textEncModelSrc: AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0,
+            lmModelSrc: AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0,
+            ditModelSrc: AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M,
+            vaeModelSrc: AUDIOGEN_VAE_BF16,
+            useGPU: true
+        }
+    });
+    console.log(`▸ Model loaded: ${modelId}`);
+    console.log(`▸ Analysing ${sourcePath}`);
+    const run = audioUnderstand({
+        modelId,
+        sourceAudio: sourcePath,
+        // Forced into the result instead of the LM's guess; omit to let it decide.
+        ...(vocalLanguage !== undefined && { vocalLanguage }),
+        seed: 11
+    });
+    console.log(`▸ requestId: ${run.requestId}`);
+    for await (const progress of run.progressStream) {
+        const value = progress.total > 0 ? `${progress.step}/${progress.total}` : `${progress.step} (indeterminate)`;
+        console.log(`▸ ${progress.stage}: ${value}`);
+    }
+    const [description, stats] = await Promise.all([run.description, run.stats]);
+    console.log(`▸ Caption: ${description.caption}`);
+    console.log(`▸ ${description.bpm} BPM, ${description.keyscale}, ${description.timesignature}`);
+    console.log(`▸ Vocal language: ${description.vocalLanguage}`);
+    // The LM's duration is an estimate; the recovered codes fix the true length.
+    console.log(`▸ Estimated duration: ${description.duration.toFixed(1)} s`);
+    console.log(`▸ Recovered ${description.audioCodes.length} semantic codes`);
+    if (stats)
+        console.log(`▸ Stats: ${JSON.stringify({ ...stats, understand: undefined })}`);
+    // `audioCodes` feeds straight back into audioGen() to re-synthesize the piece
+    // without re-running the LM:
+    //   audioGen({ modelId, caption: description.caption, audioCodes: description.audioCodes })
+    await unloadModel({ modelId });
+    modelId = undefined;
+    process.exit(0);
+}
+catch (error) {
+    if (modelId !== undefined) {
+        try {
+            await unloadModel({ modelId });
+        }
+        catch {
+            // Preserve the understand error as the primary failure.
+        }
+    }
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/diffusion-ic-lora-ltx.js

@@ -1,4 +1,4 @@
-import { GEMMA_3_12B_Q4_K_XL, loadModel, LTX_2_3_22B_DISTILLED_EMBEDDINGS_CONNECTORS, LTX_2_3_22B_Q5_K_M, LTX_2_3_VAE, LTX_2_3_VAE_1, unloadModel, video } from '@qvac/sdk';
+import { GEMMA_3_12B_Q4_K_XL, loadModel, LTX_2_3_22B_DISTILLED_EMBEDDINGS_CONNECTORS, LTX_2_3_22B_Q5_K_M, LTX_2_3_AUDIO_VAE, LTX_2_3_VIDEO_VAE, unloadModel, video } from '@qvac/sdk';
 import fs from 'fs';
 import path from 'path';
 const loraPath = process.argv[2];
@@ -24,8 +24,8 @@ try {
             device: 'gpu',
             threads: 4,
             llmModelSrc: GEMMA_3_12B_Q4_K_XL,
-            vaeModelSrc: LTX_2_3_VAE_1,
-            audioVaeModelSrc: LTX_2_3_VAE,
+            vaeModelSrc: LTX_2_3_VIDEO_VAE,
+            audioVaeModelSrc: LTX_2_3_AUDIO_VAE,
             embeddingsConnectorsModelSrc: LTX_2_3_22B_DISTILLED_EMBEDDINGS_CONNECTORS,
             diffusion_fa: true,
             offload_to_cpu: true,

package/dist/examples/diffusion-img2vid.js

@@ -33,7 +33,7 @@ try {
             clipVisionModelSrc,
             diffusion_fa: true,
             offload_to_cpu: true,
-            vae_on_cpu: true,
+            params_backend: 'vae=cpu',
             vae_tiling: true
         },
         onProgress: (p) => {

package/dist/examples/diffusion-txt2vid-minimax-h3.d.ts

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

package/dist/examples/diffusion-txt2vid-minimax-h3.js

@@ -0,0 +1,64 @@
+import { loadModel, unloadModel, video } from '@qvac/sdk';
+import fs from 'fs';
+import path from 'path';
+// Pass a directory containing the four MiniMax-H3 files, followed by an output path.
+const modelsDir = process.argv[2];
+if (!modelsDir) {
+    throw new Error('Usage: diffusion-txt2vid-minimax-h3.ts <models-directory> [output.avi]');
+}
+const outputPath = process.argv[3] || 'minimax-h3.avi';
+const modelSrc = path.resolve(modelsDir, process.env['H3_MODEL'] || 'minimax_h3_fl2va_pruned-Q4_K.gguf');
+const llmModelSrc = path.resolve(modelsDir, process.env['H3_LLM'] || 'qwen3vl_32b_minimax_h3-Q4_K_M.gguf');
+const vaeModelSrc = path.resolve(modelsDir, 'vae/minimax_h3_video_vae_fp16.safetensors');
+const audioVaeModelSrc = path.resolve(modelsDir, 'vae/minimax_h3_audio_vae_fp32.safetensors');
+for (const file of [modelSrc, llmModelSrc, vaeModelSrc, audioVaeModelSrc])
+    fs.accessSync(file);
+let modelId;
+try {
+    modelId = await loadModel({
+        modelType: 'sdcpp-generation',
+        modelSrc,
+        modelConfig: {
+            mode: 'video',
+            llmModelSrc,
+            vaeModelSrc,
+            audioVaeModelSrc,
+            device: 'gpu',
+            diffusion_fa: true,
+            offload_to_cpu: process.env['H3_OFFLOAD_TO_CPU'] !== '0',
+            stream_layers: process.env['H3_STREAM_LAYERS'] === '1',
+            ...(process.env['H3_BACKEND'] && { backend: process.env['H3_BACKEND'] }),
+            ...(process.env['H3_PARAMS_BACKEND'] && { params_backend: process.env['H3_PARAMS_BACKEND'] }),
+            ...(process.env['H3_MAX_VRAM'] && { max_vram: process.env['H3_MAX_VRAM'] })
+        }
+    });
+    const { progressStream, outputs, stats } = video({
+        modelId,
+        mode: 'txt2vid',
+        prompt: process.env['PROMPT'] ||
+            'Premium cinematic coffee commercial. A confident adult sits at a small café table at sunrise, slowly lifts one matte black coffee cup, takes a relaxed sip, and smiles. Warm golden rim light, drifting steam, realistic skin, natural hands, shallow depth of field, subtle slow camera push-in, restrained natural motion, polished live-action advertising, no dialogue, no text overlay.',
+        negative_prompt: 'extra people, duplicate cup, malformed hands, cup fused to hand, text, subtitles, watermark, cartoon, CGI, blur, flicker, jitter, camera shake',
+        width: 960,
+        height: 544,
+        // H3 uses 17*k+5 frames; 124 frames at 24 FPS is approximately 5.17 seconds.
+        video_frames: Number(process.env['FRAMES'] || 124),
+        fps: 24,
+        steps: 8,
+        cfg_scale: 1,
+        seed: 11
+    });
+    const progress = (async () => {
+        for await (const tick of progressStream)
+            console.log(`Step ${tick.step}/${tick.totalSteps}`);
+    })();
+    const [buffers, runtimeStats] = await Promise.all([outputs, stats, progress]);
+    if (!buffers[0])
+        throw new Error('Generation finished without an AVI result');
+    fs.writeFileSync(outputPath, buffers[0]);
+    console.log(`Saved ${outputPath}`, runtimeStats);
+}
+finally {
+    if (modelId)
+        await unloadModel({ modelId, clearStorage: false });
+}
+process.exit(0);

package/dist/examples/diffusion-txt2vid.js

@@ -26,7 +26,7 @@ try {
             vaeModelSrc,
             diffusion_fa: true,
             offload_to_cpu: true,
-            vae_on_cpu: true,
+            params_backend: 'vae=cpu',
             vae_tiling: true
         },
         onProgress: (p) => {