@tanstack-ai-browser/prompt-api 0.0.0-stage → 0.2.1

package/dist/tools.js

@@ -0,0 +1,314 @@
+const DELIMITERS = [
+    { start: "```tool_call", end: "```" },
+    { start: "```tool-call", end: "```" },
+    { start: "<tool_call>", end: "</tool_call>" },
+    { start: "<|tool_call>", end: "<tool_call|>" },
+    { start: "<|tool_call_start|>", end: "<|tool_call_end|>" }
+];
+/** A Python-style call, `[name(...)]`. */
+const PYTHON_CALL = /\[(\w+)\(/;
+const isObject = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+/**
+ * The system prompt with the tools and how to call them; unchanged without
+ * tools.
+ */
+export function toolSystemPrompt(system, tools) {
+    if (tools.length === 0)
+        return system;
+    const definitions = tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description ?? "No description provided.",
+        parameters: tool.inputSchema ?? { type: "object", properties: {} }
+    }));
+    const instructions = `You are a helpful AI assistant with access to tools.
+
+# Available Tools
+${JSON.stringify(definitions, null, 2)}
+
+# Tool Calling Instructions
+Only request one tool call at a time. Wait for tool results before asking for another tool.
+
+To call a tool, output JSON in this exact format inside a \`\`\`tool_call code fence:
+
+\`\`\`tool_call
+{"name": "tool_name", "arguments": {"param1": "value1", "param2": "value2"}}
+\`\`\`
+
+Tool responses will be provided in \`\`\`tool_result fences. Each line contains JSON like:
+\`\`\`tool_result
+{"id": "call_123", "name": "tool_name", "result": {...}, "error": false}
+\`\`\`
+Use the \`result\` payload (and treat \`error\` as a boolean flag) when continuing the conversation.
+
+Important:
+- Use exact tool and parameter names from the schema above
+- Arguments must be a valid JSON object matching the tool's parameters
+- You can include brief reasoning before or after the tool call
+- If no tool is needed, respond directly without tool_call fences`;
+    return system.trim() ? `${system.trim()}\n\n${instructions}` : instructions;
+}
+/** Earlier tool calls in the conversation, as the model would have written them. */
+export function toolCallFence(calls) {
+    const lines = calls.map((call) => {
+        let args;
+        try {
+            args = JSON.parse(call.function.arguments || "{}");
+        }
+        catch {
+            args = call.function.arguments;
+        }
+        return JSON.stringify({ name: call.function.name, arguments: args, ...(call.id && { id: call.id }) });
+    });
+    return `\`\`\`tool_call\n${lines.join("\n")}\n\`\`\``;
+}
+/** A tool's result line for a ```tool_result fence. */
+export function toolResultLine(id, name, content, error) {
+    let result = error ?? content;
+    if (error === undefined) {
+        try {
+            result = JSON.parse(content);
+        }
+        catch {
+            // Plain text.
+        }
+    }
+    return JSON.stringify({ name, result: result ?? null, error: error !== undefined, ...(id && { id }) });
+}
+/** Tool results as the model reads them. */
+export const toolResultFence = (lines) => `\`\`\`tool_result\n${lines.join("\n")}\n\`\`\``;
+/**
+ * The first tool call in a fence's body: a JSON object (or an array of them,
+ * or one per line) with `name` and `arguments` (or `parameters`), the
+ * arguments possibly a JSON string; else, as the whole body, a Python-style
+ * call, `[name(key="v")]`, or `call:name{key:value}`.
+ */
+export function parseToolCall(body) {
+    const text = body.trim();
+    const candidates = [];
+    try {
+        const value = JSON.parse(text);
+        candidates.push(...(Array.isArray(value) ? value : [value]));
+    }
+    catch {
+        for (const line of text.split("\n")) {
+            try {
+                candidates.push(JSON.parse(line));
+            }
+            catch {
+                // Not JSON.
+            }
+        }
+    }
+    for (const call of candidates) {
+        if (!isObject(call) || typeof call.name !== "string" || !call.name)
+            continue;
+        let args = call.arguments ?? call.parameters ?? {};
+        if (typeof args === "string") {
+            try {
+                args = JSON.parse(args);
+            }
+            catch {
+                // Left as the model wrote it.
+            }
+        }
+        return { name: call.name, arguments: args };
+    }
+    // `call:name{key:value,…}`
+    const colon = /^call:(\w+)\{([^}]*)\}$/.exec(text);
+    if (colon)
+        return { name: colon[1], arguments: parseColonArguments(colon[2]) };
+    // Python style, `[name(key="value")]` or `name(key="value")`
+    return parsePythonCall(text);
+}
+/** `key:value,…` pairs, values read as numbers, booleans or null where they are. */
+function parseColonArguments(text) {
+    const args = {};
+    for (const pair of text.split(",")) {
+        const at = pair.indexOf(":");
+        if (at <= 0)
+            continue;
+        const key = pair.slice(0, at).trim();
+        const raw = pair.slice(at + 1).trim();
+        const number = Number(raw);
+        args[key] =
+            raw === "true" ? true : raw === "false" ? false : raw === "null" ? null : raw !== "" && !Number.isNaN(number) ? number : raw;
+    }
+    return args;
+}
+/** The index of the bracket that closes the one at `open`, past quoted text, or -1. */
+function closing(text, open) {
+    const pairs = { "(": ")", "[": "]", "{": "}" };
+    const stack = [];
+    let quote = "";
+    for (let i = open; i < text.length; i++) {
+        const c = text[i];
+        if (quote) {
+            if (c === "\\")
+                i++;
+            else if (c === quote)
+                quote = "";
+        }
+        else if (c === '"' || c === "'")
+            quote = c;
+        else if (pairs[c])
+            stack.push(pairs[c]);
+        else if (c === stack.at(-1)) {
+            stack.pop();
+            if (stack.length === 0)
+                return i;
+        }
+    }
+    return -1;
+}
+/** `text` split at its top-level commas (not inside quotes or brackets). */
+function splitTopLevel(text) {
+    const parts = [];
+    let depth = 0;
+    let quote = "";
+    let from = 0;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (quote) {
+            if (c === "\\")
+                i++;
+            else if (c === quote)
+                quote = "";
+        }
+        else if (c === '"' || c === "'")
+            quote = c;
+        else if ("([{".includes(c))
+            depth++;
+        else if (")]}".includes(c))
+            depth--;
+        else if (c === "," && depth === 0) {
+            parts.push(text.slice(from, i));
+            from = i + 1;
+        }
+    }
+    parts.push(text.slice(from));
+    return parts.map((part) => part.trim()).filter(Boolean);
+}
+/** A Python literal (string, number, True/False/None, list, dict) as a value. */
+function pythonValue(raw) {
+    const text = raw.trim();
+    if (text === "True")
+        return true;
+    if (text === "False")
+        return false;
+    if (text === "None")
+        return null;
+    if (/^(["']).*\1$/s.test(text))
+        return text.slice(1, -1).replace(/\\(["'\\])/g, "$1");
+    const json = text
+        .replace(/'((?:[^'\\]|\\.)*)'/g, (_, inner) => JSON.stringify(inner.replace(/\\'/g, "'")))
+        .replace(/\bTrue\b/g, "true")
+        .replace(/\bFalse\b/g, "false")
+        .replace(/\bNone\b/g, "null");
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return text;
+    }
+}
+/** `text` as one Python-style call: `name(key=value, …)`, maybe in brackets. */
+function parsePythonCall(text) {
+    const match = /^(\[?\s*)(\w+)\(/.exec(text);
+    if (!match)
+        return undefined;
+    const open = match[0].length - 1;
+    const close = closing(text, open);
+    if (close === -1 || text.slice(close + 1).trim() !== (match[1] ? "]" : ""))
+        return undefined;
+    const args = {};
+    for (const part of splitTopLevel(text.slice(open + 1, close))) {
+        const at = part.indexOf("=");
+        if (at <= 0)
+            continue;
+        args[part.slice(0, at).trim()] = pythonValue(part.slice(at + 1));
+    }
+    return { name: match[2], arguments: args };
+}
+/** Characters at the end of `text` that could start a fence. */
+function partialFenceStart(text) {
+    for (let size = Math.min(text.length, Math.max(...DELIMITERS.map((d) => d.start.length)) - 1); size > 0; size--) {
+        const end = text.slice(-size);
+        if (DELIMITERS.some((d) => d.start.startsWith(end)))
+            return size;
+    }
+    return 0;
+}
+/**
+ * Reads a streamed reply: `push` each piece and get back the text that can
+ * be shown now; text inside a ```tool_call fence (or another call's
+ * delimiters: `<tool_call>`, `<|tool_call>`, `<|tool_call_start|>`, or a
+ * Python-style `[name(…)]`) is held back. The first fence that closes with
+ * a call in it ends the reply (stop generating then): `call` is the call,
+ * and `trailing` the text after it. A fence without a call, a call to a tool
+ * not in `names` (when given), and other code fences, are text. `end` gives
+ * the rest, an unclosed fence as text.
+ */
+export function toolCallReader(names) {
+    let buffer = "";
+    // The delimiter of the call being read; a Python-style call is read whole.
+    let start;
+    let call;
+    // Text after the call, in the piece that closed it.
+    let trailing = "";
+    const read = () => {
+        let shown = "";
+        while (!call) {
+            if (!start) {
+                const python = PYTHON_CALL.exec(buffer);
+                const found = [
+                    ...DELIMITERS.map((d) => ({ d, at: buffer.indexOf(d.start) })),
+                    ...(python ? [{ d: { start: python[0], end: ")]", python: true }, at: python.index }] : [])
+                ]
+                    .filter((f) => f.at !== -1)
+                    .sort((a, b) => a.at - b.at)[0];
+                if (!found) {
+                    const keep = partialFenceStart(buffer);
+                    shown += buffer.slice(0, buffer.length - keep);
+                    buffer = buffer.slice(buffer.length - keep);
+                    return shown;
+                }
+                shown += buffer.slice(0, found.at);
+                buffer = buffer.slice(found.at);
+                start = found.d;
+            }
+            const close = buffer.indexOf(start.end, start.start.length);
+            if (close === -1)
+                return shown;
+            const fence = buffer.slice(0, close + start.end.length);
+            const parsed = parseToolCall(start.python ? fence : fence.slice(start.start.length, close));
+            call = parsed && (!names || names.includes(parsed.name)) ? parsed : undefined;
+            buffer = buffer.slice(fence.length);
+            start = undefined;
+            if (call)
+                trailing = buffer;
+            else
+                shown += fence;
+        }
+        return shown;
+    };
+    return {
+        get call() {
+            return call;
+        },
+        /** Text that came after the call: shown after it. */
+        get trailing() {
+            return trailing;
+        },
+        push(piece) {
+            buffer += piece;
+            return read();
+        },
+        end() {
+            if (call)
+                return "";
+            const rest = buffer;
+            buffer = "";
+            return rest;
+        }
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The parts of the Prompt API (https://github.com/webmachinelearning/prompt-api)
+ * this package uses. TypeScript's DOM library has no types for it yet.
+ * Shapes follow the spec and `@types/dom-chromium-ai`, kept here instead of
+ * depending on that package: it declares `LanguageModel` as a global (in
+ * every app that uses this package). Tools are left out: Chrome's tool use
+ * doesn't work on web pages, so the adapter calls tools by prompt
+ * (`tools.ts`). Names follow the spec: `contextUsage`,
+ * `contextWindow` and `contextoverflow` (web pages no longer have the old
+ * `inputUsage`, `inputQuota` and `quotaoverflow`).
+ */
+export type Availability = "unavailable" | "downloadable" | "downloading" | "available";
+/** A download's progress, from 0 to 1. */
+export type DownloadProgressCallback = (progress: number) => void;
+/** Sampling presets, for web pages (the raw `temperature` and `topK` are for extensions). */
+export type SamplingMode = "most-predictable" | "predictable" | "slightly-predictable" | "balanced" | "slightly-creative" | "creative" | "most-creative";
+export type LanguageModelMessageType = "text" | "image" | "audio";
+export type LanguageModelExpected = {
+    type: LanguageModelMessageType;
+    languages?: Array<string>;
+};
+/**
+ * A piece of a message: text, an image (`Blob`, `ImageBitmap`, canvas...)
+ * or audio (`Blob`, `AudioBuffer`...).
+ */
+export type LanguageModelContent = {
+    type: LanguageModelMessageType;
+    value: unknown;
+};
+export type LanguageModelMessage = {
+    role: "system" | "user" | "assistant";
+    content: string | Array<LanguageModelContent>;
+};
+/** Options `availability()` takes, which `create()` takes too. */
+export type LanguageModelCoreOptions = {
+    expectedInputs?: Array<LanguageModelExpected>;
+    expectedOutputs?: Array<LanguageModelExpected>;
+    /** Web pages get it only with Chrome's Sampling Parameters origin trial. */
+    samplingMode?: SamplingMode;
+    /** Extensions only; web pages ignore them. Chrome refuses them together with `samplingMode`. */
+    temperature?: number;
+    topK?: number;
+};
+export type LanguageModelCreateOptions = LanguageModelCoreOptions & {
+    initialPrompts?: Array<LanguageModelMessage>;
+    /** Aborting it destroys the session, during `create()` or after. */
+    signal?: AbortSignal;
+    monitor?: (monitor: EventTarget) => void;
+};
+export type LanguageModelPromptOptions = {
+    signal?: AbortSignal;
+    /** A JSON Schema (or RegExp) the reply must match. */
+    responseConstraint?: object;
+    omitResponseConstraintInput?: boolean;
+};
+export type LanguageModelInput = string | Array<LanguageModelMessage>;
+export interface LanguageModelSession extends EventTarget {
+    /** Tokens the session holds. */
+    readonly contextUsage: number;
+    /** Tokens it can hold. */
+    readonly contextWindow: number;
+    /** The preset the session samples with; null when made with raw parameters. */
+    readonly samplingMode?: SamplingMode | null;
+    prompt(input: LanguageModelInput, options?: LanguageModelPromptOptions): Promise<string>;
+    /** The reply's text, in pieces as it's written. */
+    promptStreaming(input: LanguageModelInput, options?: LanguageModelPromptOptions): ReadableStream<string> & AsyncIterable<string>;
+    measureContextUsage(input: LanguageModelInput, options?: LanguageModelPromptOptions): Promise<number>;
+    destroy(): void;
+}
+export type LanguageModelStatic = {
+    availability(options?: LanguageModelCoreOptions): Promise<Availability>;
+    create(options?: LanguageModelCreateOptions): Promise<LanguageModelSession>;
+};
+/** The `downloadprogress` event: `loaded` goes from 0 to 1. */
+export type DownloadProgressEvent = Event & {
+    loaded: number;
+    total?: number;
+};
+/** The page's `LanguageModel`, or undefined where the browser has none. */
+export declare const languageModel: () => LanguageModelStatic | undefined;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * The parts of the Prompt API (https://github.com/webmachinelearning/prompt-api)
+ * this package uses. TypeScript's DOM library has no types for it yet.
+ * Shapes follow the spec and `@types/dom-chromium-ai`, kept here instead of
+ * depending on that package: it declares `LanguageModel` as a global (in
+ * every app that uses this package). Tools are left out: Chrome's tool use
+ * doesn't work on web pages, so the adapter calls tools by prompt
+ * (`tools.ts`). Names follow the spec: `contextUsage`,
+ * `contextWindow` and `contextoverflow` (web pages no longer have the old
+ * `inputUsage`, `inputQuota` and `quotaoverflow`).
+ */
+/** The page's `LanguageModel`, or undefined where the browser has none. */
+export const languageModel = () => globalThis.LanguageModel;

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@tanstack-ai-browser/prompt-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "TanStack AI adapter for the browser's built-in language model (the Prompt API: Gemini Nano in Chrome, Phi-4-mini in Edge)",
+  "license": "MIT",
+  "author": "daveycodez",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daveycodez/tanstack-ai-browser.git",
+    "directory": "packages/prompt-api"
+  },
+  "homepage": "https://github.com/daveycodez/tanstack-ai-browser/tree/main/packages/prompt-api#readme",
+  "bugs": "https://github.com/daveycodez/tanstack-ai-browser/issues",
+  "keywords": [
+    "tanstack-ai",
+    "tanstack",
+    "ai",
+    "llm",
+    "prompt-api",
+    "gemini-nano",
+    "phi-4-mini",
+    "built-in-ai",
+    "browser",
+    "on-device",
+    "local-ai"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@tanstack-ai-browser/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "nx": {
+    "name": "prompt-api"
+  },
+  "scripts": {
+    "test": "node --import @swc-node/register/esm-register --test \"src/**/*.test.ts\""
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "^1.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/ai": "1.4.0",
+    "esbuild": "0.28.2"
+  }
+}