@happyvertical/smrt-svelte 0.51.11 → 0.51.14

package/AGENTS.md

@@ -195,6 +195,33 @@ for a data-surface one — for exactly the component's lifetime.
 - **Warm client cache**: module-level Map survives navigation/remounts -- avoids re-downloading WASM/models
 - **Adapters**: STT (browser-speech, whisper-cpp, whisper-wasm), TTS (browser-synthesis), LLM (webllm, transformers-llm)
 - Cache API: `getCachedSTT()`, `getCachedTTS()`, `getCachedLLM()`, `getCacheStats()`, `clearAllCaches()`
+- **Inference backends (browser-ai)**: two `@happyvertical/smrt-web/ai` `InferenceBackend`s, both
+  `kind: 'local'`, both refusing `tool`/`function` messages, non-string content, `tool_calls` and
+  `options.tools` with `InferencePathError` (`unsupported_message`) through the SHARED
+  `assertTextOnlyTurn`, so a per-call switch between backends never changes what a turn means.
+  - `createWebLlmInferenceBackend()` wraps an `LLMAdapter` — `status` derives from the adapter's
+  `initState` (plus an explicit in-flight flag, because the adapter only flips to `initializing`
+  after its own awaits), `progress` mirrors `DownloadProgressInfo`, and `load()`/`unload()` drive
+  `ensureInitialized`/`unloadModel`. It reports `unavailable` without WebGPU so an `auto` path skips
+  it. Pass `adapter` to share the app-state-managed warm-cached adapter; construct once, so two
+  callers cannot each start an unshared adapter and a second download.
+  Its `loadModule` option matters: the default `importOptional()` resolves a VARIABLE specifier,
+  which a browser cannot resolve (`TypeError: Failed to resolve module specifier`) — a host that has
+  `@mlc-ai/web-llm` must pass `() => import('@mlc-ai/web-llm')` so the bundler rewrites a static one.
+  It does NOT forward `signal` (the adapter has no cancellation seam).
+  - `createBitGpuInferenceBackend()` wraps `bitgpu` (MIT, optional peer), the engine behind the
+    Bonsai WebGPU demo PrismML's own docs list as their in-browser option. `loadBitGpu`/`loadChat`
+    are REQUIRED loaders (`() => import('bitgpu')`, `() => import('bitgpu/chat')`) — a static import
+    here would fail the build for every consumer without the optional peer, and a bare specifier is
+    not resolvable by a browser either. `bitgpu`'s `LoadProgress.phase` maps to `InferenceProgress`
+    (`manifest`/`weights` → `downloading`, `pipelines` → `extracting`). Unlike the WebLLM backend it
+    **forwards `signal`** — bitgpu aborts a live generation — and it does NOT lazily load: weights
+    run to GBs, so a turn before `load()` fails with a named reason. `model` in the per-call options
+    is ignored (one engine binds one model), and bitgpu's tools/JSON-schema/think support is
+    deliberately left unexposed for now so the text-only invariant holds across backends.
+- **`ModelStatusControl.svelte`**: the user-facing model lifecycle surface (state, Load/Unload,
+  download progress) driven entirely by a backend's own `status`/`progress`/`subscribe`, so it works
+  without a `<Provider>` ancestor. `unavailable` is a first-class state that offers NO load action.
 
 ## Permission Action
 

package/dist/browser-ai/adapters/llm/bitgpu-inference-backend.d.ts

