@qvac/sdk 0.8.2 → 0.9.0

package/dist/client/api/diffusion.js

@@ -0,0 +1,103 @@
+import { diffusionStreamResponseSchema, } from "../../schemas/index.js";
+import { stream as streamRpc } from "../rpc/rpc-client.js";
+import { decodeBase64 } from "../../utils/encoding.js";
+/**
+ * Generate images using a loaded diffusion model.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const { outputs, stats } = diffusion({ modelId, prompt: "a cat" });
+ * const buffers = await outputs;
+ * fs.writeFileSync("output.png", buffers[0]);
+ *
+ * // With progress tracking
+ * const { progressStream, outputs } = diffusion({ modelId, prompt: "a cat" });
+ * for await (const { step, totalSteps } of progressStream) {
+ *   console.log(`${step}/${totalSteps}`);
+ * }
+ * const buffers = await outputs;
+ * ```
+ */
+export function diffusion(params) {
+    const request = {
+        type: "diffusionStream",
+        ...params,
+    };
+    let statsResolver = () => { };
+    let statsRejecter = () => { };
+    const statsPromise = new Promise((resolve, reject) => {
+        statsResolver = resolve;
+        statsRejecter = reject;
+    });
+    statsPromise.catch(() => { });
+    const progressQueue = [];
+    const collectedBuffers = [];
+    let progressDone = false;
+    let progressResolve = null;
+    let streamError = null;
+    let outputsResolver = () => { };
+    let outputsRejecter = () => { };
+    const outputsPromise = new Promise((resolve, reject) => {
+        outputsResolver = resolve;
+        outputsRejecter = reject;
+    });
+    outputsPromise.catch(() => { });
+    const processResponses = async () => {
+        try {
+            for await (const response of streamRpc(request)) {
+                if (response &&
+                    typeof response === "object" &&
+                    "type" in response &&
+                    response.type === "diffusionStream") {
+                    const parsed = diffusionStreamResponseSchema.parse(response);
+                    if (parsed.step != null && parsed.totalSteps != null && parsed.elapsedMs != null) {
+                        progressQueue.push({ step: parsed.step, totalSteps: parsed.totalSteps, elapsedMs: parsed.elapsedMs });
+                        if (progressResolve) {
+                            progressResolve();
+                            progressResolve = null;
+                        }
+                    }
+                    if (parsed.data) {
+                        collectedBuffers.push(decodeBase64(parsed.data));
+                    }
+                    if (parsed.done) {
+                        statsResolver(parsed.stats);
+                        outputsResolver(collectedBuffers);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            streamError = error instanceof Error ? error : new Error(String(error));
+            statsRejecter(streamError);
+            outputsRejecter(streamError);
+        }
+        progressDone = true;
+        if (progressResolve) {
+            progressResolve();
+            progressResolve = null;
+        }
+    };
+    void processResponses();
+    const progressStream = (async function* () {
+        while (true) {
+            if (progressQueue.length > 0) {
+                yield progressQueue.shift();
+            }
+            else if (progressDone) {
+                if (streamError)
+                    throw streamError;
+                return;
+            }
+            else {
+                await new Promise((resolve) => { progressResolve = resolve; });
+            }
+        }
+    })();
+    return {
+        progressStream,
+        outputs: outputsPromise,
+        stats: statsPromise,
+    };
+}

package/dist/client/api/embed.d.ts

@@ -1,4 +1,4 @@
-import { type RPCOptions } from "../../schemas/index";
+import { type EmbedStats, type RPCOptions } from "../../schemas/index";
 /**
  * Generates embeddings for a single text using a specified model.
  *
@@ -11,7 +11,10 @@ import { type RPCOptions } from "../../schemas/index";
 export declare function embed(params: {
     modelId: string;
     text: string;
-}, options?: RPCOptions): Promise<number[]>;
+}, options?: RPCOptions): Promise<{
+    embedding: number[];
+    stats?: EmbedStats;
+}>;
 /**
  * Generates embeddings for multiple texts using a specified model.
  *
@@ -24,5 +27,8 @@ export declare function embed(params: {
 export declare function embed(params: {
     modelId: string;
     text: string[];
-}, options?: RPCOptions): Promise<number[][]>;
+}, options?: RPCOptions): Promise<{
+    embedding: number[][];
+    stats?: EmbedStats;
+}>;
 //# sourceMappingURL=embed.d.ts.map

package/dist/client/api/embed.js

@@ -10,5 +10,8 @@ export async function embed(params, options) {
     if (response.type !== "embed") {
         throw new InvalidResponseError("embed");
     }
-    return response.embedding;
+    return {
+        embedding: response.embedding,
+        ...(response.stats !== undefined && { stats: response.stats }),
+    };
 }

package/dist/client/api/finetune.d.ts

@@ -0,0 +1,69 @@
+import { type FinetuneGetStateParams, type FinetuneProgress, type FinetuneResult, type FinetuneRunParams, type FinetuneStopParams, type RPCOptions } from "../../schemas/index";
+export interface FinetuneHandle {
+    progressStream: AsyncGenerator<FinetuneProgress>;
+    result: Promise<FinetuneResult>;
+}
+type FinetuneReplyParams = FinetuneStopParams | FinetuneGetStateParams;
+/**
+ * Starts, resumes, inspects, pauses, or cancels a finetuning job for a loaded model.
+ *
+ * @param params - The finetuning parameters
+ * @param params.modelId - The identifier of the loaded model to finetune
+ * @param params.operation - The finetuning operation. Omit it to let the add-on
+ *   choose whether to start fresh or resume automatically
+ * @param params.options - Finetuning options for run and `getState` operations
+ * @param params.options.trainDatasetDir - Directory containing the training dataset
+ * @param params.options.validation - Validation configuration for the finetuning run
+ * @param params.options.outputParametersDir - Directory where output adapter parameters are written
+ * @param params.options.numberOfEpochs - Optional number of epochs to run
+ * @param params.options.learningRate - Optional learning rate override
+ * @param params.options.contextLength - Optional context length override
+ * @param params.options.batchSize - Optional batch size override
+ * @param params.options.microBatchSize - Optional micro batch size override
+ * @param params.options.assistantLossOnly - Optional flag to compute loss only on assistant tokens
+ * @param params.options.loraRank - Optional LoRA rank override
+ * @param params.options.loraAlpha - Optional LoRA alpha override
+ * @param params.options.loraInitStd - Optional LoRA initialization standard deviation
+ * @param params.options.loraSeed - Optional LoRA initialization seed
+ * @param params.options.loraModules - Optional comma-separated LoRA module selection
+ * @param params.options.checkpointSaveDir - Optional directory for checkpoint snapshots
+ * @param params.options.checkpointSaveSteps - Optional checkpoint save interval
+ * @param params.options.chatTemplatePath - Optional custom chat template path
+ * @param params.options.lrScheduler - Optional learning rate scheduler
+ * @param params.options.lrMin - Optional minimum learning rate
+ * @param params.options.warmupRatio - Optional warmup ratio
+ * @param params.options.warmupRatioSet - Optional flag to enable warmup ratio
+ * @param params.options.warmupSteps - Optional warmup step count
+ * @param params.options.warmupStepsSet - Optional flag to enable explicit warmup steps
+ * @param params.options.weightDecay - Optional weight decay override
+ * @param rpcOptions - Optional RPC transport options
+ * @returns For omitted-operation runs, `start`, and `resume`, returns a handle
+ *   with a `progressStream` generator and a terminal `result` promise. For
+ *   `getState`, `pause`, and `cancel`, returns a promise that resolves to the
+ *   current finetune state/result.
+ * @example
+ * ```typescript
+ * const handle = finetune({
+ *   modelId,
+ *   options: {
+ *     trainDatasetDir: "./dataset/train",
+ *     validation: { type: "split", fraction: 0.05 },
+ *     outputParametersDir: "./artifacts/lora",
+ *     numberOfEpochs: 2,
+ *   },
+ * });
+ *
+ * for await (const progress of handle.progressStream) {
+ *   console.log(progress.global_steps, progress.loss);
+ * }
+ *
+ * console.log(await handle.result);
+ *
+ * const pauseResult = await finetune({ modelId, operation: "pause" });
+ * console.log(pauseResult.status);
+ * ```
+ */
+export declare function finetune(params: FinetuneRunParams, rpcOptions?: RPCOptions): FinetuneHandle;
+export declare function finetune(params: FinetuneReplyParams, rpcOptions?: RPCOptions): Promise<FinetuneResult>;
+export {};
+//# sourceMappingURL=finetune.d.ts.map

package/dist/client/api/finetune.js

@@ -0,0 +1,139 @@
+import { send, stream as streamRpc } from "../rpc/rpc-client.js";
+import { finetuneRunParamsSchema, finetuneRunRequestSchema, finetuneStopRequestSchema, finetuneGetStateParamsSchema, finetuneGetStateRequestSchema, finetuneProgressResponseSchema, finetuneResponseSchema, } from "../../schemas/index.js";
+import { InvalidResponseError, StreamEndedError, } from "../../utils/errors-client.js";
+function isFinetuneReplyParams(params) {
+    return (params.operation === "pause" ||
+        params.operation === "cancel" ||
+        params.operation === "getState");
+}
+function createFinetuneReplyRequest(params) {
+    if (params.operation === "getState") {
+        const getStateParams = finetuneGetStateParamsSchema.parse(params);
+        return finetuneGetStateRequestSchema.parse({
+            type: "finetune",
+            ...getStateParams,
+        });
+    }
+    return finetuneStopRequestSchema.parse({
+        type: "finetune",
+        modelId: params.modelId,
+        operation: params.operation,
+    });
+}
+export function finetune(params, rpcOptions) {
+    if (isFinetuneReplyParams(params)) {
+        const request = createFinetuneReplyRequest(params);
+        const resultPromise = (async () => {
+            const response = await send(request, rpcOptions);
+            if (!response ||
+                typeof response !== "object" ||
+                !("type" in response) ||
+                response.type !== "finetune") {
+                throw new InvalidResponseError("finetune");
+            }
+            return finetuneResponseSchema.parse(response);
+        })();
+        resultPromise.catch(() => { });
+        return resultPromise;
+    }
+    const runParams = finetuneRunParamsSchema.parse(params);
+    let resultResolver = () => { };
+    let resultRejecter = () => { };
+    const resultPromise = new Promise((resolve, reject) => {
+        resultResolver = resolve;
+        resultRejecter = reject;
+    });
+    resultPromise.catch(() => { });
+    const progressQueue = [];
+    let progressDone = false;
+    let progressResolve = null;
+    let streamError = null;
+    const processResponses = async () => {
+        try {
+            let sawTerminalResponse = false;
+            const request = finetuneRunRequestSchema.parse({
+                type: "finetune",
+                ...runParams,
+                withProgress: true,
+            });
+            const responses = streamRpc(request, rpcOptions);
+            for await (const response of responses) {
+                if (response &&
+                    typeof response === "object" &&
+                    "type" in response &&
+                    response.type === "finetune:progress") {
+                    const progressResponse = finetuneProgressResponseSchema.parse(response);
+                    progressQueue.push({
+                        is_train: progressResponse.is_train,
+                        loss: progressResponse.loss,
+                        loss_uncertainty: progressResponse.loss_uncertainty,
+                        accuracy: progressResponse.accuracy,
+                        accuracy_uncertainty: progressResponse.accuracy_uncertainty,
+                        global_steps: progressResponse.global_steps,
+                        current_epoch: progressResponse.current_epoch,
+                        current_batch: progressResponse.current_batch,
+                        total_batches: progressResponse.total_batches,
+                        elapsed_ms: progressResponse.elapsed_ms,
+                        eta_ms: progressResponse.eta_ms,
+                    });
+                    if (progressResolve) {
+                        progressResolve();
+                        progressResolve = null;
+                    }
+                    continue;
+                }
+                if (response &&
+                    typeof response === "object" &&
+                    "type" in response &&
+                    response.type === "finetune") {
+                    sawTerminalResponse = true;
+                    const finetuneResponse = finetuneResponseSchema.parse(response);
+                    resultResolver(finetuneResponse);
+                    progressDone = true;
+                    if (progressResolve) {
+                        progressResolve();
+                        progressResolve = null;
+                    }
+                }
+                else {
+                    throw new InvalidResponseError("finetune");
+                }
+            }
+            if (!sawTerminalResponse) {
+                throw new StreamEndedError();
+            }
+        }
+        catch (error) {
+            streamError = error instanceof Error ? error : new Error(String(error));
+            resultRejecter(error);
+            progressDone = true;
+            if (progressResolve) {
+                progressResolve();
+                progressResolve = null;
+            }
+        }
+    };
+    void processResponses();
+    const progressStream = (async function* () {
+        while (true) {
+            if (progressQueue.length > 0) {
+                yield progressQueue.shift();
+            }
+            else if (progressDone) {
+                if (streamError !== null) {
+                    throw streamError;
+                }
+                break;
+            }
+            else {
+                await new Promise((resolve) => {
+                    progressResolve = resolve;
+                });
+            }
+        }
+    })();
+    return {
+        progressStream,
+        result: resultPromise,
+    };
+}

package/dist/client/api/get-model-info.d.ts

@@ -4,7 +4,7 @@ export declare function getModelInfo(params: GetModelInfoParams): Promise<{
     modelId: string;
     expectedSize: number;
     sha256Checksum: string;
-    addon: "llm" | "whisper" | "embeddings" | "nmt" | "parakeet" | "tts" | "ocr" | "vad" | "other";
+    addon: "llm" | "whisper" | "embeddings" | "nmt" | "parakeet" | "tts" | "ocr" | "diffusion" | "vad" | "other";
     isCached: boolean;
     isLoaded: boolean;
     cacheFiles: {

package/dist/client/api/index.d.ts

@@ -7,6 +7,7 @@ export { loggingStream } from "./logging-stream";
 export { heartbeat } from "./heartbeat";
 export { transcribe, transcribeStream } from "./transcribe";
 export { embed } from "./embed";
+export { finetune, type FinetuneHandle } from "./finetune";
 export { translate } from "./translate";
 export { cancel } from "./cancel";
 export { startQVACProvider } from "./provide";
@@ -16,5 +17,8 @@ export { textToSpeech } from "./text-to-speech";
 export { getModelInfo } from "./get-model-info";
 export { ocr } from "./ocr";
 export { invokePlugin, invokePluginStream } from "./invoke-plugin";
+export { diffusion, type DiffusionProgressTick } from "./diffusion";
 export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel, type ModelRegistrySearchParams, } from "./registry";
+export { suspend } from "./suspend";
+export { resume } from "./resume";
 //# sourceMappingURL=index.d.ts.map

package/dist/client/api/index.js

@@ -7,6 +7,7 @@ export { loggingStream } from "./logging-stream.js";
 export { heartbeat } from "./heartbeat.js";
 export { transcribe, transcribeStream } from "./transcribe.js";
 export { embed } from "./embed.js";
+export { finetune } from "./finetune.js";
 export { translate } from "./translate.js";
 export { cancel } from "./cancel.js";
 export { startQVACProvider } from "./provide.js";
@@ -16,4 +17,7 @@ export { textToSpeech } from "./text-to-speech.js";
 export { getModelInfo } from "./get-model-info.js";
 export { ocr } from "./ocr.js";
 export { invokePlugin, invokePluginStream } from "./invoke-plugin.js";
+export { diffusion } from "./diffusion.js";
 export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel, } from "./registry.js";
+export { suspend } from "./suspend.js";
+export { resume } from "./resume.js";

package/dist/client/api/rag.d.ts

@@ -84,7 +84,7 @@ export declare function ragIngest(params: RagIngestParams, options?: RPCOptions)
  * ```typescript
  * // Segregated flow
  * const chunks = await ragChunk({ documents: ["text1", "text2"] });
- * const embeddings = await embed({ modelId, text: chunks.map(c => c.content) });
+ * const { embedding: embeddings } = await embed({ modelId, text: chunks.map(c => c.content) });
  * const embeddedDocs = chunks.map((chunk, i) => ({
  *   ...chunk,
  *   embedding: embeddings[i],

package/dist/client/api/rag.js

@@ -145,7 +145,7 @@ export async function ragIngest(params, options) {
  * ```typescript
  * // Segregated flow
  * const chunks = await ragChunk({ documents: ["text1", "text2"] });
- * const embeddings = await embed({ modelId, text: chunks.map(c => c.content) });
+ * const { embedding: embeddings } = await embed({ modelId, text: chunks.map(c => c.content) });
  * const embeddedDocs = chunks.map((chunk, i) => ({
  *   ...chunk,
  *   embedding: embeddings[i],

package/dist/client/api/resume.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resumes all suspended Hyperswarm and Corestore resources
+ *
+ * Idempotent — calling while already active is a no-op.
+ * Also serves as the recovery path after a partial suspend failure.
+ *
+ * @throws {RPCError} When one or more resources fail to resume.
+ *
+ * @example
+ * // Foreground handler
+ * await resume();
+ */
+export declare function resume(): Promise<void>;
+//# sourceMappingURL=resume.d.ts.map

package/dist/client/api/resume.js

@@ -0,0 +1,20 @@
+import { send } from "../rpc/rpc-client.js";
+import { InvalidResponseError } from "../../utils/errors-client.js";
+/**
+ * Resumes all suspended Hyperswarm and Corestore resources
+ *
+ * Idempotent — calling while already active is a no-op.
+ * Also serves as the recovery path after a partial suspend failure.
+ *
+ * @throws {RPCError} When one or more resources fail to resume.
+ *
+ * @example
+ * // Foreground handler
+ * await resume();
+ */
+export async function resume() {
+    const response = await send({ type: "resume" });
+    if (response.type !== "resume") {
+        throw new InvalidResponseError("resume");
+    }
+}

package/dist/client/api/suspend.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Suspends all active Hyperswarm and Corestore resources
+ *
+ * Idempotent — calling while already suspended is a no-op.
+ *
+ * @throws {RPCError} When one or more resources fail to suspend (partial failure).
+ *
+ * @example
+ * // Background handler
+ * await suspend();
+ */
+export declare function suspend(): Promise<void>;
+//# sourceMappingURL=suspend.d.ts.map

package/dist/client/api/suspend.js

@@ -0,0 +1,19 @@
+import { send } from "../rpc/rpc-client.js";
+import { InvalidResponseError } from "../../utils/errors-client.js";
+/**
+ * Suspends all active Hyperswarm and Corestore resources
+ *
+ * Idempotent — calling while already suspended is a no-op.
+ *
+ * @throws {RPCError} When one or more resources fail to suspend (partial failure).
+ *
+ * @example
+ * // Background handler
+ * await suspend();
+ */
+export async function suspend() {
+    const response = await send({ type: "suspend" });
+    if (response.type !== "suspend") {
+        throw new InvalidResponseError("suspend");
+    }
+}

package/dist/client/api/transcribe.d.ts

@@ -1,28 +1,36 @@
-import { type TranscribeClientParams, type RPCOptions } from "../../schemas/index";
+import { type TranscribeClientParams, type RPCOptions, type TranscribeStreamClientParams, type TranscribeStreamSession } from "../../schemas/index";
 /**
- * This function streams audio transcription results in real-time, yielding
- * text chunks as they become available from the model.
+ * 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
- * @yields {string} Text chunks as they are transcribed
- * @throws {QvacErrorBase} When transcription fails with an error message
+ * @returns The complete transcribed text
  */
-export declare function transcribeStream(params: TranscribeClientParams, options?: RPCOptions): AsyncGenerator<string, void, unknown>;
+export declare function transcribe(params: TranscribeClientParams, options?: RPCOptions): Promise<string>;
 /**
- * This function provides a simple interface for transcribing audio by
- * collecting all streaming results into a single string response.
+ * @deprecated Pass audio via `transcribe()` instead. This overload will be
+ * removed in the next major version.
  *
- * @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)
+ * Streaming transcription with upfront audio: sends full audio, yields text
+ * chunks as they arrive.
  */
-export declare function transcribe(params: TranscribeClientParams, options?: RPCOptions): Promise<string>;
+export declare function transcribeStream(params: TranscribeClientParams, options?: RPCOptions): AsyncGenerator<string>;
+/**
+ * Opens a bidirectional streaming transcription session. Audio is streamed
+ * in via `write()`, and transcription text is yielded as the model's VAD
+ * detects complete speech segments.
+ *
+ * The returned session is single-use. Attempting to iterate a second
+ * time will throw a `TranscriptionFailedError`.
+ *
+ * @param params.modelId - The loaded transcription model to use
+ * @param params.prompt - Optional initial prompt to guide transcription
+ * @returns A session object: call `write(buffer)` to feed audio,
+ *          iterate with `for await (const text of session)` to receive
+ *          transcription, and `end()` to signal end of audio.
+ */
+export declare function transcribeStream(params: TranscribeStreamClientParams, options?: RPCOptions): Promise<TranscribeStreamSession>;
 //# sourceMappingURL=transcribe.d.ts.map