@qvac/sdk 0.8.0 → 1.0.0

package/dist/examples/logging-streaming.js

@@ -1,75 +0,0 @@
-import { loadModel, completion, unloadModel, loggingStream, SDK_LOG_ID, LLAMA_3_2_1B_INST_Q4_0, GTE_LARGE_FP16, VERBOSITY, embed, } from "@qvac/sdk";
-try {
-    console.log("🚀 Starting log streaming demo...\n");
-    // Note: To configure logging (level and console output), use config file:
-    // { "loggerLevel": "debug", "loggerConsoleOutput": false } in qvac.config.json/js/ts
-    // Subscribe to SDK server logs in background
-    console.log("📡 Starting SDK server log stream...\n");
-    (async () => {
-        for await (const log of loggingStream({ id: SDK_LOG_ID })) {
-            console.log(`[SDK] [${log.level.toUpperCase()}] [${log.namespace}] ${log.message}`);
-        }
-    })().catch(() => {
-        // Stream terminated - normal on shutdown
-    });
-    // Load models
-    console.log("📥 Loading models (watch SDK logs above)...\n");
-    const llmModelId = await loadModel({
-        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
-        modelType: "llm",
-        modelConfig: {
-            ctx_size: 2048,
-            temp: 0.7,
-            verbosity: VERBOSITY.ERROR, // Only log errors, remaining logs are captured by loggingStream
-        },
-    });
-    const embedModelId = await loadModel({
-        modelSrc: GTE_LARGE_FP16,
-        modelType: "embeddings",
-    });
-    console.log("📡 Starting model-specific log streams...\n");
-    (async () => {
-        for await (const log of loggingStream({ id: llmModelId })) {
-            const timestamp = new Date(log.timestamp).toISOString();
-            console.log(`[LLM] [${timestamp}] [${log.level.toUpperCase()}] ${log.namespace}: ${log.message}`);
-        }
-    })().catch(() => {
-        // Stream terminated - this is normal when model unloads
-    });
-    (async () => {
-        for await (const log of loggingStream({ id: embedModelId })) {
-            const timestamp = new Date(log.timestamp).toISOString();
-            console.log(`[EMBED] [${timestamp}] [${log.level.toUpperCase()}] ${log.namespace}: ${log.message}`);
-        }
-    })().catch(() => {
-        // Stream terminated - this is normal when model unloads
-    });
-    const messages = [
-        { role: "user", content: "Count from 1 to 5 and explain each number." },
-    ];
-    const result = completion({
-        modelId: llmModelId,
-        history: messages,
-        stream: true,
-    });
-    const embedding = await embed({
-        modelId: embedModelId,
-        text: messages[0]?.content ?? "Hello, world!",
-    });
-    console.log("📝 Response:\n");
-    for await (const token of result.tokenStream) {
-        process.stdout.write(token);
-    }
-    console.log("Embedding (first 20 elements)", embedding.slice(0, 20));
-    console.log("Embeddings length", embedding.length);
-    console.log("\n💡 Notice three log streams running:\n" +
-        "   - [SDK] = SDK server operations\n" +
-        "   - [LLM] = LLM model inference logs\n" +
-        "   - [EMBED] = Embedding model logs\n");
-    await unloadModel({ modelId: llmModelId, clearStorage: false });
-    await unloadModel({ modelId: embedModelId, clearStorage: false });
-}
-catch (error) {
-    console.error("❌ Error:", error);
-    process.exit(1);
-}

package/dist/examples/mcp-websearch.d.ts

@@ -1,13 +0,0 @@
-/**
- * MCP DuckDuckGo Search Example
- *
- * A web search example using DuckDuckGo - no API key required!
- * The server provides tools to search the web and get answers.
- *
- * Prerequisites:
- * - Install MCP SDK: bun add @modelcontextprotocol/sdk
- *
- * Run with: bun run examples/mcp-websearch.ts
- */
-export {};
-//# sourceMappingURL=mcp-websearch.d.ts.map

package/dist/examples/mcp-websearch.js

