@qvac/sdk 0.3.0 → 0.4.1

package/dist/examples/llamacpp-hyperdrive.js

@@ -31,7 +31,6 @@ try {
     console.log("\n📊 Performance Stats:", stats);
     // Change `clearStorage: true` to delete cached model files
     await unloadModel({ modelId, clearStorage: false });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

package/dist/examples/llamacpp-multimodal.js

@@ -54,7 +54,6 @@ try {
     console.log("\n📊 Performance Stats:", stats2);
     console.log("--------------------------------");
     await unloadModel({ modelId, clearStorage: false });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

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

@@ -1,62 +1,144 @@
-import { completion, loadModel, unloadModel } from "@qvac/sdk";
-// Get GGUF file path from command line arguments
-const ggufPath = process.argv[2];
-if (!ggufPath) {
-    console.error("❌ Error: Please provide the path to a GGUF file as the first argument");
-    console.error("Usage: bun run examples/llamacpp-native-tools.ts <path-to-gguf-file>");
-    process.exit(1);
-}
-// Tool definition
+import { z } from "zod";
+import { completion, loadModel, unloadModel, QWEN_3_1_7B_INST_Q4, } from "../index.js";
+// Define Zod schemas for tool parameters
+const weatherSchema = z.object({
+    city: z.string().describe("City name"),
+    country: z.string().describe("Country code").optional(),
+});
+const horoscopeSchema = z.object({
+    sign: z.string().describe("An astrological sign like Taurus or Aquarius"),
+});
+// Map tool names to their schemas for runtime validation
+const toolSchemas = {
+    get_weather: weatherSchema,
+    get_horoscope: horoscopeSchema,
+};
+// Simple tool definitions - just name, description, and Zod schema!
 const tools = [
     {
-        type: "function",
+        name: "get_weather",
+        description: "Get current weather for a city",
+        parameters: weatherSchema,
+    },
+    {
         name: "get_horoscope",
-        description: "Get today's horoscope for an astrological sign.",
-        parameters: {
-            type: "object",
-            properties: {
-                sign: {
-                    type: "string",
-                    description: "An astrological sign like Taurus or Aquarius",
-                },
-            },
-            required: ["sign"],
-        },
+        description: "Get today's horoscope for an astrological sign",
+        parameters: horoscopeSchema,
     },
 ];
-// @ts-expect-error - Function will be used in future implementation
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-function getHoroscope(sign) {
-    return sign + " Next Tuesday you will befriend a baby otter.";
-}
-console.log(`🚀 Loading GGUF model from: ${ggufPath}`);
 try {
-    // Load model from provided file path
+    // Load model from provided file path with tools support enabled
     const modelId = await loadModel({
-        modelSrc: ggufPath,
+        modelSrc: QWEN_3_1_7B_INST_Q4,
         modelType: "llm",
         modelConfig: {
             ctx_size: 4096,
+            tools: true, // Enable tools support
         },
         onProgress: (progress) => console.log(`Loading: ${progress.percentage.toFixed(1)}%`),
     });
     console.log(`✅ Model loaded successfully! Model ID: ${modelId}`);
     // Create conversation history
     const history = [
-        { role: "user", content: "Explain Bitcoin in 3 key points" },
+        {
+            role: "system",
+            content: "You are a helpful assistant that can use tools to get the weather and horoscope.",
+        },
+        {
+            role: "user",
+            content: "What's the weather in Tokyo and my horoscope for Aquarius?",
+        },
     ];
     console.log("\n🤖 AI Response:");
-    process.stdout.write(""); // Start response on new line
-    // Stream completion
+    console.log("(Streaming with tool definitions in prompt)\n");
     const result = completion({ modelId, history, stream: true, tools });
-    for await (const token of result.tokenStream) {
-        process.stdout.write(token);
-    }
+    // Consume token stream
+    const tokensTask = (async () => {
+        for await (const token of result.tokenStream) {
+            process.stdout.write(token);
+        }
+    })();
+    // Consume tool call events
+    const toolsTask = (async () => {
+        for await (const evt of result.toolCallStream) {
+            if (evt.type === "toolCall") {
+                console.log(`\n\n→ Tool Call Detected: ${evt.call.name}(${JSON.stringify(evt.call.arguments)})`);
+                console.log(`   ID: ${evt.call.id}`);
+            }
+            else if (evt.type === "toolCallError") {
+                console.warn(`\n⚠️  Tool Error: ${evt.error.message}`);
+                console.warn(`   Code: ${evt.error.code}`);
+            }
+        }
+    })();
+    await Promise.all([tokensTask, toolsTask]);
     const stats = await result.stats;
+    const toolCalls = await result.toolCalls;
+    console.log("\n\n📋 Parsed Tool Calls:");
+    if (toolCalls.length > 0) {
+        for (const call of toolCalls) {
+            console.log(`  - ${call.name}(${JSON.stringify(call.arguments)})`);
+            const schema = toolSchemas[call.name];
+            if (schema) {
+                const validated = schema.safeParse(call.arguments);
+                if (validated.success) {
+                    console.log(`    ✓ Arguments validated with Zod`);
+                }
+                else {
+                    console.log(`    ✗ Validation failed:`, validated.error);
+                }
+            }
+        }
+    }
+    else {
+        console.log("  No tool calls detected in response");
+    }
     console.log("\n📊 Performance Stats:", stats);
+    // Execute tool calls and send results back to the model
+    if (toolCalls.length > 0) {
+        console.log("\n\n🔧 Simulating Tool Execution...");
+        // Simulate tool execution (in a real app, you'd call actual APIs)
+        const toolResults = toolCalls.map((call) => {
+            let result = "";
+            if (call.name === "get_weather") {
+                const args = call.arguments;
+                result = `The weather in ${args.city} is sunny, 22°C with light clouds.`;
+            }
+            else if (call.name === "get_horoscope") {
+                const args = call.arguments;
+                result = `Horoscope for ${args.sign}: Today is a great day for new beginnings and creative endeavors!`;
+            }
+            console.log(`  ✓ ${call.name}: ${result}`);
+            return { toolCallId: call.id, result };
+        });
+        // Add tool results to conversation history
+        history.push({
+            role: "assistant",
+            content: await result.text,
+        });
+        // Add tool results as tool messages
+        for (const toolResult of toolResults) {
+            history.push({
+                role: "tool",
+                content: toolResult.result,
+            });
+        }
+        // Send follow-up question with tool results
+        console.log("\n\n🤖 Follow-up Response with Tool Results:");
+        const followUpResult = completion({
+            modelId,
+            history,
+            stream: true,
+            tools,
+        });
+        for await (const token of followUpResult.tokenStream) {
+            process.stdout.write(token);
+        }
+        const followUpStats = await followUpResult.stats;
+        console.log("\n\n📊 Follow-up Stats:", followUpStats);
+    }
     console.log("\n\n🎉 Completed!");
     await unloadModel({ modelId, clearStorage: false });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

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

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

package/dist/examples/llamacpp-sharded.js

@@ -0,0 +1,44 @@
+import { completion, loadModel, unloadModel, VERBOSITY, LLAMA_3_2_1B_INST_Q4_0_SHARD, } from "@qvac/sdk";
+try {
+    const modelId = await loadModel({
+        modelSrc: LLAMA_3_2_1B_INST_Q4_0_SHARD,
+        modelType: "llm",
+        modelConfig: {
+            device: "gpu",
+            ctx_size: 2048,
+            verbosity: VERBOSITY.SILENT,
+        },
+        onProgress: (progress) => {
+            if (progress.shardInfo) {
+                const { shardInfo } = progress;
+                console.log(`📥 Downloading ${shardInfo.shardName} (${shardInfo.currentShard}/${shardInfo.totalShards})\n` +
+                    `   File: ${progress.percentage.toFixed(1)}% (${(progress.downloaded / 1024 / 1024).toFixed(2)}MB / ${(progress.total / 1024 / 1024).toFixed(2)}MB)\n` +
+                    `   Overall: ${shardInfo.overallPercentage.toFixed(1)}% (${(shardInfo.overallDownloaded / 1024 / 1024).toFixed(2)}MB / ${(shardInfo.overallTotal / 1024 / 1024).toFixed(2)}MB)`);
+            }
+            else {
+                // Fallback for non-sharded models
+                console.log(`📥 Progress: ${progress.percentage.toFixed(1)}% ` +
+                    `(${(progress.downloaded / 1024 / 1024).toFixed(2)}MB / ${(progress.total / 1024 / 1024).toFixed(2)}MB)`);
+            }
+        },
+    });
+    const history = [
+        {
+            role: "user",
+            content: "What are the benefits of sharding large language models? Use emojis in your response.",
+        },
+    ];
+    const result = completion({ modelId, history, stream: true });
+    console.log("\n🤖 Model response:");
+    for await (const token of result.tokenStream) {
+        process.stdout.write(token);
+    }
+    const stats = await result.stats;
+    console.log("\n\n📊 Performance Stats:", stats);
+    await unloadModel({ modelId, clearStorage: false });
+    process.exit(0);
+}
+catch (error) {
+    console.error("❌ Error:", error);
+    process.exit(1);
+}

package/dist/examples/multi-model-demo.js

@@ -67,7 +67,6 @@ try {
     console.log("📊 Bob Stats: ", await bobResponse2.stats);
     await unloadModel({ modelId: alice, clearStorage: false });
     await unloadModel({ modelId: bob, clearStorage: false });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

package/dist/examples/parallel-download.js

@@ -1,4 +1,4 @@
-import { LLAMA_3_2_1B_INST_Q4_0, downloadAsset, WHISPER_LARGE_3, } from "@qvac/sdk";
+import { LLAMA_3_2_1B_INST_Q4_0, downloadAsset, WHISPER_LARGE_3, close, } from "@qvac/sdk";
 try {
     const llamaDownloadPromise = downloadAsset({
         assetSrc: LLAMA_3_2_1B_INST_Q4_0,
@@ -13,7 +13,7 @@ try {
         },
     });
     await Promise.all([llamaDownloadPromise, whisperDownloadPromise]);
-    process.exit(0);
+    void close();
 }
 catch (error) {
     console.error("❌ Error:", error);

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

@@ -122,7 +122,6 @@ try {
         console.log();
     }
     await unloadModel({ modelId });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

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

@@ -99,7 +99,6 @@ try {
         console.log("\n🗑️  Deleted one medical chunk");
     }
     await unloadModel({ modelId });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

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

@@ -42,7 +42,6 @@ try {
         console.log();
     });
     await unloadModel({ modelId });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

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

@@ -87,7 +87,6 @@ try {
         console.log();
     });
     await unloadModel({ modelId });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

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

@@ -99,7 +99,6 @@ try {
     });
     await unloadModel({ modelId });
     db.close();
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

package/dist/examples/text-to-speech.d.ts

@@ -0,0 +1,3 @@
+export declare function createWav(audioBuffer: number[], sampleRate?: number, filename?: string): void;
+export declare function playAudio(audioBuffer: Buffer): void;
+//# sourceMappingURL=text-to-speech.d.ts.map

package/dist/examples/text-to-speech.js

@@ -0,0 +1,137 @@
+import { loadModel, textToSpeech, unloadModel, TTS_PIPER_NORMAN_EN_US_ONNX_MEDIUM, TTS_PIPER_NORMAN_EN_US_ONNX_MEDIUM_CONFIG, } from "@qvac/sdk";
+import { writeFileSync, unlinkSync } from "fs";
+import { spawnSync } from "child_process";
+import { platform } from "os";
+// Get eSpeakDataPath from command line arguments or use default
+const eSpeakDataPath = process.argv[2];
+console.log(`Using eSpeak data path: ${eSpeakDataPath}`);
+if (!eSpeakDataPath) {
+    console.error("eSpeakDataPath is required");
+    process.exit(1);
+}
+try {
+    const modelId = await loadModel({
+        modelSrc: TTS_PIPER_NORMAN_EN_US_ONNX_MEDIUM,
+        modelType: "tts",
+        configSrc: TTS_PIPER_NORMAN_EN_US_ONNX_MEDIUM_CONFIG,
+        eSpeakDataPath,
+        modelConfig: {
+            language: "en",
+        },
+        onProgress: (progress) => {
+            console.log(progress);
+        },
+    });
+    console.log(`Model loaded: ${modelId}`);
+    // Test TTS
+    console.log("🎵 Testing Text-to-Speech...");
+    const result = textToSpeech({
+        modelId,
+        text: `QVAC SDK is the canonical entry point to QVAC. Written in TypeScript, it provides all QVAC capabilities through a unified interface while also abstracting away the complexity of running your application in a JS environment other than Bare. Supported JS environments include Bare, Node.js, Expo and Bun.`,
+        inputType: "text",
+        stream: false,
+    });
+    const audioBuffer = await result.buffer;
+    console.log(`TTS complete. Total bytes: ${audioBuffer.length}`);
+    // Save and play audio
+    console.log("💾 Saving audio to file...");
+    createWav(audioBuffer, 22050, "tts-output.wav");
+    console.log("✅ Audio saved to tts-output.wav");
+    console.log("🔊 Playing audio...");
+    const audioData = int16ArrayToBuffer(audioBuffer);
+    const wavBuffer = Buffer.concat([
+        createWavHeader(audioData.length),
+        audioData,
+    ]);
+    playAudio(wavBuffer);
+    console.log("✅ Audio playback complete");
+    // Unload the model
+    await unloadModel({ modelId });
+    console.log("Model unloaded");
+}
+catch (error) {
+    console.error("❌ Error:", error);
+    process.exit(1);
+}
+// Function to create WAV header for 16-bit PCM audio
+function createWavHeader(dataLength, sampleRate = 22050) {
+    const header = Buffer.alloc(44);
+    // RIFF header
+    header.write("RIFF", 0);
+    header.writeUInt32LE(36 + dataLength, 4);
+    header.write("WAVE", 8);
+    // fmt chunk
+    header.write("fmt ", 12);
+    header.writeUInt32LE(16, 16); // fmt chunk size
+    header.writeUInt16LE(1, 20); // PCM format
+    header.writeUInt16LE(1, 22); // mono
+    header.writeUInt32LE(sampleRate, 24);
+    header.writeUInt32LE(sampleRate * 2, 28); // byte rate
+    header.writeUInt16LE(2, 32); // block align
+    header.writeUInt16LE(16, 34); // bits per sample
+    // data chunk
+    header.write("data", 36);
+    header.writeUInt32LE(dataLength, 40);
+    return header;
+}
+// Function to convert Int16Array to Buffer
+function int16ArrayToBuffer(int16Array) {
+    const buffer = Buffer.alloc(int16Array.length * 2);
+    for (let i = 0; i < int16Array.length; i++) {
+        const value = int16Array[i] ?? 0;
+        buffer.writeInt16LE(value, i * 2);
+    }
+    return buffer;
+}
+// Function to create and save WAV file (similar to reference implementation)
+export function createWav(audioBuffer, sampleRate = 22050, filename = "output.wav") {
+    const audioData = int16ArrayToBuffer(audioBuffer);
+    const wavHeader = createWavHeader(audioData.length, sampleRate);
+    const wavFile = Buffer.concat([wavHeader, audioData]);
+    writeFileSync(filename, wavFile);
+    console.log(`WAV file saved as: ${filename}`);
+}
+// Function to play audio using system audio players
+export function playAudio(audioBuffer) {
+    const currentPlatform = platform();
+    const tempFile = `/tmp/audio-${Date.now()}.wav`;
+    // Write audio buffer to temporary file
+    writeFileSync(tempFile, audioBuffer);
+    let audioPlayer;
+    let args;
+    switch (currentPlatform) {
+        case "darwin":
+            audioPlayer = "afplay";
+            args = [tempFile];
+            break;
+        case "linux":
+            audioPlayer = "aplay";
+            args = [tempFile];
+            break;
+        case "win32":
+            audioPlayer = "powershell";
+            args = [
+                "-Command",
+                `Add-Type -AssemblyName presentationCore; (New-Object Media.SoundPlayer).LoadStream([System.IO.File]::ReadAllBytes('${tempFile}')).PlaySync()`,
+            ];
+            break;
+        default:
+            audioPlayer = "aplay";
+            args = [tempFile];
+    }
+    const result = spawnSync(audioPlayer, args, {
+        stdio: ["inherit", "inherit", "inherit"],
+    });
+    try {
+        unlinkSync(tempFile);
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+    if (result.error) {
+        throw new Error(`Audio player failed: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(`Audio player exited with code ${result.status}`);
+    }
+}

package/dist/examples/translation/translation-indic.js

@@ -1,4 +1,7 @@
 import { loadModel, translate, unloadModel, MARIAN_EN_HI_INDIC_1B_Q4_0, } from "@qvac/sdk";
+// NOTE: @qvac/translation-nmtcpp version 0.1.6 does not work well with IndicTrans models
+// This example is expected to fail
+// A fix is in progress for future releases
 try {
     const modelId = await loadModel({
         modelSrc: MARIAN_EN_HI_INDIC_1B_Q4_0,
@@ -22,7 +25,6 @@ try {
     const translatedText = await result.text;
     console.log(`Translated text EN -> HI: ${text} -> "${translatedText}"`);
     await unloadModel({ modelId });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

package/dist/examples/translation/translation-llm-context.js

@@ -22,7 +22,6 @@ try {
     const translatedTextExplicit = await resultExplicit.text;
     console.log(`${engText} -> "${translatedTextExplicit}"`); // "banco" (not "orilla")
     await unloadModel({ modelId, clearStorage: false });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

package/dist/examples/translation/translation-llm.js

@@ -1,4 +1,4 @@
-import { translate, loadModel, SALAMANDRATA_2B_INST_Q4 } from "@qvac/sdk";
+import { translate, loadModel, unloadModel, SALAMANDRATA_2B_INST_Q4, } from "@qvac/sdk";
 try {
     const modelId = await loadModel({
         modelSrc: SALAMANDRATA_2B_INST_Q4,
@@ -30,7 +30,7 @@ try {
     const translatedTextAutodetect = await resultAutodetect.text;
     console.log(`Explicit source: ${engText} -> "${translatedTextExplicit}"`);
     console.log(`Autodetected source: ${espText} -> "${translatedTextAutodetect}"`);
-    process.exit(0);
+    await unloadModel({ modelId, clearStorage: false });
 }
 catch (error) {
     console.error("❌ Error:", error);

package/dist/examples/translation/translation-opus.js

@@ -6,6 +6,9 @@ try {
         modelConfig: {
             from: "en",
             to: "it",
+            temperature: 0.2,
+            norepeatngramsize: 3,
+            lengthpenalty: 1.2,
         },
         onProgress: (progress) => {
             console.log(progress);
@@ -22,7 +25,6 @@ try {
     const translatedText = await result.text;
     console.log(`Translated text EN -> IT: ${text} -> "${translatedText}"`);
     await unloadModel({ modelId });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

package/dist/examples/translation/translation-stream.js

@@ -27,7 +27,6 @@ try {
         console.log(`Processing stats:`, stats);
     }
     await unloadModel({ modelId, clearStorage: false });
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

package/dist/examples/whispercpp-filesystem.js

@@ -15,11 +15,39 @@ try {
         modelType: "whisper",
         vadModelSrc: VAD_SILERO_5_1_2,
         modelConfig: {
-            mode: "caption",
-            output_format: "plaintext",
-            min_seconds: 2,
-            max_seconds: 6,
             audio_format: "f32le",
+            // Sampling strategy
+            strategy: "greedy",
+            n_threads: 4,
+            // Transcription options
+            language: "en",
+            translate: false,
+            no_timestamps: false,
+            single_segment: false,
+            print_timestamps: true,
+            token_timestamps: true,
+            // Quality settings
+            temperature: 0.0,
+            suppress_blank: true,
+            suppress_nst: true,
+            // Advanced tuning
+            entropy_thold: 2.4,
+            logprob_thold: -1.0,
+            // VAD configuration
+            vad_params: {
+                threshold: 0.35,
+                min_speech_duration_ms: 200,
+                min_silence_duration_ms: 150,
+                max_speech_duration_s: 30.0,
+                speech_pad_ms: 600,
+                samples_overlap: 0.3,
+            },
+            // Context parameters for GPU
+            contextParams: {
+                use_gpu: true,
+                flash_attn: true,
+                gpu_device: 0,
+            },
         },
         onProgress: (progress) => {
             console.log(progress);
@@ -35,7 +63,6 @@ try {
     console.log("🧹 Unloading Whisper model...");
     await unloadModel({ modelId });
     console.log("✅ Whisper model unloaded successfully");
-    process.exit(0);
 }
 catch (error) {
     console.error("❌ Error:", error);

package/dist/examples/whispercpp-microphone-record.js

@@ -1,4 +1,4 @@
-import { loadModel, downloadAsset, unloadModel, transcribe, transcribeStream, WHISPER_TINY, VAD_SILERO_5_1_2, } from "@qvac/sdk";
+import { loadModel, unloadModel, transcribe, transcribeStream, WHISPER_TINY, VAD_SILERO_5_1_2, } from "@qvac/sdk";
 import { spawn, spawnSync } from "child_process";
 import * as readline from "readline";
 import { platform } from "os";
@@ -239,7 +239,6 @@ function startInteractiveSession(rl, modelId) {
         if (ffmpeg) {
             ffmpeg.kill();
         }
-        process.exit(0);
     });
     rl.prompt();
 }
@@ -266,18 +265,20 @@ async function main() {
         console.log("   - FFmpeg installed");
         // Check FFmpeg availability
         checkFFmpegAvailable();
-        // Download VAD model (asset download only - doesn't load into memory)
-        console.log("\n📥 Ensuring VAD model is available...");
-        await downloadAsset({ assetSrc: VAD_SILERO_5_1_2 });
         // Load the Whisper model with VAD
-        console.log("\n📥 Loading Whisper model...");
+        console.log("\n📥 Loading Whisper model with VAD...");
         modelId = await loadModel({
             modelSrc: WHISPER_TINY,
             modelType: "whisper",
+            vadModelSrc: VAD_SILERO_5_1_2,
             modelConfig: {
-                mode: "caption",
-                update_frequency: "on_end",
                 audio_format: "f32le",
+                vad_params: {
+                    threshold: 0.6,
+                    min_speech_duration_ms: 250,
+                    min_silence_duration_ms: 2000,
+                    max_speech_duration_s: 30.0,
+                },
             },
             onProgress: (progress) => {
                 console.log(progress);
@@ -305,7 +306,6 @@ async function main() {
 // Handle graceful shutdown
 process.on("SIGINT", () => {
     console.log("\n🛑 Stopping microphone transcription...");
-    process.exit(0);
 });
 // Start the application
 main().catch(console.error);

package/dist/examples/whispercpp-prompt.d.ts

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