QVAC-14104 feat[api]: SDK diffusion plugin integration

packages/sdk/client/api/diffusion.ts

@@ -0,0 +1,131 @@
+import {
+  diffusionStreamResponseSchema,
+  type DiffusionStreamRequest,
+  type DiffusionClientParams,
+  type DiffusionStats,
+} from "@/schemas";
+import { stream as streamRpc } from "@/client/rpc/rpc-client";
+
+export interface DiffusionProgressTick {
+  step: number;
+  totalSteps: number;
+  elapsedMs: number;
+}
+
+interface DiffusionResult {
+  progressStream: AsyncGenerator<DiffusionProgressTick>;
+  outputs: Promise<Buffer[]>;
+  stats: Promise<DiffusionStats | undefined>;
+}
+
+/**
+ * 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: DiffusionClientParams): DiffusionResult {
+  const request: DiffusionStreamRequest = {
+    type: "diffusionStream",
+    ...params,
+  };
+
+  let statsResolver: (value: DiffusionStats | undefined) => void = () => {};
+  let statsRejecter: (error: unknown) => void = () => {};
+  const statsPromise = new Promise<DiffusionStats | undefined>(
+    (resolve, reject) => {
+      statsResolver = resolve;
+      statsRejecter = reject;
+    },
+  );
+  statsPromise.catch(() => {});
+
+  const progressQueue: DiffusionProgressTick[] = [];
+  const collectedBuffers: Buffer[] = [];
+  let progressDone = false;
+  let progressResolve: (() => void) | null = null;
+  let streamError: Error | null = null;
+
+  let outputsResolver: (value: Buffer[]) => void = () => {};
+  let outputsRejecter: (error: unknown) => void = () => {};
+  const outputsPromise = new Promise<Buffer[]>((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(Buffer.from(parsed.data, "base64"));
+          }
+
+          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* (): AsyncGenerator<DiffusionProgressTick> {
+    while (true) {
+      if (progressQueue.length > 0) {
+        yield progressQueue.shift()!;
+      } else if (progressDone) {
+        if (streamError) throw streamError as Error;
+        return;
+      } else {
+        await new Promise<void>((resolve) => { progressResolve = resolve; });
+      }
+    }
+  })();
+
+  return {
+    progressStream,
+    outputs: outputsPromise,
+    stats: statsPromise,
+  };
+}

packages/sdk/client/api/index.ts

@@ -26,6 +26,7 @@ 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,

packages/sdk/examples/diffusion-flux2-klein.ts

@@ -0,0 +1,54 @@
+import { loadModel, unloadModel, diffusion, FLUX_2_KLEIN_4B_Q4_0, FLUX_2_KLEIN_4B_VAE, QWEN3_4B_Q4_K_M } from "@qvac/sdk";
+import fs from "fs";
+import path from "path";
+
+// FLUX.2 [klein] uses a split-layout: separate diffusion model + LLM text encoder + VAE
+const diffusionModelSrc = process.argv[2] || FLUX_2_KLEIN_4B_Q4_0;
+const llmModelSrc = process.argv[3] || QWEN3_4B_Q4_K_M;
+const vaeModelSrc = process.argv[4] || FLUX_2_KLEIN_4B_VAE;
+const prompt = process.argv[5] || "a futuristic city at sunset, photorealistic";
+const outputDir = process.argv[6] || ".";
+
+console.log("Loading FLUX.2 [klein] split-layout model...");
+
+const modelId = await loadModel({
+  modelSrc: diffusionModelSrc,
+  modelType: "diffusion",
+  modelConfig: {
+    device: "gpu",
+    threads: 4,
+    llmModelSrc,
+    vaeModelSrc,
+  },
+  onProgress: (p) => console.log(`Loading: ${p.percentage.toFixed(1)}%`),
+});
+console.log(`Model loaded: ${modelId}`);
+
+console.log(`\nGenerating: "${prompt}"`);
+
+const { progressStream, outputs, stats } = diffusion({
+  modelId,
+  prompt,
+  width: 512,
+  height: 512,
+  steps: 20,
+  guidance: 3.5,
+  seed: -1,
+});
+
+for await (const { step, totalSteps } of progressStream) {
+  process.stdout.write(`\rStep ${step}/${totalSteps}`);
+}
+console.log();
+
+const buffers = await outputs;
+for (let i = 0; i < buffers.length; i++) {
+  const outputPath = path.join(outputDir, `flux2_${i}.png`);
+  fs.writeFileSync(outputPath, buffers[i]!);
+  console.log(`Saved: ${outputPath}`);
+}
+
+console.log("\nStats:", await stats);
+await unloadModel({ modelId, clearStorage: false });
+console.log("Done.");
+process.exit(0);

packages/sdk/examples/diffusion-simple.ts

@@ -0,0 +1,22 @@
+import { loadModel, unloadModel, diffusion, SD_V2_1_1B_Q8_0 } from "@qvac/sdk";
+import fs from "fs";
+
+// Minimal diffusion example — single GGUF model, no companion files needed.
+// Works with SD 1.x / 2.x all-in-one models.
+const modelSrc = process.argv[2] || SD_V2_1_1B_Q8_0;
+const prompt = process.argv[3] || "a photo of a cat sitting on a windowsill";
+
+const modelId = await loadModel({
+  modelSrc,
+  modelType: "diffusion",
+  modelConfig: { prediction: "v" },
+});
+
+const { outputs } = diffusion({ modelId, prompt });
+const buffers = await outputs;
+
+fs.writeFileSync("output.png", buffers[0]!);
+console.log("Saved: output.png");
+
+await unloadModel({ modelId, clearStorage: false });
+process.exit(0);

packages/sdk/examples/diffusion-txt2img.ts

@@ -0,0 +1,49 @@
+import { loadModel, unloadModel, diffusion, FLUX_2_KLEIN_4B_Q4_0, FLUX_2_KLEIN_4B_VAE, QWEN3_4B_Q4_K_M } from "@qvac/sdk";
+import fs from "fs";
+import path from "path";
+
+const modelSrc = process.argv[2] || FLUX_2_KLEIN_4B_Q4_0;
+
+const prompt =
+  process.argv[3] ||
+  "a photo of a cat sitting on a windowsill, golden hour lighting";
+const outputDir = process.argv[4] || ".";
+
+console.log(`Loading diffusion model...`);
+// FLUX.2 models require companion LLM + VAE models
+const modelId = await loadModel({
+  modelSrc,
+  modelType: "diffusion",
+  modelConfig: { device: "gpu", threads: 4, llmModelSrc: QWEN3_4B_Q4_K_M, vaeModelSrc: FLUX_2_KLEIN_4B_VAE },
+  onProgress: (p) => console.log(`Loading: ${p.percentage.toFixed(1)}%`),
+});
+console.log(`Model loaded: ${modelId}`);
+
+console.log(`\nGenerating: "${prompt}"`);
+
+const { progressStream, outputs, stats } = diffusion({
+  modelId,
+  prompt,
+  width: 512,
+  height: 512,
+  steps: 20,
+  cfg_scale: 7.0,
+  seed: -1,
+});
+
+for await (const { step, totalSteps } of progressStream) {
+  process.stdout.write(`\rStep ${step}/${totalSteps}`);
+}
+console.log();
+
+const buffers = await outputs;
+for (let i = 0; i < buffers.length; i++) {
+  const outputPath = path.join(outputDir, `output_${i}.png`);
+  fs.writeFileSync(outputPath, buffers[i]!);
+  console.log(`Saved: ${outputPath}`);
+}
+
+console.log("\nStats:", await stats);
+await unloadModel({ modelId, clearStorage: false });
+console.log("Done.");
+process.exit(0);

packages/sdk/examples/mcp-websearch.ts

@@ -19,7 +19,9 @@ import {
 
 // MCP SDK is a user-installed optional dependency
 // Install with: bun add @modelcontextprotocol/sdk
+// eslint-disable-next-line import/no-unresolved
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+// eslint-disable-next-line import/no-unresolved
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 
 // ============================================================

packages/sdk/index.ts

@@ -28,6 +28,8 @@ export {
   ocr,
   invokePlugin,
   invokePluginStream,
+  diffusion,
+  type DiffusionProgressTick,
   modelRegistryList,
   modelRegistrySearch,
   modelRegistryGetModel,
@@ -71,6 +73,9 @@ export {
   type OCRClientParams,
   type OCRTextBlock,
   type OCROptions,
+  type DiffusionClientParams,
+  type DiffusionStreamResponse,
+  type DiffusionStats,
   definePlugin,
   defineHandler,
   type QvacPlugin,
@@ -84,6 +89,7 @@ export {
   PLUGIN_NMT,
   PLUGIN_TTS,
   PLUGIN_OCR,
+  PLUGIN_DIFFUSION,
   SDK_DEFAULT_PLUGINS,
   type BuiltinPlugin,
   type ProfilerMode,

packages/sdk/models/history/7481157e3.txt

@@ -0,0 +1,17 @@
+commit=7481157e314d68f268a2fcac10af36e576339635
+timestamp=2026-03-19T14:12:56.864Z
+previous_count=312
+new_count=322
+
+[added]
+FLUX_2_KLEIN_4B_VAE
+SD_V2_1_1B_Q4_0
+SD_V2_1_1B_Q8_0
+SDXL_BASE_1_0_3B_Q4_0
+SDXL_BASE_1_0_3B_Q8_0
+FLUX_2_KLEIN_4B_Q4_0
+FLUX_2_KLEIN_4B_Q4_K_M
+FLUX_2_KLEIN_4B_Q6_K
+FLUX_2_KLEIN_4B_Q8_0
+QWEN3_4B_Q4_K_M
+

packages/sdk/models/history/d514e414.txt

@@ -0,0 +1,17 @@
+commit=d514e414b345258b6fcac5887261002a8cb5beca
+timestamp=2026-03-16T05:58:16.168Z
+previous_count=310
+new_count=320
+
+[added]
+FLUX_2_KLEIN_4B_VAE
+SD_V2_1_1B_Q4_0
+SD_V2_1_1B_Q8_0
+SDXL_BASE_1_0_3B_Q4_0
+SDXL_BASE_1_0_3B_Q8_0
+FLUX_2_KLEIN_4B_Q4_0
+FLUX_2_KLEIN_4B_Q4_K_M
+FLUX_2_KLEIN_4B_Q6_K
+FLUX_2_KLEIN_4B_Q8_0
+QWEN3_4B_Q4_K_M
+