@qvac/sdk 0.12.2 → 0.13.1

package/README.md

@@ -117,6 +117,18 @@ This outputs a tarball under `dist/sdk-{version}.tgz` that you can install in yo
 npm i path/to/sdk-0.3.0.tgz
 ```
 
+## Testing
+
+The SDK test suite is organized into three buckets by runtime:
+
+| Bucket | Runtime | Location | Command |
+|--------|---------|----------|---------|
+| Unit | Bun / Node | `test/unit/` | `bun run test:unit` |
+| Server (Bare) | Bare | `test/bare/` | `bun run test:bare` |
+| Client (consumer) | Node / RN | `e2e/` | See [`e2e/README.md`](./e2e/README.md) |
+
+See [`TESTING.md`](./TESTING.md) for the full decision tree on where new tests should land.
+
 ## Contributing
 
 ### Commit Message and PR Title Format

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

@@ -0,0 +1,57 @@
+import { type BciTranscribeClientParams, type BciTranscribeStreamClientParams, type BciTranscribeStreamSession, type BciTranscribeStreamMetadataSession, type RPCOptions, type TranscribeSegment } from "../../schemas/index";
+/**
+ * Transcribe a neural-signal buffer with a loaded BCI model and return the
+ * complete text. Accepts either a `.bin` file path or a raw neural buffer.
+ *
+ * @param params - BCI transcription parameters.
+ * @param params.modelId - The identifier of the loaded BCI model to use.
+ * @param params.neuralData - Neural signal as either a file path (string) or
+ *                            a binary buffer (`Uint8Array`).
+ * @param params.metadata - When true, resolves to an array of transcript
+ *                          segments (`{ text, startMs, endMs, append, id }`)
+ *                          instead of joined text.
+ * @param options - Optional RPC options including per-call profiling.
+ * @returns A promise (decorated with `requestId`) resolving to the complete
+ *          transcribed text, or — when `metadata` is true — the list of
+ *          transcript segments in emission order. The `requestId` is
+ *          reachable synchronously so callers can target this in-flight
+ *          transcription with `cancel({ requestId })` before `await` resolves.
+ */
+export declare function bciTranscribe(params: BciTranscribeClientParams & {
+    metadata: true;
+}, options?: RPCOptions): Promise<TranscribeSegment[]> & {
+    requestId: string;
+};
+export declare function bciTranscribe(params: BciTranscribeClientParams, options?: RPCOptions): Promise<string> & {
+    requestId: string;
+};
+/**
+ * Opens a bidirectional streaming BCI transcription session. Neural-signal
+ * chunks are streamed in via `write()`, and transcription is yielded as the
+ * addon's sliding window decodes successive windows.
+ *
+ * The returned session is single-use. Attempting to iterate a second time
+ * will throw a `TranscriptionFailedError`.
+ *
+ * @param params - Streaming BCI transcription parameters.
+ * @param params.modelId - The loaded BCI model to use.
+ * @param params.metadata - When true, the session yields transcript segment
+ *                          objects (`{ text, startMs, endMs, append, id }`)
+ *                          instead of plain text.
+ * @param params.windowTimesteps - Decode window size in timesteps.
+ * @param params.hopTimesteps - How far the window advances between decodes.
+ * @param params.emit - `'delta'` (default) yields only the newly-discovered
+ *                       tail per window; `'full'` yields the full running
+ *                       transcript each update.
+ * @param options - Optional RPC options including per-call profiling.
+ * @returns A session object: call `write(neuralChunk)` with a `Uint8Array`
+ *          to feed neural-signal bytes, iterate with `for await (...)` to
+ *          receive transcription, and `end()` to signal end of input. The
+ *          session exposes `requestId` synchronously for targeted
+ *          `cancel({ requestId })`.
+ */
+export declare function bciTranscribeStream(params: BciTranscribeStreamClientParams & {
+    metadata: true;
+}, options?: RPCOptions): Promise<BciTranscribeStreamMetadataSession>;
+export declare function bciTranscribeStream(params: BciTranscribeStreamClientParams, options?: RPCOptions): Promise<BciTranscribeStreamSession>;
+//# sourceMappingURL=bci-transcribe.d.ts.map

package/dist/client/api/bci-transcribe.js

@@ -0,0 +1,172 @@
+import { bciTranscribeResponseSchema, bciTranscribeClientParamsSchema, bciTranscribeStreamResponseSchema, } from "../../schemas/index.js";
+import { stream, duplex } from "../rpc/rpc-client.js";
+import { getClientLogger } from "../../logging/index.js";
+import { TranscriptionFailedError } from "../../utils/errors-client.js";
+import { decoratePromise } from "../../utils/decorate-promise.js";
+import { generateClientRequestId } from "./client-request-id.js";
+const logger = getClientLogger();
+function buildBciTranscribeRequest(params, requestId) {
+    return {
+        type: "bciTranscribe",
+        modelId: params.modelId,
+        neuralData: typeof params.neuralData === "string"
+            ? { type: "filePath", value: params.neuralData }
+            : {
+                type: "base64",
+                value: Buffer.from(params.neuralData).toString("base64"),
+            },
+        ...(params.metadata === true && { metadata: true }),
+        requestId,
+    };
+}
+export function bciTranscribe(params, options) {
+    const parsed = bciTranscribeClientParamsSchema.parse(params);
+    const requestId = generateClientRequestId();
+    const inner = runBciTranscribe(parsed, requestId, options);
+    return decoratePromise(inner, { requestId });
+}
+async function runBciTranscribe(params, requestId, options) {
+    const request = buildBciTranscribeRequest(params, requestId);
+    if (params.metadata === true) {
+        const segments = [];
+        for await (const response of stream(request, options)) {
+            if (response.type === "bciTranscribe") {
+                const parsed = bciTranscribeResponseSchema.parse(response);
+                if (parsed.segment) {
+                    segments.push(parsed.segment);
+                }
+                if (parsed.done) {
+                    break;
+                }
+            }
+        }
+        return segments;
+    }
+    let fullText = "";
+    for await (const response of stream(request, options)) {
+        if (response.type === "bciTranscribe") {
+            const parsed = bciTranscribeResponseSchema.parse(response);
+            if (parsed.text) {
+                fullText += parsed.text;
+            }
+            if (parsed.done) {
+                break;
+            }
+        }
+    }
+    return fullText;
+}
+function buildBciTranscribeStreamRequest(params, requestId) {
+    const streamOpts = {
+        ...(params.windowTimesteps !== undefined && {
+            windowTimesteps: params.windowTimesteps,
+        }),
+        ...(params.hopTimesteps !== undefined && {
+            hopTimesteps: params.hopTimesteps,
+        }),
+        ...(params.emit !== undefined && { emit: params.emit }),
+    };
+    return {
+        type: "bciTranscribeStream",
+        modelId: params.modelId,
+        ...(params.metadata === true && { metadata: true }),
+        ...(Object.keys(streamOpts).length > 0 && { streamOpts }),
+        requestId,
+    };
+}
+export function bciTranscribeStream(params, options) {
+    if (params.metadata === true) {
+        return createBciStreamSession(params, options, processLineMetadata, "BciTranscribeStreamMetadataSession");
+    }
+    return createBciStreamSession(params, options, processLine, "BciTranscribeStreamSession");
+}
+async function createBciStreamSession(params, options, process, sessionName) {
+    const requestId = generateClientRequestId();
+    const request = buildBciTranscribeStreamRequest(params, requestId);
+    const { requestStream, responseStream } = await duplex(request, options);
+    const responses = parseLines(responseStream, process);
+    let consumed = false;
+    return {
+        requestId,
+        write(neuralChunk) {
+            requestStream.write(neuralChunk);
+        },
+        end() {
+            requestStream.end();
+        },
+        destroy() {
+            requestStream.destroy();
+            responseStream.destroy();
+        },
+        [Symbol.asyncIterator]() {
+            if (consumed) {
+                throw new TranscriptionFailedError(`${sessionName} can only be iterated once`);
+            }
+            consumed = true;
+            return responses;
+        },
+    };
+}
+/**
+ * Line-delimited parser: reads newline-separated frames from a duplex
+ * response stream, passes each non-empty line through `process`, and yields
+ * whatever values it returns. `null` from `process` terminates the stream.
+ */
+async function* parseLines(responseStream, process) {
+    let buf = "";
+    for await (const chunk of responseStream) {
+        buf += chunk.toString();
+        const lines = buf.split("\n");
+        buf = lines.pop() || "";
+        for (const line of lines) {
+            const result = process(line);
+            if (result === null)
+                return;
+            if (result !== undefined)
+                yield result;
+        }
+    }
+    if (buf.trim()) {
+        const result = process(buf);
+        if (result !== null && result !== undefined)
+            yield result;
+    }
+}
+function parseResponseLine(line) {
+    if (!line.trim())
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        logger.warn("bciTranscribeStream: malformed JSON from server:", line);
+        return null;
+    }
+    const obj = parsed;
+    if (obj["type"] === "error") {
+        throw new TranscriptionFailedError(obj["message"] ?? "Unknown server error");
+    }
+    return bciTranscribeStreamResponseSchema.parse(parsed);
+}
+/**
+ * Shared wire-frame decoder. Returns `null` for the terminal `done` frame,
+ * `undefined` for frames the caller should skip, or the value extracted from
+ * the frame.
+ */
+function processWith(line, extract) {
+    const response = parseResponseLine(line);
+    if (response === null)
+        return undefined;
+    if (response.error)
+        throw new TranscriptionFailedError(response.error);
+    if (response.done)
+        return null;
+    return extract(response);
+}
+function processLine(line) {
+    return processWith(line, (response) => response.text?.trim() ? response.text : undefined);
+}
+function processLineMetadata(line) {
+    return processWith(line, (response) => response.segment);
+}

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" | "vla" | "llm" | "whisper" | "nmt" | "parakeet" | "classification" | "vad" | "other";
+    addon: "embeddings" | "diffusion" | "tts" | "ocr" | "vla" | "llm" | "whisper" | "bci" | "nmt" | "parakeet" | "classification" | "vad" | "other";
     isCached: boolean;
     isLoaded: boolean;
     cacheFiles: {

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

@@ -6,6 +6,7 @@ export { unloadModel } from "./unload-model";
 export { loggingStream } from "./logging-stream";
 export { heartbeat } from "./heartbeat";
 export { transcribe, transcribeStream } from "./transcribe";
+export { bciTranscribe, bciTranscribeStream } from "./bci-transcribe";
 export { embed } from "./embed";
 export { finetune, type FinetuneHandle } from "./finetune";
 export { translate } from "./translate";

package/dist/client/api/index.js

@@ -6,6 +6,7 @@ export { unloadModel } from "./unload-model.js";
 export { loggingStream } from "./logging-stream.js";
 export { heartbeat } from "./heartbeat.js";
 export { transcribe, transcribeStream } from "./transcribe.js";
+export { bciTranscribe, bciTranscribeStream } from "./bci-transcribe.js";
 export { embed } from "./embed.js";
 export { finetune } from "./finetune.js";
 export { translate } from "./translate.js";

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

@@ -16,11 +16,13 @@ export interface VideoResult {
  * @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.
+ * Supports `txt2vid` (text-to-video) and `img2vid` (image-to-video). For `img2vid`,
+ * load the Wan pipeline with `modelConfig.clipVisionModelSrc` set to
+ * `clip_vision_h.safetensors`. On React Native, prefer a `modelId` loaded with a
+ * `delegate` since the bundled video diffusion models are too large for typical mobile devices.
  *
- * @example
+ * @example Basic txt2vid generation
  * ```typescript