@@ -1,176 +0,0 @@
-/**
- * MCP DuckDuckGo Search Example
- *
- * A web search example using DuckDuckGo - no API key required!
- * The server provides tools to search the web and get answers.
- *
- * Prerequisites:
- * - Install MCP SDK: bun add @modelcontextprotocol/sdk
- *
- * Run with: bun run examples/mcp-websearch.ts
- */
-import { completion, loadModel, unloadModel, QWEN3_1_7B_INST_Q4, } from "../index.js";
-// MCP SDK is a user-installed optional dependency
-// Install with: bun add @modelcontextprotocol/sdk
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-function parseSearchResults(mcpResult) {
-    try {
-        const result = mcpResult;
-        // Extract text content from MCP response
-        const textContent = result.content?.find((c) => c.type === "text");
-        if (!textContent?.text) {
-            return JSON.stringify(mcpResult);
-        }
-        // Parse the JSON array of search results
-        const rawResults = JSON.parse(textContent.text);
-        // Extract just the useful fields (title, url, snippet)
-        const cleanResults = rawResults.slice(0, 5).map((r) => ({
-            title: r.title ?? "Unknown",
-            url: r.url ?? "",
-            snippet: r.snippet ?? "",
-        }));
-        // Format as concise text for LLM
-        return cleanResults
-            .map((r, i) => `[${i + 1}] ${r.title}\n    URL: ${r.url}\n    ${r.snippet}`)
-            .join("\n\n");
-    }
-    catch {
-        // If parsing fails, return a truncated version
-        const str = typeof mcpResult === "string" ? mcpResult : JSON.stringify(mcpResult);
-        return str.slice(0, 2000);
-    }
-}
-let mcpClient = null;
-try {
-    console.log("🦆 MCP DuckDuckGo Search Example\n");
-    // ============================================================
-    // STEP 1: Connect to DuckDuckGo MCP server
-    // ============================================================
-    console.log("1️⃣  Starting DuckDuckGo MCP server...");
-    mcpClient = new Client({
-        name: "qvac-ddg-example",
-        version: "1.0.0",
-    });
-    const transport = new StdioClientTransport({
-        command: "npx",
-        args: ["-y", "@oevortex/ddg_search"],
-    });
-    await mcpClient.connect(transport);
-    console.log("   ✓ MCP server connected\n");
-    // ============================================================
-    // STEP 2: Load model
-    // ============================================================
-    console.log("2️⃣  Loading model...");
-    const modelId = await loadModel({
-        modelSrc: QWEN3_1_7B_INST_Q4,
-        modelType: "llm",
-        modelConfig: {
-            ctx_size: 4096,
-            tools: true,
-        },
-        onProgress: (progress) => process.stdout.write(`\r   Loading: ${progress.percentage.toFixed(1)}%`),
-    });
-    console.log(`\n   ✓ Model loaded\n`);
-    // ============================================================
-    // STEP 3: Ask AI to search the web (with MCP client)
-    // ============================================================
-    const history = [
-        {
-            role: "system",
-            content: `You are a helpful assistant with access to web search.
-Use the search tool when you need current information.
-Always cite your sources with the URL.`,
-        },
-        {
-            role: "user",
-            content: "What is the current weather in New York City?",
-        },
-    ];
-    console.log("3️⃣  Asking AI to search the web...\n");
-    console.log("🤖 AI Response:");
-    // Pass MCP client directly to completion - tools are adapted internally!
-    const result = completion({
-        modelId,
-        history,
-        stream: true,
-        mcp: [{ client: mcpClient, includeResources: false }],
-    });
-    for await (const token of result.tokenStream) {
-        process.stdout.write(token);
-    }
-    const toolCalls = await result.toolCalls;
-    console.log("\n");
-    // ============================================================
-    // STEP 4: Execute tool calls using call() - automatic MCP routing!
-    // ============================================================
-    if (toolCalls.length > 0) {
-        console.log("4️⃣  Executing search...\n");
-        const toolResults = [];
-        for (const toolCall of toolCalls) {
-            console.log(`🔍 ${toolCall.name}(${JSON.stringify(toolCall.arguments)})`);
-            if (!toolCall.invoke) {
-                console.log(`   ⚠️ No handler found for tool "${toolCall.name}"`);
-                continue;
-            }
-            // Use invoke() - automatically routes to the correct MCP client!
-            const mcpResult = await toolCall.invoke();
-            // Parse and clean up the search results
-            const cleanResult = parseSearchResults(mcpResult);
-            console.log(`   ✓ Got search results:`);
-            console.log(cleanResult
-                .split("\n")
-                .map((l) => `      ${l}`)
-                .join("\n"));
-            console.log();
-            toolResults.push({ id: toolCall.id, result: cleanResult });
-        }
-        // ============================================================
-        // STEP 5: Continue with search results
-        // ============================================================
-        console.log("5️⃣  Getting AI response with search results...\n");
-        history.push({
-            role: "assistant",
-            content: await result.text,
-        });
-        for (const tr of toolResults) {
-            history.push({
-                role: "tool",
-                content: tr.result,
-            });
-        }
-        console.log("🤖 Final Response:");
-        const finalResult = completion({
-            modelId,
-            history,
-            stream: true,
-            mcp: [{ client: mcpClient, includeResources: false }],
-        });
-        for await (const token of finalResult.tokenStream) {
-            process.stdout.write(token);
-        }
-        console.log("\n");
-    }
-    // ============================================================
-    // Cleanup
-    // ============================================================
-    console.log("6️⃣  Cleaning up...");
-    await unloadModel({ modelId, clearStorage: false });
-    console.log("   ✓ Done\n");
-    console.log("🎉 Example completed!");
-    process.exit(0);
-}
-catch (error) {
-    console.error("❌ Error:", error);
-    process.exit(1);
-}
-finally {
-    if (mcpClient) {
-        try {
-            await mcpClient.close();
-        }
-        catch {
-            // Ignore close errors
-        }
-    }
-}