@@ -0,0 +1,129 @@
+/**
+ * An `InferenceBackend` over `bitgpu` — a WebGPU runtime for 1-bit (binary-weight)
+ * LLMs in the browser.
+ *
+ * ## Why this engine and not WebLLM
+ *
+ * `bitgpu` (MIT, zero runtime dependencies) is the engine behind the Bonsai
+ * WebGPU demo PrismML's own docs list as their in-browser option, and it is the
+ * one browser runtime in this package that can honor `signal`: its
+ * `ChatSendOptions.signal` aborts a generation in flight, which the WebLLM
+ * adapter has no seam for. It also reports load progress by phase and reuses the
+ * KV cache across turns.
+ *
+ * ## What this backend does not expose (yet)
+ *
+ * `bitgpu` supports tool calling, JSON-schema-constrained decoding, thinking
+ * budgets and vision. This backend deliberately exposes only the TEXT subset
+ * that {@link assertTextOnlyTurn} enforces, so that switching backend per call
+ * never changes what a turn means: the WebLLM and route backends refuse tool
+ * turns, and a backend that silently accepted them would break that invariant.
+ * Widening this is a deliberate follow-up, not an oversight.
+ *
+ * `model` in {@link InferenceChatOptions} is ignored: one engine is bound to one
+ * model (`createEngine`), so a per-call model id has nothing to select.
+ *
+ * ## Loading
+ *
+ * Unlike the WebLLM backend, `chat`/`stream` do NOT lazily load. Weights for
+ * these models run from hundreds of MB to multiple GB, so an implicit download
+ * behind the first turn would be hostile; a caller must `load()` first (the path
+ * only auto-selects a backend whose status is `ready`, so `auto` already
+ * requires it). Calling a turn before loading fails with a clear message.
+ *
+ * @module
+ */
+import { type InferenceBackend } from '@happyvertical/smrt-web/ai';
+/** Mirrors `LoadProgress`. Exported so a host or test can type the callback. */
+export interface BitGpuLoadProgress {
+    phase: 'manifest' | 'weights' | 'pipelines';
+    loaded?: number;
+    total?: number;
+}
+/** Mirrors `ChatMessage`. */
+interface BitGpuMessage {
+    role: string;
+    content: string;
+}
+/** Mirrors `ChatResult`. */
+interface BitGpuChatResult {
+    text: string;
+    finishReason: 'stop' | 'length' | 'abort' | 'tool_calls';
+}
+/** Mirrors `ChatSendOptions` (only the fields this backend forwards). */
+interface BitGpuSendOptions {
+    maxTokens?: number;
+    temperature?: number;
+    topP?: number;
+    stopSequences?: string[];
+    onText?: (delta: string) => void;
+    signal?: AbortSignal;
+}
+interface BitGpuEngine {
+    dispose(): void;
+}
+interface BitGpuChat {
+    send(messages: BitGpuMessage[], options?: BitGpuSendOptions): Promise<BitGpuChatResult>;
+    /** Deltas, with the final result as the generator's return value. */
+    stream(messages: BitGpuMessage[], options?: BitGpuSendOptions): AsyncGenerator<string, BitGpuChatResult>;
+}
+/** The `bitgpu` entry point (`createEngine`, errors). */
+export interface BitGpuModule {
+    createEngine(options: string | {
+        modelUrl?: string;
+        manifestUrl?: string;
+        dataUrl?: string;
+        auxUrl?: string;
+        maxSeqLen?: number;
+        kvCache?: 'f32' | 'f16' | 'q8';
+        onProgress?: (progress: BitGpuLoadProgress) => void;
+    }): Promise<BitGpuEngine>;
+    WebGPUUnavailableError: new (message: string) => Error;
+}
+/** The `bitgpu/chat` entry point. */
+export interface BitGpuChatModule {
+    createChat(engine: BitGpuEngine, options: {
+        modelUrl?: string;
+        tokenizerJsonUrl?: string;
+        tokenizerConfigUrl?: string;
+    }): Promise<BitGpuChat>;
+}
+export interface BitGpuInferenceBackendOptions {
+    /** Backend id. Defaults to `'bitgpu'`. */
+    id?: string;
+    /** Model directory holding `manifest.json` plus its data/aux files. */
+    modelUrl?: string;
+    /** Explicit URLs, when they are not colocated. */
+    manifestUrl?: string;
+    dataUrl?: string;
+    auxUrl?: string;
+    /** Tokenizer files; default to `modelUrl` when omitted. */
+    tokenizerJsonUrl?: string;
+    tokenizerConfigUrl?: string;
+    /** KV window. Larger costs more GPU memory. */
+    maxSeqLen?: number;
+    /** KV cache precision. `q8` trades a little quality for context length. */
+    kvCache?: 'f32' | 'f16' | 'q8';
+    /**
+     * Supplies the `bitgpu` entry point (`createEngine`).
+     *
+     * Required, not optional: `bitgpu` is an OPTIONAL peer dependency, so a static
+     * import here would fail the build for every consumer that has not installed
+     * it — and a bare specifier is not resolvable by a browser at runtime either.
+     * The host supplies a static import from its own code, where the bundler can
+     * see it: `() => import('bitgpu')`.
+     */
+    loadBitGpu: () => Promise<BitGpuModule>;
+    /** Supplies the `bitgpu/chat` entry point. See {@link BitGpuInferenceBackendOptions.loadBitGpu}. */
+    loadChat: () => Promise<BitGpuChatModule>;
+}
+/**
+ * A local backend over `bitgpu`.
+ *
+ * `status` reports `'unavailable'` without WebGPU, so an `auto` path skips it
+ * rather than starting a multi-gigabyte download on a device that cannot run the
+ * result. `load()` must be called before a turn; see the module header.
+ */
+export declare function createBitGpuInferenceBackend(options: BitGpuInferenceBackendOptions): InferenceBackend;
+export {};
+//# sourceMappingURL=bitgpu-inference-backend.d.ts.map

