@qvac/sdk 0.8.2 → 0.9.0

package/dist/client/api/transcribe.js

@@ -1,54 +1,134 @@
-import { transcribeStreamResponseSchema, } from "../../schemas/index.js";
-import { stream } from "../rpc/rpc-client.js";
-/**
- * This function streams audio transcription results in real-time, yielding
- * text chunks as they become available from the model.
- *
- * @param params - The arguments for the transcription
- * @param params.modelId - The identifier of the transcription model to use
- * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
- * @param params.prompt - Optional initial prompt to guide the transcription
- * @param options - Optional RPC options including per-call profiling
- * @yields {string} Text chunks as they are transcribed
- * @throws {QvacErrorBase} When transcription fails with an error message
- */
-export async function* transcribeStream(params, options) {
-    const request = {
-        type: "transcribeStream",
+import { transcribeResponseSchema, transcribeStreamResponseSchema, } from "../../schemas/index.js";
+import { stream, duplex } from "../rpc/rpc-client.js";
+import { getClientLogger } from "../../logging/index.js";
+import { TranscriptionFailedError } from "../../utils/errors-client.js";
+const logger = getClientLogger();
+function buildTranscribeRequest(params) {
+    return {
+        type: "transcribe",
         modelId: params.modelId,
         audioChunk: typeof params.audioChunk === "string"
             ? { type: "filePath", value: params.audioChunk }
             : { type: "base64", value: params.audioChunk.toString("base64") },
         ...(params.prompt && { prompt: params.prompt }),
     };
-    for await (const response of stream(request, options)) {
-        if (response.type === "transcribeStream") {
-            const streamResponse = transcribeStreamResponseSchema.parse(response);
-            if (streamResponse.text) {
-                yield streamResponse.text;
-            }
-            if (streamResponse.done) {
-                break;
-            }
-        }
-    }
 }
 /**
- * This function provides a simple interface for transcribing audio by
- * collecting all streaming results into a single string response.
+ * Transcribe audio and return the complete text. Accepts either a file
+ * path or an audio buffer.
  *
- * @param params - The arguments for the transcription
  * @param params.modelId - The identifier of the transcription model to use
  * @param params.audioChunk - Audio input as either a file path (string) or audio buffer
  * @param params.prompt - Optional initial prompt to guide the transcription
  * @param options - Optional RPC options including per-call profiling
- * @returns {Promise<string>} The complete transcribed text
- * @throws {QvacErrorBase} When transcription fails (propagated from transcribeStream)
+ * @returns The complete transcribed text
  */
 export async function transcribe(params, options) {
+    const request = buildTranscribeRequest(params);
     let fullText = "";
-    for await (const textChunk of transcribeStream(params, options)) {
-        fullText += textChunk;
+    for await (const response of stream(request, options)) {
+        if (response.type === "transcribe") {
+            const parsed = transcribeResponseSchema.parse(response);
+            if (parsed.text) {
+                fullText += parsed.text;
+            }
+            if (parsed.done) {
+                break;
+            }
+        }
     }
     return fullText;
 }
+export function transcribeStream(params, options) {
+    if ("audioChunk" in params && params.audioChunk !== undefined) {
+        logger.warn("transcribeStream() with audioChunk is deprecated — use transcribe() instead.");
+        return transcribeStreamWithAudio(params, options);
+    }
+    return transcribeStreamDuplex(params, options);
+}
+async function* transcribeStreamWithAudio(params, options) {
+    const request = buildTranscribeRequest(params);
+    for await (const response of stream(request, options)) {
+        if (response.type === "transcribe") {
+            const parsed = transcribeResponseSchema.parse(response);
+            if (parsed.text)
+                yield parsed.text;
+            if (parsed.done)
+                break;
+        }
+    }
+}
+async function transcribeStreamDuplex(params, options) {
+    const request = {
+        type: "transcribeStream",
+        modelId: params.modelId,
+        ...(params.prompt && { prompt: params.prompt }),
+    };
+    const { requestStream, responseStream } = await duplex(request, options);
+    const responses = parseResponseLines(responseStream);
+    let consumed = false;
+    return {
+        write(audioChunk) {
+            requestStream.write(audioChunk);
+        },
+        end() {
+            requestStream.end();
+        },
+        destroy() {
+            requestStream.destroy();
+            responseStream.destroy();
+        },
+        [Symbol.asyncIterator]() {
+            if (consumed) {
+                throw new TranscriptionFailedError("TranscribeStreamSession can only be iterated once");
+            }
+            consumed = true;
+            return responses;
+        },
+    };
+}
+async function* parseResponseLines(responseStream) {
+    let buf = "";
+    for await (const chunk of responseStream) {
+        buf += chunk.toString();
+        const lines = buf.split("\n");
+        buf = lines.pop() || "";
+        for (const line of lines) {
+            const result = processLine(line);
+            if (result === null)
+                return;
+            if (result !== undefined)
+                yield result;
+        }
+    }
+    // Process any residual data after stream ends
+    if (buf.trim()) {
+        const result = processLine(buf);
+        if (result !== null && result !== undefined)
+            yield result;
+    }
+}
+function processLine(line) {
+    if (!line.trim())
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        logger.warn("transcribeStream: malformed JSON from server:", line);
+        return undefined;
+    }
+    const obj = parsed;
+    if (obj["type"] === "error") {
+        throw new TranscriptionFailedError(obj["message"] ?? "Unknown server error");
+    }
+    const response = transcribeStreamResponseSchema.parse(parsed);
+    if (response.error)
+        throw new TranscriptionFailedError(response.error);
+    if (response.done)
+        return null;
+    if (response.text?.trim())
+        return response.text;
+    return undefined;
+}

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

@@ -7,5 +7,9 @@ export declare function getRPC(): Promise<{
         createResponseStream(): AsyncGenerator<Buffer<ArrayBuffer>, void, unknown>;
     };
 }>;
-export declare function close(): void;
+export declare function close(): Promise<void>;
+export declare function createDuplexSession(payload: string, _commandId: number): Promise<{
+    requestStream: import("bare-stream").Transform<import("bare-stream").TransformEvents>;
+    responseStream: import("bare-stream").Transform<import("bare-stream").TransformEvents>;
+}>;
 //# sourceMappingURL=bare-client.d.ts.map

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

@@ -1,6 +1,8 @@
 import { normalizeModelType } from "../../schemas/index.js";
 import os from "bare-os";
 import { handlers } from "../../server/rpc/handlers/index.js";
+import { registry } from "../../server/rpc/handler-registry.js";
+import { createErrorResponse } from "../../schemas/index.js";
 import { PearWorkerEntryRequiredError, RPCNoHandlerError, RPCRequestNotSentError, } from "../../utils/errors-client.js";
 import { initializeConfig } from "../init-hooks.js";
 import { setSDKConfig } from "../../server/bare/registry/config-registry.js";
@@ -9,7 +11,7 @@ import { resolveModelConfig } from "../../server/bare/registry/model-config-regi
 import { resolveConfig } from "../config-loader/resolve-config.bare.js";
 import { getClientLogger } from "../../logging/index.js";
 import { getAllPlugins } from "../../server/plugins/index.js";
-import { initializeWorkerCore } from "../../server/worker-core.js";
+import { initializeWorkerCore, shutdownBareDirectWorker, } from "../../server/worker-core.js";
 const logger = getClientLogger();
 /**
  * Load worker entry to register plugins before any SDK calls.
@@ -67,6 +69,37 @@ function applyDeviceDefaultsToLoadModel(request) {
     const configWithDefaults = resolveModelConfig(canonicalType, rawConfig);
     return { ...request, modelConfig: configWithDefaults };
 }
+function supportsProgressStreaming(request) {
+    return ("withProgress" in request &&
+        request.withProgress &&
+        ["loadModel", "downloadAsset", "rag", "finetune"].includes(request.type));
+}
+async function* streamWithProgress(request, handler) {
+    const queue = [];
+    const errors = [];
+    let done = false;
+    handler(request, (update) => queue.push(update))
+        .then((final) => {
+        queue.push(final);
+        done = true;
+    })
+        .catch((error) => {
+        errors.push(error);
+        done = true;
+    });
+    while (!done || queue.length > 0) {
+        if (queue.length > 0) {
+            yield queue.shift();
+        }
+        else {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+    const handlerError = errors[0];
+    if (handlerError) {
+        throw handlerError;
+    }
+}
 export async function send(request) {
     const handler = getHandler(request.type);
     if (!handler)
@@ -78,61 +111,9 @@ async function* stream(request) {
     const handler = getHandler(request.type);
     if (!handler)
         throw new RPCNoHandlerError(request.type);
-    // Special handling for loadModel with progress
-    if (request.type === "loadModel" &&
-        "withProgress" in request &&
-        request.withProgress) {
+    if (supportsProgressStreaming(request)) {
         const processedRequest = applyDeviceDefaultsToLoadModel(request);
-        async function* streamWithProgress() {
-            const queue = [];
-            let done = false;
-            const loadModelHandler = handler;
-            loadModelHandler(processedRequest, (update) => queue.push(update))
-                .then((final) => {
-                queue.push(final);
-                done = true;
-            })
-                .catch((error) => {
-                done = true;
-                throw error;
-            });
-            while (!done || queue.length > 0) {
-                if (queue.length > 0) {
-                    yield queue.shift();
-                }
-                else {
-                    await new Promise((resolve) => setTimeout(resolve, 10));
-                }
-            }
-        }
-        yield* streamWithProgress();
-    }
-    else if (request.type === "downloadAsset" &&
-        "withProgress" in request &&
-        request.withProgress) {
-        async function* streamWithProgress() {
-            const queue = [];
-            let done = false;
-            const downloadAssetHandler = handler;
-            downloadAssetHandler(request, (update) => queue.push(update))
-                .then((final) => {
-                queue.push(final);
-                done = true;
-            })
-                .catch((error) => {
-                done = true;
-                throw error;
-            });
-            while (!done || queue.length > 0) {
-                if (queue.length > 0) {
-                    yield queue.shift();
-                }
-                else {
-                    await new Promise((resolve) => setTimeout(resolve, 10));
-                }
-            }
-        }
-        yield* streamWithProgress();
+        yield* streamWithProgress(processedRequest, handler);
     }
     else {
         const result = handler(request);
@@ -214,6 +195,38 @@ export async function getRPC() {
     }
     return mockRPC;
 }
-export function close() {
-    // noop
+export async function close() {
+    await shutdownBareDirectWorker("rpc-close");
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export async function createDuplexSession(payload, _commandId) {
+    await getRPC();
+    const { PassThrough } = await import("bare-stream");
+    const request = JSON.parse(payload);
+    const entry = registry[request.type];
+    if (!entry || entry.type !== "duplex") {
+        throw new RPCNoHandlerError(request.type);
+    }
+    const inputStream = new PassThrough();
+    const outputStream = new PassThrough();
+    const duplexHandler = entry.handler;
+    void (async () => {
+        try {
+            for await (const response of duplexHandler(request, inputStream)) {
+                outputStream.write(JSON.stringify(response) + "\n", "utf-8");
+            }
+        }
+        catch (error) {
+            inputStream.destroy();
+            const errorResponse = createErrorResponse(error);
+            outputStream.write(JSON.stringify(errorResponse) + "\n", "utf-8");
+        }
+        finally {
+            outputStream.end();
+        }
+    })();
+    return {
+        requestStream: inputStream,
+        responseStream: outputStream,
+    };
 }

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

@@ -1,4 +1,8 @@
 import RPC from "bare-rpc";
 export declare function getRPC(): Promise<RPC>;
 export declare function close(): void;
+export declare function createDuplexSession(payload: string, commandId: number): Promise<{
+    requestStream: RPC.OutgoingStream;
+    responseStream: RPC.IncomingStream;
+}>;
 //# sourceMappingURL=expo-rpc-client.d.ts.map

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

@@ -98,3 +98,11 @@ export function close() {
     rpcInstance = null;
     rpcPromise = null;
 }
+export async function createDuplexSession(payload, commandId) {
+    const rpc = await getRPC();
+    const req = rpc.request(commandId);
+    const requestStream = req.createRequestStream();
+    const responseStream = req.createResponseStream({ encoding: "utf-8" });
+    requestStream.write(payload, "utf-8");
+    return { requestStream, responseStream };
+}

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

@@ -1,4 +1,8 @@
 import RPC from "bare-rpc";
 export declare function getRPC(): Promise<RPC>;
+export declare function createDuplexSession(payload: string, commandId: number): Promise<{
+    requestStream: RPC.OutgoingStream;
+    responseStream: RPC.IncomingStream;
+}>;
 export declare function close(): Promise<void>;
 //# sourceMappingURL=node-rpc-client.d.ts.map

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

@@ -204,6 +204,14 @@ async function ensureRPC() {
 export async function getRPC() {
     return ensureRPC();
 }
+export async function createDuplexSession(payload, commandId) {
+    const rpc = await ensureRPC();
+    const req = rpc.request(commandId);
+    const requestStream = req.createRequestStream();
+    const responseStream = req.createResponseStream({ encoding: "utf-8" });
+    requestStream.write(payload, "utf-8");
+    return { requestStream, responseStream };
+}
 export async function close() {
     if (closePromise) {
         await closePromise;

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

@@ -2,5 +2,18 @@ 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, options?: RPCOptions, rpc?: RPC): Promise<Response>;
 export declare function stream<T extends Request>(request: T, options?: RPCOptions, rpc?: RPC): AsyncGenerator<Response>;
+export interface DuplexWritable {
+    write(chunk: Buffer): void;
+    end(): void;
+    destroy(): void;
+}
+export interface DuplexReadable extends AsyncIterable<Buffer> {
+    destroy(): void;
+}
+export interface DuplexSession {
+    requestStream: DuplexWritable;
+    responseStream: DuplexReadable;
+}
+export declare function duplex<T extends Request>(request: T, options?: RPCOptions): Promise<DuplexSession>;
 export declare function close(): Promise<void>;
 //# sourceMappingURL=rpc-client.d.ts.map

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

@@ -2,7 +2,7 @@ import { requestSchema, responseSchema, PROFILING_TRAILER_KEY, } from "../../sch
 import { RPCError } from "./rpc-error.js";
 import { withTimeout, withTimeoutStream } from "../../utils/withTimeout.js";
 import { getClientLogger, summarizeRequest } from "../../logging/index.js";
-import { getRPC, close as closeRPC } from "#rpc";
+import { getRPC, close as closeRPC, createDuplexSession } from "#rpc";
 import { nowMs, shouldProfile, shouldIncludeServerBreakdown, generateId as createProfileId, createProfilingMeta, createProfilingDisabledMeta, injectProfilingMetaIntoObject, extractProfilingMeta, stripProfilingMeta, recordFailure, } from "../../profiling/index.js";
 import { createClientTimings, createClientStreamTimings, recordClientEvents, recordClientStreamEvents, cacheConnectionTime, flushConnectionTime, resetConnectionTracking, } from "./profiling/index.js";
 const logger = getClientLogger();
@@ -222,6 +222,136 @@ async function* streamProfiled(request, rpc, options = {}) {
         }
     }
 }
+export async function duplex(request, options) {
+    const ctx = await prepareRPCContext(request.type, options?.profiling);
+    if (!ctx.profilingEnabled) {
+        return duplexBase(request, ctx.signalDisable, options?.timeout);
+    }
+    return duplexProfiled(request, options);
+}
+async function duplexBase(request, signalDisable, timeout) {
+    const parsedRequest = requestSchema.parse(request);
+    logger.debug("RPC Client duplex:", summarizeRequest(request));
+    const payloadObj = signalDisable
+        ? injectProfilingMetaIntoObject(parsedRequest, createProfilingDisabledMeta())
+        : parsedRequest;
+    const payload = JSON.stringify(payloadObj);
+    const sessionPromise = createDuplexSession(payload, getNextCommandId());
+    const session = await withTimeout(sessionPromise, timeout);
+    return {
+        requestStream: session.requestStream,
+        responseStream: session.responseStream,
+    };
+}
+async function duplexProfiled(request, options = {}) {
+    const requestType = request.type;
+    const profileId = createProfileId();
+    const includeServer = shouldIncludeServerBreakdown(options?.profiling);
+    const timings = createClientStreamTimings(profileId, requestType);
+    let session;
+    try {
+        const zodStart = nowMs();
+        const parsedRequest = requestSchema.parse(request);
+        timings.requestZodValidationMs = nowMs() - zodStart;
+        logger.debug("RPC Client duplex:", summarizeRequest(request));
+        const requestMeta = createProfilingMeta(profileId, includeServer);
+        const requestWithMeta = injectProfilingMetaIntoObject(parsedRequest, requestMeta);
+        const stringifyStart = nowMs();
+        const payload = JSON.stringify(requestWithMeta);
+        timings.requestStringifyMs = nowMs() - stringifyStart;
+        timings.sendStart = nowMs();
+        const sessionPromise = createDuplexSession(payload, getNextCommandId());
+        session = await withTimeout(sessionPromise, options?.timeout);
+    }
+    catch (error) {
+        const base = {
+            ts: nowMs(),
+            op: timings.requestType,
+            kind: "rpc",
+            profileId: timings.profileId,
+        };
+        recordFailure(base, timings.requestStart, error);
+        throw error;
+    }
+    let profilingMeta = undefined;
+    const rawReadable = session.responseStream;
+    async function* profiledResponseStream() {
+        let lineBuffer = "";
+        try {
+            for await (const chunk of rawReadable) {
+                const chunkTime = nowMs();
+                if (timings.firstChunkAt === undefined) {
+                    timings.firstChunkAt = chunkTime;
+                }
+                timings.lastChunkAt = chunkTime;
+                lineBuffer += chunk.toString();
+                const lines = lineBuffer.split("\n");
+                lineBuffer = lines.pop() || "";
+                const outputParts = [];
+                for (const line of lines) {
+                    if (!line.trim())
+                        continue;
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(line);
+                    }
+                    catch {
+                        outputParts.push(line);
+                        continue;
+                    }
+                    const chunkMeta = extractProfilingMeta(parsed);
+                    if (chunkMeta) {
+                        profilingMeta = chunkMeta;
+                    }
+                    if (parsed[PROFILING_TRAILER_KEY] === true) {
+                        continue;
+                    }
+                    // Yield original line — consumer's Zod .parse() strips profiling keys
+                    outputParts.push(line);
+                }
+                if (outputParts.length > 0) {
+                    timings.chunkCount += outputParts.length;
+                    yield Buffer.from(outputParts.join("\n") + "\n");
+                }
+            }
+            if (lineBuffer.trim()) {
+                timings.chunkCount++;
+                yield Buffer.from(lineBuffer + "\n");
+            }
+        }
+        catch (error) {
+            if (timings.requestEnd === undefined) {
+                const base = {
+                    ts: nowMs(),
+                    op: timings.requestType,
+                    kind: "rpc",
+                    profileId: timings.profileId,
+                };
+                recordFailure(base, timings.requestStart, error);
+            }
+            throw error;
+        }
+        finally {
+            if (timings.chunkCount > 0) {
+                timings.requestEnd = nowMs();
+                recordClientStreamEvents(timings, profilingMeta);
+            }
+        }
+    }
+    const generator = profiledResponseStream();
+    const wrappedResponseStream = {
+        [Symbol.asyncIterator]() {
+            return generator[Symbol.asyncIterator]();
+        },
+        destroy() {
+            rawReadable.destroy();
+        },
+    };
+    return {
+        requestStream: session.requestStream,
+        responseStream: wrappedResponseStream,
+    };
+}
 export async function close() {
     if (!rpcInstance)
         return;

package/dist/examples/delegated-inference/composite.d.ts

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

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

@@ -0,0 +1,99 @@
+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;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const providerScript = join(__dirname, "provider.ts");
+// ── Provider lifecycle ──────────────────────────────────────────────
+function spawnProviderProcess() {
+    const child = spawn("bun", ["run", providerScript, TOPIC], {
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    child.stderr?.on("data", (chunk) => {
+        process.stderr.write(chunk);
+    });
+    return child;
+}
+function terminateProvider(provider) {
+    if (!provider.killed) {
+        provider.kill("SIGTERM");
+    }
+}
+// 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>"
+function waitForProviderPublicKey(provider) {
+    return new Promise((resolve, reject) => {
+        let output = "";
+        const timeout = setTimeout(() => {
+            reject(new Error("Provider did not emit its public key in time"));
+        }, PROVIDER_STARTUP_TIMEOUT_MS);
+        provider.stdout.on("data", (chunk) => {
+            const str = chunk.toString();
+            output += str;
+            process.stdout.write(str);
+            const match = output.match(/Provider Public Key \(unique\): ([a-f0-9]+)/i);
+            if (match) {
+                clearTimeout(timeout);
+                resolve(match[1]);
+            }
+        });
+        provider.on("error", (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+        provider.on("close", (code) => {
+            clearTimeout(timeout);
+            reject(new Error(`Provider exited unexpectedly (code ${String(code)})`));
+        });
+    });
+}
+// ── Consumer: delegated model load + completion ─────────────────────
+async function runDelegatedCompletion(topic, 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,
+        },
+        onProgress: (progress) => {
+            console.log(`  Download: ${progress.percentage.toFixed(1)}%`);
+        },
+    });
+    console.log(`✅ Model loaded: ${modelId}\n`);
+    console.log("→ Running delegated completion (streamed)...");
+    const response = completion({
+        modelId,
+        history: [{ role: "user", content: "Say hello in exactly 5 words." }],
+        stream: true,
+    });
+    process.stdout.write("  Response: ");
+    for await (const token of response.tokenStream) {
+        process.stdout.write(token);
+    }
+    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);
+    void close();
+}
+finally {
+    terminateProvider(provider);
+}
+process.exit(0);

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

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