@qvac/sdk 0.9.1 → 0.10.0

package/dist/examples/delegated-inference/composite.js

@@ -2,16 +2,14 @@ import { spawn } from "child_process";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { completion, loadModel, close, LLAMA_3_2_1B_INST_Q4_0, } from "@qvac/sdk";
-// ── Config ──────────────────────────────────────────────────────────
-// Any 64-char hex string works as a topic — it's a shared secret that
-// lets the consumer discover the provider on Hyperswarm.
-const TOPIC = "66646f696865726f6569686a726530776a66646f696865726f6569686a726530";
-const PROVIDER_STARTUP_TIMEOUT_MS = 30_000;
+// The consumer connects to the provider directly via its public key over the
+// DHT (`dht.connect(publicKey)`). No topic or discovery step is involved —
+// the provider just needs its DHT server listening on its keyPair.
+const PROVIDER_STARTUP_TIMEOUT_MS = 60_000;
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const providerScript = join(__dirname, "provider.ts");
-// ── Provider lifecycle ──────────────────────────────────────────────
 function spawnProviderProcess() {
-    const child = spawn("bun", ["run", providerScript, TOPIC], {
+    const child = spawn("bun", ["run", providerScript], {
         stdio: ["pipe", "pipe", "pipe"],
     });
     child.stderr?.on("data", (chunk) => {
@@ -25,9 +23,9 @@ function terminateProvider(provider) {
     }
 }
 // The provider's Hyperswarm identity (and therefore its public key) is
-// generated at startup — it can't be known ahead of time. We parse it
-// from the provider's stdout where it prints:
-//   "🆔 Provider Public Key (unique): <hex>"
+// generated at startup — it can't be known ahead of time. We parse it from
+// the provider's stdout where it prints:
+//   "🆔 Provider Public Key: <hex>"
 function waitForProviderPublicKey(provider) {
     return new Promise((resolve, reject) => {
         let output = "";
@@ -38,7 +36,7 @@ function waitForProviderPublicKey(provider) {
             const str = chunk.toString();
             output += str;
             process.stdout.write(str);
-            const match = output.match(/Provider Public Key \(unique\): ([a-f0-9]+)/i);
+            const match = output.match(/Provider Public Key: ([a-f0-9]+)/i);
             if (match) {
                 clearTimeout(timeout);
                 resolve(match[1]);
@@ -54,14 +52,12 @@ function waitForProviderPublicKey(provider) {
         });
     });
 }
-// ── Consumer: delegated model load + completion ─────────────────────
-async function runDelegatedCompletion(topic, providerPublicKey) {
+async function runDelegatedCompletion(providerPublicKey) {
     console.log("→ Loading model via delegation...");
     const modelId = await loadModel({
         modelSrc: LLAMA_3_2_1B_INST_Q4_0,
         modelType: "llm",
         delegate: {
-            topic,
             providerPublicKey,
             timeout: 30_000,
         },
@@ -83,14 +79,12 @@ async function runDelegatedCompletion(topic, providerPublicKey) {
     const stats = await response.stats;
     console.log(`\n📊 Stats: ${JSON.stringify(stats)}`);
 }
-// ── Main ────────────────────────────────────────────────────────────
 const provider = spawnProviderProcess();
 try {
     console.log("🔧 Waiting for provider to start and announce its key...\n");
     const publicKey = await waitForProviderPublicKey(provider);
-    console.log(`\n📡 Provider ready — key: ${publicKey}`);
-    console.log(`📡 Topic: ${TOPIC}\n`);
-    await runDelegatedCompletion(TOPIC, publicKey);
+    console.log(`\n📡 Provider ready — key: ${publicKey}\n`);
+    await runDelegatedCompletion(publicKey);
     void close();
 }
 finally {

package/dist/examples/delegated-inference/consumer-profiled.js

@@ -1,27 +1,20 @@
 import { close, completion, LLAMA_3_2_1B_INST_Q4_0, loadModel, profiler, } from "@qvac/sdk";
-const topicHex = process.argv[2];
-if (!topicHex) {
-    console.error("❌ Usage: bun run consumer-profiled.ts <topic> <publicKey>");
-    process.exit(1);
-}
-const providerPublicKey = process.argv[3];
+const providerPublicKey = process.argv[2];
 if (!providerPublicKey) {
-    console.error("❌ Usage: bun run consumer-profiled.ts <topic> <publicKey>");
+    console.error("❌ Usage: bun run consumer-profiled.ts <providerPublicKey>");
     process.exit(1);
 }
 try {
     profiler.enable({ mode: "verbose", includeServerBreakdown: true });
     console.log("✓ Profiler enabled");
-    console.log(`\n📡 Topic: ${topicHex}`);
-    console.log(`🔑 Provider: ${providerPublicKey}\n`);
+    console.log(`\n🔑 Provider: ${providerPublicKey}\n`);
     console.log("→ Loading model (delegated, unary)...");
     const modelId = await loadModel({
         modelSrc: LLAMA_3_2_1B_INST_Q4_0,
         modelType: "llm",
         delegate: {
-            topic: topicHex,
             providerPublicKey,
-            timeout: 30_000,
+            timeout: 60_000,
         },
     });
     console.log(`✓ Model loaded: ${modelId}\n`);

package/dist/examples/delegated-inference/consumer.js

@@ -1,22 +1,14 @@
 import { completion, LLAMA_3_2_1B_INST_Q4_0, loadModel, close, } from "@qvac/sdk";
-// Topic hex (required)
-const topicHex = process.argv[2];
-if (!topicHex) {
-    console.error("❌ Topic hex is required. Usage: node consumer.ts <topic-hex> <provider-public-key> [consumer-seed]");
-    process.exit(1);
-}
-// Provider public key (required)
-const providerPublicKey = process.argv[3];
+const providerPublicKey = process.argv[2];
 if (!providerPublicKey) {
-    console.error("❌ Provider public key is required. Usage: node consumer.ts <topic-hex> <provider-public-key> [consumer-seed]");
+    console.error("❌ Provider public key is required. Usage: node consumer.ts <provider-public-key> [consumer-seed]");
     process.exit(1);
 }
 try {
     // Optional: Consumer seed for deterministic consumer identity (for firewall testing)
-    const consumerSeed = process.argv[4];
+    const consumerSeed = process.argv[3];
     process.env["QVAC_HYPERSWARM_SEED"] = consumerSeed;
     console.log(`🚀 Testing delegated inference`);
-    console.log(`📡 Topic: ${topicHex}`);
     console.log(`🔑 Provider: ${providerPublicKey}`);
     if (consumerSeed) {
         console.log(`🔑 Consumer seed: ${consumerSeed.substring(0, 16)}... (deterministic identity)`);
@@ -28,9 +20,12 @@ try {
         modelSrc: LLAMA_3_2_1B_INST_Q4_0,
         modelType: "llm",
         delegate: {
-            topic: topicHex,
             providerPublicKey,
-            timeout: 5_000, // Optional: 5 second timeout for delegated requests
+            // Generous timeout for the first call on a cold DHT: bootstrapping
+            // hyperdht and looking up the provider's key can take 15–45s on the
+            // very first run. Subsequent connections in the same process are
+            // sub-second because the DHT is already warm.
+            timeout: 60_000,
             fallbackToLocal: true, // Optional: Fall back to local inference if delegation fails
             // forceNewConnection: true, // Optional: Force a new connection instead of reusing cached one
         },

package/dist/examples/delegated-inference/provider.js

@@ -1,20 +1,17 @@
 import { startQVACProvider } from "@qvac/sdk";
-// Random topic if not provided
-const topic = process.argv[2] ||
-    "66646f696865726f6569686a726530776a66646f696865726f6569686a726530";
 // Optional: Seed for deterministic provider identity (64-character hex string)
-const seed = process.argv[3];
-process.env["QVAC_HYPERSWARM_SEED"] = seed;
+const seed = process.argv[2];
+if (seed) {
+    process.env["QVAC_HYPERSWARM_SEED"] = seed;
+}
 // Optional: Consumer public key for firewall (allow only this consumer)
-const allowedConsumerPublicKey = process.argv[4];
-console.log(`🚀 Starting provider service with topic: ${topic}...`);
+const allowedConsumerPublicKey = process.argv[3];
+console.log(`🚀 Starting provider service...`);
 try {
     if (allowedConsumerPublicKey) {
         console.log(`🔒 Firewall enabled: only allowing consumer ${allowedConsumerPublicKey}`);
     }
-    // Start the provider service with optional firewall and seed
     const response = await startQVACProvider({
-        topic,
         firewall: allowedConsumerPublicKey
             ? {
                 mode: "allow",
@@ -26,14 +23,13 @@ try {
     console.log("🔗 Provider is now available for delegated inference requests");
     console.log("");
     console.log("📋 Connection Details:");
-    console.log(`   📡 Topic (shared): ${topic}`);
-    console.log(`   🆔 Provider Public Key (unique): ${response.publicKey}`);
+    console.log(`   🆔 Provider Public Key: ${response.publicKey}`);
     console.log("");
     console.log("💡 Consumer command:");
-    console.log(`   node consumer.ts ${topic} ${response.publicKey}`);
+    console.log(`   node consumer.ts ${response.publicKey}`);
     console.log("");
     console.log("💡 To reproduce this provider identity:");
-    console.log(`   node provider.ts ${topic} ${seed || "<random-seed>"}`);
+    console.log(`   node provider.ts ${seed || "<random-seed>"}`);
     if (!seed) {
         console.log("   (Note: seed was random this time, set one for reproducible identity)");
     }
@@ -41,9 +37,8 @@ try {
     console.log("🔒 For firewall testing:");
     console.log("   1. Generate a consumer seed (64-char hex)");
     console.log("   2. Get consumer public key: getConsumerPublicKey(consumerSeed)");
-    console.log("   3. Restart provider with consumer public key as 4th argument");
-    console.log(`   4. Run consumer with: node consumer.ts ${topic} ${response.publicKey} <consumer-seed>`);
-    // Keep the process running
+    console.log("   3. Restart provider with consumer public key as 2nd argument");
+    console.log(`   4. Run consumer with: node consumer.ts ${response.publicKey} <consumer-seed>`);
     console.log("📡 Provider is running... Press Ctrl+C to stop");
     process.on("SIGINT", () => {
         console.log("\n🛑 Provider service stopped");

package/dist/examples/diffusion-flux2-klein-img2img.d.ts

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

package/dist/examples/diffusion-flux2-klein-img2img.js

@@ -0,0 +1,60 @@
+import { loadModel, unloadModel, diffusion, FLUX_2_KLEIN_4B_Q4_0, FLUX_2_KLEIN_4B_VAE, QWEN3_4B_Q4_K_M, } from "@qvac/sdk";
+import fs from "fs";
+import path from "path";
+// img2img with FLUX.2 [klein] split-layout — uses in-context conditioning ("flux2_flow").
+const inputPath = process.argv[2];
+const prompt = process.argv[3] || "oil painting style, vibrant colors";
+const outputDir = process.argv[4] || ".";
+const diffusionModelSrc = process.argv[5] || FLUX_2_KLEIN_4B_Q4_0;
+const llmModelSrc = process.argv[6] || QWEN3_4B_Q4_K_M;
+const vaeModelSrc = process.argv[7] || FLUX_2_KLEIN_4B_VAE;
+if (!inputPath) {
+    console.error("❌ Error: input image path is required");
+    console.error("Usage: bun run bare:example dist/examples/diffusion-flux2-klein-img2img.js <inputImage> [prompt] [outputDir] [diffusionModelSrc] [llmModelSrc] [vaeModelSrc]");
+    process.exit(1);
+}
+try {
+    console.log("Loading FLUX.2 [klein] split-layout model...");
+    const modelId = await loadModel({
+        modelSrc: diffusionModelSrc,
+        modelType: "diffusion",
+        modelConfig: {
+            device: "gpu",
+            threads: 4,
+            llmModelSrc,
+            vaeModelSrc,
+            prediction: "flux2_flow",
+        },
+        onProgress: (p) => console.log(`Loading: ${p.percentage.toFixed(1)}%`),
+    });
+    console.log(`Model loaded: ${modelId}`);
+    const init_image = new Uint8Array(fs.readFileSync(inputPath));
+    console.log(`\nTransforming "${inputPath}" with prompt: "${prompt}"`);
+    const { progressStream, outputs, stats } = diffusion({
+        modelId,
+        prompt,
+        init_image,
+        steps: 20,
+        guidance: 3.5,
+        cfg_scale: 1,
+        seed: -1,
+    });
+    for await (const { step, totalSteps } of progressStream) {
+        process.stdout.write(`\rStep ${step}/${totalSteps}`);
+    }
+    console.log();
+    const buffers = await outputs;
+    for (let i = 0; i < buffers.length; i++) {
+        const outputPath = path.join(outputDir, `flux2_img2img_${i}.png`);
+        fs.writeFileSync(outputPath, buffers[i]);
+        console.log(`Saved: ${outputPath}`);
+    }
+    console.log("\nStats:", await stats);
+    await unloadModel({ modelId, clearStorage: false });
+    console.log("Done.");
+    process.exit(0);
+}
+catch (error) {
+    console.error("❌ Error:", error);
+    process.exit(1);
+}

package/dist/examples/diffusion-flux2-klein.js

@@ -28,6 +28,7 @@ const { progressStream, outputs, stats } = diffusion({
     height: 512,
     steps: 20,
     guidance: 3.5,
+    cfg_scale: 1,
     seed: -1,
 });
 for await (const { step, totalSteps } of progressStream) {

package/dist/examples/diffusion-img2img.d.ts

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

package/dist/examples/diffusion-img2img.js

@@ -0,0 +1,49 @@
+import { loadModel, unloadModel, diffusion, SD_V2_1_1B_Q8_0 } from "@qvac/sdk";
+import fs from "fs";
+import path from "path";
+// img2img example — transforms an input image guided by a text prompt.
+const inputPath = process.argv[2];
+const prompt = process.argv[3] || "oil painting style, vibrant colors";
+const outputDir = process.argv[4] || ".";
+const modelSrc = process.argv[5] || SD_V2_1_1B_Q8_0;
+if (!inputPath) {
+    console.error("❌ Error: input image path is required");
+    console.error("Usage: bun run bare:example dist/examples/diffusion-img2img.js <inputImage> [prompt] [outputDir] [modelSrc]");
+    process.exit(1);
+}
+try {
+    console.log("Loading diffusion model...");
+    const modelId = await loadModel({
+        modelSrc,
+        modelType: "diffusion",
+    });
+    console.log(`Model loaded: ${modelId}`);
+    const init_image = new Uint8Array(fs.readFileSync(inputPath));
+    console.log(`\nTransforming "${inputPath}" with prompt: "${prompt}"`);
+    const { progressStream, outputs, stats } = diffusion({
+        modelId,
+        prompt,
+        init_image,
+        strength: 0.5,
+        steps: 30,
+        seed: -1,
+    });
+    for await (const { step, totalSteps } of progressStream) {
+        process.stdout.write(`\rStep ${step}/${totalSteps}`);
+    }
+    console.log();
+    const buffers = await outputs;
+    for (let i = 0; i < buffers.length; i++) {
+        const outputPath = path.join(outputDir, `img2img_${i}.png`);
+        fs.writeFileSync(outputPath, buffers[i]);
+        console.log(`Saved: ${outputPath}`);
+    }
+    console.log("\nStats:", await stats);
+    await unloadModel({ modelId, clearStorage: false });
+    console.log("Done.");
+    process.exit(0);
+}
+catch (error) {
+    console.error("❌ Error:", error);
+    process.exit(1);
+}

package/dist/examples/diffusion-txt2img.js

@@ -21,7 +21,8 @@ const { progressStream, outputs, stats } = diffusion({
     width: 512,
     height: 512,
     steps: 20,
-    cfg_scale: 7.0,
+    guidance: 3.5,
+    cfg_scale: 1,
     seed: -1,
 });
 for await (const { step, totalSteps } of progressStream) {

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

@@ -11,8 +11,8 @@ try {
         },
     });
     console.log("🧠 Testing KV Cache functionality...\n");
-    // First conversation with cache enabled
-    console.log("📝 First conversation (building cache):");
+    // First conversation with auto-keyed cache enabled
+    console.log("📝 First conversation (building cache for the next turn):");
     const history1 = [
         { role: "user", content: "What is the capital of France?" },
     ];
@@ -22,24 +22,23 @@ try {
         stream: true,
         kvCache: true,
     }); // kvCache = true
-    let response1 = "";
     for await (const token of result1.tokenStream) {
-        response1 += token;
         process.stdout.write(token);
     }
-    const stats1 = await result1.stats;
+    const final1 = await result1.final;
+    const stats1 = final1.stats;
     console.log(`\n⏱️  First completion stats: ${JSON.stringify(stats1)}\n`);
-    // Continue conversation (should reuse cache from previous conversation)
-    console.log("🔄 Continuing conversation (reusing cache):");
+    // Continue conversation (should reuse the completed first-turn cache).
+    console.log("🔄 Continuing conversation (reusing previous turn cache):");
     const history2 = [
         { role: "user", content: "What is the capital of France?" },
-        { role: "assistant", content: response1.trim() },
+        { role: "assistant", content: final1.cacheableAssistantContent ?? final1.contentText },
         { role: "user", content: "What about Germany?" },
     ];
-    // This should:
-    // 1. Find existing cache from [user: "What is the capital of France?"] (history minus last message)
-    // 2. Load that cache and process the new "What about Germany?" message
-    // 3. Save the updated cache and rename it to include all messages
+    // Auto-keyed caching should:
+    // 1. Find the cache saved after turn 1 under [user, assistant]
+    // 2. Load that cache and process only the new "What about Germany?" user turn
+    // 3. Save the updated cache and rename it to include the new assistant response
     const result2 = completion({
         modelId,
         history: history2,

package/dist/examples/llamacpp-cache.d.ts

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

package/dist/examples/llamacpp-cache.js

@@ -0,0 +1,107 @@
+import { completion, deleteCache, LLAMA_3_2_1B_INST_Q4_0, loadModel, unloadModel, VERBOSITY, } from "@qvac/sdk";
+const sharedCacheKey = "llamacpp-cache-demo-shared";
+const isolatedCacheKey = "llamacpp-cache-demo-isolated";
+const systemPrompt = {
+    role: "system",
+    content: "You are a concise travel assistant. Keep track of the user's preferences across turns.",
+};
+function printStats(stats) {
+    console.log("\nPerformance Stats:", {
+        timeToFirstToken: stats?.timeToFirstToken,
+        tokensPerSecond: stats?.tokensPerSecond,
+        cacheTokens: stats?.cacheTokens,
+    });
+}
+async function runCachedCompletion(params) {
+    console.log(`\n=== ${params.label} ===`);
+    console.log(`Cache key: ${params.kvCache || "disabled"}`);
+    console.log("AI Response:");
+    const result = completion({
+        modelId: params.modelId,
+        history: params.history,
+        stream: true,
+        kvCache: params.kvCache,
+    });
+    let text = "";
+    for await (const token of result.tokenStream) {
+        text += token;
+        process.stdout.write(token);
+    }
+    const stats = await result.stats;
+    printStats(stats);
+    return { text, stats };
+}
+let modelId;
+try {
+    console.log("Loading llama.cpp model with cache support...");
+    modelId = await loadModel({
+        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
+        modelType: "llm",
+        modelConfig: {
+            ctx_size: 4096,
+            verbosity: VERBOSITY.ERROR,
+        },
+        onProgress: (progress) => {
+            console.log(`Loading: ${progress.percentage.toFixed(1)}%`);
+        },
+    });
+    console.log(`Model loaded successfully. Model ID: ${modelId}`);
+    await deleteCache({ kvCacheKey: sharedCacheKey });
+    await deleteCache({ kvCacheKey: isolatedCacheKey });
+    const firstUserMessage = {
+        role: "user",
+        content: "I am planning a weekend in Lisbon. I prefer museums, seafood, and walking routes. Suggest a day plan in 3 bullets.",
+    };
+    const firstTurn = await runCachedCompletion({
+        label: "Turn 1: create a named cache",
+        modelId,
+        kvCache: sharedCacheKey,
+        history: [systemPrompt, firstUserMessage],
+    });
+    await runCachedCompletion({
+        label: "Turn 2: reuse the same cache key",
+        modelId,
+        kvCache: sharedCacheKey,
+        history: [
+            systemPrompt,
+            firstUserMessage,
+            { role: "assistant", content: firstTurn.text.trim() },
+            {
+                role: "user",
+                content: "Now revise the plan for a rainy day, but keep the same preferences.",
+            },
+        ],
+    });
+    await runCachedCompletion({
+        label: "Turn 3: use a different cache key for an isolated session",
+        modelId,
+        kvCache: isolatedCacheKey,
+        history: [
+            systemPrompt,
+            {
+                role: "user",
+                content: "I am planning a weekend in Berlin. I prefer nightlife and late starts. Suggest a day plan in 3 bullets.",
+            },
+        ],
+    });
+    console.log("\nSummary:");
+    console.log(`- Reusing "${sharedCacheKey}" keeps conversation context across turns.`);
+    console.log(`- Switching to "${isolatedCacheKey}" starts a separate cache session.`);
+    console.log('- Use deleteCache({ kvCacheKey: "your-session" }) to clear a saved session.');
+    await deleteCache({ kvCacheKey: sharedCacheKey });
+    await deleteCache({ kvCacheKey: isolatedCacheKey });
+    await unloadModel({ modelId, clearStorage: false });
+    process.exit(0);
+}
+catch (error) {
+    if (modelId) {
+        try {
+            await unloadModel({ modelId, clearStorage: false });
+        }
+        catch (cleanupError) {
+            console.warn("⚠️ cleanup failed:", cleanupError);
+        }
+    }
+    console.error("❌ Error:", error);
+    process.exit(1);
+}

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

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

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

@@ -0,0 +1,144 @@
+/**
+ * Dynamic-tools mode example.
+ *
+ * In `dynamic` mode each user prompt can carry its own tool set: the addon
+ * anchors tools after the last user message, runs the tool-call chain, then
+ * trims the tools + chain output from the kv-cache so a later turn can ship
+ * a different tool list without poisoning the cache. Compare with
+ * `llamacpp-native-tools.ts`, which uses the default `static` mode where
+ * one shared tool set lives at the top of the session.
+ *
+ * Run with:
+ *   bun run build
+ *   bun run bare:example dist/examples/llamacpp-dynamic-tools.js
+ */
+import { z } from "zod";
+import { completion, loadModel, unloadModel, QWEN3_1_7B_INST_Q4, } from "@qvac/sdk";
+const weatherSchema = z.object({
+    city: z.string().describe("City name"),
+});
+const horoscopeSchema = z.object({
+    sign: z.string().describe("An astrological sign, e.g. Taurus or Aquarius"),
+});
+const dateSchema = z.object({});
+const toolSchemas = {
+    get_weather: weatherSchema,
+    get_horoscope: horoscopeSchema,
+    get_date: dateSchema,
+};
+const weatherTools = [
+    {
+        name: "get_weather",
+        description: "Get current weather for a city",
+        parameters: weatherSchema,
+    },
+];
+const horoscopeTools = [
+    {
+        name: "get_horoscope",
+        description: "Get today's horoscope for an astrological sign",
+        parameters: horoscopeSchema,
+    },
+];
+const dateTools = [
+    {
+        name: "get_date",
+        description: "Get today's date",
+        parameters: dateSchema,
+    },
+];
+function executeToolCall(call) {
+    if (call.name === "get_weather") {
+        const args = call.arguments;
+        return `The weather in ${args.city} is rainy, 8°C with heavy clouds.`;
+    }
+    if (call.name === "get_horoscope") {
+        const args = call.arguments;
+        return `Horoscope for ${args.sign}: a great day for new beginnings.`;
+    }
+    if (call.name === "get_date") {
+        return new Date().toISOString().slice(0, 10);
+    }
+    return `Unknown tool: ${call.name}`;
+}
+async function chatTurn({ modelId, kvCache, history, tools }) {
+    const result = completion({
+        modelId,
+        history,
+        tools,
+        kvCache,
+        stream: true,
+    });
+    const tokensTask = (async () => {
+        for await (const token of result.tokenStream) {
+            process.stdout.write(token);
+        }
+    })();
+    const toolEventsTask = (async () => {
+        for await (const evt of result.toolCallStream) {
+            console.log(`\n→ tool call: ${evt.call.name}(${JSON.stringify(evt.call.arguments)})`);
+        }
+    })();
+    await Promise.all([tokensTask, toolEventsTask]);
+    const text = await result.text;
+    const toolCalls = await result.toolCalls;
+    if (toolCalls.length === 0) {
+        history.push({ role: "assistant", content: text });
+        return;
+    }
+    for (const call of toolCalls) {
+        const schema = toolSchemas[call.name];
+        if (schema) {
+            const parsed = schema.safeParse(call.arguments);
+            if (!parsed.success) {
+                console.warn(`   ✗ validation failed for ${call.name}:`, parsed.error);
+            }
+        }
+    }
+    history.push({ role: "assistant", content: text });
+    for (const call of toolCalls) {
+        history.push({ role: "tool", content: executeToolCall(call) });
+    }
+    // Follow-up turn so the model can incorporate the tool results.
+    await chatTurn({ modelId, kvCache, history, tools });
+}
+async function main() {
+    const modelId = await loadModel({
+        modelSrc: QWEN3_1_7B_INST_Q4,
+        modelType: "llm",
+        modelConfig: {
+            ctx_size: 4096,
+            tools: true,
+            toolsMode: "dynamic",
+        },
+        onProgress: (progress) => console.log(`Loading: ${progress.percentage.toFixed(1)}%`),
+    });
+    console.log(`✅ Model loaded: ${modelId}`);
+    const kvCache = `dynamic-tools-${Date.now()}`;
+    const history = [
+        {
+            role: "system",
+            content: "You are a helpful assistant that uses tools when they are available. " +
+                "User's cat is named Windy and dog is named Butch.",
+        },
+    ];
+    // Turn 1 — only weather tools available.
+    history.push({ role: "user", content: "What's the weather in Tokyo?" });
+    console.log("\n🤖 Turn 1 (tools=weather):\n");
+    await chatTurn({ modelId, kvCache, history, tools: weatherTools });
+    // Turn 2 — same session, swap to horoscope tools. Dynamic mode lets the
+    // model see a different tool set without invalidating the kv-cache.
+    history.push({ role: "user", content: "Now check my horoscope for Aquarius." });
+    console.log("\n\n🤖 Turn 2 (tools=horoscope):\n");
+    await chatTurn({ modelId, kvCache, history, tools: horoscopeTools });
+    // Turn 3 — swap to a parameterless tool to confirm empty-arg flows work.
+    history.push({ role: "user", content: "What's today's date?" });
+    console.log("\n\n🤖 Turn 3 (tools=date):\n");
+    await chatTurn({ modelId, kvCache, history, tools: dateTools });
+    console.log("\n\n🎉 Done.");
+    await unloadModel({ modelId, clearStorage: false });
+}
+main().catch((err) => {
+    console.error("❌ Error:", err);
+    process.exit(1);
+});