@qvac/sdk 0.10.1 → 0.11.0

package/dist/examples/diffusion-esrgan-upscale.d.ts

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

package/dist/examples/diffusion-esrgan-upscale.js

@@ -0,0 +1,78 @@
+import { loadModel, unloadModel, diffusion, SD_V2_1_1B_Q8_0, REALESRGAN_X4PLUS_ANIME_6B, } from "@qvac/sdk";
+import fs from "fs";
+import path from "path";
+// ESRGAN upscale example.
+//
+// Usage:
+//   bun run examples/diffusion-esrgan-upscale.ts [esrganSrc] [prompt] [outputDir]
+const esrganArg = process.argv[2];
+const promptArg = process.argv[3];
+const outputDirArg = process.argv[4];
+const esrganModelSrc = esrganArg ??
+    REALESRGAN_X4PLUS_ANIME_6B;
+const prompt = promptArg ??
+    "an illustrated red fox portrait, clean line art, soft watercolor background, detailed fur, crisp eyes";
+const negative_prompt = "blurry, low quality, watermark, text";
+const outputDir = outputDirArg ?? ".";
+const seed = 42;
+try {
+    console.log("Loading SD 2.1 + ESRGAN upscaler...");
+    const modelId = await loadModel({
+        modelSrc: SD_V2_1_1B_Q8_0,
+        modelType: "diffusion",
+        modelConfig: {
+            prediction: "v",
+            upscaler: {
+                type: "esrgan",
+                model_src: esrganModelSrc,
+                tile_size: 128,
+            },
+        },
+        onProgress: (p) => console.log(`Loading: ${p.percentage.toFixed(1)}%`),
+    });
+    console.log(`Model loaded: ${modelId}`);
+    // Source size is intentionally small — each ESRGAN repeat multiplies dimensions.
+    const baseParams = {
+        modelId,
+        prompt,
+        negative_prompt,
+        width: 128,
+        height: 128,
+        steps: 5,
+        cfg_scale: 7.5,
+        seed,
+    };
+    console.log(`\nGenerating ESRGAN x4 upscale: "${prompt}"`);
+    const single = diffusion({ ...baseParams, upscale: true });
+    for await (const { step, totalSteps } of single.progressStream) {
+        process.stdout.write(`\rStep ${step}/${totalSteps}\x1b[K`);
+    }
+    console.log();
+    const singleBuffers = await single.outputs;
+    for (let i = 0; i < singleBuffers.length; i++) {
+        const out = path.join(outputDir, `sd2_esrgan_x4_seed${seed}_${i}.png`);
+        fs.writeFileSync(out, singleBuffers[i]);
+        console.log(`Saved: ${out}`);
+    }
+    console.log("Stats:", await single.stats);
+    console.log("\nGenerating ESRGAN two-pass x16 upscale...");
+    const twoPass = diffusion({ ...baseParams, upscale: { repeats: 2 } });
+    for await (const { step, totalSteps } of twoPass.progressStream) {
+        process.stdout.write(`\rStep ${step}/${totalSteps}\x1b[K`);
+    }
+    console.log();
+    const twoPassBuffers = await twoPass.outputs;
+    for (let i = 0; i < twoPassBuffers.length; i++) {
+        const out = path.join(outputDir, `sd2_esrgan_x16_seed${seed}_${i}.png`);
+        fs.writeFileSync(out, twoPassBuffers[i]);
+        console.log(`Saved: ${out}`);
+    }
+    console.log("Stats:", await twoPass.stats);
+    await unloadModel({ modelId, clearStorage: false });
+    console.log("Done.");
+    process.exit(0);
+}
+catch (error) {
+    console.error("❌ Error:", error);
+    process.exit(1);
+}

package/dist/examples/download-with-cancel.js