package/dist/examples/ocr-fasttext.d.ts

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

package/dist/examples/ocr-fasttext.js

@@ -1,52 +0,0 @@
-import { close, loadModel, ocr, OCR_LATIN_RECOGNIZER_1, unloadModel, } from "@qvac/sdk";
-import path from "path";
-import { fileURLToPath } from "url";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const imagePath = process.argv[2] || path.join(__dirname, "image/basic_test.bmp");
-try {
-    console.log("🚀 Loading OCR model...");
-    const modelId = await loadModel({
-        modelSrc: OCR_LATIN_RECOGNIZER_1,
-        modelType: "ocr",
-        modelConfig: {
-            langList: ["en"],
-            useGPU: true,
-            timeout: 30000,
-            magRatio: 1.5,
-            defaultRotationAngles: [90, 180, 270],
-            contrastRetry: false,
-            lowConfidenceThreshold: 0.5,
-            recognizerBatchSize: 1,
-        },
-    });
-    console.log(`✅ Model loaded successfully! Model ID: ${modelId}`);
-    console.log(`\n🔍 Running OCR on: ${imagePath}`);
-    const { blocks } = ocr({
-        modelId,
-        image: imagePath,
-        options: {
-            paragraph: false,
-        },
-    });
-    const result = await blocks;
-    console.log("\n📝 OCR Results:");
-    console.log("================================");
-    for (const block of result) {
-        console.log(`\n📄 Text: ${block.text}`);
-        if (block.bbox) {
-            console.log(`   📍 BBox: [${block.bbox.join(", ")}]`);
-        }
-        if (block.confidence !== undefined) {
-            console.log(`   ✓ Confidence: ${block.confidence}`);
-        }
-    }
-    console.log("\n================================");
-    console.log("\n🔄 Unloading model...");
-    await unloadModel({ modelId, clearStorage: false });
-    console.log("✅ Model unloaded successfully.");
-    process.exit(0);
-}
-catch (error) {
-    console.error("❌ Error during OCR processing:", error);
-    await close();
-}