package/dist/browser-ai/adapters/llm/bitgpu-inference-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bitgpu-inference-backend.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/llm/bitgpu-inference-backend.ts"],"names":[],"mappings":"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"}

package/dist/browser-ai/adapters/llm/bitgpu-inference-backend.js

@@ -0,0 +1,331 @@
+/**
+ * An `InferenceBackend` over `bitgpu` — a WebGPU runtime for 1-bit (binary-weight)
+ * LLMs in the browser.
+ *
+ * ## Why this engine and not WebLLM
+ *
+ * `bitgpu` (MIT, zero runtime dependencies) is the engine behind the Bonsai
+ * WebGPU demo PrismML's own docs list as their in-browser option, and it is the
+ * one browser runtime in this package that can honor `signal`: its
+ * `ChatSendOptions.signal` aborts a generation in flight, which the WebLLM
+ * adapter has no seam for. It also reports load progress by phase and reuses the
+ * KV cache across turns.
+ *
+ * ## What this backend does not expose (yet)
+ *
+ * `bitgpu` supports tool calling, JSON-schema-constrained decoding, thinking
+ * budgets and vision. This backend deliberately exposes only the TEXT subset
+ * that {@link assertTextOnlyTurn} enforces, so that switching backend per call
+ * never changes what a turn means: the WebLLM and route backends refuse tool
+ * turns, and a backend that silently accepted them would break that invariant.
+ * Widening this is a deliberate follow-up, not an oversight.
+ *
+ * `model` in {@link InferenceChatOptions} is ignored: one engine is bound to one
+ * model (`createEngine`), so a per-call model id has nothing to select.
+ *
+ * ## Loading
+ *
+ * Unlike the WebLLM backend, `chat`/`stream` do NOT lazily load. Weights for
+ * these models run from hundreds of MB to multiple GB, so an implicit download
+ * behind the first turn would be hostile; a caller must `load()` first (the path
+ * only auto-selects a backend whose status is `ready`, so `auto` already
+ * requires it). Calling a turn before loading fails with a clear message.
+ *
+ * @module
+ */
+import { assertTextOnlyTurn, InferencePathError, requestSignal, } from '@happyvertical/smrt-web/ai';
+import { detectCapabilities } from '../../capabilities/detector.js';
+const BACKEND_LABEL = 'The bitgpu backend';
+/** `bitgpu`'s load phases mapped onto the mirrored progress states. */
+const PROGRESS_STATE = {
+    // Fetching the manifest and the weights is one continuous download from the
+    // caller's point of view.
+    manifest: 'downloading',
+    weights: 'downloading',
+    // Building the WGSL pipelines is the closest analogue to unpacking.
+    pipelines: 'extracting',
+};
+/**
+ * Map a bitgpu load report onto {@link InferenceProgress}.
+ *
+ * `loaded`/`total` are bytes when the engine reports them; when it reports only
+ * a phase, the percent stays 0 and `currentFile` names the phase instead.
+ */
+function toProgress(report) {
+    const total = report.total ?? 0;
+    const loaded = report.loaded ?? 0;
+    return {
+        state: PROGRESS_STATE[report.phase] ?? 'downloading',
+        bytesLoaded: loaded,
+        bytesTotal: total,
+        percent: total > 0 ? Math.round((loaded / total) * 100) : 0,
+        currentFile: report.phase,
+    };
+}
+/** Forward only the options the engine can honor. */
+function toSendOptions(options) {
+    const stop = options?.stop;
+    // bitgpu aborts a live generation, so it is the one local backend that can
+    // honor a deadline: compose it the same way the route backend does rather
+    // than silently dropping the caller's `timeout`.
+    const signal = requestSignal(options);
+    return {
+        ...(options?.maxTokens !== undefined
+            ? { maxTokens: options.maxTokens }
+            : {}),
+        ...(options?.temperature !== undefined
+            ? { temperature: options.temperature }
+            : {}),
+        ...(options?.topP !== undefined ? { topP: options.topP } : {}),
+        ...(stop ? { stopSequences: Array.isArray(stop) ? stop : [stop] } : {}),
+        ...(signal ? { signal } : {}),
+    };
+}
+/**
+ * A local backend over `bitgpu`.
+ *
+ * `status` reports `'unavailable'` without WebGPU, so an `auto` path skips it
+ * rather than starting a multi-gigabyte download on a device that cannot run the
+ * result. `load()` must be called before a turn; see the module header.
+ */
+export function createBitGpuInferenceBackend(options) {
+    let engine = null;
+    let chat = null;
+    let progress;
+    let loadError = null;
+    let loadInFlight = false;
+    // Memoized so concurrent callers share one load. Stamped with the epoch that
+    // created it: once `unload()` invalidates an attempt, a later `load()` must
+    // start real work rather than be handed the discarded attempt's promise.
+    let loading = null;
+    // Bumped by `unload()`. A load captures it before its first `await` and
+    // re-checks it afterwards, so a load that overlaps an `unload()` discards the
+    // engine it built instead of publishing it and reporting `ready`.
+    let loadEpoch = 0;
+    const listeners = new Set();
+    function broadcast() {
+        for (const listener of [...listeners])
+            listener();
+    }
+    function currentStatus() {
+        if (!detectCapabilities().llm.webgpu)
+            return 'unavailable';
+        if (loadError)
+            return 'error';
+        if (loadInFlight)
+            return 'loading';
+        if (engine && chat)
+            return 'ready';
+        return 'idle';
+    }
+    /** The loaded chat, or a failure naming what the caller forgot to do. */
+    function requireChat() {
+        if (!chat) {
+            throw new InferencePathError(`${BACKEND_LABEL} has no loaded model. Call load() first — weights are too large to fetch behind the first turn.`, 'no_usable_backend');
+        }
+        return chat;
+    }
+    return {
+        id: options.id ?? 'bitgpu',
+        kind: 'local',
+        get status() {
+            return currentStatus();
+        },
+        get progress() {
+            return progress;
+        },
+        load(onProgress) {
+            // Marked before the first await: reading `status` immediately after
+            // calling `load()` must not report `idle`, the state auto-selection skips.
+            if (currentStatus() === 'unavailable') {
+                return Promise.reject(new InferencePathError('bitgpu requires WebGPU, which this browser does not expose.', 'no_usable_backend'));
+            }
+            // No-op when already ready — the documented contract for `load`. Without
+            // this, a second call fetches the weights again (hundreds of MB) and
+            // overwrites `engine` without disposing it, leaving two live WebGPU
+            // engines, while `status` flickers through `loading` and an `auto` path
+            // stops selecting this backend.
+            if (engine && chat)
+                return Promise.resolve();
+            // Reuse only a load from the CURRENT epoch: after `unload()` the memo
+            // belongs to a discarded attempt, and returning it would resolve a fresh
+            // `load()` without loading anything.
+            if (loading && loading.epoch === loadEpoch)
+                return loading.promise;
+            loadInFlight = true;
+            loadError = null;
+            broadcast();
+            // Captured before the first `await` below; every step that could publish
+            // state re-checks it, because `unload()` may run while this is in flight.
+            const epoch = loadEpoch;
+            const pending = (async () => {
+                // Hoisted: an engine created here is owned by this attempt until it is
+                // published, and anything that abandons the attempt must dispose it —
+                // nothing else holds a reference to it.
+                let created;
+                try {
+                    const [bitgpu, chatModule] = await Promise.all([
+                        options.loadBitGpu(),
+                        options.loadChat(),
+                    ]);
+                    created = await bitgpu.createEngine({
+                        ...(options.modelUrl ? { modelUrl: options.modelUrl } : {}),
+                        ...(options.manifestUrl
+                            ? { manifestUrl: options.manifestUrl }
+                            : {}),
+                        ...(options.dataUrl ? { dataUrl: options.dataUrl } : {}),
+                        ...(options.auxUrl ? { auxUrl: options.auxUrl } : {}),
+                        ...(options.maxSeqLen !== undefined
+                            ? { maxSeqLen: options.maxSeqLen }
+                            : {}),
+                        ...(options.kvCache ? { kvCache: options.kvCache } : {}),
+                        onProgress: (report) => {
+                            // A download that outlives an `unload()` must not resurrect
+                            // progress on a backend the caller has just released.
+                            if (epoch !== loadEpoch)
+                                return;
+                            progress = toProgress(report);
+                            onProgress?.(progress);
+                            broadcast();
+                        },
+                    });
+                    // The tokenizer resolves from `modelUrl` unless told otherwise; both
+                    // sides of the split are surfaced so a host can host them apart.
+                    const createdChat = await chatModule.createChat(created, {
+                        ...(options.modelUrl ? { modelUrl: options.modelUrl } : {}),
+                        ...(options.tokenizerJsonUrl
+                            ? { tokenizerJsonUrl: options.tokenizerJsonUrl }
+                            : {}),
+                        ...(options.tokenizerConfigUrl
+                            ? { tokenizerConfigUrl: options.tokenizerConfigUrl }
+                            : {}),
+                    });
+                    if (epoch !== loadEpoch) {
+                        // `unload()` ran while these were being created. Publishing them
+                        // would report `ready` with a live GPU device nothing disposes, and
+                        // a later `load()` would no-op on it.
+                        try {
+                            created.dispose();
+                        }
+                        catch {
+                            // Abandoning the attempt, not reporting its failure: a teardown
+                            // error must not become the caller's error.
+                        }
+                        created = undefined;
+                        return;
+                    }
+                    engine = created;
+                    chat = createdChat;
+                    // Ownership moves to the backend, so the failure path below must not
+                    // dispose it.
+                    created = undefined;
+                    progress = undefined;
+                }
+                catch (error) {
+                    // A failure AFTER the engine exists (the tokenizer comes from a
+                    // different host than the manifest, so `createChat` failing here is
+                    // the documented real case) would otherwise orphan a live GPU device
+                    // and its weights — and every retry would allocate another.
+                    try {
+                        created?.dispose();
+                    }
+                    catch {
+                        // A teardown error must not replace the load failure the caller is
+                        // about to see, nor skip recording it.
+                    }
+                    created = undefined;
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    // A failure that overlaps an `unload()` leaves the backend idle
+                    // rather than reporting an error for work the caller cancelled.
+                    if (epoch === loadEpoch) {
+                        loadError = err;
+                        // Keep whatever the load had reported so a caller can see how far
+                        // it got, and mark it failed.
+                        progress = {
+                            bytesLoaded: progress?.bytesLoaded ?? 0,
+                            bytesTotal: progress?.bytesTotal ?? 0,
+                            percent: progress?.percent ?? 0,
+                            state: 'error',
+                            error: err.message,
+                        };
+                    }
+                    throw err;
+                }
+                finally {
+                    // A superseded attempt must not clear the flag for the load that
+                    // replaced it.
+                    if (epoch === loadEpoch)
+                        loadInFlight = false;
+                    broadcast();
+                }
+            })();
+            loading = { promise: pending, epoch };
+            // Cleared here, never inside the body above: the body runs synchronously
+            // up to its first `await`, so a host loader that throws synchronously (a
+            // legal `() => Promise<T>` callback) settles it BEFORE the assignment
+            // just above. Clearing inside would then be overwritten by that already
+            // settled promise, and every later `load()` would replay its rejection —
+            // the documented retry path dead for the life of the backend.
+            const releaseLoading = () => {
+                // Only clear the memo while it still points at THIS attempt: a later
+                // `load()` may already own it.
+                if (loading?.promise === pending)
+                    loading = null;
+            };
+            void pending.then(releaseLoading, releaseLoading);
+            return pending;
+        },
+        async unload() {
+            // Invalidate anything in flight: a load re-checks the epoch after every
+            // `await` and disposes what it built rather than publishing it, and the
+            // memoized promise is dropped so a later `load()` starts real work
+            // instead of being handed the discarded attempt.
+            loadEpoch += 1;
+            loading = null;
+            loadInFlight = false;
+            // `dispose()` tears down the GPU device; the chat layer holds KV state
+            // bound to it, so both references go together.
+            engine?.dispose();
+            engine = null;
+            chat = null;
+            progress = undefined;
+            loadError = null;
+            broadcast();
+        },
+        async chat(messages, chatOptions) {
+            assertTextOnlyTurn(BACKEND_LABEL, messages, chatOptions);
+            const result = await requireChat().send(messages.map(({ role, content }) => ({ role, content })), toSendOptions(chatOptions));
+            return {
+                content: result.text,
+                // bitgpu also reports `'abort'`, which `AIResponse.finishReason` has no
+                // member for: an aborted turn carries no finish reason here rather than
+                // inventing one.
+                //
+                // The consequence is worth knowing before wiring `timeout`/`signal`: an
+                // aborted generation returns its PARTIAL text and is therefore not
+                // distinguishable from a short reply. The route backend fails closed for
+                // the same deadline (a coded `InferencePathError`), so matching that here
+                // would need a code this mirrored vocabulary does not have yet.
+                ...(result.finishReason === 'stop' ||
+                    result.finishReason === 'length' ||
+                    result.finishReason === 'tool_calls'
+                    ? { finishReason: result.finishReason }
+                    : {}),
+            };
+        },
+        async *stream(messages, chatOptions) {
+            assertTextOnlyTurn(BACKEND_LABEL, messages, chatOptions);
+            const iterator = requireChat().stream(messages.map(({ role, content }) => ({ role, content })), toSendOptions(chatOptions));
+            for await (const delta of iterator) {
+                chatOptions?.onProgress?.(delta);
+                yield delta;
+            }
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}