foxmind 0.0.0-stage → 0.1.0

package/dist/browser/gliner2.js

@@ -0,0 +1,50 @@
+import { Gliner2 } from "./gliner2-model.js";
+import { loadOnce, onProgress, pickDevice, toBrowserError } from "./runtime.js";
+export function gliner2(options = {}) {
+    const model = options.model ?? "pooria/gliner2-multi-v1-agent-batch-ONNX";
+    const name = options.name ?? "gliner2";
+    const origin = { provider: name, tier: "browser", secrets: [] };
+    const capabilities = ["extract", "classify"];
+    const loader = loadOnce(origin, model, options.device ?? "auto", async (device, progress) => {
+        const loaded = await Gliner2.load(model, { device, dtype: options.dtype ?? "fp16", progress_callback: onProgress(progress) });
+        // Compile the WebGPU shaders now, not on the first real call.
+        await loaded.classify("warm up", "warmup", { a: undefined, b: undefined });
+        return loaded;
+    });
+    async function run(work) {
+        const loaded = await loader.get();
+        try {
+            return await work(loaded);
+        }
+        catch (error) {
+            throw toBrowserError(origin, error, model);
+        }
+    }
+    return {
+        name,
+        tier: "browser",
+        model,
+        capabilities,
+        async probe() {
+            const picked = await pickDevice(options.device ?? "auto");
+            return "code" in picked ? { ok: false, code: picked.code, reason: picked.reason } : { ok: true, where: picked.device, ...(picked.note ? { reason: picked.note } : {}) };
+        },
+        status() {
+            const { state, where, progress, reason } = loader.state;
+            return { name, tier: "browser", model, capabilities, state, ...(where ? { where } : {}), ...(progress === undefined ? {} : { progress }), ...(reason ? { reason } : {}) };
+        },
+        async load() {
+            await loader.get();
+        },
+        async extract(text, labels, extractOptions) {
+            if (!Object.keys(labels).length)
+                return {};
+            return run((loaded) => loaded.extractEntities(text, labels, extractOptions.threshold ?? 0.5));
+        },
+        async classify(texts, prompt, labels) {
+            if (!Object.keys(labels).length)
+                return texts.map(() => ({}));
+            return run((loaded) => loaded.classifyMany(texts, prompt, labels));
+        },
+    };
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,4 @@
+export { configureRuntime, hasWebGPU, purgeModel, type Device, type RuntimeOptions } from "./runtime.js";
+export { transformers, type TransformersOptions } from "./transformers.js";
+export { requestTrialML, trialML, wllama, type TrialMLOptions } from "./trialml.js";
+export { gliner2, type Gliner2Options } from "./gliner2.js";

package/dist/browser/index.js

@@ -0,0 +1,6 @@
+// foxmind/browser: the providers that run models inside the browser.
+// They need the optional peer dependency @huggingface/transformers.
+export { configureRuntime, hasWebGPU, purgeModel } from "./runtime.js";
+export { transformers } from "./transformers.js";
+export { requestTrialML, trialML, wllama } from "./trialml.js";
+export { gliner2 } from "./gliner2.js";

package/dist/browser/runtime.d.ts

@@ -0,0 +1,61 @@
+import { type Origin } from "../http.js";
+import { FoxmindError } from "../errors.js";
+import type { CallOptions } from "../types.js";
+type Transformers = typeof import("@huggingface/transformers");
+export type Device = "auto" | "webgpu" | "wasm";
+export interface RuntimeOptions {
+    /** Where ONNX Runtime's asyncify .mjs and .wasm files are. Default: ort/ in the extension. */
+    wasmPaths?: {
+        mjs: string;
+        wasm: string;
+    };
+    /** The model hub, for a mirror. It applies to every model on the page. Default "https://huggingface.co/". */
+    remoteHost?: string;
+}
+/** Change the runtime settings. Call it before the first model loads. */
+export declare function configureRuntime(next: RuntimeOptions): void;
+/** transformers.js, loaded once, set for extension pages: no remote code, one WASM thread when there is no SharedArrayBuffer. */
+export declare function transformersJs(): Promise<Transformers>;
+/** True when the browser gives a WebGPU adapter. */
+export declare function hasWebGPU(): Promise<boolean>;
+/** The device to load on, or why the asked device cannot run. */
+export declare function pickDevice(device: Device): Promise<{
+    device: "webgpu" | "wasm";
+    note?: string;
+} | {
+    code: "webgpu_missing";
+    reason: string;
+}>;
+/** Delete one model's files from Cache Storage. Returns how many it deleted. */
+export declare function purgeModel(model: string): Promise<number>;
+export declare function isCached(model: string): Promise<boolean>;
+/**
+ * Wait for work, but stop waiting at the caller's abort or after timeoutMs
+ * (when either is given). onStop runs then, to stop the work where it can.
+ */
+export declare function bounded<T>(origin: Origin, work: Promise<T>, limits: CallOptions, onStop?: () => void): Promise<T>;
+/** Map an error from a model load or run to a FoxmindError code. */
+export declare function toBrowserError(origin: Origin, error: unknown, model: string): FoxmindError;
+export interface LoadState {
+    state: "idle" | "loading" | "ready" | "error";
+    where?: "webgpu" | "wasm";
+    progress?: number;
+    reason?: string;
+}
+/**
+ * Loads a model once. Calls that come during a load wait for it. A failed
+ * load is not kept, so the next call tries again. With device "auto", a model
+ * that fails on WebGPU loads on WASM before anything is deleted. Cached files
+ * are deleted and downloaded once more only when every device failed, or when
+ * the error points at the files.
+ */
+export declare function loadOnce<T>(origin: Origin, model: string, device: Device, open: (device: "webgpu" | "wasm", progress: (p: number) => void) => Promise<T>): {
+    state: LoadState;
+    get(): Promise<T>;
+};
+/** The progress callback transformers.js takes, as one number from 0 to 1. */
+export declare function onProgress(progress: (p: number) => void): (info: {
+    status?: string;
+    progress?: number;
+}) => void;
+export {};

package/dist/browser/runtime.js

@@ -0,0 +1,205 @@
+// What every in-browser model needs: transformers.js set up for an extension
+// page, WebGPU detection, the model cache, and load errors mapped to codes.
+import { failure } from "../http.js";
+import { FoxmindError } from "../errors.js";
+let options = {};
+let loaded;
+let adapter;
+/** Change the runtime settings. Call it before the first model loads. */
+export function configureRuntime(next) {
+    options = { ...options, ...next };
+}
+function extensionURL(path) {
+    const runtime = globalThis.browser?.runtime;
+    return runtime?.getURL?.(path);
+}
+/** transformers.js, loaded once, set for extension pages: no remote code, one WASM thread when there is no SharedArrayBuffer. */
+export async function transformersJs() {
+    const module = await (loaded ??= import("@huggingface/transformers").then((fresh) => {
+        const { env } = fresh;
+        env.allowLocalModels = false;
+        // MV3 forbids blob: and remote scripts, so ONNX Runtime loads its own files.
+        env.useWasmCache = false;
+        const wasm = env.backends.onnx.wasm;
+        const mjs = extensionURL("ort/ort-wasm-simd-threaded.asyncify.mjs");
+        const paths = options.wasmPaths ?? (mjs ? { mjs, wasm: extensionURL("ort/ort-wasm-simd-threaded.asyncify.wasm") } : undefined);
+        if (paths)
+            wasm.wasmPaths = paths;
+        if (!globalThis.crossOriginIsolated)
+            wasm.numThreads = 1;
+        return fresh;
+    }));
+    module.env.remoteHost = options.remoteHost ?? "https://huggingface.co/";
+    return module;
+}
+/** True when the browser gives a WebGPU adapter. */
+export function hasWebGPU() {
+    adapter ??= (async () => {
+        const gpu = globalThis.navigator?.gpu;
+        if (!gpu)
+            return false;
+        try {
+            return Boolean(await gpu.requestAdapter());
+        }
+        catch {
+            return false;
+        }
+    })();
+    return adapter;
+}
+/** The device to load on, or why the asked device cannot run. */
+export async function pickDevice(device) {
+    if (device === "wasm")
+        return { device: "wasm" };
+    if (await hasWebGPU())
+        return { device: "webgpu" };
+    if (device === "webgpu")
+        return { code: "webgpu_missing", reason: "This browser gives no WebGPU adapter (Firefox has none on Linux, Intel Macs and Android). Use device \"auto\" or \"wasm\"." };
+    return { device: "wasm", note: "WebGPU is missing, so it runs on WASM." };
+}
+const CACHE = "transformers-cache";
+/** The cached requests that belong to one model. */
+async function cachedFiles(model) {
+    if (typeof caches === "undefined")
+        return undefined;
+    const cache = await caches.open(CACHE);
+    const keys = (await cache.keys()).filter((request) => request.url.includes(`/${model}/`));
+    return { cache, keys };
+}
+/** Delete one model's files from Cache Storage. Returns how many it deleted. */
+export async function purgeModel(model) {
+    const files = await cachedFiles(model);
+    if (!files)
+        return 0;
+    await Promise.all(files.keys.map((key) => files.cache.delete(key)));
+    return files.keys.length;
+}
+export async function isCached(model) {
+    return Boolean((await cachedFiles(model))?.keys.length);
+}
+/**
+ * Wait for work, but stop waiting at the caller's abort or after timeoutMs
+ * (when either is given). onStop runs then, to stop the work where it can.
+ */
+export async function bounded(origin, work, limits, onStop) {
+    const { signal, timeoutMs } = limits;
+    if (!signal && timeoutMs === undefined)
+        return work;
+    let timer;
+    let onAbort;
+    const stopped = new Promise((_, reject) => {
+        const stop = (error) => {
+            onStop?.();
+            reject(error);
+        };
+        onAbort = () => stop(failure(origin, "aborted", "The caller stopped the call."));
+        if (signal?.aborted)
+            onAbort();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (timeoutMs !== undefined)
+            timer = setTimeout(() => stop(failure(origin, "timeout", `No answer within ${timeoutMs} ms.`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([work, stopped]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (onAbort)
+            signal?.removeEventListener("abort", onAbort);
+    }
+}
+/** Map an error from a model load or run to a FoxmindError code. */
+export function toBrowserError(origin, error, model) {
+    if (error instanceof FoxmindError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    if (/out of memory|allocation failed|could not allocate|memory access out of bounds|device (was )?lost|maximum buffer size|exceeds the max/i.test(message)) {
+        return failure(origin, "out_of_memory", `${model} needs more memory than this device has (${message}). Try a smaller model or a smaller dtype such as "q4".`, { cause: error });
+    }
+    if (/Could not locate file|Unauthorized access to file|Forbidden access to file/i.test(message)) {
+        return failure(origin, "model_not_found", `The hub has no ${model}, or it is private: ${message}`, { cause: error });
+    }
+    if (/NetworkError|Failed to fetch|network|body stream|input stream|terminated|load failed|Gateway|Service unavailable/i.test(message)) {
+        return failure(origin, "download_failed", `The download of ${model} stopped: ${message}. Call again to download it again.`, { cause: error });
+    }
+    return failure(origin, "bad_response", `${model} did not load: ${message}`, { cause: error });
+}
+/** Errors that point at the model files, not at the device. */
+const FILE_ERROR = /protobuf|pars(e|ing)|Unexpected (token|end)|JSON|invalid model|not a valid|corrupt|magic/i;
+/**
+ * Loads a model once. Calls that come during a load wait for it. A failed
+ * load is not kept, so the next call tries again. With device "auto", a model
+ * that fails on WebGPU loads on WASM before anything is deleted. Cached files
+ * are deleted and downloaded once more only when every device failed, or when
+ * the error points at the files.
+ */
+export function loadOnce(origin, model, device, open) {
+    const state = { state: "idle" };
+    let pending;
+    const progress = (p) => { state.progress = p; };
+    async function attempt() {
+        const picked = await pickDevice(device);
+        if ("code" in picked)
+            throw failure(origin, picked.code, picked.reason);
+        Object.assign(state, { state: "loading", where: picked.device, progress: 0, reason: picked.note });
+        const hadCache = await isCached(model);
+        const devices = device === "auto" && picked.device === "webgpu" ? ["webgpu", "wasm"] : [picked.device];
+        let first;
+        let last;
+        for (const where of devices) {
+            state.where = where;
+            try {
+                const value = await open(where, progress);
+                if (first)
+                    state.reason = `WebGPU failed (${first.message ?? first}), so it runs on WASM.`;
+                return value;
+            }
+            catch (error) {
+                const mapped = toBrowserError(origin, error, model);
+                // A missing model or a broken download is the same on every device.
+                if (mapped.code === "model_not_found" || mapped.code === "download_failed")
+                    throw mapped;
+                first ??= error;
+                last = error;
+            }
+        }
+        const mapped = toBrowserError(origin, last, model);
+        const message = last instanceof Error ? last.message : String(last);
+        if (mapped.code !== "bad_response" || !hadCache || (devices.length === 1 && !FILE_ERROR.test(message)))
+            throw mapped;
+        const where = devices.at(-1);
+        const removed = await purgeModel(model);
+        try {
+            const value = await open(where, progress);
+            state.reason = `Repaired: deleted ${removed} cached files of ${model} that did not load, and downloaded them again.`;
+            return value;
+        }
+        catch (second) {
+            const again = toBrowserError(origin, second, model);
+            if (again.code !== "bad_response")
+                throw again;
+            throw failure(origin, "cache_corrupt", `${model} did not load from a fresh download either: ${again.message}`, { cause: second });
+        }
+    }
+    return {
+        state,
+        get() {
+            pending ??= attempt().then((value) => {
+                Object.assign(state, { state: "ready", progress: 1 });
+                return value;
+            }, (error) => {
+                pending = undefined;
+                Object.assign(state, { state: "error", reason: error.message });
+                throw error;
+            });
+            return pending;
+        },
+    };
+}
+/** The progress callback transformers.js takes, as one number from 0 to 1. */
+export function onProgress(progress) {
+    return (info) => {
+        if (info.status === "progress_total" && typeof info.progress === "number")
+            progress(info.progress / 100);
+    };
+}

package/dist/browser/toolcalls.d.ts

@@ -0,0 +1,6 @@
+import type { ToolCall } from "../types.js";
+/** Qwen3 and Hermes-style models write tool calls as <tool_call>{"name": …, "arguments": …}</tool_call>. */
+export declare function parseToolCalls(text: string): {
+    content: string;
+    toolCalls: ToolCall[];
+};

package/dist/browser/toolcalls.js

@@ -0,0 +1,20 @@
+/** Qwen3 and Hermes-style models write tool calls as <tool_call>{"name": …, "arguments": …}</tool_call>. */
+export function parseToolCalls(text) {
+    const toolCalls = [];
+    const content = text.replace(/<tool_call>([\s\S]*?)(<\/tool_call>|$)/g, (_, body) => {
+        const raw = body.trim();
+        let name = raw.match(/"name"\s*:\s*"([^"]+)"/)?.[1] ?? "unknown";
+        let args = raw;
+        try {
+            const parsed = JSON.parse(raw);
+            name = parsed.name ?? name;
+            args = typeof parsed.arguments === "string" ? parsed.arguments : JSON.stringify(parsed.arguments ?? {});
+        }
+        catch {
+            // checkReply() reports the raw text as a bad tool call.
+        }
+        toolCalls.push({ id: `call_${toolCalls.length}`, type: "function", function: { name, arguments: args } });
+        return "";
+    });
+    return { content: content.trim(), toolCalls };
+}

package/dist/browser/transformers.d.ts

@@ -0,0 +1,18 @@
+import type { Provider } from "../types.js";
+import { type Device } from "./runtime.js";
+export interface TransformersOptions {
+    task: "embed" | "chat";
+    /** Default "Xenova/all-MiniLM-L6-v2" for embed and "onnx-community/Qwen3-0.6B-ONNX" for chat. */
+    model?: string;
+    /** Default "auto": WebGPU when the browser has it, else WASM. */
+    device?: Device;
+    /** Default on WebGPU: "fp16" for embed, "q4f16" for chat. On WASM: "q8" for embed, "q4" for chat. */
+    dtype?: string;
+    /** Default "transformers-embed" or "transformers-chat". */
+    name?: string;
+    /** Chat: the most tokens to write. Default 256. */
+    maxNewTokens?: number;
+    /** Chat: let Qwen3 think before it answers. Default false. */
+    thinking?: boolean;
+}
+export declare function transformers(options: TransformersOptions): Provider;

package/dist/browser/transformers.js

@@ -0,0 +1,81 @@
+import { checkReply } from "../reply.js";
+import { bounded, loadOnce, onProgress, pickDevice, toBrowserError, transformersJs } from "./runtime.js";
+import { parseToolCalls } from "./toolcalls.js";
+export function transformers(options) {
+    const chat = options.task === "chat";
+    const model = options.model ?? (chat ? "onnx-community/Qwen3-0.6B-ONNX" : "Xenova/all-MiniLM-L6-v2");
+    const name = options.name ?? `transformers-${options.task}`;
+    const origin = { provider: name, tier: "browser", secrets: [] };
+    const capabilities = chat ? ["chat"] : ["embed"];
+    const loader = loadOnce(origin, model, options.device ?? "auto", async (device, progress) => {
+        const { pipeline } = await transformersJs();
+        const dtype = options.dtype ?? (device === "webgpu" ? (chat ? "q4f16" : "fp16") : chat ? "q4" : "q8");
+        const task = chat ? "text-generation" : "feature-extraction";
+        return (await pipeline(task, model, { device, dtype, progress_callback: onProgress(progress) }));
+    });
+    async function run(work) {
+        const pipe = await loader.get();
+        try {
+            return await work(pipe);
+        }
+        catch (error) {
+            throw toBrowserError(origin, error, model);
+        }
+    }
+    return {
+        name,
+        tier: "browser",
+        model,
+        capabilities,
+        async probe() {
+            const picked = await pickDevice(options.device ?? "auto");
+            return "code" in picked ? { ok: false, code: picked.code, reason: picked.reason } : { ok: true, where: picked.device, ...(picked.note ? { reason: picked.note } : {}) };
+        },
+        status() {
+            const { state, where, progress, reason } = loader.state;
+            return { name, tier: "browser", model, capabilities, state, ...(where ? { where } : {}), ...(progress === undefined ? {} : { progress }), ...(reason ? { reason } : {}) };
+        },
+        async load() {
+            await loader.get();
+        },
+        ...(chat
+            ? {
+                async chat(messages, chatOptions) {
+                    const rule = chatOptions.json ? [{ role: "system", content: "Reply with one JSON object and nothing else." }] : [];
+                    return run(async (pipe) => {
+                        const { TextStreamer, InterruptableStoppingCriteria } = await transformersJs();
+                        // Stops the generation itself when the caller aborts or the time runs out.
+                        const stopper = new InterruptableStoppingCriteria();
+                        const prompt = pipe.tokenizer.apply_chat_template([...rule, ...messages.map(({ reasoning: _r, provider_data: _p, ...m }) => m)], {
+                            tokenize: false,
+                            add_generation_prompt: true,
+                            enable_thinking: options.thinking ?? false,
+                            ...(chatOptions.tools?.length ? { tools: chatOptions.tools } : {}),
+                        });
+                        const onDelta = chatOptions.onDelta;
+                        const streamer = onDelta ? new TextStreamer(pipe.tokenizer, { skip_prompt: true, skip_special_tokens: true, callback_function: onDelta }) : undefined;
+                        const generation = pipe(prompt, {
+                            max_new_tokens: chatOptions.maxTokens ?? options.maxNewTokens ?? 256,
+                            do_sample: (chatOptions.temperature ?? 0) > 0,
+                            ...(chatOptions.temperature ? { temperature: chatOptions.temperature } : {}),
+                            return_full_text: false,
+                            stopping_criteria: stopper,
+                            ...(streamer ? { streamer } : {}),
+                        });
+                        const [output] = (await bounded(origin, generation, chatOptions, () => stopper.interrupt()));
+                        const { content, toolCalls } = parseToolCalls(output?.generated_text ?? "");
+                        const message = { role: "assistant", content, ...(toolCalls.length ? { tool_calls: toolCalls } : {}) };
+                        return checkReply(origin, { message, finishReason: toolCalls.length ? "tool_calls" : "stop" }, chatOptions.json);
+                    });
+                },
+            }
+            : {
+                async embed(texts) {
+                    return run(async (pipe) => {
+                        const tensor = (await pipe(texts, { pooling: "mean", normalize: true }));
+                        return tensor.tolist();
+                    });
+                },
+            }),
+    };
+}

package/dist/browser/trialml.d.ts

@@ -0,0 +1,32 @@
+import type { Provider } from "../types.js";
+export interface TrialMLOptions {
+    task: "embed" | "chat";
+    /** Default "Xenova/all-MiniLM-L6-v2" for embed and "Xenova/Qwen1.5-0.5B-Chat" for chat. */
+    model?: string;
+    /** Default "wasm". "gpu" uses WebGPU where Firefox has it. */
+    device?: "wasm" | "gpu";
+    /** Default "trialml-embed" or "trialml-chat". */
+    name?: string;
+    /** "llama.cpp" runs a GGUF file (set `modelFile`). Default: Firefox's ONNX backend. */
+    backend?: "llama.cpp";
+    /** The GGUF file in the model repo, for the llama.cpp backend. */
+    modelFile?: string;
+    /** Refuse model files larger than this many bytes before the download. Default 4 GB. */
+    maxBytes?: number;
+}
+/** Ask the user for the optional trialML permission. Call it from a click handler. */
+export declare function requestTrialML(): Promise<boolean>;
+/** One vector per text from whatever shape the engine returns. */
+export declare function toVectors(result: unknown, count: number): number[][] | undefined;
+export declare function trialML(options: TrialMLOptions): Provider;
+/**
+ * Experimental: a GGUF model on Firefox's llama.cpp backend, through trial ML.
+ * Small models only: trial ML takes models from the Mozilla and Xenova orgs,
+ * and foxmind refuses files over `maxBytes` (default 4 GB) before the download.
+ */
+export declare function wllama(options: {
+    model: string;
+    modelFile: string;
+    name?: string;
+    maxBytes?: number;
+}): Provider;