package/dist/examples/plugins.d.ts

@@ -1,14 +0,0 @@
-/**
- * Plugin Selection Example
- *
- * Config: examples/config/plugins/plugins.config.json
- *   Selected: llamacpp-completion (LLM), nmtcpp-translation (NMT)
- *
- * Demonstrates:
- *   1. LLM completion    -> works (plugin selected)
- *   2. NMT translation   -> works (plugin selected)
- *   3. Embeddings        -> fails (plugin not selected)
- *
- */
-export {};
-//# sourceMappingURL=plugins.d.ts.map

package/dist/examples/plugins.js

@@ -1,129 +0,0 @@
-/**
- * Plugin Selection Example
- *
- * Config: examples/config/plugins/plugins.config.json
- *   Selected: llamacpp-completion (LLM), nmtcpp-translation (NMT)
- *
- * Demonstrates:
- *   1. LLM completion    -> works (plugin selected)
- *   2. NMT translation   -> works (plugin selected)
- *   3. Embeddings        -> fails (plugin not selected)
- *
- */
-import { execSync } from "child_process";
-import { existsSync, rmSync } from "fs";
-import path from "path";
-const configDir = import.meta.dirname ?? process.cwd();
-const configPath = `${configDir}/config/plugins/plugins.config.json`;
-const projectRoot = path.resolve(configDir, "..");
-const qvacOutputDir = path.join(projectRoot, "qvac");
-// ─── Generate the worker bundle from the plugins config ─────────────────────
-console.log(`🔍 Config: ${configPath}`);
-console.log(`⚠️  This example will generate a worker bundle in ${qvacOutputDir} and delete it on exit.`);
-console.log("   If you have an existing qvac/ folder with bundled files, they will be overwritten and removed.\n");
-console.log("🔨 Generating worker bundle from plugins config...\n");
-try {
-    execSync(`npx @qvac/cli bundle sdk --config "${configPath}" --quiet`, {
-        cwd: projectRoot,
-        stdio: "inherit",
-    });
-}
-catch (error) {
-    console.error("❌ Failed to generate worker bundle. Ensure @qvac/cli is installed:");
-    console.error("   npm install -D @qvac/cli");
-    console.error("❌ Error:", error);
-    process.exit(1);
-}
-console.log("");
-// Cleanup generated qvac/ folder on exit
-function cleanup() {
-    if (existsSync(qvacOutputDir)) {
-        rmSync(qvacOutputDir, { recursive: true, force: true });
-        console.log(`\n🧹 Cleaned up ${qvacOutputDir}`);
-    }
-}
-process.on("exit", cleanup);
-// Point config before importing the SDK.
-// In a real app, place qvac.config.json (or .js/.ts) in your project root (auto-discovered).
-process.env["QVAC_CONFIG_PATH"] = configPath;
-const { completion, translate, embed, loadModel, unloadModel, LLAMA_3_2_1B_INST_Q4_0, MARIAN_OPUS_EN_IT_Q4_0, GTE_LARGE_FP16, } = await import("@qvac/sdk");
-console.log("1. LLM Completion (llamacpp-completion plugin)");
-try {
-    const llmModelId = await loadModel({
-        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
-        modelType: "llm",
-        modelConfig: { ctx_size: 2048 },
-        onProgress: (p) => console.log(`   Loading LLM: ${p.percentage.toFixed(1)}%`),
-    });
-    console.log(`   Model loaded: ${llmModelId}`);
-    const question = "What is 2 + 2? Answer in one word.";
-    console.log(`   Question: ${question}`);
-    const result = completion({
-        modelId: llmModelId,
-        history: [{ role: "user", content: question }],
-        stream: true,
-    });
-    process.stdout.write("   Response: ");
-    for await (const token of result.tokenStream) {
-        process.stdout.write(token);
-    }
-    console.log("\n");
-    await unloadModel({ modelId: llmModelId });
-    console.log("   ✅ LLM unloaded\n");
-}
-catch (error) {
-    console.error("   ❌ LLM failed:", error);
-    process.exit(1);
-}
-console.log("2. Translation (nmtcpp-translation plugin)");
-try {
-    const nmtModelId = await loadModel({
-        modelSrc: MARIAN_OPUS_EN_IT_Q4_0,
-        modelType: "nmt",
-        modelConfig: {
-            engine: "Opus",
-            from: "en",
-            to: "it",
-        },
-        onProgress: (p) => console.log(`   Loading NMT: ${p.percentage.toFixed(1)}%`),
-    });
-    console.log(`   Model loaded: ${nmtModelId}`);
-    const text = "Hello, how are you?";
-    const result = translate({
-        modelId: nmtModelId,
-        text,
-        modelType: "nmt",
-        stream: false,
-    });
-    const translated = await result.text;
-    console.log(`   "${text}" -> "${translated}"\n`);
-    await unloadModel({ modelId: nmtModelId });
-    console.log("   ✅ NMT unloaded\n");
-}
-catch (error) {
-    console.error("   ❌ Translation failed:", error);
-    process.exit(1);
-}
-console.log("3. Embeddings (llamacpp-embedding plugin NOT in config)");
-console.log("   Attempting to load an embeddings model...\n");
-try {
-    const embedModelId = await loadModel({
-        modelSrc: GTE_LARGE_FP16,
-        modelType: "embeddings",
-    });
-    await embed({ modelId: embedModelId, text: "test" });
-    console.error("   ❌ Unexpected: embed succeeded without the plugin!");
-    process.exit(1);
-}
-catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (message.includes("Plugin not found")) {
-        console.log("   ✅ Expected PLUGIN_NOT_FOUND error:");
-        console.log(`   ${message}\n`);
-    }
-    else {
-        console.error("   ❌ Unexpected error:", error);
-        process.exit(1);
-    }
-}
-console.log("Done! Only the selected plugins were available.");

