@qvac/sdk 0.5.0 → 0.6.1

package/dist/client/rpc/bare-client.d.ts

@@ -1,181 +1,3 @@
-import type { Request, Response } from "../../schemas/index";
-export declare function send<T extends Request>(request: T): Promise<Response>;
-export declare function stream<T extends Request>(request: T): AsyncGenerator<{
-    type: "cancel";
-    success: boolean;
-    error?: string | undefined;
-} | {
-    type: "completionStream";
-    token: string;
-    done?: boolean | undefined;
-    stats?: {
-        timeToFirstToken: number;
-        tokensPerSecond: number;
-        cacheTokens: number;
-    } | undefined;
-    toolCallEvent?: {
-        type: "toolCall";
-        call: {
-            id: string;
-            name: string;
-            arguments: Record<string, unknown>;
-            raw?: string | undefined;
-        };
-    } | {
-        type: "toolCallError";
-        error: {
-            code: "PARSE_ERROR" | "VALIDATION_ERROR" | "UNKNOWN_TOOL";
-            message: string;
-            raw?: string | undefined;
-        };
-    } | undefined;
-    toolCalls?: {
-        id: string;
-        name: string;
-        arguments: Record<string, unknown>;
-        raw?: string | undefined;
-    }[] | undefined;
-    error?: string | undefined;
-} | {
-    type: "deleteCache";
-    success: boolean;
-    error?: string | undefined;
-} | {
-    type: "textToSpeech";
-    buffer: number[];
-    done: boolean;
-} | {
-    type: "loadModel";
-    success: boolean;
-    modelId?: string | undefined;
-    error?: string | undefined;
-} | {
-    type: "modelProgress";
-    downloaded: number;
-    total: number;
-    percentage: number;
-    downloadKey: string;
-    shardInfo?: {
-        currentShard: number;
-        totalShards: number;
-        shardName: string;
-        overallDownloaded: number;
-        overallTotal: number;
-        overallPercentage: number;
-    } | undefined;
-} | {
-    type: "downloadAsset";
-    success: boolean;
-    assetId?: string | undefined;
-    error?: string | undefined;
-} | {
-    type: "embed";
-    success: boolean;
-    embedding: number[] | number[][];
-    error?: string | undefined;
-} | {
-    type: "loggingStream";
-    id: string;
-    level: "error" | "warn" | "info" | "debug" | "off";
-    namespace: string;
-    message: string;
-    timestamp: number;
-} | {
-    type: "provide";
-    success: boolean;
-    error?: string | undefined;
-    publicKey?: string | undefined;
-} | {
-    type: "stopProvide";
-    success: boolean;
-    error?: string | undefined;
-} | {
-    type: "unloadModel";
-    success: boolean;
-    error?: string | undefined;
-    hasActiveModels?: boolean | undefined;
-    hasActiveProviders?: boolean | undefined;
-} | {
-    type: "pong";
-    number: number;
-} | {
-    type: "transcribeStream";
-    text?: string | undefined;
-    done?: boolean | undefined;
-    error?: string | undefined;
-} | {
-    type: "translate";
-    token: string;
-    done?: boolean | undefined;
-    stats?: {
-        processedTokens: number;
-        processingTime: number;
-    } | undefined;
-    error?: string | undefined;
-} | {
-    type: "error";
-    message: string;
-    stack?: string | undefined;
-    timestamp?: string | undefined;
-    name?: string | undefined;
-    code?: number | undefined;
-    cause?: unknown;
-} | {
-    type: "rag";
-    success: boolean;
-    operation: "saveEmbeddings";
-    processed: {
-        status: "fulfilled" | "rejected";
-        id?: string | undefined;
-        error?: string | undefined;
-    }[];
-    droppedIndices: number[];
-    error?: string | undefined;
-} | {
-    type: "rag";
-    success: boolean;
-    operation: "search";
-    results: {
-        id: string;
-        content: string;
-        score: number;
-    }[];
-    error?: string | undefined;
-} | {
-    type: "rag";
-    success: boolean;
-    operation: "deleteEmbeddings";
-    error?: string | undefined;
-} | {
-    type: "getModelInfo";
-    modelInfo: {
-        name: string;
-        modelId: string;
-        hyperdriveKey: string;
-        hyperbeeKey: string;
-        expectedSize: number;
-        sha256Checksum: string;
-        addon: "llm" | "whisper" | "embeddings" | "nmt" | "tts" | "vad";
-        isCached: boolean;
-        isLoaded: boolean;
-        cacheFiles: {
-            filename: string;
-            path: string;
-            expectedSize: number;
-            sha256Checksum: string;
-            isCached: boolean;
-            actualSize?: number | undefined;
-            cachedAt?: Date | undefined;
-        }[];
-        actualSize?: number | undefined;
-        cachedAt?: Date | undefined;
-        loadedInstances?: {
-            registryId: string;
-            loadedAt: Date;
-            config?: unknown;
-        }[] | undefined;
-    };
-}, void, any>;
 export declare function getRPC(): Promise<{
     request(): {
         send(payload: string): void;
@@ -183,4 +5,5 @@ export declare function getRPC(): Promise<{
         createResponseStream(): AsyncGenerator<Buffer<ArrayBuffer>, void, unknown>;
     };
 }>;
+export declare function close(): void;
 //# sourceMappingURL=bare-client.d.ts.map

package/dist/client/rpc/bare-client.js

@@ -1,23 +1,43 @@
+import { normalizeModelType } from "../../schemas/index.js";
+import os from "bare-os";
 import { handlers } from "../../server/rpc/handlers/index.js";
 import { RPCNoHandlerError, RPCRequestNotSentError, } from "../../utils/errors-client.js";
 import { initializeConfig } from "../init-hooks.js";
 import { setSDKConfig } from "../../server/bare/registry/config-registry.js";
+import { setRuntimeContext } from "../../server/bare/registry/runtime-context-registry.js";
+import { resolveModelConfig } from "../../server/bare/registry/model-config-registry.js";
 import { resolveConfig } from "../config-loader/resolve-config.bare.js";
 // Get the handler for a request type
-const getHandler = (type) => {
+function getHandler(type) {
     const handler = handlers[type];
     return typeof handler === "function" ? handler : undefined;
-};
-export async function send(request) {
+}
+function applyDeviceDefaultsToLoadModel(request) {
+    if (request.type !== "loadModel" || !("modelSrc" in request)) {
+        return request;
+    }
+    let canonicalType;
+    try {
+        canonicalType = normalizeModelType(request.modelType);
+    }
+    catch {
+        return request;
+    }
+    const rawConfig = request.modelConfig ?? {};
+    const configWithDefaults = resolveModelConfig(canonicalType, rawConfig);
+    return { ...request, modelConfig: configWithDefaults };
+}
+async function send(request) {
     if (request.type === "ping") {
         return { type: "pong", number: Math.random() * 100 };
     }
     const handler = getHandler(request.type);
     if (!handler)
         throw new RPCNoHandlerError(request.type);
-    return (await handler(request));
+    const processedRequest = applyDeviceDefaultsToLoadModel(request);
+    return (await handler(processedRequest));
 }
-export async function* stream(request) {
+async function* stream(request) {
     const handler = getHandler(request.type);
     if (!handler)
         throw new RPCNoHandlerError(request.type);
@@ -25,11 +45,12 @@ export async function* stream(request) {
     if (request.type === "loadModel" &&
         "withProgress" in request &&
         request.withProgress) {
+        const processedRequest = applyDeviceDefaultsToLoadModel(request);
         async function* streamWithProgress() {
             const queue = [];
             let done = false;
             const loadModelHandler = handler;
-            loadModelHandler(request, (update) => queue.push(update))
+            loadModelHandler(processedRequest, (update) => queue.push(update))
                 .then((final) => {
                 queue.push(final);
                 done = true;
@@ -105,8 +126,13 @@ const createMockRPCRequest = () => {
                 "type" in requestData &&
                 requestData.type === "__init_config") {
                 try {
-                    const configData = requestData;
-                    setSDKConfig(configData.config);
+                    const initData = requestData;
+                    if (initData.config) {
+                        setSDKConfig(initData.config);
+                    }
+                    if (initData.runtimeContext) {
+                        setRuntimeContext(initData.runtimeContext);
+                    }
                     return Buffer.from(JSON.stringify({ success: true }));
                 }
                 catch (error) {
@@ -138,8 +164,15 @@ export async function getRPC() {
     };
     // Initialize config once on first call
     if (!configInitialized) {
-        await initializeConfig(mockRPC, resolveConfig);
+        const runtimeContext = {
+            runtime: "bare",
+            platform: os.platform(),
+        };
+        await initializeConfig(mockRPC, resolveConfig, runtimeContext);
         configInitialized = true;
     }
     return mockRPC;
 }
+export function close() {
+    // noop
+}

package/dist/client/rpc/expo-rpc-client.js

@@ -6,7 +6,48 @@ import { getClientLogger } from "../../logging/index.js";
 const logger = getClientLogger();
 let rpcInstance = null;
 let rpcPromise = null;
+let workletInstance = null;
+let workletInitialized = false;
+let cachedRuntimeContext;
 logger.debug("EXPO RPC Client bundle");
+async function getRuntimeContext() {
+    if (cachedRuntimeContext) {
+        return cachedRuntimeContext;
+    }
+    // expo-device is optional - gracefully handle if not installed
+    let deviceModel;
+    let deviceBrand;
+    let platform;
+    try {
+        const expoModulesCore = await import("expo-modules-core");
+        // this looks odd, but is necessary to ensure that import can be used safely.
+        // It will crash the app if the module is not installed, but the node dependency is present.
+        const nativeDeviceModule = expoModulesCore.requireOptionalNativeModule("ExpoDevice");
+        if (nativeDeviceModule) {
+            const Device = await import("expo-device");
+            logger.info(`Device: ${Device.modelName} ${Device.brand} ${Device.osName}`);
+            const osName = Device?.osName?.toLowerCase();
+            if (osName?.includes("ios")) {
+                platform = "ios";
+            }
+            else if (osName?.includes("android")) {
+                platform = "android";
+            }
+            deviceModel = Device.modelName ?? undefined;
+            deviceBrand = Device.brand ?? undefined;
+        }
+    }
+    catch {
+        logger.debug("expo-device not available, device info will be omitted");
+    }
+    cachedRuntimeContext = {
+        runtime: "react-native",
+        platform,
+        deviceModel,
+        deviceBrand,
+    };
+    return cachedRuntimeContext;
+}
 export async function getRPC() {
     if (rpcInstance) {
         return rpcInstance;
@@ -15,10 +56,22 @@ export async function getRPC() {
         return rpcPromise;
     }
     rpcPromise = (async () => {
+        if (workletInstance) {
+            logger.debug("🔄 Reusing existing worklet");
+            rpcInstance = new RPC(workletInstance.IPC, () => { });
+            // Only initialize once per worklet - server state persists
+            if (!workletInitialized) {
+                const runtimeContext = await getRuntimeContext();
+                await initializeConfig(rpcInstance, resolveConfig, runtimeContext);
+                workletInitialized = true;
+            }
+            return rpcInstance;
+        }
         const { Paths } = await import("expo-file-system");
         const bareKitModule = await import("react-native-bare-kit");
         const worklet = new bareKitModule.Worklet();
-        logger.debug("Starting worklet");
+        workletInstance = worklet;
+        logger.debug("Starting new worklet");
         // Load the mobile bundle - this will be generated by the Expo plugin
         // using the user's installed bare library versions
         let mobileBundle;
@@ -47,7 +100,9 @@ export async function getRPC() {
         rpcInstance = new RPC(worklet.IPC, () => {
             // Use this for async callbacks
         });
-        await initializeConfig(rpcInstance, resolveConfig);
+        const runtimeContext = await getRuntimeContext();
+        await initializeConfig(rpcInstance, resolveConfig, runtimeContext);
+        workletInitialized = true;
         return rpcInstance;
     })();
     try {

package/dist/client/rpc/node-rpc-client.js

@@ -54,7 +54,11 @@ async function ensureRPC() {
         });
     });
     const rpc = await rpcPromise;
-    await initializeConfig(rpc, resolveConfig);
+    const runtimeContext = {
+        runtime: "node",
+        platform: process.platform,
+    };
+    await initializeConfig(rpc, resolveConfig, runtimeContext);
     return rpc;
 }
 const mockRPC = {

package/dist/client/rpc/rpc-client.d.ts

@@ -2,5 +2,5 @@ import type RPC from "bare-rpc";
 import { type Request, type Response, type RPCOptions } from "../../schemas/index";
 export declare function send<T extends Request>(request: T, rpc?: RPC, options?: RPCOptions): Promise<Response>;
 export declare function stream<T extends Request>(request: T, rpc?: RPC, options?: RPCOptions): AsyncGenerator<Response>;
-export declare function close(): Promise<void>;
+export declare function close(): void;
 //# sourceMappingURL=rpc-client.d.ts.map

package/dist/client/rpc/rpc-client.js

@@ -1,8 +1,8 @@
 import { requestSchema, responseSchema, } from "../../schemas/index.js";
 import { RPCError } from "./rpc-error.js";
 import { withTimeout, withTimeoutStream } from "../../utils/withTimeout.js";
-import { isReactNative, isBare } from "../../utils/runtime.js";
-import { getClientLogger } from "../../logging/index.js";
+import { getClientLogger, summarizeRequest } from "../../logging/index.js";
+import { getRPC, close as closeRPC } from "#rpc";
 const logger = getClientLogger();
 let rpcInstance = null;
 let commandCounter = 0;
@@ -15,52 +15,17 @@ function checkAndThrowError(response) {
         throw new RPCError(response);
     }
 }
-async function getRPC() {
+async function getRPCInstance() {
     if (rpcInstance)
         return rpcInstance;
-    const isRN = isReactNative();
-    const isBareRuntime = isBare();
-    // TODO Lots of type unsafe hacks to make this work cross platform
-    if (isRN) {
-        logger.debug("React Native runtime detected");
-        // Only import expo client for React Native - Metro won't bundle the Node client
-        const expoRPCClientPath = "./expo-rpc-client";
-        const mod = (await import(expoRPCClientPath));
-        rpcInstance = await (typeof mod === "function" ? mod() : mod.getRPC());
-        return rpcInstance;
-    }
-    else if (isBareRuntime) {
-        logger.debug("Bare runtime detected");
-        // Use dynamic import for Bare client
-        const mod = await import("./bare-client.js");
-        rpcInstance = (await mod.getRPC());
-        return rpcInstance;
-    }
-    else {
-        logger.debug("Node runtime detected");
-        // Use dynamic import for Node client to prevent Metro from bundling it
-        const mod = await import("./node-rpc-client.js");
-        rpcInstance = mod.getRPC();
-        return rpcInstance;
-    }
+    rpcInstance = await getRPC();
+    return rpcInstance;
 }
 export async function send(request, rpc, options) {
     const parsedRequest = requestSchema.parse(request);
-    const rpcInstance = rpc || (await getRPC());
+    const rpcInstance = rpc || (await getRPCInstance());
     const req = rpcInstance.request(getNextCommandId());
-    // TODO temp for debugging, find a better solution to exclude large payloads
-    // Log request type and basic info, avoid logging large payloads
-    if (request.type === "transcribeStream") {
-        logger.debug("RPC Client sending:", {
-            type: request.type,
-            modelId: request.modelId,
-            audioChunkType: request.audioChunk.type,
-            audioChunkSize: request.audioChunk.value.length,
-        });
-    }
-    else {
-        logger.debug("RPC Client sending:", request);
-    }
+    logger.debug("RPC Client sending:", summarizeRequest(request));
     const payload = JSON.stringify(parsedRequest);
     req.send(payload, "utf-8");
     const response = await withTimeout(req.reply("utf-8"), options?.timeout);
@@ -71,8 +36,9 @@ export async function send(request, rpc, options) {
 }
 export async function* stream(request, rpc, options = {}) {
     const parsedRequest = requestSchema.parse(request);
-    const rpcInstance = rpc || (await getRPC());
+    const rpcInstance = rpc || (await getRPCInstance());
     const req = rpcInstance.request(getNextCommandId());
+    logger.debug("RPC Client streaming:", summarizeRequest(request));
     req.send(JSON.stringify(parsedRequest), "utf-8");
     const responseStream = req.createResponseStream({ encoding: "utf-8" });
     let buffer = "";
@@ -96,21 +62,9 @@ export async function* stream(request, rpc, options = {}) {
         }
     }
 }
-export async function close() {
+export function close() {
     if (!rpcInstance)
         return;
-    const isRN = isReactNative();
-    const isBareRuntime = isBare();
-    if (isRN) {
-        const mod = (await import("./expo-rpc-client.js"));
-        mod.close();
-    }
-    else if (isBareRuntime) {
-        // Bare runs in-process (no separate worker), so no cleanup needed
-    }
-    else {
-        const mod = (await import("./node-rpc-client.js"));
-        mod.close();
-    }
+    closeRPC();
     rpcInstance = null;
 }

package/dist/examples/config/blind-relay/blind-relay.config.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    swarmRelays: string[];
+};
+export default _default;
+//# sourceMappingURL=blind-relay.config.d.ts.map

package/dist/examples/config/blind-relay/blind-relay.config.js

@@ -0,0 +1,7 @@
+export default {
+    swarmRelays: [
+        "0000000000000000000000000000000000000000000000000000000000000001",
+        "0000000000000000000000000000000000000000000000000000000000000002",
+        "0000000000000000000000000000000000000000000000000000000000000003",
+    ],
+};

package/dist/examples/config/default/default.config.d.ts

@@ -0,0 +1,8 @@
+declare const _default: {
+    loggerLevel: string;
+    loggerConsoleOutput: boolean;
+    httpDownloadConcurrency: number;
+    httpConnectionTimeoutMs: number;
+};
+export default _default;
+//# sourceMappingURL=default.config.d.ts.map

package/dist/examples/config/default/default.config.js

@@ -0,0 +1,6 @@
+export default {
+    loggerLevel: "info",
+    loggerConsoleOutput: true,
+    httpDownloadConcurrency: 3,
+    httpConnectionTimeoutMs: 10000,
+};

package/dist/examples/default-config-usage.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Default Config Example
+ *
+ * This example demonstrates how to use a config file with the SDK.
+ *
+ * Supported config formats:
+ * - qvac.config.json (JSON)
+ * - qvac.config.js   (JavaScript with default export)
+ * - qvac.config.ts   (TypeScript with default export)
+ *
+ * Config resolution order:
+ * 1. QVAC_CONFIG_PATH environment variable (used here for demo purposes)
+ * 2. Config file in project root - auto-discovered, no env var needed
+ * 3. SDK defaults
+ */
+export {};
+//# sourceMappingURL=default-config-usage.d.ts.map

package/dist/examples/default-config-usage.js

@@ -0,0 +1,47 @@
+/**
+ * Default Config Example
+ *
+ * This example demonstrates how to use a config file with the SDK.
+ *
+ * Supported config formats:
+ * - qvac.config.json (JSON)
+ * - qvac.config.js   (JavaScript with default export)
+ * - qvac.config.ts   (TypeScript with default export)
+ *
+ * Config resolution order:
+ * 1. QVAC_CONFIG_PATH environment variable (used here for demo purposes)
+ * 2. Config file in project root - auto-discovered, no env var needed
+ * 3. SDK defaults
+ */
+// Note: This example uses .js file for the config
+// However it could be .json or .ts as well, depending on your needs.
+const configDir = import.meta.dirname ?? process.cwd();
+process.env["QVAC_CONFIG_PATH"] =
+    `${configDir}/config/default/default.config.js`;
+console.log(`🔍 Using config from: ${process.env["QVAC_CONFIG_PATH"]}`);
+const { loadModel, unloadModel, completion, LLAMA_3_2_1B_INST_Q4_0 } = await import("@qvac/sdk");
+try {
+    console.log("🚀 Loading model with configured settings...\n");
+    const modelId = await loadModel({
+        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
+        modelType: "llm",
+    });
+    console.log("\n💬 Running completion...\n");
+    const result = completion({
+        modelId,
+        history: [
+            { role: "user", content: "Say 'Config works!' in exactly 3 words." },
+        ],
+        stream: true,
+    });
+    for await (const token of result.tokenStream) {
+        process.stdout.write(token);
+    }
+    console.log("\n");
+    await unloadModel({ modelId });
+}
+catch (error) {
+    console.error("❌ Error:", error);
+    process.exit(1);
+}
+export {};

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

@@ -32,6 +32,7 @@ try {
             providerPublicKey,
             timeout: 5_000, // Optional: 5 second timeout for delegated requests
             fallbackToLocal: true, // Optional: Fall back to local inference if delegation fails
+            // forceNewConnection: true, // Optional: Force a new connection instead of reusing cached one
         },
         onProgress: (progress) => {
             console.log(`📊 Download progress: ${progress.percentage.toFixed(1)}% (${progress.downloaded}/${progress.total} bytes)`);

package/dist/examples/download-with-blind-relays.js

@@ -1,8 +1,9 @@
 // Set config path before importing SDK - the SDK loads config during initialization
 // This example uses a config file that defines blind relay public keys for improved P2P connectivity
 // Blind relays help establish connections through NAT/firewalls by acting as intermediaries
-import { getConfigPath } from "./config/config-path.js";
-process.env["QVAC_CONFIG_PATH"] = getConfigPath(import.meta.url, "qvac.config.json");
+const configDir = import.meta.dirname ?? process.cwd();
+process.env["QVAC_CONFIG_PATH"] =
+    `${configDir}/config/blind-relay/blind-relay.config.js`;
 import { downloadAsset, close, LLAMA_3_2_1B_INST_Q4_0, loadModel, getModelInfo, unloadModel, } from "@qvac/sdk";
 console.log(`🚀 Download with Blind Relays Example`);
 console.log(`${"=".repeat(60)}\n`);
@@ -37,7 +38,7 @@ try {
     });
     console.log(`\n✅ Model downloaded successfully using blind relays!`);
     console.log(`Blind relays helped establish peer connections through NAT/firewalls\n`);
-    await close();
+    close();
 }
 catch (error) {
     console.error("❌ Error:", error);

package/dist/examples/embed-hyperdrive.js

@@ -13,6 +13,10 @@ try {
         onProgress: (progress) => {
             console.log(progress);
         },
+        modelConfig: {
+            gpuLayers: 99,
+            device: "gpu",
+        },
     });
     console.log("\n📝 Example 1: Single Text Embedding");
     console.log("=".repeat(50));

package/dist/examples/kv-cache-custom-key.js

@@ -14,7 +14,7 @@ try {
         modelConfig: {
             device: "gpu",
             ctx_size: 2048,
-            verbosity: VERBOSITY.ERROR,
+            verbosity: VERBOSITY.DEBUG,
         },
     });
     // Prompt 1 with cache key "session-a" (first time - no cache exists)
@@ -70,6 +70,21 @@ try {
     }
     const stats3 = await result3.stats;
     console.log(`\n   Stats: TTFT=${stats3?.timeToFirstToken}ms, CacheTokens=${stats3?.cacheTokens}\n`);
+    // Prompt 4: Go back to session-a to trigger flush of session-b
+    console.log('\n📝 Prompt 4: "What is 5+5?" with cache key "session-a" (BACK TO FIRST)');
+    console.log("   Status: This should trigger session-b to be flushed to disk\n");
+    const result4 = completion({
+        modelId,
+        history: [systemPromptMessage, { role: "user", content: "What is 5+5?" }],
+        stream: true,
+        kvCache: "session-a", // Back to session-a!
+    });
+    console.log("   Response: ");
+    for await (const token of result4.tokenStream) {
+        process.stdout.write(token);
+    }
+    const stats4 = await result4.stats;
+    console.log(`\n   Stats: TTFT=${stats4?.timeToFirstToken}ms, CacheTokens=${stats4?.cacheTokens}\n`);
     // Summary
     console.log("\n✅ Summary:");
     console.log('   - Prompts 1 & 2 share cache key "session-a" → same cache file');