@qvac/sdk 0.11.0 → 0.12.0

package/README.md

@@ -16,6 +16,8 @@ See [https://docs.qvac.tether.io/sdk/getting-started](https://docs.qvac.tether.i
 
 For AI/LLM tools, use [https://docs.qvac.tether.io/llms-full.txt](https://docs.qvac.tether.io/llms-full.txt) as the consolidated plaintext documentation export.
 
+> **Assembling a custom worker on Bare?** See [`@qvac/bare-sdk`](../bare-sdk/README.md) — the same SDK surface with no built-in plugin addons, designed for consumers wiring their own worker entry (Pear apps, bare-expo apps, direct Bare scripts).
+
 ## Supported environments and installation
 
 See https://docs.qvac.tether.io/sdk/getting-started/installation

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

@@ -0,0 +1,23 @@
+import { type ClassifyClientParams, type ClassificationResult } from "../../schemas/index";
+/**
+ * Classifies an image using a loaded classification model.
+ *
+ * The bundled MobileNetV3-Small model produces 3 labels: `"food"`, `"report"`, `"other"`.
+ * Custom models may emit different labels sourced from the GGUF metadata.
+ *
+ * @param params.modelId - The identifier of the loaded classification model
+ * @param params.image - JPEG or PNG buffer; raw RGB bytes also accepted with `width`, `height`, `channels`
+ * @param params.topK - Limit results to top-K classes (default: all)
+ * @returns Sorted classification results, highest confidence first
+ *
+ * @example
+ * ```typescript
+ * const modelId = await loadModel({ modelType: "ggml-classification" });
+ * const jpeg = fs.readFileSync("photo.jpg");
+ * const results = await classify({ modelId, image: jpeg });
+ * // [ { label: "food", confidence: 0.93 }, { label: "other", confidence: 0.05 }, ... ]
+ * await unloadModel({ modelId });
+ * ```
+ */
+export declare function classify(params: ClassifyClientParams): Promise<ClassificationResult[]>;
+//# sourceMappingURL=classify.d.ts.map

package/dist/client/api/classify.js

@@ -0,0 +1,43 @@
+import { classifyResponseSchema, } from "../../schemas/index.js";
+import { stream as streamRpc } from "../rpc/rpc-client.js";
+import { encodeBase64 } from "../../utils/encoding.js";
+/**
+ * Classifies an image using a loaded classification model.
+ *
+ * The bundled MobileNetV3-Small model produces 3 labels: `"food"`, `"report"`, `"other"`.
+ * Custom models may emit different labels sourced from the GGUF metadata.
+ *
+ * @param params.modelId - The identifier of the loaded classification model
+ * @param params.image - JPEG or PNG buffer; raw RGB bytes also accepted with `width`, `height`, `channels`
+ * @param params.topK - Limit results to top-K classes (default: all)
+ * @returns Sorted classification results, highest confidence first
+ *
+ * @example
+ * ```typescript
+ * const modelId = await loadModel({ modelType: "ggml-classification" });
+ * const jpeg = fs.readFileSync("photo.jpg");
+ * const results = await classify({ modelId, image: jpeg });
+ * // [ { label: "food", confidence: 0.93 }, { label: "other", confidence: 0.05 }, ... ]
+ * await unloadModel({ modelId });
+ * ```
+ */
+export async function classify(params) {
+    const request = {
+        type: "classify",
+        modelId: params.modelId,
+        image: encodeBase64(params.image),
+        ...(params.topK !== undefined && { topK: params.topK }),
+        ...(params.width !== undefined && { width: params.width }),
+        ...(params.height !== undefined && { height: params.height }),
+        ...(params.channels !== undefined && { channels: params.channels }),
+    };
+    for await (const response of streamRpc(request)) {
+        if (response && typeof response === "object" && "type" in response && response.type === "classify") {
+            const parsed = classifyResponseSchema.parse(response);
+            if (parsed.done) {
+                return parsed.results;
+            }
+        }
+    }
+    return [];
+}

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

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

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

@@ -19,9 +19,13 @@ export { getLoadedModelInfo } from "./get-loaded-model-info";
 export { ocr } from "./ocr";
 export { invokePlugin, invokePluginStream } from "./invoke-plugin";
 export { diffusion, type DiffusionProgressTick } from "./diffusion";
+export { classify } from "./classify";
+export { video, type VideoProgressTick } from "./video";
 export { upscale } from "./upscale";
 export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel, type ModelRegistrySearchParams, } from "./registry";
 export { suspend } from "./suspend";
 export { resume } from "./resume";
 export { state } from "./state";
+export { vla, vlaHparams } from "./vla";
+export { vlaPreprocessImage, vlaPadState, VLA_DEFAULT_IMAGE_SIZE, } from "./vla-helpers";
 //# sourceMappingURL=index.d.ts.map

package/dist/client/api/index.js

@@ -19,8 +19,12 @@ export { getLoadedModelInfo } from "./get-loaded-model-info.js";
 export { ocr } from "./ocr.js";
 export { invokePlugin, invokePluginStream } from "./invoke-plugin.js";
 export { diffusion } from "./diffusion.js";
+export { classify } from "./classify.js";
+export { video } from "./video.js";
 export { upscale } from "./upscale.js";
 export { modelRegistryList, modelRegistrySearch, modelRegistryGetModel, } from "./registry.js";
 export { suspend } from "./suspend.js";
 export { resume } from "./resume.js";
 export { state } from "./state.js";
+export { vla, vlaHparams } from "./vla.js";
+export { vlaPreprocessImage, vlaPadState, VLA_DEFAULT_IMAGE_SIZE, } from "./vla-helpers.js";

package/dist/client/api/load-model.js

@@ -1,12 +1,17 @@
 import { send, stream } from "../rpc/rpc-client.js";
 import { startLoggingStreamForModel } from "../logging-stream-registry.js";
-import { loadModelOptionsToRequestSchema, reloadConfigOptionsToRequestSchema, isModelTypeAlias, normalizeModelType, inferModelTypeFromModelSrc, } from "../../schemas/index.js";
+import { loadModelOptionsToRequestSchema, reloadConfigOptionsToRequestSchema, isModelTypeAlias, normalizeModelType, inferModelTypeFromModelSrc, ModelType, } from "../../schemas/index.js";
 import { ModelLoadFailedError, ModelTypeRequiredError, StreamEndedError, InvalidResponseError, } from "../../utils/errors-client.js";
 import { assertModelSrcMatchesModelType } from "../../utils/load-model-validation.js";
 import { getClientLogger } from "../../logging/index.js";
 import { decoratePromise } from "../../utils/decorate-promise.js";
 import { generateClientRequestId } from "./client-request-id.js";
 const logger = getClientLogger();
+function isReactNativeRuntime() {
+    const runtime = globalThis;
+    return runtime.navigator?.product === "ReactNative";
+}
+let warnedLocalVideoModelLoad = false;
 export function loadModel(options, rpcOptions) {
     // Generate a stable `requestId` once, synchronously, before kicking
     // off any async work. The same id is:
@@ -45,6 +50,24 @@ async function runLoadModel(options, requestId, rpcOptions) {
             const canonical = normalizeModelType(modelType);
             logger.warn(`Model type "${modelType}" is an alias and will be deprecated. Use "${canonical}" instead.`);
         }
+        const canonicalModelType = typeof modelType === "string" ? normalizeModelType(modelType) : modelType;
+        const modelConfig = resolvedOptions["modelConfig"];
+        if (isReactNativeRuntime() &&
+            canonicalModelType === ModelType.sdcppGeneration &&
+            modelConfig?.mode === "video" &&
+            resolvedOptions["delegate"] === undefined &&
+            !warnedLocalVideoModelLoad) {
+            warnedLocalVideoModelLoad = true;
+            const message = "QVAC video generation works on React Native, but loading the video " +
+                "model on-device will usually fail or take several minutes — the video " +
+                "diffusion models currently shipped by the SDK are too large to load " +
+                "on typical mobile devices. Pass a `delegate` to `loadModel(...)` to " +
+                "run generation on a desktop peer instead.";
+            logger.warn(message);
+            // Surface via console too - if an RN host app doesn't wire getClientLogger()
+            // to a visible transport, logger.warn alone won't reach the dev.
+            console.warn(message);
+        }
     }
     // Splice the client-generated `requestId` onto the resolved options so
     // the wire envelope carries it. The server uses the same value as the

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

@@ -66,6 +66,9 @@ export declare function transcribeStream(params: TranscribeClientParams, options
 export declare function transcribeStream(params: TranscribeStreamClientParams & {
     emitVadEvents: true;
 }, options?: RPCOptions): Promise<TranscribeStreamConversationSession>;
+export declare function transcribeStream(params: TranscribeStreamClientParams & {
+    parakeetStreamingConfig: NonNullable<TranscribeStreamClientParams["parakeetStreamingConfig"]>;
+}, options?: RPCOptions): Promise<TranscribeStreamConversationSession>;
 export declare function transcribeStream(params: TranscribeStreamClientParams & {
     metadata: true;
 }, options?: RPCOptions): Promise<TranscribeStreamMetadataSession>;

package/dist/client/api/transcribe.js

@@ -67,7 +67,8 @@ export function transcribeStream(params, options) {
         return transcribeStreamWithAudio(params, options);
     }
     const streamParams = params;
-    if (streamParams.emitVadEvents === true) {
+    if (streamParams.emitVadEvents === true ||
+        streamParams.parakeetStreamingConfig !== undefined) {
         return transcribeStreamDuplexConversation(streamParams, options);
     }
     if (streamParams.metadata === true) {
@@ -111,6 +112,9 @@ function buildTranscribeStreamRequest(params) {
         ...(params.vadRunIntervalMs !== undefined && {
             vadRunIntervalMs: params.vadRunIntervalMs,
         }),
+        ...(params.parakeetStreamingConfig && {
+            parakeetStreamingConfig: params.parakeetStreamingConfig,
+        }),
     };
 }
 /**
@@ -227,9 +231,16 @@ function processLineConversation(line, wantsMetadata) {
             };
         }
         if (response.endOfTurn) {
+            if (response.endOfTurn.source === "whisper") {
+                return {
+                    type: "endOfTurn",
+                    source: "whisper",
+                    silenceDurationMs: response.endOfTurn.silenceDurationMs,
+                };
+            }
             return {
                 type: "endOfTurn",
-                silenceDurationMs: response.endOfTurn.silenceDurationMs,
+                source: "parakeet",
             };
         }
         if (wantsMetadata) {

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

@@ -0,0 +1,64 @@
+import { type VideoClientParams, type VideoStats } from "../../schemas/index";
+export interface VideoProgressTick {
+    step: number;
+    totalSteps: number;
+    elapsedMs: number;
+}
+export interface VideoResult {
+    requestId: string;
+    progressStream: AsyncGenerator<VideoProgressTick>;
+    outputs: Promise<Uint8Array[]>;
+    stats: Promise<VideoStats | undefined>;
+}
+/**
+ * Generates a video using a loaded video diffusion model.
+ *
+ * @param params - Video request parameters (model, prompt, dimensions, frame count, fps, sampler, seed, etc.).
+ * @returns A result object exposing `requestId` (stable identifier for this in-flight generation), `progressStream` (async iterator of `{ step, totalSteps, elapsedMs }`), `outputs` (promise of the generated video buffers, typically a single AVI file), and `stats` (promise of generation statistics).
+ *
+ * Only `txt2vid` mode is supported today. On React Native, prefer a `modelId` loaded with a `delegate` since the bundled video diffusion models are too large for typical mobile devices.
+ *
+ * @example
+ * ```typescript
+ * // Basic txt2vid generation
+ * const { outputs, stats } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "a cat surfing a wave at sunset",
+ *   width: 480,
+ *   height: 832,
+ *   video_frames: 17, // must satisfy (4*k + 1)
+ *   fps: 16,
+ * });
+ * const buffers = await outputs;
+ * fs.writeFileSync("output.avi", buffers[0]);
+ *
+ * // With progress tracking
+ * const { progressStream, outputs } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "a sunset over the ocean",
+ * });
+ * for await (const { step, totalSteps } of progressStream) {
+ *   console.log(`${step}/${totalSteps}`);
+ * }
+ * const buffers = await outputs;
+ *
+ * // With control frames (e.g. for guided generation)
+ * const frameA = fs.readFileSync("frame-a.png");
+ * const frameB = fs.readFileSync("frame-b.png");
+ * const { outputs } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "smooth transition between scenes",
+ *   control_frames: [frameA, frameB],
+ * });
+ *
+ * // Cancellation via requestId
+ * const { requestId, outputs } = video({ modelId, mode: "txt2vid", prompt: "..." });
+ * // ...later
+ * await cancel(requestId);
+ * ```
+ */
+export declare function video(params: VideoClientParams): VideoResult;
+//# sourceMappingURL=video.d.ts.map

package/dist/client/api/video.js

@@ -0,0 +1,147 @@
+import { videoStreamResponseSchema, } from "../../schemas/index.js";
+import { stream as streamRpc } from "../rpc/rpc-client.js";
+import { generateClientRequestId } from "./client-request-id.js";
+import { decodeBase64, encodeBase64 } from "../../utils/encoding.js";
+/**
+ * Generates a video using a loaded video diffusion model.
+ *
+ * @param params - Video request parameters (model, prompt, dimensions, frame count, fps, sampler, seed, etc.).
+ * @returns A result object exposing `requestId` (stable identifier for this in-flight generation), `progressStream` (async iterator of `{ step, totalSteps, elapsedMs }`), `outputs` (promise of the generated video buffers, typically a single AVI file), and `stats` (promise of generation statistics).
+ *
+ * Only `txt2vid` mode is supported today. On React Native, prefer a `modelId` loaded with a `delegate` since the bundled video diffusion models are too large for typical mobile devices.
+ *
+ * @example
+ * ```typescript
+ * // Basic txt2vid generation
+ * const { outputs, stats } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "a cat surfing a wave at sunset",
+ *   width: 480,
+ *   height: 832,
+ *   video_frames: 17, // must satisfy (4*k + 1)
+ *   fps: 16,
+ * });
+ * const buffers = await outputs;
+ * fs.writeFileSync("output.avi", buffers[0]);
+ *
+ * // With progress tracking
+ * const { progressStream, outputs } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "a sunset over the ocean",
+ * });
+ * for await (const { step, totalSteps } of progressStream) {
+ *   console.log(`${step}/${totalSteps}`);
+ * }
+ * const buffers = await outputs;
+ *
+ * // With control frames (e.g. for guided generation)
+ * const frameA = fs.readFileSync("frame-a.png");
+ * const frameB = fs.readFileSync("frame-b.png");
+ * const { outputs } = video({
+ *   modelId,
+ *   mode: "txt2vid",
+ *   prompt: "smooth transition between scenes",
+ *   control_frames: [frameA, frameB],
+ * });
+ *
+ * // Cancellation via requestId
+ * const { requestId, outputs } = video({ modelId, mode: "txt2vid", prompt: "..." });
+ * // ...later
+ * await cancel(requestId);
+ * ```
+ */
+export function video(params) {
+    const { control_frames, ...rest } = params;
+    const requestId = generateClientRequestId();
+    const request = {
+        ...rest,
+        ...(control_frames !== undefined && {
+            control_frames: control_frames.map(encodeBase64),
+        }),
+        type: "videoStream",
+        requestId,
+    };
+    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(() => { });
+    async function processResponses() {
+        try {
+            for await (const response of streamRpc(request)) {
+                if (response &&
+                    typeof response === "object" &&
+                    "type" in response &&
+                    response.type === "videoStream") {
+                    const parsed = videoStreamResponseSchema.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 {
+        requestId,
+        progressStream,
+        outputs: outputsPromise,
+        stats: statsPromise,
+    };
+}

package/dist/client/api/vla-helpers.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure-JS helpers for preparing VLA inference inputs on the client side.
+ *
+ * Mirrors `preprocessImage` / `padState` / `DEFAULT_IMAGE_SIZE` from
+ * `@qvac/vla-ggml/addon.js`. Kept inlined (not re-exported from the addon)
+ * so the SDK's client surface never loads the addon's native binding —
+ * consumers running under Node / Bun / Expo without VLA prebuilds can still
+ * use the SDK to drive a remote VLA worker.
+ *
+ * This file is a verbatim port of the addon's JS implementation; keep them
+ * in sync so the wire-format tensors stay byte-identical regardless of
+ * where preprocessing runs (consumer process vs worker vs addon).
+ */
+/** Default vision tower image size used by SmolVLA-LIBERO. */
+export declare const VLA_DEFAULT_IMAGE_SIZE = 512;
+type PixelsInput = Float32Array | Uint8Array | number[];
+type ImageLayout = "hwc" | "chw";
+export interface VlaPreprocessImageOptions {
+    size?: number;
+    layout?: ImageLayout;
+    /**
+     * Skip the [0,255] vs [0,1] auto-detection heuristic when the caller knows
+     * the range. `1` = pixels already in [0,1] (no rescale). `1/255` = pixels
+     * in [0,255] (rescale to [0,1]). Any other value (including the literal
+     * `'auto'`) falls back to the heuristic.
+     */
+    scale?: number | "auto";
+}
+/**
+ * Resize + letterbox + normalize a camera frame to `(3, size, size)` Float32
+ * in `[-1, 1]`. Drop-in equivalent of `@qvac/vla-ggml`'s `preprocessImage`.
+ *
+ * Letterbox places the resized content at the **bottom-right** with padding
+ * at top/left (`padLeft = size - newW`, `padTop = size - newH`), matching
+ * the reference smolvla.cpp behavior.
+ */
+export declare function vlaPreprocessImage(pixels: PixelsInput, width: number, height: number, opts?: VlaPreprocessImageOptions): Float32Array;
+/**
+ * Zero-pad a state vector to `targetDim`. Extra entries are zero-initialised;
+ * input longer than `targetDim` raises. Mirrors how smolvla.cpp expects the
+ * state tensor (`max_state_dim` = 32 by default).
+ */
+export declare function vlaPadState(state: ArrayLike<number>, targetDim?: number): Float32Array;
+export {};
+//# sourceMappingURL=vla-helpers.d.ts.map

package/dist/client/api/vla-helpers.js

@@ -0,0 +1,130 @@
+/**
+ * Pure-JS helpers for preparing VLA inference inputs on the client side.
+ *
+ * Mirrors `preprocessImage` / `padState` / `DEFAULT_IMAGE_SIZE` from
+ * `@qvac/vla-ggml/addon.js`. Kept inlined (not re-exported from the addon)
+ * so the SDK's client surface never loads the addon's native binding —
+ * consumers running under Node / Bun / Expo without VLA prebuilds can still
+ * use the SDK to drive a remote VLA worker.
+ *
+ * This file is a verbatim port of the addon's JS implementation; keep them
+ * in sync so the wire-format tensors stay byte-identical regardless of
+ * where preprocessing runs (consumer process vs worker vs addon).
+ */
+/** Default vision tower image size used by SmolVLA-LIBERO. */
+export const VLA_DEFAULT_IMAGE_SIZE = 512;
+function detectScale(pixels) {
+    if (pixels instanceof Uint8Array)
+        return 1 / 255;
+    // Float/Number arrays: scan a small window to decide whether it's [0,255] or [0,1].
+    const limit = Math.min(pixels.length, 256);
+    let maxVal = 0;
+    for (let i = 0; i < limit; i++) {
+        const v = pixels[i];
+        if (v > maxVal)
+            maxVal = v;
+    }
+    return maxVal > 1.001 ? 1 / 255 : 1;
+}
+/**
+ * Resize + letterbox + normalize a camera frame to `(3, size, size)` Float32
+ * in `[-1, 1]`. Drop-in equivalent of `@qvac/vla-ggml`'s `preprocessImage`.
+ *
+ * Letterbox places the resized content at the **bottom-right** with padding
+ * at top/left (`padLeft = size - newW`, `padTop = size - newH`), matching
+ * the reference smolvla.cpp behavior.
+ */
+export function vlaPreprocessImage(pixels, width, height, opts = {}) {
+    const size = opts.size ?? VLA_DEFAULT_IMAGE_SIZE;
+    const layout = opts.layout ?? "hwc";
+    if (!Number.isInteger(width) ||
+        !Number.isInteger(height) ||
+        width <= 0 ||
+        height <= 0) {
+        throw new TypeError("vlaPreprocessImage: width/height must be positive integers");
+    }
+    const expected = width * height * 3;
+    if (pixels.length !== expected) {
+        throw new RangeError(`vlaPreprocessImage: expected ${expected} pixel values, got ${pixels.length}`);
+    }
+    const normalize = opts.scale === 1 || opts.scale === 1 / 255
+        ? opts.scale
+        : detectScale(pixels);
+    // Letterbox target size (aspect-ratio preserving).
+    const ratio = Math.max(width / size, height / size);
+    const newW = Math.max(1, Math.floor(width / ratio));
+    const newH = Math.max(1, Math.floor(height / ratio));
+    const padLeft = size - newW;
+    const padTop = size - newH;
+    const xScale = width / newW;
+    const yScale = height / newH;
+    // Output starts at -1 so the pad region is already in [-1, 1] and we only
+    // need to overwrite the (newH × newW) inner region with the resized content.
+    const out = new Float32Array(3 * size * size);
+    out.fill(-1);
+    const planeStride = size * size;
+    const widthHeight = width * height;
+    for (let yy = 0; yy < newH; yy++) {
+        const yIn = (yy + 0.5) * yScale - 0.5;
+        const y0 = Math.max(0, Math.floor(yIn));
+        const y1 = Math.min(height - 1, y0 + 1);
+        const dy = Math.min(1, Math.max(0, yIn - y0));
+        const dyInv = 1 - dy;
+        const outY = yy + padTop;
+        for (let xx = 0; xx < newW; xx++) {
+            const xIn = (xx + 0.5) * xScale - 0.5;
+            const x0 = Math.max(0, Math.floor(xIn));
+            const x1 = Math.min(width - 1, x0 + 1);
+            const dx = Math.min(1, Math.max(0, xIn - x0));
+            const dxInv = 1 - dx;
+            const outX = xx + padLeft;
+            const w00 = dxInv * dyInv;
+            const w10 = dx * dyInv;
+            const w01 = dxInv * dy;
+            const w11 = dx * dy;
+            const outIdx = outY * size + outX;
+            if (layout === "hwc") {
+                const i00 = (y0 * width + x0) * 3;
+                const i10 = (y0 * width + x1) * 3;
+                const i01 = (y1 * width + x0) * 3;
+                const i11 = (y1 * width + x1) * 3;
+                for (let c = 0; c < 3; c++) {
+                    const v = pixels[i00 + c] * w00 +
+                        pixels[i10 + c] * w10 +
+                        pixels[i01 + c] * w01 +
+                        pixels[i11 + c] * w11;
+                    // Apply scale and shift into [-1, 1] in one fused multiply-add.
+                    out[c * planeStride + outIdx] = v * normalize * 2 - 1;
+                }
+            }
+            else {
+                for (let c = 0; c < 3; c++) {
+                    const plane = c * widthHeight;
+                    const v = pixels[plane + y0 * width + x0] * w00 +
+                        pixels[plane + y0 * width + x1] * w10 +
+                        pixels[plane + y1 * width + x0] * w01 +
+                        pixels[plane + y1 * width + x1] * w11;
+                    out[c * planeStride + outIdx] = v * normalize * 2 - 1;
+                }
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Zero-pad a state vector to `targetDim`. Extra entries are zero-initialised;
+ * input longer than `targetDim` raises. Mirrors how smolvla.cpp expects the
+ * state tensor (`max_state_dim` = 32 by default).
+ */
+export function vlaPadState(state, targetDim = 32) {
+    if (!Number.isInteger(targetDim) || targetDim <= 0) {
+        throw new TypeError("vlaPadState: targetDim must be a positive integer");
+    }
+    if (state.length > targetDim) {
+        throw new RangeError(`vlaPadState: input length ${state.length} exceeds targetDim ${targetDim}`);
+    }
+    const out = new Float32Array(targetDim);
+    for (let i = 0; i < state.length; i++)
+        out[i] = state[i];
+    return out;
+}

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

@@ -0,0 +1,65 @@
+import { type VlaClientRunParams, type VlaClientRunResult, type VlaHparams } from "../../schemas/index";
+/**
+ * Run SmolVLA inference on a loaded VLA model and return the produced action
+ * chunk plus per-stage timings.
+ *
+ * @param params - Inference inputs.
+ * @param params.modelId - Identifier of the loaded VLA model (returned by
+ *   `loadModel({ modelType: "vla", ... })`).
+ * @param params.images - One or more preprocessed camera frames; each is a
+ *   `Float32Array` of length `3 * imgWidth * imgHeight` in CHW layout, range
+ *   `[-1, 1]`. Use the addon's `preprocessImage()` (re-exported as
+ *   `vlaPreprocessImage`) to produce them.
+ * @param params.imgWidth - Width of each preprocessed image; must equal
+ *   `hparams.visionImageSize`.
+ * @param params.imgHeight - Height of each preprocessed image; must equal
+ *   `hparams.visionImageSize`.
+ * @param params.state - Robot end-effector / gripper state padded to
+ *   `hparams.maxStateDim` (use `vlaPadState`).
+ * @param params.tokens - Tokenized instruction (`Int32Array` of length
+ *   `hparams.tokenizerMaxLength`). Tokenize on the consumer side with the
+ *   SmolVLM2 tokenizer.
+ * @param params.mask - Token attention mask (`Uint8Array` matching `tokens`).
+ * @param params.noise - Optional seeded noise prior
+ *   (`Float32Array` of length `hparams.chunkSize * hparams.maxActionDim`).
+ *   When omitted the addon samples its own prior.
+ * @returns A `VlaClientRunResult` with the produced `actions` Float32Array
+ *   (length `chunkSize * actionDim`), the corresponding `chunkSize` /
+ *   `actionDim` returned by the addon, and optional per-stage `stats`.
+ *
+ * @example
+ * ```typescript
+ * import { loadModel, vla, vlaPreprocessImage, vlaPadState, vlaHparams } from "@qvac/sdk";
+ *
+ * const modelId = await loadModel({ modelSrc: "/path/to/smolvla.gguf", modelType: "vla" });
+ * const { hparams } = await vlaHparams({ modelId });
+ * const size = hparams.visionImageSize;
+ * const front = vlaPreprocessImage(frontPixels, frontW, frontH, { size });
+ * const wrist = vlaPreprocessImage(wristPixels, wristW, wristH, { size });
+ * const state = vlaPadState(robotState, hparams.maxStateDim);
+ * const tokens = new Int32Array(hparams.tokenizerMaxLength);
+ * const mask = new Uint8Array(hparams.tokenizerMaxLength);
+ * // ...tokenize the instruction into tokens/mask...
+ * const { actions } = await vla({
+ *   modelId, images: [front, wrist], imgWidth: size, imgHeight: size,
+ *   state, tokens, mask,
+ * });
+ * ```
+ */
+export declare function vla(params: VlaClientRunParams): Promise<VlaClientRunResult>;
+/**
+ * Fetch the loaded VLA model's hyperparameters and the active ggml backend
+ * name. Useful to size token / state / noise buffers before calling `vla()`.
+ *
+ * @param params - Identifier of the loaded VLA model.
+ * @returns The model's hparams and the human-readable backend name
+ *   (`"CPU"` / `"Vulkan"` / `"Metal"` / `"OpenCL"` / `null` if the addon
+ *   has not surfaced one).
+ */
+export declare function vlaHparams(params: {
+    modelId: string;
+}): Promise<{
+    hparams: VlaHparams;
+    backendName: string | null;
+}>;
+//# sourceMappingURL=vla.d.ts.map