package/dist/examples/profiling/basic.d.ts

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

package/dist/examples/profiling/basic.js

@@ -1,71 +0,0 @@
-import { completion, loadModel, unloadModel, LLAMA_3_2_1B_INST_Q4_0, profiler, } from "@qvac/sdk";
-try {
-    // Enable profiling globally
-    profiler.enable({
-        mode: "verbose",
-        includeServerBreakdown: true,
-    });
-    console.log("Profiler enabled:", profiler.isEnabled());
-    const modelId = await loadModel({
-        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
-        modelType: "llm",
-        onProgress: (p) => console.log(`  ${p.percentage.toFixed(1)}%`),
-    });
-    console.log("Model loaded:", modelId);
-    console.log("\n→ Running completion...");
-    const result = completion({
-        modelId,
-        history: [{ role: "user", content: "Say hello in one sentence." }],
-        stream: true,
-    });
-    for await (const token of result.tokenStream) {
-        process.stdout.write(token);
-    }
-    console.log();
-    await unloadModel({ modelId });
-    // Export profiling data
-    console.log("\n=== Profiler Summary ===");
-    console.log(profiler.exportSummary());
-    console.log("\n=== Profiler Table ===");
-    console.log(profiler.exportTable());
-    const json = profiler.exportJSON();
-    console.log("\n=== Load Model Metrics ===");
-    // Filter for operation-level event (kind: "handler"), not RPC phase events
-    const loadModelEvent = json.recentEvents?.find((e) => e.op === "loadModel" && e.kind === "handler");
-    if (loadModelEvent) {
-        const tags = loadModelEvent.tags ?? {};
-        const gauges = loadModelEvent.gauges ?? {};
-        console.log("  sourceType:", tags["sourceType"] ?? "(not set)");
-        console.log("  cacheHit:", tags["cacheHit"] ?? "(not set)");
-        console.log("  totalLoadTime:", gauges["totalLoadTime"], "ms");
-        console.log("  modelInitializationTime:", gauges["modelInitializationTime"], "ms");
-        if (tags["cacheHit"] !== "true") {
-            console.log("  downloadTime:", gauges["downloadTime"] ?? "(cached)", "ms");
-            console.log("  totalBytesDownloaded:", gauges["totalBytesDownloaded"] ?? "(cached)");
-            console.log("  downloadSpeedBps:", gauges["downloadSpeedBps"] ?? "(cached)");
-        }
-        else {
-            console.log("  (download metrics omitted - cache hit)");
-        }
-        if (gauges["checksumValidationTime"] !== undefined) {
-            console.log("  checksumValidationTime:", gauges["checksumValidationTime"], "ms");
-        }
-    }
-    else {
-        console.log("  (no loadModel handler event captured)");
-        // Debug: show what ops are available
-        const ops = [...new Set(json.recentEvents?.map((e) => `${e.op}:${e.kind}`) ?? [])];
-        console.log("  Available ops:", ops.join(", "));
-    }
-    console.log("\n=== Profiler JSON (structure) ===");
-    console.log("  aggregates:", Object.keys(json.aggregates).length, "metrics");
-    console.log("  recentEvents:", json.recentEvents?.length ?? 0, "events");
-    console.log("  config:", json.config);
-    // Disable profiling
-    profiler.disable();
-    console.log("\nProfiler disabled:", !profiler.isEnabled());
-}
-catch (error) {
-    console.error("Error:", error);
-    process.exit(1);
-}