- * // Basic txt2vid generation
  * const { outputs, stats } = video({
  *   modelId,
  *   mode: "txt2vid",
@@ -32,8 +34,10 @@ export interface VideoResult {
  * });
  * const buffers = await outputs;
  * fs.writeFileSync("output.avi", buffers[0]);
+ * ```
  *
- * // With progress tracking
+ * @example With progress tracking
+ * ```typescript
  * const { progressStream, outputs } = video({
  *   modelId,
  *   mode: "txt2vid",
@@ -43,8 +47,22 @@ export interface VideoResult {
  *   console.log(`${step}/${totalSteps}`);
  * }
  * const buffers = await outputs;
+ * ```
+ *
+ * @example Image-to-video (first frame + motion prompt)
+ * ```typescript
+ * const firstFrame = fs.readFileSync("portrait.png");
+ * const { outputs } = video({
+ *   modelId,
+ *   mode: "img2vid",
+ *   prompt: "the subject slowly turns and smiles, cinematic lighting",
+ *   init_image: firstFrame,
+ *   strength: 0.85,
+ * });
+ * ```
  *
- * // With control frames (e.g. for guided generation)
+ * @example With control frames (e.g. for guided generation)
+ * ```typescript
  * const frameA = fs.readFileSync("frame-a.png");
  * const frameB = fs.readFileSync("frame-b.png");
  * const { outputs } = video({
@@ -53,8 +71,10 @@ export interface VideoResult {
  *   prompt: "smooth transition between scenes",
  *   control_frames: [frameA, frameB],
  * });
+ * ```
  *
- * // Cancellation via requestId
+ * @example Cancellation via requestId
+ * ```typescript
  * const { requestId, outputs } = video({ modelId, mode: "txt2vid", prompt: "..." });
  * // ...later
  * await cancel(requestId);

package/dist/client/api/video.js

@@ -8,11 +8,13 @@ import { decodeBase64, encodeBase64 } from "../../utils/encoding.js";
  * @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.
+ * Supports `txt2vid` (text-to-video) and `img2vid` (image-to-video). For `img2vid`,
+ * load the Wan pipeline with `modelConfig.clipVisionModelSrc` set to
+ * `clip_vision_h.safetensors`. On React Native, prefer a `modelId` loaded with a
+ * `delegate` since the bundled video diffusion models are too large for typical mobile devices.
  *
- * @example
+ * @example Basic txt2vid generation
  * ```typescript
- * // Basic txt2vid generation
  * const { outputs, stats } = video({
  *   modelId,
  *   mode: "txt2vid",
@@ -24,8 +26,10 @@ import { decodeBase64, encodeBase64 } from "../../utils/encoding.js";
  * });
  * const buffers = await outputs;
  * fs.writeFileSync("output.avi", buffers[0]);
+ * ```
  *
- * // With progress tracking
+ * @example With progress tracking
+ * ```typescript
  * const { progressStream, outputs } = video({
  *   modelId,
  *   mode: "txt2vid",
@@ -35,8 +39,22 @@ import { decodeBase64, encodeBase64 } from "../../utils/encoding.js";
  *   console.log(`${step}/${totalSteps}`);
  * }
  * const buffers = await outputs;
+ * ```
  *
- * // With control frames (e.g. for guided generation)
+ * @example Image-to-video (first frame + motion prompt)
+ * ```typescript
+ * const firstFrame = fs.readFileSync("portrait.png");
+ * const { outputs } = video({
+ *   modelId,
+ *   mode: "img2vid",
+ *   prompt: "the subject slowly turns and smiles, cinematic lighting",
+ *   init_image: firstFrame,
+ *   strength: 0.85,
+ * });
+ * ```
+ *
+ * @example With control frames (e.g. for guided generation)
+ * ```typescript
  * const frameA = fs.readFileSync("frame-a.png");
  * const frameB = fs.readFileSync("frame-b.png");
  * const { outputs } = video({
@@ -45,21 +63,26 @@ import { decodeBase64, encodeBase64 } from "../../utils/encoding.js";
  *   prompt: "smooth transition between scenes",
  *   control_frames: [frameA, frameB],
  * });
+ * ```
  *
- * // Cancellation via requestId
+ * @example Cancellation via requestId
+ * ```typescript
  * 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 { control_frames, init_image, ...rest } = params;
     const request = {
         ...rest,
         ...(control_frames !== undefined && {
             control_frames: control_frames.map(encodeBase64),
         }),
+        ...(init_image !== undefined && {
+            init_image: encodeBase64(init_image),
+        }),
         type: "videoStream",
         requestId,
     };

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

@@ -1,24 +1,28 @@
 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.
+ * Run VLA inference on a loaded model (SmolVLA or π₀.₅) 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
+ * @param params.images - The 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
+ *   `[-1, 1]`. Pass exactly `hparams.numCameras` frames (2 for SmolVLA, 3
+ *   for π₀.₅). 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.state - Robot end-effector / gripper state. For
+ *   continuous-state models (SmolVLA) pad to `hparams.maxStateDim` with
+ *   `vlaPadState`. For discrete-state models (π₀.₅,
+ *   `hparams.stateInputMode === 'discrete'`) the state is tokenised into the
+ *   prompt and this buffer is ignored — pass an empty `Float32Array(0)`.
  * @param params.tokens - Tokenized instruction (`Int32Array` of length
  *   `hparams.tokenizerMaxLength`). Tokenize on the consumer side with the
- *   SmolVLM2 tokenizer.
+ *   model's tokenizer (SmolVLM2 for SmolVLA, PaliGemma/Gemma for π₀.₅).
  * @param params.mask - Token attention mask (`Uint8Array` matching `tokens`).
  * @param params.noise - Optional seeded noise prior
  *   (`Float32Array` of length `hparams.chunkSize * hparams.maxActionDim`).

package/dist/client/api/vla.js

@@ -13,25 +13,29 @@ function f32FromBase64(b64) {
     return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength / 4);
 }
 /**
- * Run SmolVLA inference on a loaded VLA model and return the produced action
- * chunk plus per-stage timings.
+ * Run VLA inference on a loaded model (SmolVLA or π₀.₅) 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
+ * @param params.images - The 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
+ *   `[-1, 1]`. Pass exactly `hparams.numCameras` frames (2 for SmolVLA, 3
+ *   for π₀.₅). 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.state - Robot end-effector / gripper state. For
+ *   continuous-state models (SmolVLA) pad to `hparams.maxStateDim` with
+ *   `vlaPadState`. For discrete-state models (π₀.₅,
+ *   `hparams.stateInputMode === 'discrete'`) the state is tokenised into the
+ *   prompt and this buffer is ignored — pass an empty `Float32Array(0)`.
  * @param params.tokens - Tokenized instruction (`Int32Array` of length
  *   `hparams.tokenizerMaxLength`). Tokenize on the consumer side with the
- *   SmolVLM2 tokenizer.
+ *   model's tokenizer (SmolVLM2 for SmolVLA, PaliGemma/Gemma for π₀.₅).
  * @param params.mask - Token attention mask (`Uint8Array` matching `tokens`).
  * @param params.noise - Optional seeded noise prior
  *   (`Float32Array` of length `hparams.chunkSize * hparams.maxActionDim`).

package/dist/client/rpc/bare-client.js

@@ -9,7 +9,7 @@ import { setSDKConfig } from "../../server/bare/registry/config-registry.js";
 import { setRuntimeContext } from "../../server/bare/registry/runtime-context-registry.js";
 import { resolveModelConfig } from "../../server/bare/registry/model-config-registry.js";
 import { resolveConfig } from "../config-loader/resolve-config.bare.js";
-import { initializeWorkerCore, shutdownBareDirectWorker, cleanupForTerminate, } from "../../server/worker-core.js";
+import { initializeWorkerCore, cleanupForTerminate, } from "../../server/worker-core.js";
 import { assertLifecycleAllowed } from "../../server/bare/runtime-lifecycle.js";
 import { ensurePluginsRegistered } from "./ensure-worker-ready.js";
 async function ensureWorkerReady() {
@@ -216,7 +216,7 @@ export async function getRPC() {
     return mockRPC;
 }
 export async function close() {
-    await shutdownBareDirectWorker("rpc-close");
+    await cleanupForTerminate();
 }
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 export async function createDuplexSession(payload, _commandId) {

package/dist/commands/bundle/constants.js

@@ -2,11 +2,13 @@ export const BUILTIN_PLUGINS = {
     "llamacpp-completion": { exportName: "llmPlugin" },
     "llamacpp-embedding": { exportName: "embeddingsPlugin" },
     "whispercpp-transcription": { exportName: "whisperPlugin" },
+    "bci-whispercpp-transcription": { exportName: "bciPlugin" },
     "parakeet-transcription": { exportName: "parakeetPlugin" },
     "nmtcpp-translation": { exportName: "nmtPlugin" },
     "tts-ggml": { exportName: "ttsPlugin" },
     "onnx-ocr": { exportName: "ocrPlugin" },
     "sdcpp-generation": { exportName: "diffusionPlugin" },
+    "ggml-vla": { exportName: "vlaPlugin" },
 };
 export const BUILTIN_SUFFIXES = Object.keys(BUILTIN_PLUGINS);
 export const DEFAULT_HOSTS = [

package/dist/examples/bci/bci-filesystem-streaming.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bci-filesystem-streaming.d.ts.map

package/dist/examples/bci/bci-filesystem-streaming.js

@@ -0,0 +1,77 @@
+/**
+ * Streaming BCI transcription from a neural-signal file.
+ *
+ * Reads a raw neural-signal `.bin` file and feeds it to the BCI
+ * (whisper.cpp) addon chunk-by-chunk through a duplex `bciTranscribeStream`
+ * session, printing transcript text as the sliding window decodes
+ * successive windows.
+ *
+ * Usage: bun run examples/bci/bci-filesystem-streaming.ts <neural-bin-file-path>
+ */
+import { loadModel, unloadModel, bciTranscribeStream, BCI_WINDOWED, } from "@qvac/sdk";
+import { readFileSync } from "fs";
+const args = process.argv.slice(2);
+if (!args[0]) {
+    console.error("Usage: bun run examples/bci/bci-filesystem-streaming.ts <neural-bin-file-path>");
+    process.exit(1);
+}
+const neuralFilePath = args[0];
+// Feed the neural buffer in fixed-size chunks to simulate a live stream.
+const CHUNK_SIZE = 64 * 1024;
+try {
+    console.log("=== BCI transcribeStream file test ===");
+    console.log(`File: ${neuralFilePath}`);
+    console.log(`Chunk size: ${CHUNK_SIZE} bytes\n`);
+    console.log("Loading model...");
+    const modelId = await loadModel({
+        modelSrc: BCI_WINDOWED,
+        modelConfig: {
+            whisperConfig: {
+                language: "en",
+                n_threads: 4,
+                temperature: 0.0,
+            },
+            // Session day index selects the day-specific projection matrices.
+            // Set this to match the recording session your neural file came from.
+            bciConfig: {
+                day_idx: 1,
+            },
+        },
+    });
+    console.log(`Model loaded: ${modelId}\n`);
+    console.log("Opening live session...");
+    const session = await bciTranscribeStream({ modelId, emit: "delta" });
+    console.log("Session open. Streaming neural signal...\n");
+    // Drain the session concurrently with writing so the sliding-window
+    // decode can make progress as chunks arrive instead of stalling.
+    const consume = (async () => {
+        let transcript = "";
+        for await (const text of session) {
+            transcript += text;
+            process.stdout.write(text);
+        }
+        return transcript;
+    })();
+    const data = readFileSync(neuralFilePath);
+    let totalBytes = 0;
+    for (let offset = 0; offset < data.length; offset += CHUNK_SIZE) {
+        const chunk = data.subarray(offset, offset + CHUNK_SIZE);
+        session.write(chunk);
+        totalBytes += chunk.length;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    console.log(`\n\nNeural signal streamed: ${totalBytes} bytes`);
+    console.log("Waiting for transcription to finish...\n");
+    session.end();
+    const transcript = await consume;
+    console.log("\n=== Results ===");
+    console.log(`Transcript: ${transcript.trim() || "(no text received)"}`);
+    console.log("\nUnloading model...");
+    await unloadModel({ modelId });
+    console.log("Done.");
+    process.exit(0);
+}
+catch (error) {
+    console.error("❌ Error:", error);
+    process.exit(1);
+}

package/dist/examples/bci/bci-filesystem.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=bci-filesystem.d.ts.map