foxmind 0.0.0-stage → 0.1.0

package/dist/providers/presets.js

@@ -0,0 +1,89 @@
+// Ready-made settings for the local servers people run on their own machine.
+import { FoxmindError } from "../errors.js";
+import { openaiCompatible } from "./openai.js";
+/** Underdog Saluki 27B 1.0, from its Hugging Face model card (checked 2026-10-08). */
+export const SALUKI = {
+    repo: "ConwayResearch/Underdog-Saluki-27B-1.0",
+    file: "Underdog-Saluki-27B-1.0-IQ2-mix.gguf",
+    sizeGB: 7.89,
+    license: "Apache-2.0",
+    download: "huggingface-cli download ConwayResearch/Underdog-Saluki-27B-1.0 Underdog-Saluki-27B-1.0-IQ2-mix.gguf --local-dir .",
+    serve: "llama-server -m Underdog-Saluki-27B-1.0-IQ2-mix.gguf --jinja -ngl 99 -fa on -c 32768",
+};
+function escape(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Ollama's OpenAI-compatible API. "llama3.2" matches "llama3.2:latest". */
+export function ollama(options) {
+    const tagged = options.model.includes(":") ? escape(options.model) : `${escape(options.model)}(:latest)?`;
+    const provider = openaiCompatible({
+        name: "ollama",
+        baseURL: "http://127.0.0.1:11434/v1",
+        checkModel: new RegExp(`^${tagged}$`),
+        hint: `Start Ollama with "ollama serve", then run "ollama pull ${options.model}".`,
+        ...options,
+    });
+    // Ollama answers 403 to an origin it does not allow, such as moz-extension://.
+    const explain = (error) => {
+        if (!(error instanceof FoxmindError) || error.status !== 403)
+            return error;
+        return new FoxmindError("auth", 'Ollama refused this origin (HTTP 403). Start it with OLLAMA_ORIGINS="moz-extension://*" to allow Firefox extensions.', { provider: provider.name, tier: provider.tier, status: 403 });
+    };
+    const { chat, embed, probe } = provider;
+    const root = (options.baseURL ?? "http://127.0.0.1:11434/v1").replace(/\/v1\/?$/, "");
+    return {
+        ...provider,
+        // Ollama can run a model on a remote host with a name that does not say so.
+        // /api/tags lists that host; a local-tier provider must not use such a model.
+        async probe(probeOptions) {
+            const result = await probe(probeOptions);
+            if (!result.ok || provider.tier === "cloud")
+                return result;
+            const tags = await fetch(`${root}/api/tags`, { signal: AbortSignal.timeout(3000), redirect: "manual" })
+                .then((response) => (response.ok ? response.json() : undefined))
+                .catch(() => undefined);
+            // Fail closed: when we cannot see where the model runs, a local-tier provider does not use it.
+            if (!tags)
+                return { ok: false, code: "unreachable", where: result.where, reason: `Cannot read ${root}/api/tags to check that ${options.model} runs on this machine.` };
+            const entry = tags.models?.find((model) => model.name === options.model || model.name === `${options.model}:latest`);
+            if (!entry?.remote_host)
+                return result;
+            return { ok: false, code: "remote_model", where: result.where, reason: `Ollama runs ${options.model} on ${entry.remote_host}, not on this machine. Pass tier: "cloud" to use it as a cloud model.` };
+        },
+        chat: (messages, chatOptions) => chat(messages, chatOptions).catch((error) => { throw explain(error); }),
+        embed: (texts, embedOptions) => embed(texts, embedOptions).catch((error) => { throw explain(error); }),
+    };
+}
+/** llama.cpp llama-server. It serves one model, so the name is not checked. */
+export function llamaServer(options = {}) {
+    return openaiCompatible({
+        name: "llama-server",
+        baseURL: "http://127.0.0.1:8080/v1",
+        checkModel: false,
+        hint: 'Start it with "llama-server -m <model.gguf> --jinja".',
+        ...options,
+        model: options.model ?? "default",
+    });
+}
+/** LM Studio's local server. */
+export function lmStudio(options) {
+    return openaiCompatible({ name: "lm-studio", baseURL: "http://127.0.0.1:1234/v1", hint: 'Start it with "lms server start".', ...options });
+}
+/**
+ * Underdog Saluki 27B on llama-server: the default planner for private mode.
+ * Thinking is off by default with temperature 0, the model card's settings
+ * for direct tool calls. `thinking: true` uses its settings for reasoning.
+ */
+export function saluki(options = {}) {
+    const { thinking = false, ...rest } = options;
+    const sampling = thinking ? { temperature: 0.6, top_p: 0.95, top_k: 20 } : { temperature: 0 };
+    return openaiCompatible({
+        name: "saluki",
+        baseURL: "http://127.0.0.1:8080/v1",
+        checkModel: /saluki/i,
+        hint: `Download it with "${SALUKI.download}", then start it with "${SALUKI.serve}".`,
+        ...rest,
+        model: SALUKI.file,
+        body: { ...sampling, chat_template_kwargs: { enable_thinking: thinking }, ...rest.body },
+    });
+}

package/dist/reply.d.ts

@@ -0,0 +1,10 @@
+import { type Origin } from "./http.js";
+import type { ChatReply, Message } from "./types.js";
+/** Move a leading <think>…</think> block out of the answer, as Qwen3 servers often send it. */
+export declare function splitThinking(message: Message): Message;
+/**
+ * Throws `bad_tool_call` when a tool call's arguments are not a JSON object,
+ * and `bad_json` when the caller asked for JSON and got something else.
+ * Empty arguments become "{}", which is what servers send for a tool with no parameters.
+ */
+export declare function checkReply(origin: Origin, reply: ChatReply, json: boolean | undefined): ChatReply;

package/dist/reply.js

@@ -0,0 +1,60 @@
+// Checks every provider runs on a reply before foxmind returns it.
+import { failure } from "./http.js";
+/** Move a leading <think>…</think> block out of the answer, as Qwen3 servers often send it. */
+export function splitThinking(message) {
+    const match = message.content?.match(/^\s*<think>([\s\S]*?)<\/think>\s*/);
+    if (!match || message.content == null)
+        return message;
+    const reasoning = [message.reasoning, match[1].trim()].filter(Boolean).join("\n");
+    return { ...message, content: message.content.slice(match[0].length), ...(reasoning ? { reasoning } : {}) };
+}
+/** The JSON text in a reply: the whole reply, or the one ```json block in it. */
+function jsonText(content) {
+    for (const candidate of [content.trim(), content.match(/```(?:json)?\s*([\s\S]*?)```/)?.[1]?.trim()]) {
+        if (!candidate)
+            continue;
+        try {
+            JSON.parse(candidate);
+            return candidate;
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    return undefined;
+}
+/**
+ * Throws `bad_tool_call` when a tool call's arguments are not a JSON object,
+ * and `bad_json` when the caller asked for JSON and got something else.
+ * Empty arguments become "{}", which is what servers send for a tool with no parameters.
+ */
+export function checkReply(origin, reply, json) {
+    const message = splitThinking(reply.message);
+    const calls = message.tool_calls?.map((toolCall) => {
+        const text = toolCall.function.arguments.trim() || "{}";
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw failure(origin, "bad_tool_call", `The arguments of tool call "${toolCall.function.name}" are not valid JSON.`, { raw: toolCall.function.arguments });
+        }
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            throw failure(origin, "bad_tool_call", `The arguments of tool call "${toolCall.function.name}" are not a JSON object.`, { raw: text });
+        }
+        // Only the OpenAI fields: some servers add their own (Ollama adds "index").
+        return { id: toolCall.id, type: "function", function: { name: toolCall.function.name, arguments: text } };
+    });
+    if (calls?.length)
+        message.tool_calls = calls;
+    else
+        delete message.tool_calls;
+    if (json && !calls?.length) {
+        const text = jsonText(message.content ?? "");
+        if (text === undefined)
+            throw failure(origin, "bad_json", "The reply is not JSON, but the call asked for JSON.", { raw: message.content ?? "" });
+        message.content = text;
+    }
+    const finishReason = calls?.length && reply.finishReason === "stop" ? "tool_calls" : reply.finishReason;
+    return { ...reply, message: message, finishReason };
+}

package/dist/sse.d.ts

@@ -0,0 +1,6 @@
+export interface SseEvent {
+    event?: string;
+    data: string;
+}
+/** Yield each event. A read error (a dropped connection, an abort) is thrown to the caller. */
+export declare function events(body: ReadableStream<Uint8Array>): AsyncGenerator<SseEvent>;

package/dist/sse.js

@@ -0,0 +1,38 @@
+// Server-sent events from a fetch body, as OpenAI and Anthropic stream them.
+function parse(block) {
+    let event;
+    const data = [];
+    for (const line of block.split(/\r?\n/)) {
+        if (line.startsWith("event:"))
+            event = line.slice(6).trim();
+        else if (line.startsWith("data:"))
+            data.push(line.slice(5).replace(/^ /, ""));
+    }
+    return data.length ? { ...(event ? { event } : {}), data: data.join("\n") } : undefined;
+}
+/** Yield each event. A read error (a dropped connection, an abort) is thrown to the caller. */
+export async function* events(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            for (let end = buffer.search(/\r?\n\r?\n/); end >= 0; end = buffer.search(/\r?\n\r?\n/)) {
+                const event = parse(buffer.slice(0, end));
+                buffer = buffer.slice(end).replace(/^\r?\n\r?\n/, "");
+                if (event)
+                    yield event;
+            }
+        }
+        const last = parse(buffer);
+        if (last)
+            yield last;
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+/** Where a provider runs: in the browser, on a server on this machine, or in a cloud you pay with your key. */
+export type Tier = "browser" | "local" | "cloud";
+export type Capability = "chat" | "embed" | "extract" | "classify";
+export type Role = "system" | "user" | "assistant" | "tool";
+export interface ToolCall {
+    id: string;
+    type: "function";
+    /** `arguments` is a JSON string. foxmind checks that it parses before it returns it. */
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface Message {
+    role: Role;
+    content: string | null;
+    name?: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    /** The model's thinking, when the server sends it apart from the answer. */
+    reasoning?: string;
+    /** Provider-specific data to send back unchanged on the next turn (for example Anthropic thinking blocks). */
+    provider_data?: Record<string, unknown>;
+}
+export interface Tool {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+export interface CallOptions {
+    signal?: AbortSignal;
+    /**
+     * The longest wait, in milliseconds, for the response headers and then for
+     * each next piece of the body. A stream that keeps sending is never cut.
+     */
+    timeoutMs?: number;
+}
+export interface ChatOptions extends CallOptions {
+    tools?: Tool[];
+    /** Ask for one JSON object, and fail with `bad_json` when the reply is not JSON. */
+    json?: boolean;
+    temperature?: number;
+    maxTokens?: number;
+    /** Stream the reply. Called with each new piece of text. */
+    onDelta?: (text: string) => void;
+}
+export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter";
+export interface ChatReply {
+    message: Message & {
+        role: "assistant";
+    };
+    finishReason: FinishReason;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface Entity {
+    text: string;
+    confidence: number;
+    start: number;
+    end: number;
+}
+/** Label name to an optional description, as GLiNER2 takes them. */
+export type Labels = Record<string, string | undefined>;
+export interface ExtractOptions extends CallOptions {
+    /** Keep spans at or above this confidence. Default 0.5. */
+    threshold?: number;
+}
+export interface Probe {
+    ok: boolean;
+    /** Why the provider cannot run, as an error code. */
+    code?: string;
+    reason?: string;
+    /** Where it runs, for example "webgpu", "wasm" or a server URL. */
+    where?: string;
+}
+export interface ProviderStatus {
+    name: string;
+    tier: Tier;
+    model: string;
+    capabilities: readonly Capability[];
+    state: "idle" | "loading" | "ready" | "unavailable" | "error";
+    where?: string;
+    /** Download progress from 0 to 1 while a model loads. */
+    progress?: number;
+    reason?: string;
+}
+export interface Provider {
+    readonly name: string;
+    readonly tier: Tier;
+    readonly model: string;
+    readonly capabilities: readonly Capability[];
+    /** Check, without a model call, that the provider can run now. */
+    probe(options?: CallOptions): Promise<Probe>;
+    status(): ProviderStatus;
+    /** Download and start the model now, not at the first call. */
+    load?(options?: CallOptions): Promise<void>;
+    chat?(messages: Message[], options: ChatOptions): Promise<ChatReply>;
+    embed?(texts: string[], options: CallOptions): Promise<number[][]>;
+    extract?(text: string, labels: Labels, options: ExtractOptions): Promise<Record<string, Entity[]>>;
+    classify?(texts: string[], prompt: string, labels: Labels, options: CallOptions): Promise<Record<string, number>[]>;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// The shapes foxmind speaks. Messages, tools and tool calls follow the OpenAI
+// chat completions API, so code written for it works here unchanged.
+export {};

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "foxmind",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "One API for on-device AI models in the browser and for your own model key.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Pooria Arab",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pooriaarab/foxmind.git"
+  },
+  "homepage": "https://github.com/pooriaarab/foxmind#readme",
+  "packageManager": "pnpm@11.10.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "default": "./dist/browser/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --deny-warnings",
+    "test": "vitest run --passWithNoTests",
+    "ci:local": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm build:ext && pnpm lint:ext",
+    "build:ext": "node scripts/build-ext.mjs",
+    "lint:ext": "web-ext lint -s dist-ext",
+    "e2e": "pnpm build && node scripts/build-ext.mjs --e2e && node e2e/run.mjs"
+  },
+  "devDependencies": {
+    "@huggingface/transformers": "^4.3.1",
+    "@types/node": "^24.19.1",
+    "create-foxkit": "^0.1.0",
+    "esbuild": "^0.28.2",
+    "oxlint": "^1.87.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3",
+    "web-ext": "^10.7.0"
+  },
+  "bin": {
+    "foxmind": "dist/bin.js"
+  },
+  "peerDependencies": {
+    "@huggingface/transformers": "^4.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
+  }
+}