@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.2

package/src/services/imagegen/tensorrt-unavailable.d.ts

@@ -0,0 +1,83 @@
+/**
+ * TensorRT image-gen backend contract (WS3) — Windows NVIDIA.
+ *
+ * On Windows NVIDIA hosts, packaged `imagegen.exe` (built against
+ * TensorRT 10.x with the Demo Diffusion plan) is the fastest path —
+ * `nvidia/Stable-Diffusion-3.5-Medium-TensorRT` and the SDXL Turbo
+ * TensorRT plans give a 2–4× speedup over sd-cpp + CUDA on the same
+ * hardware.
+ *
+ * Why a child-process backend (and not TensorRT bindings):
+ *   - TensorRT runtime is C++; a Node binding would require shipping a
+ *     CUDA toolkit and a TensorRT runtime DLL on every Windows install,
+ *     plus rebuilding when CUDA versions change.
+ *   - The packaged `imagegen.exe` is a thin wrapper around the official
+ *     Demo Diffusion sample. The bundle installer drops it at
+ *     `${MODELS_DIR}/bin/imagegen.exe` alongside the TensorRT plan files.
+ *   - Subprocess cost is negligible relative to inference time (≈10ms
+ *     spawn vs ≈400ms inference).
+ *
+ * Binary resolution:
+ *   1. `opts.binaryPath` (test injection).
+ *   2. `process.env.IMAGEGEN_TRT_BIN` (operator override).
+ *   3. `${MODELS_DIR}/bin/imagegen.exe`.
+ *
+ * Plan file resolution:
+ *   The packaged binary expects a `--plan <path>` flag pointing at the
+ *   prebuilt TensorRT engine for the active resolution. The catalog
+ *   binds tier → plan; the installer materializes them under
+ *   `${MODELS_DIR}/imagegen/trt-plans/<modelKey>/`.
+ *
+ * Until the bundle installer + packaged binary land for Windows NVIDIA,
+ * `loadTensorRtImageGenBackend` throws `ImageGenBackendUnavailableError`
+ * and the selector falls through to sd-cpp.
+ *
+ * Publishing pipeline (Windows x86_64 NVIDIA only):
+ *
+ *   Build (`imagegen.exe`):
+ *     git clone https://github.com/NVIDIA/TensorRT && cd TensorRT/demo/Diffusion
+ *     # Build against TensorRT 10.x + CUDA 12.x
+ *     pip install -r requirements.txt
+ *     python build.py --hf-token <ci-secret> \
+ *       --version 1.5 --denoising-steps 20 \
+ *       --build-static-batch --output-dir ../../../build/imagegen-sd15
+ *     # Thin wrapper produces imagegen.exe linking against
+ *     # nvinfer_10.dll + cudart64_12.dll; pyinstaller-onefile produces a
+ *     # 35-MB executable next to the static .plan files.
+ *   Build TensorRT plan (per resolution, per model):
+ *     trtexec --onnx=unet.onnx --saveEngine=unet.plan --fp16 \
+ *       --minShapes=sample:1x4x64x64 --optShapes=sample:1x4x64x64 \
+ *       --maxShapes=sample:1x4x64x64
+ *     # Drop plan files under imagegen/trt-plans/<modelKey>/{unet,vae,clip}.plan.
+ *   Sign:
+ *     signtool sign /tr http://timestamp.digicert.com /td sha256 \
+ *       /fd sha256 /sha1 <eliza-labs-cert-thumbprint> imagegen.exe
+ *     # SmartScreen reputation builds over the first ~1000 installs;
+ *     # submit to Microsoft Defender Bytes-for-Bots if a new cert.
+ *   Drop:
+ *     releases.elizaos.ai/imagegen-trt/<version>/windows-x86_64/imagegen.exe
+ *     releases.elizaos.ai/imagegen-trt/<version>/windows-x86_64/plans/
+ *       sd-1.5-512x512/{unet,vae,clip}.plan
+ *       sdxl-turbo-1024x1024/{unet,vae,clip}.plan
+ *   The bundle installer writes the binary to
+ *   `${MODELS_DIR}/bin/imagegen.exe` and the plans under
+ *   `${MODELS_DIR}/imagegen/trt-plans/<modelKey>/`.
+ *
+ * Notarization:
+ *   N/A on Windows; SmartScreen reputation replaces the macOS notarize
+ *   step. Authenticode-signed binaries with a valid EV cert clear without
+ *   warning on first launch.
+ */
+import { type SdCppSpawnLike } from "./sd-cpp";
+import type { ImageGenBackend, ImageGenLoadArgs } from "./types";
+export interface TensorRtBackendOptions {
+    loadArgs: ImageGenLoadArgs;
+    modelKey: string;
+    binaryPath?: string;
+    outputDir?: string;
+    spawnImpl?: SdCppSpawnLike;
+    fakeImageBytes?: Uint8Array;
+    now?: () => number;
+}
+export declare function loadTensorRtImageGenBackend(opts: TensorRtBackendOptions): Promise<ImageGenBackend>;
+//# sourceMappingURL=tensorrt-unavailable.d.ts.map

