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

package/src/services/imagegen/sd-cpp.d.ts

@@ -0,0 +1,180 @@
+/**
+ * stable-diffusion.cpp image-gen backend (WS3) — Linux + Windows
+ * (CPU/CUDA/Vulkan), and Android NDK builds reuse the same binary via
+ * `plugin-aosp-local-inference`'s JNI bridge.
+ *
+ * Why a child-process backend (and not a Node binding):
+ *
+ *   - stable-diffusion.cpp ships a single CLI binary (`sd`) per build
+ *     flavour (CPU / CUDA / Vulkan / Metal). Linking it as a Node addon
+ *     would require maintaining a parallel build matrix to llama.cpp;
+ *     we instead reuse the same binary shipped by the bundle installer.
+ *   - The CLI is stable across versions for monolithic SD checkpoints
+ *     (`--model …` / `--prompt …` / `-o …`) and split diffusion assets
+ *     (`--diffusion-model …` plus companion encoders / VAE), so contract
+ *     drift is unlikely.
+ *   - Diffusion runs in seconds, not milliseconds; the subprocess
+ *     spawn cost is negligible relative to inference time.
+ *
+ * Binary resolution order:
+ *
+ *   1. `opts.binaryPath` (test injection, explicit override).
+ *   2. `process.env.SD_CPP_BIN` (operator override).
+ *   3. `${MODELS_DIR}/bin/sd` (default install path; the bundle drops
+ *      the binary here on first activation of an image-gen tier).
+ *
+ * Availability is checked at load time by spawning the binary with
+ * `--version`. CUDA loads also require explicit capability evidence from
+ * an adjacent manifest, `--help`, or `--version`; a Linux NVIDIA GPU alone
+ * is not evidence that the installed binary was compiled with CUDA.
+ *
+ * Accelerator flags (from `ImageGenLoadArgs.accelerator`):
+ *
+ *   - `"cuda"`  → no extra flag; relies on the CUDA-built binary.
+ *   - `"vulkan"` → `--backend vulkan0` (works on AMD + Intel + NV Vulkan paths).
+ *   - `"cpu"`   → `--backend cpu --params-backend cpu` (forces CPU).
+ *   - `"auto"`  → no extra flag; the binary's own auto-detection runs.
+ *
+ * GPU validation status (this host has no GPU):
+ *   The contract here is binary surface only. CUDA / Vulkan smoke tests
+ *   run on real hardware as part of the WS5 e2e gate; documented at the
+ *   bottom of `__tests__/imagegen-handler.test.ts`.
+ *
+ * Publishing pipeline (per platform):
+ *
+ *   Linux x86_64 (CUDA):
+ *     git clone https://github.com/leejet/stable-diffusion.cpp && cd stable-diffusion.cpp \
+ *       && cmake -B build -DSD_CUDA=ON -DCMAKE_BUILD_TYPE=Release \
+ *       && cmake --build build --config Release -j
+ *     Strip + tar; sign: not required (Linux). Drop into
+ *     releases.elizaos.ai/sd-cpp/<version>/linux-x86_64-cuda/sd.tar.zst.
+ *   Linux x86_64 (Vulkan):
+ *     cmake -B build -DSD_VULKAN=ON -DCMAKE_BUILD_TYPE=Release && cmake --build build -j
+ *   Linux x86_64 (CPU):
+ *     cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j
+ *   Windows x86_64 (CUDA):
+ *     Same cmake invocation under MSVC 2022; produces sd.exe. Sign with the
+ *     Eliza Labs EV cert (signtool sign /tr ...); submit to Microsoft
+ *     SmartScreen if a new cert. Drop into releases.elizaos.ai/sd-cpp/
+ *     <version>/windows-x86_64-cuda/sd.exe.
+ *   Windows x86_64 (Vulkan, CPU): mirror the CUDA build with the matching
+ *     cmake -DSD_VULKAN=ON / -DCMAKE_BUILD_TYPE=Release flags.
+ *   Android (arm64-v8a JNI): cross-compile through the NDK against the
+ *     same upstream; not consumed directly here — `plugin-aosp-local-inference`
+ *     wraps it as `libstable-diffusion-jni.so` and the AOSP backend (see
+ *     `aosp-unavailable.ts`) calls into it via the eliza-llama-shim FFI surface.
+ *   macOS (Metal): cmake -B build -DSD_METAL=ON; codesign with the Eliza
+ *     Labs Developer ID Application cert and notarize via `xcrun notarytool
+ *     submit ...`; staple. Drop into releases.elizaos.ai/sd-cpp/<version>/
+ *     darwin-{arm64,x86_64}/sd. macOS Apple Silicon prefers `mflux` over
+ *     sd-cpp (see `mflux.ts`), but sd-cpp Metal is the fallback.
+ *   Linux riscv64 (CPU): unavailable as a shipped binary. Cross-compile via
+ *     `zig cc --target=riscv64-linux-musl` (same toolchain
+ *     packages/app-core/scripts/aosp/compile-libllama.mjs uses; see also
+ *     `native/build-omnivoice.mjs` for the omnivoice / ggml precedent).
+ *     There is no Node/host build script for sd-cpp in this repo — sd-cpp
+ *     is a child-process backend wrapping a precompiled `sd` binary
+ *     fetched from releases.elizaos.ai. Wiring riscv64 is a CDN-side
+ *     artifact addition (drop a `releases.elizaos.ai/sd-cpp/<version>/
+ *     linux-riscv64-cpu/sd` build); no build-matrix entry needs to land
+ *     here. Until then, the riscv64 binary-resolution attempt simply
+ *     surfaces the same `ImageGenBackendUnavailableError("sd-cpp", ...)`
+ *     it surfaces today on any host where the bundle installer did not
+ *     stage `sd` — i.e. image-gen is silently disabled on riscv64
+ *     (acceptable: the eliza-1 phone tier does not require image-gen).
+ */
+import { ImageGenBackendUnavailableError } from "./errors";
+import type { ImageGenBackend, ImageGenLoadArgs } from "./types";
+/**
+ * Optional test seam. Production code uses Node's `child_process.spawn`;
+ * tests inject a fake to drive deterministic outputs without forking.
+ */
+export type SdCppSpawnLike = (command: string, args: readonly string[], options?: {
+    signal?: AbortSignal;
+    cwd?: string;
+}) => {
+    stdout: AsyncIterable<Buffer> | NodeJS.ReadableStream | null;
+    stderr: AsyncIterable<Buffer> | NodeJS.ReadableStream | null;
+    on(event: "exit", listener: (code: number | null) => void): unknown;
+    on(event: "error", listener: (err: Error) => void): unknown;
+    kill?(signal?: NodeJS.Signals): void;
+};
+export interface SdCppBackendOptions {
+    loadArgs: ImageGenLoadArgs;
+    /** Catalog key — copied into `ImageGenResult.metadata.model`. */
+    modelKey: string;
+    /** Override the binary path. Useful for tests. */
+    binaryPath?: string;
+    /**
+     * Override the on-disk output directory. Defaults to a fresh dir
+     * under `os.tmpdir()`. Tests can pin this so the deterministic
+     * fixture is read from a known path.
+     */
+    outputDir?: string;
+    /** Spawn implementation. Defaults to Node's `child_process.spawn`. */
+    spawnImpl?: SdCppSpawnLike;
+    /**
+     * For tests: instead of running the binary, write `fakeImageBytes`
+     * to the output file and return it. When set, `binaryPath` and
+     * version-probing are skipped.
+     */
+    fakeImageBytes?: Uint8Array;
+    /**
+     * For tests: override `Date.now` so timing assertions are stable.
+     */
+    now?: () => number;
+}
+/**
+ * Load (or in this case, "smoke-check") the sd-cpp backend. The binary
+ * lives out-of-process; "loading" is verifying it exists and runs.
+ * The actual model weights are passed per-call as either `--model <path>`
+ * or `--diffusion-model <path>`, so the same binary serves multiple
+ * GGUFs without an explicit unload step.
+ */
+export declare function loadSdCppImageGenBackend(opts: SdCppBackendOptions): Promise<ImageGenBackend>;
+interface SdCppCommandResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}
+type SdCppAccelerator = NonNullable<ImageGenLoadArgs["accelerator"]>;
+export interface SdCppCapabilities {
+    version: string | null;
+    accelerators: readonly SdCppAccelerator[];
+    evidence: readonly string[];
+}
+export declare function probeSdCppCapabilitiesFromBinary(binary: string, versionResult?: SdCppCommandResult, spawnImpl?: SdCppSpawnLike): Promise<SdCppCapabilities>;
+export declare function buildArgs(input: {
+    modelPath: string;
+    splitDiffusionModel?: boolean;
+    vae?: string;
+    llm?: string;
+    prompt: string;
+    negativePrompt?: string;
+    width: number;
+    height: number;
+    steps: number;
+    guidanceScale: number;
+    seed: number;
+    scheduler?: string;
+    output: string;
+    accelerator?: ImageGenLoadArgs["accelerator"];
+}): string[];
+/** 31-bit positive integer — sd-cpp stores seed as int32. */
+export declare function pickSeed(): number;
+/** Resolve a caller-supplied seed or pick a random one. */
+export declare function resolveSeed(seed: number | undefined): number;
+export declare const PNG_SIGNATURE: readonly [137, 80, 78, 71, 13, 10, 26, 10];
+/**
+ * Assert `bytes` begins with the PNG magic number. `label` is the
+ * `[imagegen/<backend>]` prefix used in the error message.
+ */
+export declare function assertPngOutput(bytes: Uint8Array, label: string, errorCode: ConstructorParameters<typeof ImageGenBackendUnavailableError>[1]): void;
+/**
+ * Wrap Node's `spawn` in the narrower `SdCppSpawnLike` shape that the
+ * subprocess backends share. The cast is centralised here so call sites
+ * don't each need their own `as unknown as` escape.
+ */
+export declare function defaultSpawn(spawnImpl: SdCppSpawnLike | undefined): SdCppSpawnLike;
+export {};
+//# sourceMappingURL=sd-cpp.d.ts.map

package/src/services/imagegen/sd-cpp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sd-cpp.d.ts","sourceRoot":"","sources":["sd-cpp.ts"],"names":[],"mappings":"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"}