package/dist/examples/profiling/per-call.d.ts

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

package/dist/examples/profiling/per-call.js

@@ -1,30 +0,0 @@
-import { embed, loadModel, unloadModel, GTE_LARGE_FP16, profiler, } from "@qvac/sdk";
-try {
-    profiler.disable();
-    console.log("Profiler globally enabled:", profiler.isEnabled());
-    const modelId = await loadModel({
-        modelSrc: GTE_LARGE_FP16,
-        modelType: "embeddings",
-        onProgress: (p) => console.log(`  ${p.percentage.toFixed(1)}%`),
-    });
-    console.log("Model loaded:", modelId);
-    console.log("\n=== Embed with per-call profiling ===");
-    const embedding1 = await embed({ modelId, text: "Profile this specific call" }, { profiling: { enabled: true, includeServerBreakdown: true } });
-    console.log("Embedding dimensions:", embedding1.length);
-    console.log("\n=== Embed without profiling ===");
-    const embedding2 = await embed({
-        modelId,
-        text: "This call is not profiled",
-    });
-    console.log("Embedding dimensions:", embedding2.length);
-    console.log("\n=== Embed with profiling explicitly disabled ===");
-    const embedding3 = await embed({ modelId, text: "Profiling explicitly disabled for this call" }, { profiling: { enabled: false } });
-    console.log("Embedding dimensions:", embedding3.length);
-    await unloadModel({ modelId });
-    console.log("\n=== Profiler Summary (per-call data only) ===");
-    console.log(profiler.exportSummary());
-}
-catch (error) {
-    console.error("Error:", error);
-    process.exit(1);
-}

package/dist/examples/quickstart.d.ts

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

package/dist/examples/quickstart.js

@@ -1,28 +0,0 @@
-import { loadModel, LLAMA_3_2_1B_INST_Q4_0, completion, unloadModel, } from "@qvac/sdk";
-try {
-    // Load a model into memory
-    const modelId = await loadModel({
-        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
-        modelType: "llm",
-        onProgress: (progress) => {
-            console.log(progress);
-        },
-    });
-    // You can use the loaded model multiple times
-    const history = [
-        {
-            role: "user",
-            content: "Explain quantum computing in one sentence",
-        },
-    ];
-    const result = completion({ modelId, history, stream: true });
-    for await (const token of result.tokenStream) {
-        process.stdout.write(token);
-    }
-    // Unload model to free up system resources
-    await unloadModel({ modelId });
-}
-catch (error) {
-    console.error("❌ Error:", error);
-    process.exit(1);
-}

package/dist/examples/rag/rag-hyperdb/cancellation.d.ts

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