package/src/services/imagegen/tensorrt-unavailable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tensorrt-unavailable.d.ts","sourceRoot":"","sources":["tensorrt-unavailable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAMH,OAAO,EAIN,KAAK,cAAc,EACnB,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACX,eAAe,EACf,gBAAgB,EAEhB,MAAM,SAAS,CAAC;AAEjB,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,cAAc,CAAC,EAAE,UAAU,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAID,wBAAsB,2BAA2B,CAChD,IAAI,EAAE,sBAAsB,GAC1B,OAAO,CAAC,eAAe,CAAC,CAmI1B"}

package/src/services/imagegen/tensorrt-unavailable.ts

@@ -0,0 +1,295 @@
+/**
+ * TensorRT image-gen backend contract (WS3) — Windows NVIDIA.
+ *
+ * On Windows NVIDIA hosts, packaged `imagegen.exe` (built against
+ * TensorRT 10.x with the Demo Diffusion plan) is the fastest path —
+ * `nvidia/Stable-Diffusion-3.5-Medium-TensorRT` and the SDXL Turbo
+ * TensorRT plans give a 2–4× speedup over sd-cpp + CUDA on the same
+ * hardware.
+ *
+ * Why a child-process backend (and not TensorRT bindings):
+ *   - TensorRT runtime is C++; a Node binding would require shipping a
+ *     CUDA toolkit and a TensorRT runtime DLL on every Windows install,
+ *     plus rebuilding when CUDA versions change.
+ *   - The packaged `imagegen.exe` is a thin wrapper around the official
+ *     Demo Diffusion sample. The bundle installer drops it at
+ *     `${MODELS_DIR}/bin/imagegen.exe` alongside the TensorRT plan files.
+ *   - Subprocess cost is negligible relative to inference time (≈10ms
+ *     spawn vs ≈400ms inference).
+ *
+ * Binary resolution:
+ *   1. `opts.binaryPath` (test injection).
+ *   2. `process.env.IMAGEGEN_TRT_BIN` (operator override).
+ *   3. `${MODELS_DIR}/bin/imagegen.exe`.
+ *
+ * Plan file resolution:
+ *   The packaged binary expects a `--plan <path>` flag pointing at the
+ *   prebuilt TensorRT engine for the active resolution. The catalog
+ *   binds tier → plan; the installer materializes them under
+ *   `${MODELS_DIR}/imagegen/trt-plans/<modelKey>/`.
+ *
+ * Until the bundle installer + packaged binary land for Windows NVIDIA,
+ * `loadTensorRtImageGenBackend` throws `ImageGenBackendUnavailableError`
+ * and the selector falls through to sd-cpp.
+ *
+ * Publishing pipeline (Windows x86_64 NVIDIA only):
+ *
+ *   Build (`imagegen.exe`):
+ *     git clone https://github.com/NVIDIA/TensorRT && cd TensorRT/demo/Diffusion
+ *     # Build against TensorRT 10.x + CUDA 12.x
+ *     pip install -r requirements.txt
+ *     python build.py --hf-token <ci-secret> \
+ *       --version 1.5 --denoising-steps 20 \
+ *       --build-static-batch --output-dir ../../../build/imagegen-sd15
+ *     # Thin wrapper produces imagegen.exe linking against
+ *     # nvinfer_10.dll + cudart64_12.dll; pyinstaller-onefile produces a
+ *     # 35-MB executable next to the static .plan files.
+ *   Build TensorRT plan (per resolution, per model):
+ *     trtexec --onnx=unet.onnx --saveEngine=unet.plan --fp16 \
+ *       --minShapes=sample:1x4x64x64 --optShapes=sample:1x4x64x64 \
+ *       --maxShapes=sample:1x4x64x64
+ *     # Drop plan files under imagegen/trt-plans/<modelKey>/{unet,vae,clip}.plan.
+ *   Sign:
+ *     signtool sign /tr http://timestamp.digicert.com /td sha256 \
+ *       /fd sha256 /sha1 <eliza-labs-cert-thumbprint> imagegen.exe
+ *     # SmartScreen reputation builds over the first ~1000 installs;
+ *     # submit to Microsoft Defender Bytes-for-Bots if a new cert.
+ *   Drop:
+ *     releases.elizaos.ai/imagegen-trt/<version>/windows-x86_64/imagegen.exe
+ *     releases.elizaos.ai/imagegen-trt/<version>/windows-x86_64/plans/
+ *       sd-1.5-512x512/{unet,vae,clip}.plan
+ *       sdxl-turbo-1024x1024/{unet,vae,clip}.plan
+ *   The bundle installer writes the binary to
+ *   `${MODELS_DIR}/bin/imagegen.exe` and the plans under
+ *   `${MODELS_DIR}/imagegen/trt-plans/<modelKey>/`.
+ *
+ * Notarization:
+ *   N/A on Windows; SmartScreen reputation replaces the macOS notarize
+ *   step. Authenticode-signed binaries with a valid EV cert clear without
+ *   warning on first launch.
+ */
+
+import { existsSync, promises as fs, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ImageGenBackendUnavailableError } from "./errors";
+import {
+	assertPngOutput,
+	defaultSpawn,
+	resolveSeed,
+	type SdCppSpawnLike,
+} from "./sd-cpp";
+import type {
+	ImageGenBackend,
+	ImageGenLoadArgs,
+	ImageGenResult,
+} from "./types";
+
+export interface TensorRtBackendOptions {
+	loadArgs: ImageGenLoadArgs;
+	modelKey: string;
+	binaryPath?: string;
+	outputDir?: string;
+	spawnImpl?: SdCppSpawnLike;
+	fakeImageBytes?: Uint8Array;
+	now?: () => number;
+}
+
+const DEFAULT_BIN = "imagegen.exe";
+
+export async function loadTensorRtImageGenBackend(
+	opts: TensorRtBackendOptions,
+): Promise<ImageGenBackend> {
+	const binary = resolveBinary(opts.binaryPath);
+	const now = opts.now ?? Date.now;
+
+	if (!opts.fakeImageBytes) {
+		// On non-Windows platforms there's nothing to even try; surface
+		// the unavailability cleanly so the selector moves on.
+		if (process.platform !== "win32" && !opts.binaryPath) {
+			throw new ImageGenBackendUnavailableError(
+				"tensorrt",
+				"unsupported_runtime",
+				`[imagegen/tensorrt] TensorRT backend is Windows-only; current platform: ${process.platform}`,
+			);
+		}
+		await assertBinaryAvailable(binary, opts.spawnImpl);
+		if (!existsSync(opts.loadArgs.modelPath)) {
+			throw new ImageGenBackendUnavailableError(
+				"tensorrt",
+				"model_missing",
+				`[imagegen/tensorrt] TensorRT plan not found: ${opts.loadArgs.modelPath}`,
+			);
+		}
+	}
+
+	const outputDir =
+		opts.outputDir ?? mkdtempSync(join(tmpdir(), "trt-imagegen-"));
+	let disposed = false;
+
+	return {
+		id: "tensorrt",
+		supports(req) {
+			// TensorRT plans are compiled for a fixed resolution. The plan
+			// file embeds the resolution; we accept any size and let the
+			// binary error out — except we reject obviously bad inputs.
+			const w = req.width ?? 1024;
+			const h = req.height ?? 1024;
+			if (w <= 0 || h <= 0) return false;
+			if (w > 4096 || h > 4096) return false;
+			return true;
+		},
+		async generate(req): Promise<ImageGenResult> {
+			if (disposed) {
+				throw new ImageGenBackendUnavailableError(
+					"tensorrt",
+					"binding_unavailable",
+					"[imagegen/tensorrt] generate called after dispose()",
+				);
+			}
+			if (!req.prompt.trim()) {
+				throw new ImageGenBackendUnavailableError(
+					"tensorrt",
+					"unsupported_request",
+					"[imagegen/tensorrt] prompt is empty",
+				);
+			}
+			const seed = resolveSeed(req.seed);
+			const width = req.width ?? 1024;
+			const height = req.height ?? 1024;
+			const steps = req.steps ?? 25;
+			const guidanceScale = req.guidanceScale ?? 4.0;
+			const outputPath = join(outputDir, `out-${seed}-${now()}.png`);
+			const startMs = now();
+
+			if (opts.fakeImageBytes) {
+				await fs.writeFile(outputPath, opts.fakeImageBytes);
+				const elapsed = Math.max(1, now() - startMs);
+				if (req.onProgressChunk)
+					req.onProgressChunk({ step: steps, total: steps });
+				return {
+					image: opts.fakeImageBytes,
+					mime: "image/png",
+					seed,
+					metadata: {
+						model: opts.modelKey,
+						prompt: req.prompt,
+						steps,
+						guidanceScale,
+						inferenceTimeMs: elapsed,
+					},
+				};
+			}
+
+			const args = [
+				"--plan",
+				opts.loadArgs.modelPath,
+				"--prompt",
+				req.prompt,
+				"--width",
+				String(width),
+				"--height",
+				String(height),
+				"--steps",
+				String(steps),
+				"--cfg",
+				String(guidanceScale),
+				"--seed",
+				String(seed),
+				"--output",
+				outputPath,
+			];
+			if (req.negativePrompt) {
+				args.push("--negative", req.negativePrompt);
+			}
+
+			await runTensorRt(binary, args, {
+				signal: req.signal,
+				spawnImpl: opts.spawnImpl,
+			});
+
+			const bytes = new Uint8Array(await fs.readFile(outputPath));
+			assertPngOutput(bytes, "tensorrt", "subprocess_failed");
+			const elapsed = Math.max(1, now() - startMs);
+			return {
+				image: bytes,
+				mime: "image/png",
+				seed,
+				metadata: {
+					model: opts.modelKey,
+					prompt: req.prompt,
+					steps,
+					guidanceScale,
+					inferenceTimeMs: elapsed,
+				},
+			};
+		},
+		async dispose() {
+			if (disposed) return;
+			disposed = true;
+			await fs.rm(outputDir, { recursive: true, force: true }).catch(() => {});
+		},
+	};
+}
+
+function resolveBinary(override?: string): string {
+	if (override) return override;
+	const envBin = process.env.IMAGEGEN_TRT_BIN;
+	if (envBin?.trim()) return envBin.trim();
+	return DEFAULT_BIN;
+}
+
+async function assertBinaryAvailable(
+	binary: string,
+	spawnImpl?: SdCppSpawnLike,
+): Promise<void> {
+	try {
+		const code = await new Promise<number | null>((resolve, reject) => {
+			const proc = defaultSpawn(spawnImpl)(binary, ["--version"]);
+			proc.on("error", (err: Error) => reject(err));
+			proc.on("exit", (c: number | null) => resolve(c));
+		});
+		if (code !== 0) {
+			throw new ImageGenBackendUnavailableError(
+				"tensorrt",
+				"binary_version_mismatch",
+				`[imagegen/tensorrt] '${binary} --version' exited with code ${code}`,
+			);
+		}
+	} catch (err) {
+		if (err instanceof ImageGenBackendUnavailableError) throw err;
+		const msg = err instanceof Error ? err.message : String(err);
+		throw new ImageGenBackendUnavailableError(
+			"tensorrt",
+			"binary_missing",
+			`[imagegen/tensorrt] cannot run '${binary} --version': ${msg}. Install the bundle's TensorRT imagegen package, or set IMAGEGEN_TRT_BIN to a built binary.`,
+			{ cause: err },
+		);
+	}
+}
+
+async function runTensorRt(
+	binary: string,
+	args: readonly string[],
+	opts: { signal?: AbortSignal; spawnImpl?: SdCppSpawnLike },
+): Promise<void> {
+	await new Promise<void>((resolve, reject) => {
+		const proc = defaultSpawn(opts.spawnImpl)(binary, args, {
+			signal: opts.signal,
+		});
+		proc.on("error", (err: Error) => reject(err));
+		proc.on("exit", (code: number | null) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(
+				new ImageGenBackendUnavailableError(
+					"tensorrt",
+					"subprocess_failed",
+					`[imagegen/tensorrt] imagegen.exe exited with code ${code}`,
+				),
+			);
+		});
+	});
+}