@@ -4,8 +4,11 @@ console.log(`\n💡 Press Ctrl+C to pause the download (it will resume on restar
 let modelId;
 let cancelled = false;
 try {
-    // Download model with progress tracking and cancellation
-    await downloadAsset({
+    // Download model with progress tracking and cancellation. The
+    // `downloadAsset(...)` call returns a *decorated* promise: the
+    // promise resolves to the modelId, and the same value carries a
+    // synchronous `requestId` field so we can cancel before it settles.
+    const download = downloadAsset({
         assetSrc: LLAMA_3_2_1B_INST_Q4_0,
         onProgress: (progress) => {
             const downloadedMB = (progress.downloaded / 1024 / 1024).toFixed(2);
@@ -18,17 +21,14 @@ try {
                 console.log(`📊 Progress: ${percentage}% (${downloadedMB}MB / ${totalMB}MB)`);
                 console.log(progress);
                 cancelled = true;
-                // Use the downloadKey to cancel
-                if (progress.downloadKey) {
-                    void cancel({
-                        operation: "downloadAsset",
-                        downloadKey: progress.downloadKey,
-                        // clearCache: true, // Uncomment to delete partial file instead of resuming
-                    });
-                }
+                void cancel({
+                    requestId: download.requestId,
+                    // clearCache: true, // Uncomment to delete partial file instead of resuming
+                });
             }
         },
     });
+    await download;
     console.log(`\n✅ Model downloaded successfully! Model ID: ${modelId}`);
     console.log("🎯 Download completed without interruption");
     void close();

package/dist/examples/embed-multi-gpu.d.ts

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

package/dist/examples/embed-multi-gpu.js

@@ -0,0 +1,46 @@
+import { loadModel, embed, unloadModel, EMBEDDINGGEMMA_300M_Q8_0 } from "@qvac/sdk";
+// Multi-GPU embedding distributes model layers across multiple GPUs using
+// llama.cpp's built-in split modes. Two strategies are available:
+//
+// - "layer": splits layers and KV cache across GPUs.
+// - "row":   splits layers and KV cache across GPUs, and uses tensor parallelism
+//            where supported.
+//
+// tensorSplit controls the proportion of work assigned to each GPU.
+// "1,1" distributes evenly across two GPUs; "3,1" assigns 75% to GPU 0.
+//
+// mainGpu selects which GPU is used for the entire model when splitMode is
+// "none", and pins the primary device in multi-GPU mode.
+// Accepts an integer device index (0, 1, ...) or "integrated" / "dedicated".
+try {
+    const modelId = await loadModel({
+        modelSrc: EMBEDDINGGEMMA_300M_Q8_0,
+        modelType: "llamacpp-embedding",
+        modelConfig: {
+            splitMode: "layer",
+            tensorSplit: "1,1",
+            mainGpu: 0,
+            gpuLayers: 99,
+            verbosity: 0,
+        },
+    });
+    const texts = [
+        "Multi-GPU embedding distributes layer computation across GPUs.",
+        "Each GPU handles a subset of layers, improving throughput for large models.",
+        "The tensor-split ratio controls how much work each GPU receives.",
+    ];
+    for (const text of texts) {
+        const { embedding, stats } = await embed({ modelId, text });
+        console.log(`Embedded ${text.slice(0, 50)}...`);
+        console.log(`  Dimensions: ${embedding.length}`);
+        if (stats) {
+            console.log(`  Backend: ${stats.backendDevice}, TPS: ${stats.tokensPerSecond?.toFixed(1)}`);
+        }
+    }
+    await unloadModel({ modelId, clearStorage: false });
+    process.exit(0);
+}
+catch (error) {
+    console.error("Error:", error);
+    process.exit(1);
+}

package/dist/examples/llamacpp-multi-gpu.d.ts

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

package/dist/examples/llamacpp-multi-gpu.js

@@ -0,0 +1,57 @@
+import { completion, loadModel, unloadModel, VERBOSITY, LLAMA_3_2_1B_INST_Q4_0 } from "@qvac/sdk";
+// Multi-GPU inference distributes a model across multiple GPUs using llama.cpp's
+// built-in split modes. Two strategies are available:
+//
+// - "layer": splits layers and KV cache across GPUs.
+// - "row":   splits layers and KV cache across GPUs, and uses tensor parallelism
+//            where supported.
+//
+// tensor-split controls the proportion of work assigned to each GPU.
+// "1,1" distributes evenly across two GPUs; "3,1" assigns 75% to GPU 0.
+//
+// Usage:
+//   bun run bare:example dist/examples/llamacpp-multi-gpu.js
+//   bun run bare:example dist/examples/llamacpp-multi-gpu.js '<model-url>'
+const modelSrc = process.argv[2] ?? LLAMA_3_2_1B_INST_Q4_0;
+try {
+    const modelId = await loadModel({
+        modelSrc,
+        modelType: "llm",
+        modelConfig: {
+            "split-mode": "layer",
+            "tensor-split": "1,1",
+            "main-gpu": 0,
+            ctx_size: 4096,
+            gpu_layers: 99,
+            verbosity: VERBOSITY.ERROR,
+        },
+        onProgress: (progress) => {
+            if (progress.shardInfo) {
+                const { shardInfo } = progress;
+                console.log(`Downloading ${shardInfo.shardName} (${shardInfo.currentShard}/${shardInfo.totalShards}) ` +
+                    `— overall: ${shardInfo.overallPercentage.toFixed(1)}%`);
+            }
+            else {
+                console.log(`Downloading: ${progress.percentage.toFixed(1)}%`);
+            }
+        },
+    });
+    const history = [
+        {
+            role: "user",
+            content: "Explain the difference between pipeline and tensor parallelism in one paragraph.",
+        },
+    ];
+    const result = completion({ modelId, history, stream: true });
+    for await (const token of result.tokenStream) {
+        process.stdout.write(token);
+    }
+    const stats = await result.stats;
+    console.log("\n\nStats:", stats);
+    await unloadModel({ modelId, clearStorage: false });
+    process.exit(0);
+}
+catch (error) {
+    console.error("Error:", error);
+    process.exit(1);
+}

package/dist/examples/rag/rag-hyperdb/cancellation.js

@@ -31,24 +31,27 @@ try {
     console.log(`📄 Processing ${documents.length} documents...\n`);
     let progressCount = 0;
     let cancelled = false;
+    // Capture the decorated promise so we can cancel by `requestId` (the
+    // primary cancel path). For a "cancel everything RAG on this model"
+    // sweep, use `cancel({ modelId, kind: "rag" })` instead.
+    const ingest = ragIngest({
+        modelId,
+        workspace: WORKSPACE,
+        documents,
+        progressInterval: 50,
+        onProgress: (stage, current, total) => {
+            progressCount++;
+            const pct = total > 0 ? Math.round((current / total) * 100) : 0;
+            console.log(`   [${stage}] ${current}/${total} (${pct}%)`);
+            if (!cancelled && stage === "embedding" && current > 10) {
+                console.log("\n🛑 Triggering cancellation...\n");
+                cancelled = true;
+                void cancel({ requestId: ingest.requestId });
+            }
+        },
+    });
     try {
-        await ragIngest({
-            modelId,
-            workspace: WORKSPACE,
-            documents,
-            progressInterval: 50,
-            onProgress: (stage, current, total) => {
-                progressCount++;
-                const pct = total > 0 ? Math.round((current / total) * 100) : 0;
-                console.log(`   [${stage}] ${current}/${total} (${pct}%)`);
-                // Cancel during embedding stage after a few updates
-                if (!cancelled && stage === "embedding" && current > 10) {
-                    console.log("\n🛑 Triggering cancellation...\n");
-                    cancelled = true;
-                    void cancel({ operation: "rag", workspace: WORKSPACE });
-                }
-            },
-        });
+        await ingest;
         console.log("\n⚠️  Ingest completed (cancellation didn't interrupt in time)");
     }
     catch (error) {

package/dist/examples/tools/llamacpp-tools-gemma4.d.ts

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

package/dist/examples/tools/llamacpp-tools-gemma4.js

@@ -0,0 +1,76 @@
+/**
+ * Tool-calling example using the Gemma4 native dialect.
+ *
+ * Gemma4 emits tool calls in a JS-literal format with custom quote tokens:
+ *   <|tool_call>call:NAME{key:<|"|>val<|"|>,...}<tool_call|>
+ *
+ * Reasoning output (thinking) is emitted inside <|channel>thought...<channel|>
+ * frames, which are stripped from contentDelta and forwarded as thinkingDelta
+ * when captureThinking is true.
+ *
+ * The dialect is auto-detected from the model name/path when the file name
+ * contains "gemma4" or "gemma-4". Pass toolDialect: "gemma4" explicitly to
+ * completion() if auto-detection does not pick it up for a given file name.
+ *
+ * Usage:
+ *   bun run bare:example dist/examples/tools/llamacpp-tools-gemma4.js <model-url>
+ */
+import { completion, loadModel, unloadModel, } from "@qvac/sdk";
+import { tools, mockExecute } from "./shared.js";
+// bartowski's pack tags <eos> as the EOG token (matching the base tokenizer),
+// ensuring generation stops correctly; unsloth's variant maps it differently.
+const GEMMA4_HF = "https://huggingface.co/bartowski/google_gemma-4-E2B-it-GGUF/resolve/main/google_gemma-4-E2B-it-Q4_K_M.gguf";
+const modelSrc = process.argv[2] ?? GEMMA4_HF;
+let modelId;
+try {
+    modelId = await loadModel({
+        modelSrc,
+        modelType: "llm",
+        modelConfig: { ctx_size: 4096, tools: true },
+        onProgress: (progress) => console.log(`Loading: ${progress.percentage.toFixed(1)}%`),
+    });
+    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\nFinal 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 });
+}
+catch (error) {
+    console.error("Error:", error);
+    if (modelId)
+        await unloadModel({ modelId, clearStorage: false }).catch(() => { });
+    process.exit(1);
+}

package/dist/examples/tools/llamacpp-tools-qwen35.d.ts

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

package/dist/examples/tools/llamacpp-tools-qwen35.js

@@ -0,0 +1,70 @@
+/**
+ * Tool-calling example using the Qwen3.5 dialect.
+ *
+ * Qwen3.5 emits tool calls in a Pythonic-XML format:
+ *   <tool_call><function=NAME><parameter=KEY>VALUE</parameter></function></tool_call>
+ *
+ * The dialect is auto-detected from the model name/path when the model file
+ * contains "qwen3.5", "qwen3-5", "qwen3.6", or "qwen3-6". Pass
+ * toolDialect: "qwen35" explicitly if auto-detection does not pick it up.
+ *
+ * Usage:
+ *   bun run bare:example dist/examples/tools/llamacpp-tools-qwen35.js <model-url>
+ */
+import { completion, loadModel, unloadModel, } from "@qvac/sdk";
+import { tools, mockExecute } from "./shared.js";
+const QWEN35_HF = "https://huggingface.co/unsloth/Qwen3.5-0.8B-GGUF/resolve/main/Qwen3.5-0.8B-Q8_0.gguf";
+const modelSrc = process.argv[2] ?? QWEN35_HF;
+let modelId;
+try {
+    modelId = await loadModel({
+        modelSrc,
+        modelType: "llm",
+        modelConfig: { ctx_size: 4096, tools: true },
+        onProgress: (progress) => console.log(`Loading: ${progress.percentage.toFixed(1)}%`),
+    });
+    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\nFinal 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 });
+}
+catch (error) {
+    console.error("Error:", error);
+    if (modelId)
+        await unloadModel({ modelId, clearStorage: false }).catch(() => { });
+    process.exit(1);
+}

package/dist/examples/transcription/whispercpp-microphone-conversation.d.ts

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

package/dist/examples/transcription/whispercpp-microphone-conversation.js

@@ -0,0 +1,102 @@
+/**
+ * Microphone → Whisper streaming transcription with conversation events
+ * (VAD state updates + end-of-turn detection).
+ *
+ * Demonstrates the opt-in conversation API:
+ *   transcribeStream({ modelId, emitVadEvents: true, endOfTurnSilenceMs: N })
+ *
+ * The session yields a discriminated union of events:
+ *   - { type: "text", text }                      transcript chunks
+ *   - { type: "vad", speaking, probability }      VAD state updates
+ *   - { type: "endOfTurn", silenceDurationMs }    silence boundary
+ *
+ * Speak into your mic; transcripts appear as you pause, VAD ticks while
+ * you speak, and an end-of-turn event fires after 800ms of silence.
+ * Press Ctrl+C to quit.
+ *
+ * Requirements: FFmpeg installed, microphone access.
+ */
+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";
+const SAMPLE_RATE = 16000;
+try {
+    const r = spawnSync("ffmpeg", ["-version"], { stdio: "ignore" });
+    if (r.error || r.status !== 0)
+        throw new Error("FFmpeg not found");
+}
+catch {
+    console.error("❌ Error: FFmpeg is required. Install it and try again.");
+    process.exit(1);
+}
+let modelId = null;
+let ffmpeg = null;
+async function cleanup() {
+    console.log("\n\nStopping...");
+    ffmpeg?.kill();
+    if (modelId)
+        await unloadModel({ modelId });
+    console.log("Done.");
+}
+process.on("SIGINT", () => {
+    void cleanup().finally(() => process.exit(0));
+});
+process.on("SIGTERM", () => {
+    void cleanup().finally(() => process.exit(0));
+});
+try {
+    console.log("Loading model (whisper-tiny + Silero VAD)...");
+    modelId = await loadModel({
+        modelSrc: WHISPER_TINY,
+        modelType: "whisper",
+        modelConfig: {
+            vadModelSrc: VAD_SILERO_5_1_2,
+            audio_format: "f32le",
+            strategy: "greedy",
+            n_threads: 4,
+            language: "en",
+            no_timestamps: true,
+            suppress_blank: true,
+            suppress_nst: true,
+            temperature: 0.0,
+            vad_params: {
+                threshold: 0.6,
+                min_speech_duration_ms: 250,
+                min_silence_duration_ms: 300,
+                max_speech_duration_s: 15.0,
+                speech_pad_ms: 100,
+            },
+        },
+    });
+    console.log("Model loaded.\n");
+    ffmpeg = startMicrophone({ sampleRate: SAMPLE_RATE, format: "f32le" });
+    const session = await transcribeStream({
+        modelId,
+        emitVadEvents: true,
+        endOfTurnSilenceMs: 800,
+    });
+    ffmpeg.stdout.on("data", (chunk) => session.write(chunk));
+    console.log("Listening... speak and pause to see transcripts, VAD events, and end-of-turn signals.\n");
+    let lastSpeaking = false;
+    for await (const event of session) {
+        switch (event.type) {
+            case "text":
+                console.log(`> ${event.text.trim()}`);
+                break;
+            case "vad":
+                if (event.speaking !== lastSpeaking) {
+                    console.log(`[vad] speaking=${event.speaking} probability=${event.probability.toFixed(2)}`);
+                    lastSpeaking = event.speaking;
+                }
+                break;
+            case "endOfTurn":
+                console.log(`[endOfTurn] silence ${event.silenceDurationMs}ms — turn complete\n`);
+                break;
+        }
+    }
+}
+catch (error) {
+    console.error("❌ Error:", error);
+    await cleanup();
+    process.exit(1);
+}

package/dist/examples/tts/supertonic.js

@@ -12,7 +12,7 @@ try {
             language: "en",
             ttsSpeed: 1.05,
             ttsNumInferenceSteps: 5,
-            ttsSupertonicMultilingual: false, //false for English quality.
+            ttsSupertonicMultilingual: true,
             ttsTextEncoderSrc: TTS_SUPERTONIC2_OFFICIAL_TEXT_ENCODER_SUPERTONE_FP32.src,
             ttsDurationPredictorSrc: TTS_SUPERTONIC2_OFFICIAL_DURATION_PREDICTOR_SUPERTONE_FP32.src,
             ttsVectorEstimatorSrc: TTS_SUPERTONIC2_OFFICIAL_VECTOR_ESTIMATOR_SUPERTONE_FP32.src,

package/dist/expo/plugins/withMobileBundle.d.ts

@@ -1,11 +1,27 @@
 import type { ExpoConfig } from "expo/config";
+declare const MOBILE_HOSTS: string[];
 /**
- * Expo plugin that automatically generates the mobile worker bundle during build.
+ * Expo plugin: bundle, verify, then copy the mobile worker bundle.
  *
- * Runs qvac CLI (prefers local @qvac/cli, falls back to npx).
- * Uses qvac.config.* if exists, else includes all built-in plugins.
- * Output: node_modules/<sdk-package>/dist/worker.mobile.bundle.js
+ * Flow: `bundle sdk` -> assert `qvac/worker.bundle.js` exists ->
+ * `verify bundle` -> copy to `<sdkPackageDir>/dist/worker.mobile.bundle.js`.
+ * Requires a local `@qvac/cli` install. Uses `qvac.config.*` if present.
  */
 declare function withMobileBundle(config: ExpoConfig): ExpoConfig;
+/**
+ * Resolves the qvac CLI command.
+ *
+ * Prefers local @qvac/cli installation for version consistency,
+ * falls back to npx for convenience when CLI is not installed.
+ */
+export declare function resolveCliCommand(projectRoot: string): string;
+/** Builds the `qvac verify bundle` command string (pure helper for tests). */
+export declare function buildVerifyBundleCommand(opts: {
+    cliCommand: string;
+    bundlePath: string;
+    hosts: string[];
+    configPath?: string;
+}): string;
+export { MOBILE_HOSTS };
 export default withMobileBundle;
 //# sourceMappingURL=withMobileBundle.d.ts.map