@qvac/sdk 0.18.2 → 0.19.1

package/dist/examples/abot-world.js

@@ -0,0 +1,124 @@
+import { cancel, loadModel, unloadModel, worldCreateScene, worldStep, ABOT_WORLD_0_5B_Q8_0, ABOT_WORLD_0_5B_LF_VAE, ABOT_WORLD_0_5B_LF_VAE_F16, UMT5_XXL_ENC_Q8_0 } from '@qvac/sdk';
+import fs from 'fs';
+import path from 'path';
+// ABot-World: build a world from a single image, then walk it. Each step
+// generates one block of video under the keys held for it and streams the
+// decoded frames.
+//
+// Runs on the machine hosting the worker; there is no remote route. The
+// default 832x480 tier needs >= 20 GB free VRAM on a dedicated GPU (24 GB card
+// in practice); pass 448 256 to use the low-VRAM tier, which runs on ~6 GB
+// cards well below interactive frame rates.
+const firstFramePath = process.argv[2];
+const prompt = process.argv[3] || '| unknown | A realistic outdoor world scene with a navigable path.';
+const outputDir = process.argv[4] || '.';
+const blocks = Number(process.argv[5] || 8);
+const width = Number(process.argv[6] || 832);
+const height = Number(process.argv[7] || 480);
+if (!firstFramePath) {
+    console.error('✖ first frame image path is required');
+    console.error('Usage: bun run bare:example dist/examples/abot-world.js ' +
+        '<firstFrameImage> [prompt] [outputDir] [blocks] [width] [height]');
+    process.exit(1);
+}
+// A scripted walk: forward, forward while looking right, forward, idle. `keys`
+// also accepts a key-state object ({ W: true }) or a raw 8-bit mask, so a live
+// keyboard handler can pass its state straight through.
+const TAPE = [['W'], ['W', 'L'], ['W'], []];
+try {
+    console.log('▸ Loading ABot-World session (DiT + taehv + scene encoders)...');
+    const modelId = await loadModel({
+        modelSrc: ABOT_WORLD_0_5B_Q8_0,
+        modelType: 'sdcpp-generation',
+        modelConfig: {
+            mode: 'world',
+            // Two different VAEs, and the names are close enough to swap by accident:
+            //   taehvModelSrc — taew2_2, the tiny STREAMING decoder. Turns each block's
+            //     latents into pixels during the walk. Used by every worldStep.
+            //   vaeModelSrc   — the full-precision Wan2.2 VAE. ENCODES the first frame
+            //     during worldCreateScene, and is not touched again after that.
+            // Swapping them loads at first and fails once the walk starts.
+            taehvModelSrc: ABOT_WORLD_0_5B_LF_VAE,
+            t5XxlModelSrc: UMT5_XXL_ENC_Q8_0,
+            vaeModelSrc: ABOT_WORLD_0_5B_LF_VAE_F16,
+            world: {
+                seed: 42,
+                // ~3.7x fewer frame-passes per block. Without it, block times ramp from
+                // ~1.8 s to ~7.5 s as the recompute window fills.
+                kvCache: true,
+                // JPEG rather than PNG: a block is ~14 MB of raw pixels, and this
+                // example writes every frame to disk.
+                frameJpegQuality: 85
+            }
+        }
+    });
+    console.log('▸ Creating the world (umT5 prompt encode + Wan2.2 VAE first-frame encode)...');
+    const creation = worldCreateScene({
+        modelId,
+        prompt,
+        image: new Uint8Array(fs.readFileSync(firstFramePath)),
+        width,
+        height,
+        // The world is live on the session without this; ask for the bytes only
+        // because this example saves them to walk the same world again later.
+        returnPack: true
+    });
+    const scene = await creation.scene;
+    const sceneStats = await creation.stats;
+    const scenePath = path.join(outputDir, 'world.safetensors');
+    fs.writeFileSync(scenePath, scene);
+    console.log(`  scene pack written to ${scenePath} (${scene.length} bytes, ${sceneStats?.sceneCreateMs ?? '?'} ms)`);
+    console.log('  reuse it later with modelConfig.sceneSrc to walk this same world again');
+    console.log(`▸ Walking ${blocks} blocks...`);
+    let frameNumber = 0;
+    for (let block = 0; block < blocks; block++) {
+        const keys = TAPE[block % TAPE.length];
+        // One block at a time: a second step while this one streams is rejected,
+        // so drive the next call off this one rather than firing them in parallel.
+        const run = worldStep({ modelId, keys });
+        for await (const frame of run.frameStream) {
+            const framePath = path.join(outputDir, `frame-${String(frameNumber++).padStart(4, '0')}.jpg`);
+            fs.writeFileSync(framePath, frame);
+        }
+        const stats = await run.stats;
+        console.log(`  block ${block + 1}/${blocks} [${keys.join('+') || 'idle'}] — ` +
+            `${stats?.frames ?? '?'} frames in ${stats?.stepMs ?? '?'} ms`);
+    }
+    console.log(`✔ Wrote ${frameNumber} frames to ${outputDir}`);
+    // Targeted cancellation. Cancel is block-granular: the engine has no
+    // mid-block abort, so the current block finishes internally, delivery stops,
+    // and the step rejects rather than returning a truncated block. A cancel that
+    // lands after the block already finished legitimately succeeds instead — both
+    // outcomes are correct, so handle each.
+    console.log('▸ Cancelling a block mid-flight to show the contract...');
+    const cancelling = worldStep({ modelId, keys: ['W'] });
+    // The timer can fire after the block already finished, and cancelling a
+    // request that is no longer in flight rejects. Handle it here rather than
+    // leaving a floating promise: an unhandled rejection from a fire-and-forget
+    // cancel would take the whole example down for the race it is demonstrating.
+    const cancelTimer = setTimeout(() => {
+        cancel({ requestId: cancelling.requestId }).catch(() => {
+            // The block won the race; the await below reports that outcome.
+        });
+    }, 200);
+    try {
+        await cancelling.frames;
+        console.log('  the block completed before the cancel landed (the tolerated race)');
+    }
+    catch (error) {
+        console.log(`  cancelled as expected: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        clearTimeout(cancelTimer);
+    }
+    // A cancelled step is terminal for the native session, but the SDK drops it
+    // for you: another worldStep on this same modelId would transparently rebuild
+    // from the promoted pack, with no unloadModel/loadModel cycle. Unloading here
+    // only because the example is finished.
+    await unloadModel({ modelId });
+}
+catch (error) {
+    console.error('✖ World walk failed:', error instanceof Error ? error.message : error);
+    process.exit(1);
+}
+process.exit(0);

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

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

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

@@ -0,0 +1,50 @@
+/**
+ * Parakeet Unified transcription from a WAV file.
+ *
+ * Usage:
+ *   bun run examples/asr/parakeet-unified-filesystem.ts <wav-file> [parakeet-unified-gguf]
+ *
+ * Loads a single GGUF checkpoint (`PARAKEET_UNIFIED_0_6B_Q8_0` by default) and
+ * transcribes the file with the batch `transcribe` API. The Unified RNN-T
+ * checkpoint is English-only and serves both batch and low-latency streaming
+ * from the same GGUF; the engine auto-detects the model type from the GGUF
+ * metadata. Omit the model argument to use the registry constant.
+ *
+ * Audio should be 16 kHz mono PCM in a WAV container.
+ */
+import { loadModel, unloadModel, transcribe, PARAKEET_UNIFIED_0_6B_Q8_0 } from '@qvac/sdk';
+const args = process.argv.slice(2);
+if (!args[0]) {
+    console.error('Usage: bun run examples/asr/parakeet-unified-filesystem.ts <wav-file-path> ' +
+        '[parakeet-unified-gguf]');
+    console.error('\nIf the model path is omitted, defaults to the registry model.');
+    process.exit(1);
+}
+const audioFilePath = args[0];
+const parakeetModelSrc = args[1] ?? PARAKEET_UNIFIED_0_6B_Q8_0;
+try {
+    console.log('▸ Starting Parakeet Unified transcription example...');
+    console.log('▸ Loading Parakeet Unified model...');
+    const modelId = await loadModel({
+        modelSrc: parakeetModelSrc,
+        modelType: 'parakeet-transcription',
+        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(`▸ Parakeet Unified model loaded with ID: ${modelId}`);
+    console.log('▸ Transcribing audio...');
+    const text = await transcribe({ modelId, audioChunk: audioFilePath });
+    console.log(text);
+    console.log('▸ Unloading Parakeet Unified model...');
+    await unloadModel({ modelId });
+    console.log('▸ Parakeet Unified model unloaded successfully');
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/assess-model-fit.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Which models is this machine likely to run — asked before downloading any
+ * weights. Nothing is fetched, loaded or reserved.
+ *
+ * The header prints the evidence the answer rests on: `system-memory` on a
+ * CPU-only or integrated-GPU host, `device-memory` on a discrete card,
+ * `device-budget` for the per-process allowance Windows grants on one. Which
+ * of those applies depends on where the engine would put the model.
+ *
+ * `unknown` is a real answer, not an error: the evidence does not support a
+ * call either way. Show it as "can't say", never as "no".
+ */
+export {};
+//# sourceMappingURL=assess-model-fit.d.ts.map

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

@@ -0,0 +1,76 @@
+/**
+ * Which models is this machine likely to run — asked before downloading any
+ * weights. Nothing is fetched, loaded or reserved.
+ *
+ * The header prints the evidence the answer rests on: `system-memory` on a
+ * CPU-only or integrated-GPU host, `device-memory` on a discrete card,
+ * `device-budget` for the per-process allowance Windows grants on one. Which
+ * of those applies depends on where the engine would put the model.
+ *
+ * `unknown` is a real answer, not an error: the evidence does not support a
+ * call either way. Show it as "can't say", never as "no".
+ */
+import { assessModelFit, 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';
+// `as const` so `kind` stays the `'llm'` literal the input type asks for.
+const WORKLOAD = { kind: 'llm', contextTokens: 8192 };
+// A ladder ending well past what a laptop has, so one screen shows every verdict.
+const CANDIDATES = [
+    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
+];
+const VERDICT_MARK = {
+    'likely-fits': '✔',
+    'likely-too-large': '✖',
+    unknown: '?'
+};
+function gib(bytes) {
+    return `${(bytes / 1024 ** 3).toFixed(2)} GiB`;
+}
+try {
+    const result = await assessModelFit({
+        models: CANDIDATES.map((model) => ({ model, workload: WORKLOAD })),
+        // Declared for aggregation only, not a scheduling instruction: 'sequential'
+        // counts the largest operation peak, 'concurrent' counts one per model.
+        execution: 'sequential',
+        policy: 'interactive-v1'
+    });
+    console.log(`▸ Budget basis: ${result.basis}`);
+    if (result.budget) {
+        console.log(`    ${gib(result.budget.availableAfterReserveBytes)} budget` +
+            ` (${gib(result.budget.totalBytes)} total,` +
+            ` ${gib(result.budget.usedBytes)} in use,` +
+            ` ${gib(result.budget.availableBytes)} free,` +
+            ` ${gib(result.budget.reservedBytes)} held back)`);
+    }
+    // Says which device the verdicts assume, when the model would run on a GPU.
+    const placement = result.assumptions.find((line) => line.includes('assumed to execute on'));
+    if (placement)
+        console.log(`▸ ${placement}`);
+    console.log(`\n▸ At ${WORKLOAD.contextTokens} tokens of context`);
+    for (const [index, model] of result.models.entries()) {
+        const mark = VERDICT_MARK[model.verdict];
+        const size = gib(CANDIDATES[index].expectedSize).padStart(9);
+        // 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') {
+            for (const reason of model.reasons)
+                console.log(`      ${reason}`);
+        }
+    }
+    console.log(`\n▸ All five together, sequentially: ${result.verdict}`);
+    console.log('▸ Advisory only — this does not gate loadModel or reserve anything.');
+    process.exit(0);
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

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

@@ -48,7 +48,8 @@ try {
     });
     console.log(`▸ requestId: ${run.requestId}`);
     for await (const progress of run.progressStream) {
-        console.log(`▸ ${progress.stage}: ${progress.step}/${progress.total}`);
+        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));

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

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

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

@@ -0,0 +1,117 @@
+import { writeFileSync } from 'node:fs';
+import { audioGen, loadModel, unloadModel } from '@qvac/sdk';
+// Usage:
+//   AUDIOGEN_MINIMAX_LM_MODEL=/models/mm3-lm-q8.gguf \
+//   AUDIOGEN_MINIMAX_SYNTH_MODEL=/models/mm3-synth-q8.gguf \
+//   bun run examples/audiogen/generate-music-minimax.ts "warm cinematic piano" output.wav
+const caption = process.argv[2] ?? 'Warm cinematic piano with gentle strings';
+const outputPath = process.argv[3] ?? 'minimax-music3-output.wav';
+let modelId;
+try {
+    const threads = numberFromEnv('AUDIOGEN_THREADS');
+    const maxFrames = numberFromEnv('AUDIOGEN_MAX_FRAMES');
+    const inferenceSteps = numberFromEnv('AUDIOGEN_STEPS');
+    console.log('▸ Loading MiniMax-Music3 models...');
+    modelId = await loadModel({
+        modelType: 'audiogen',
+        modelConfig: {
+            engine: 'minimax',
+            lmModelSrc: requiredModelPath('AUDIOGEN_MINIMAX_LM_MODEL'),
+            synthModelSrc: requiredModelPath('AUDIOGEN_MINIMAX_SYNTH_MODEL'),
+            useGPU: process.env['AUDIOGEN_USE_GPU'] === '1',
+            ...(threads !== undefined && { threads })
+        },
+        onProgress: function (progress) {
+            logDownloadProgress(progress);
+        }
+    });
+    console.log(`▸ Model loaded: ${modelId}`);
+    console.log(`▸ Generating: ${caption}`);
+    const run = audioGen({
+        modelId,
+        caption,
+        lyrics: process.env['AUDIOGEN_LYRICS'] ?? '[Instrumental]',
+        seed: numberFromEnv('AUDIOGEN_SEED') ?? 7,
+        cfgScale: numberFromEnv('AUDIOGEN_CFG_SCALE') ?? 1.7,
+        ...(maxFrames !== undefined && { maxFrames }),
+        ...(inferenceSteps !== undefined && { inferenceSteps })
+    });
+    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;
+    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 requiredModelPath(name) {
+    const value = process.env[name];
+    if (!value)
+        throw new Error(`${name} is required`);
+    return value;
+}
+function numberFromEnv(name) {
+    const value = process.env[name];
+    if (value === undefined)
+        return undefined;
+    if (value.trim() === '')
+        throw new Error(`${name} must not be empty`);
+    const number = Number(value);
+    if (!Number.isFinite(number))
+        throw new Error(`${name} must be a finite number`);
+    return number;
+}
+function logDownloadProgress(progress) {
+    const downloadedMb = (progress.downloaded / 1e6).toFixed(1);
+    const totalMb = (progress.total / 1e6).toFixed(1);
+    const line = `▸ Downloading ${progress.percentage.toFixed(0)}% (${downloadedMb}/${totalMb} MB)`;
+    process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
+    if (process.stderr.isTTY && progress.percentage >= 100)
+        process.stderr.write('\n');
+}
+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/generate-music.js

@@ -52,7 +52,8 @@ try {
     });
     console.log(`▸ requestId: ${run.requestId}`);
     for await (const progress of run.progressStream) {
-        console.log(`▸ ${progress.stage}: ${progress.step}/${progress.total}`);
+        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]);
     const wav = createWav(audio.pcm, audio.sampleRate, audio.channels, audio.bitsPerSample);

package/dist/examples/cache-management.js

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

package/dist/examples/classification/classify-image.js

@@ -1,5 +1,5 @@
 import fs from 'fs';
-import { startQVACProvider, stopQVACProvider, loadModel, classify, unloadModel } from '@qvac/sdk';
+import { loadModel, classify, unloadModel } from '@qvac/sdk';
 /**
  * Classify an image using the bundled MobileNetV3-Small model.
  *
@@ -7,7 +7,6 @@ import { startQVACProvider, stopQVACProvider, loadModel, classify, unloadModel }
  * No modelSrc is needed — the model ships inside @qvac/classification-ggml.
  */
 async function main() {
-    await startQVACProvider({});
     const modelId = await loadModel({
         modelType: 'ggml-classification'
     });
@@ -18,6 +17,5 @@ async function main() {
         console.log(`  ${label}: ${(confidence * 100).toFixed(1)}%`);
     }
     await unloadModel({ modelId });
-    await stopQVACProvider();
 }
 main().catch(console.error);

package/dist/examples/config-reload.js

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

package/dist/examples/diffusion-ic-lora-ltx.d.ts

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

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

@@ -0,0 +1,76 @@
+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 fs from 'fs';
+import path from 'path';
+const loraPath = process.argv[2];
+const referencePath = process.argv[3];
+const prompt = process.argv[4] ||
+    'Reference sheet: a red-haired explorer in a blue parka. Generated video: the explorer crosses a snowy ridge at sunrise.';
+const outputDir = process.argv[5] || '.';
+if (!loraPath || !referencePath) {
+    console.error('Usage: bare:example examples/diffusion-ic-lora-ltx.ts <absolute-lora-path> <reference-sheet-path> [prompt] [output-dir]');
+    process.exit(1);
+}
+if (!path.isAbsolute(loraPath)) {
+    console.error('The LoRA adapter path must be absolute on the inference worker.');
+    process.exit(1);
+}
+const referenceSheet = fs.readFileSync(referencePath);
+try {
+    const modelId = await loadModel({
+        modelSrc: LTX_2_3_22B_Q5_K_M,
+        modelType: 'sdcpp-generation',
+        modelConfig: {
+            mode: 'video',
+            device: 'gpu',
+            threads: 4,
+            llmModelSrc: GEMMA_3_12B_Q4_K_XL,
+            vaeModelSrc: LTX_2_3_VAE_1,
+            audioVaeModelSrc: LTX_2_3_VAE,
+            embeddingsConnectorsModelSrc: LTX_2_3_22B_DISTILLED_EMBEDDINGS_CONNECTORS,
+            diffusion_fa: true,
+            offload_to_cpu: true,
+            vae_tiling: true,
+            lora_apply_mode: 'at_runtime'
+        }
+    });
+    const { progressStream, outputs, stats } = video({
+        modelId,
+        mode: 'txt2vid',
+        prompt,
+        negative_prompt: 'blurry, low quality, static, jittery, watermark',
+        width: 768,
+        height: 448,
+        video_frames: 217,
+        fps: 24,
+        steps: 8,
+        scheduler: 'ltx2',
+        cfg_scale: 1,
+        seed: 84,
+        lora: loraPath,
+        lora_strength: 1.37,
+        stg_scale: 1,
+        stg_block: 29,
+        reference_images: [referenceSheet],
+        reference_attention_strength: 1,
+        reference_downscale_factor: 1,
+        temporal_tiling: true,
+        vae_tile_size: 4
+    });
+    for await (const { step, totalSteps } of progressStream) {
+        console.log(`▸ step ${step}/${totalSteps}`);
+    }
+    fs.mkdirSync(outputDir, { recursive: true });
+    const buffers = await outputs;
+    for (let i = 0; i < buffers.length; i++) {
+        const outputPath = path.join(outputDir, `ltx_ic_lora_${i}.avi`);
+        fs.writeFileSync(outputPath, buffers[i]);
+        console.log(`▸ Saved ${outputPath}`);
+    }
+    console.log('▸ Stats:', await stats);
+    await unloadModel({ modelId, clearStorage: false });
+    process.exit(0);
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

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

@@ -9,12 +9,10 @@
  *
  * Run with: bun run examples/mcp-websearch.ts
  */
-import { completion, loadModel, unloadModel, QWEN3_1_7B_INST_Q4 } from '../index.js';
+import { completion, loadModel, unloadModel, QWEN3_1_7B_INST_Q4 } from '../src/index.js';
 // MCP SDK is a user-installed optional dependency
 // Install with: bun add @modelcontextprotocol/sdk
-// eslint-disable-next-line import/no-unresolved
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-// eslint-disable-next-line import/no-unresolved
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 function parseSearchResults(mcpResult) {
     try {

package/dist/examples/model-fit-ui/server.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Demo: assessModelFit's verdict next to what actually happens.
+ *
+ * Serves a page listing catalog models with two buttons. "Estimate" calls
+ * `assessModelFit` — no weights, no load. "Run" loads the model for real and
+ * runs one completion, so the verdict can be checked against the outcome.
+ *
+ * Expect `likely-too-large` to mean "will not go well" rather than "will not
+ * load": an OS with swap usually runs it anyway. Measured here, a 1.7B called
+ * too-large took 519s against 7.8s for a 600M called fits — same 32 tokens.
+ * The verdict is about the interactive budget, not about whether the load
+ * throws.
+ *
+ * Memory is read through `getSystemResources`, not `process.memoryUsage()`:
+ * inference runs in a spawned worker, so this process's own RSS never sees the
+ * model. The numbers are therefore system-wide and include whatever else the
+ * machine is doing — fine for a demo, not a measurement.
+ *
+ * Run (Node or Bun, not Bare — this uses node:http):
+ *   bun run examples/model-fit-ui/server.ts
+ *   node dist/examples/model-fit-ui/server.js
+ */
+export {};
+//# sourceMappingURL=server.d.ts.map