package/src/services/imagegen/types.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Local image-generation (diffusion) types — WS3 deliverable.
+ *
+ * Two layers live here, mirroring the WS2 vision-describe split:
+ *
+ *   1. The **request/result** contract every WS3 backend implements
+ *      (`ImageGenRequest`, `ImageGenResult`). Callers pass a text prompt
+ *      and optional knobs; backends return PNG (or JPEG) bytes + metadata.
+ *
+ *   2. The **backend** interface (`ImageGenBackend`) that the
+ *      `MemoryArbiter` (WS1) registers as a capability handler. One
+ *      backend per per-platform diffusion runtime:
+ *
+ *        - `sd-cpp` — stable-diffusion.cpp child-process binary
+ *          (Linux + Windows + Android JNI).
+ *        - `mflux`  — MLX `mflux` Python venv (macOS Apple Silicon).
+ *        - `coreml` — Capacitor bridge to Swift `apple/ml-stable-diffusion`
+ *          (iOS only).
+ *        - `tensorrt` — packaged `imagegen.exe` / `trtexec` wrapper
+ *          (Windows NVIDIA).
+ *        - `aosp`   — bun:ffi to `eliza_llama_imagegen_*` symbols in
+ *          libeliza-llama-shim (Android JNI; unavailable until shim ships).
+ *        - `fake`   — deterministic in-process backend used by tests.
+ *
+ * All backends implement the same `load → generate → dispose` shape so the
+ * arbiter can swap between them without caring how the diffusion runtime
+ * is wired.
+ *
+ * Cache contract:
+ *
+ *   Image-gen requests do NOT go through `hashVisionInput` (that's the
+ *   WS2 projector-token cache, which lives on image *inputs*). The
+ *   request-side keying space is prompt + seed + steps + scheduler + …;
+ *   if a cache lands here later it gets its own namespace (`hashImageGenRequest`)
+ *   to avoid collisions with the WS2 vision-embedding cache. For now the
+ *   capability has no result cache — diffusion is intrinsically expensive
+ *   and most callers want a fresh sample, not a cached one.
+ */
+/** Output container the backend writes. PNG is default; JPEG is opt-in. */
+export type ImageGenMimeType = "image/png" | "image/jpeg";
+/**
+ * Caller request to `generate`. All fields except `prompt` are optional —
+ * backends apply per-runtime defaults for missing knobs.
+ *
+ * Knob semantics (consistent across backends):
+ *
+ *   - `width` / `height`: pixel resolution. Default 512×512 (SD 1.5 family) /
+ *     1024×1024 (SDXL / FLUX / Z-Image). Backends round to the nearest
+ *     multiple of 8 (SD) or 16 (SDXL) when needed.
+ *   - `steps`: denoising step count. 4 for FLUX schnell / Z-Image-Turbo
+ *     (single-pass Turbo schedulers); 20 for SD 1.5 Euler-A; 25 for SDXL.
+ *   - `guidanceScale`: classifier-free guidance. Ignored by FLUX schnell
+ *     (CFG-free). 7.5 default for SD 1.5; 4.0 default for SDXL.
+ *   - `seed`: PRNG seed. -1 / omitted → random; the backend returns the
+ *     actual seed used in `ImageGenResult.seed` so the caller can replay.
+ *   - `scheduler`: sampler name (`"euler-a"`, `"dpm++-2m"`, `"ddim"`,
+ *     `"euler"`). Backends accept the strings their underlying runtime
+ *     supports; unknown values raise `ImageGenBackendUnavailableError`.
+ */
+export interface ImageGenRequest {
+    prompt: string;
+    negativePrompt?: string;
+    width?: number;
+    height?: number;
+    steps?: number;
+    guidanceScale?: number;
+    seed?: number;
+    scheduler?: string;
+    signal?: AbortSignal;
+    /**
+     * Optional per-step progress callback. Called once per denoising step
+     * with `{ step, total }`. Backends that can't surface step-level
+     * progress (Core ML batch fused path, TensorRT static engine) MAY
+     * call this once with `step === total` at completion instead of
+     * per-step. Never required.
+     */
+    onProgressChunk?: (progress: {
+        step: number;
+        total: number;
+    }) => void;
+}
+/**
+ * Backend response. `image` is the raw bytes (PNG by default); `mime`
+ * identifies the container. The metadata block carries enough state for
+ * the caller to attach to a chat turn, log to trajectories, or feed the
+ * result back into a vision-describe for the same agent.
+ */
+export interface ImageGenResult {
+    image: Uint8Array;
+    mime: ImageGenMimeType;
+    /**
+     * The actual seed the diffusion run used. Always populated — the
+     * backend MUST resolve a random seed before sampling and report it
+     * here. This is what makes a generation reproducible.
+     */
+    seed: number;
+    metadata: {
+        /** The model id (catalog key) the run used (`"imagegen-sd-1_5-q5_0"`, etc.). */
+        model: string;
+        /** Echo of the prompt that was sampled. */
+        prompt: string;
+        /** Echo of the step count actually used (post-default-resolve). */
+        steps: number;
+        /** Echo of CFG actually applied. 0 for CFG-free models (FLUX schnell). */
+        guidanceScale: number;
+        /** End-to-end wall-clock time inside the backend. */
+        inferenceTimeMs: number;
+    };
+}
+/**
+ * Per-load arguments for an image-gen backend. The arbiter's
+ * `load(modelKey)` only carries an opaque key; the binding resolves that
+ * key to real model+vae+clip+t5 paths through this struct, which
+ * `createImageGenCapabilityRegistration` populates from the catalog +
+ * `ELIZA_1_BUNDLE_EXTRAS.json`.
+ *
+ * Some diffusion families are single-file GGUFs once quantized, such as
+ * SD 1.5 Q5_0. Others stay split: stable-diffusion.cpp runs Z-Image
+ * with `--diffusion-model` plus separate Qwen LLM text encoder and VAE
+ * files. The optional paths below carry those companion assets.
+ */
+export interface ImageGenLoadArgs {
+    /** Absolute path to the primary diffusion weights (GGUF / mlpackage / engine). */
+    modelPath: string;
+    /**
+     * Treat `modelPath` as a stable-diffusion.cpp `--diffusion-model` rather
+     * than a monolithic `--model`. Required for Z-Image/Flux-style split
+     * diffusion bundles.
+     */
+    splitDiffusionModel?: boolean;
+    /** Optional split VAE path. */
+    vae?: string;
+    /** Optional split CLIP-L / CLIP-G path. */
+    clip?: string;
+    /** Optional split T5 / Gemma text encoder path. */
+    t5?: string;
+    /** Optional split LLM text encoder path, e.g. Qwen3 for Z-Image. */
+    llm?: string;
+    /**
+     * Backend-specific acceleration hint. Accepts:
+     *   - `"auto"` (default) — let the binding decide.
+     *   - `"cpu"` — force CPU.
+     *   - `"cuda"` / `"vulkan"` / `"metal"` / `"coreml"` / `"qnn"` /
+     *     `"tensorrt"` — request a specific accelerator. Unsupported
+     *     requests fall back to `auto`.
+     */
+    accelerator?: "auto" | "cpu" | "cuda" | "vulkan" | "metal" | "coreml" | "qnn" | "tensorrt";
+    /** Cancel a slow load (model file read + weight upload). */
+    signal?: AbortSignal;
+}
+/**
+ * The contract every WS3 backend implements. The shape is intentionally
+ * narrow: the arbiter only ever calls `generate`. `dispose` is wrapped
+ * by the arbiter's `unload` so the backend can free GPU/VRAM and drop
+ * file descriptors / kill subprocesses on eviction.
+ */
+export interface ImageGenBackend {
+    /** Stable identifier — matches the backend module name. */
+    readonly id: "sd-cpp" | "mflux" | "coreml" | "tensorrt" | "aosp" | "fake";
+    /**
+     * Best-effort capability check. Implementations return `false` for
+     * requests whose `width`/`height`/`scheduler` aren't supported by
+     * the loaded weights, so the arbiter can fall through to the next
+     * registered backend (selector order). Default backends accept
+     * anything reasonable; `supports` mostly matters for `coreml`
+     * (fixed resolution per `.mlpackage`) and `tensorrt` (fixed engine
+     * shape).
+     */
+    supports(request: ImageGenRequest): boolean;
+    generate(request: ImageGenRequest): Promise<ImageGenResult>;
+    /** Release the loaded weights / subprocess. Idempotent. */
+    dispose(): Promise<void>;
+}
+/**
+ * Capability handler loader. The arbiter calls it with a model key
+ * (e.g. `"imagegen-sd-1_5-q5_0"`); the implementation resolves to a
+ * real `ImageGenLoadArgs` from `ELIZA_1_BUNDLE_EXTRAS.json` + the
+ * installed bundle and returns a live backend.
+ */
+export type ImageGenBackendLoader = (modelKey: string) => Promise<ImageGenBackend>;
+//# sourceMappingURL=types.d.ts.map

package/src/services/imagegen/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,2EAA2E;AAC3E,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,YAAY,CAAC;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CACtE;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,gBAAgB,CAAC;IACvB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE;QACT,gFAAgF;QAChF,KAAK,EAAE,MAAM,CAAC;QACd,2CAA2C;QAC3C,MAAM,EAAE,MAAM,CAAC;QACf,mEAAmE;QACnE,KAAK,EAAE,MAAM,CAAC;QACd,0EAA0E;QAC1E,aAAa,EAAE,MAAM,CAAC;QACtB,qDAAqD;QACrD,eAAe,EAAE,MAAM,CAAC;KACxB,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAChC,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,+BAA+B;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;OAOG;IACH,WAAW,CAAC,EACT,MAAM,GACN,KAAK,GACL,MAAM,GACN,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,KAAK,GACL,UAAU,CAAC;IACd,4DAA4D;IAC5D,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;IAC1E;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,2DAA2D;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,CACnC,QAAQ,EAAE,MAAM,KACZ,OAAO,CAAC,eAAe,CAAC,CAAC"}