@degreesign/chat 0.6.2 → 0.7.1

package/README.md

@@ -40,8 +40,6 @@ package loads one model, streams one reply and reports status.
   capped by the prompt budgets.
 - Audio: a user turn can carry an audio URL, sent only to a model with audio
   support and capped by the prompt budgets.
-- Tools: the model may call Web search, arithmetic and currency built-ins, plus
-  any tool the host supplies, in the same reply.
 - Reusable: the loaded model stays in memory for the next call.
 - Typed: written in TypeScript with declarations for every export.
 - Portable: importing and calling works in browsers, workers, React and Node.
@@ -61,11 +59,11 @@ yarn add @degreesign/chat
 pnpm add @degreesign/chat
 ```
 
-`@wllama/wllama`, `@wllama/wllama-compat`, `@litert-lm/core` and
-`@degreesign/utils` are build-time dependencies. The engines are bundled into
-the published build as dynamic chunks and their wasm assets ship beside them,
-so a consumer installs nothing extra and resolves no engine import. Only the
-model weights are downloaded at runtime.
+`@wllama/wllama`, `@wllama/wllama-compat` and `@litert-lm/core` are build-time
+dependencies. The engines are bundled into the published build as dynamic
+chunks and their wasm assets ship beside them, so a consumer installs nothing
+extra and resolves no engine import. Only the model weights are downloaded at
+runtime.
 
 The build emits:
 
@@ -128,30 +126,33 @@ only to a model with vision support, center-crops each image to a square,
 resizes it to 288 x 288, and caps the number with `limits.maxImages`. The
 WebGPU engine asks LiteRT for the smallest Gemma 4 vision budget (70 tokens,
 630 patches), so it encodes the crop at 384 x 384 instead of upscaling it to
-768 x 768. The CPU engine uses the 288 crop directly. On a phone or tablet,
-Gemma runs the text-only browser build, so images there go through
-`qwen3_vl_2b` instead.
+768 x 768. The CPU engine uses the 288 crop directly. On a phone or tablet a
+Gemma request resolves to `gemma4_e2b_limited`, the text-only browser build, so
+images there go through `qwen3_vl_2b` instead.
 
 Attach a recording with `audio: [dataUrl]`. Gemma 4 E2B accepts WAV, MP3 and
 FLAC on the desktop WebGPU engine and loads its audio encoder on demand. A short
 16 kHz mono WAV is the best input. `limits.maxAudio` caps the clips (default 1).
 A model without audio drops the clip when the turn also has text; an audio-only
-turn reports `Model does not accept audio`. The phone build is text only, so
-audio follows the same rule as images there. The package does not transcode, so
-the host supplies one of those formats.
+turn reports `Model does not accept audio`. On a phone or tablet
+`gemma4_e2b_limited` is text only, so audio follows the same rule as images
+there. The package does not transcode, so the host supplies one of those
+formats.
 
 The package never writes storage, so the host appends the user message before
 the call and appends the assistant message after the last `onResponse`.
 
 ## Enable WebGPU
 
-A request without `model` picks `gemma4_e2b` when the browser exposes a WebGPU
-adapter and `qwen3_vl_2b` when it does not. A phone or tablet asking for Gemma
-gets `gemma-4-E2B-it-gpu.litertlm`, the 2.0 GB browser build, which is text
-only. A desktop gets the 2.6 GB multimodal build with vision and audio. Hosts
-that need images on mobile pass `qwen3_vl_2b`; audio is desktop only. The GPU
-engine is far faster on a desktop, so check the browser before blaming the
-package:
+A request without `model` picks Gemma when the browser exposes a WebGPU adapter
+and `qwen3_vl_2b` when it does not. A phone or tablet asking for Gemma gets
+`gemma4_e2b_limited`, the 2.0 GB text-only browser build
+(`gemma-4-E2B-it-gpu.litertlm`); a desktop gets `gemma4_e2b`, the 2.6 GB
+multimodal build with vision and audio. Once a model is requested or resolved,
+every status snapshot reports the build that runs in `model`, so a host that
+asks for `gemma4_e2b` on a phone reads `gemma4-e2b-limited` back. Hosts that
+need images on mobile pass `qwen3_vl_2b`; audio is desktop only. The GPU engine
+is far faster on a desktop, so check the browser before blaming the package:
 
 ```js
 // Run in the console of the page that loads the package
@@ -215,8 +216,8 @@ budget, 70 tokens and 630 patches, so the encoder runs one small signature and
 the crop is resized to 384 x 384 rather than the full 768 x 768. If the error
 still appears, close other GPU tabs, unload the model, or switch to the CPU
 model. A lost device needs a page or model reload; later calls cannot reuse it.
-A phone or tablet uses the text-only browser build, so it never starts the
-vision or audio encoder.
+A phone or tablet resolves Gemma to the text-only browser build, so it never
+starts the vision or audio encoder.
 
 ## Public API
 
@@ -241,12 +242,6 @@ requested model is already loaded, no download or load happens.
 | `onResponse` | Receives the accumulated reply text as it streams. Required. |
 | `onSpeed?` | Receives the current generation speed in tokens per second. |
 | `onStatus?` | Receives a `ChatStatusSnapshot` on every state change. |
-| `builtins?` | Built-in tools to attach, all three by default; `false` attaches none. |
-| `websearch?` | `WebSearchConfig` for the built-in search, provider, language and limits. |
-| `tools?` | Extra `ChatTool` entries, appended after the built-ins. |
-| `onToolCall?` | Receives a `ChatToolCall` before a tool runs. |
-| `onToolResult?` | Receives a `ChatToolResult` when a tool returns or throws. |
-| `maxToolRounds?` | Ceiling on tool rounds in one reply, default 4, clamped 1 to 25. |
 
 Without `model` the package picks the GPU build when the browser provides a
 WebGPU adapter and the CPU build when it does not. The budget defaults are 250
@@ -294,143 +289,33 @@ on failure. A preload owns no cancel function; a new load replaces it.
 
 ## Tools
 
-Gemma 4 E2B on the WebGPU engine can call tools. A reply may contain a tool
-call, the package runs it, feeds the result back and lets the model answer, all
-inside the one `createChat` call. Qwen3-VL 2B and the CPU engine never receive
-tools: `ChatStatusSnapshot.supportsTools` reports `false` there, the built-ins
-are dropped and a host tool ends the call with `Model does not accept tools`.
-
-Three built-ins ship and all three attach by default:
-
-| `BuiltinTool` | What it does |
-| ------------- | ------------ |
-| `websearch` | Searches Wikipedia by default, or DuckDuckGo, and returns a few hits. |
-| `calculate` | Evaluates an arithmetic expression with a safe parser. |
-| `currency` | Quotes and converts fiat, crypto and metals with the 24-hour change. |
+Three built-in tools ship as descriptors. They are not connected to the model:
+the package never declares a tool to an engine and never runs one by itself.
 
 ```ts
-import { BuiltinTool, WebSearchProvider, createChat } from "@degreesign/chat";
+import { builtinTools, BuiltinTool } from '@degreesign/chat';
 
-const cancel = createChat({
-  messages,
-  // all three by default; narrow or disable them here
-  builtins: [BuiltinTool.calculate, BuiltinTool.currency],
-  websearch: { provider: WebSearchProvider.wikipedia, language: "en", limit: 3 },
-  onToolCall: (call) => renderToolStart(call),
-  onToolResult: (result) => renderToolEnd(result),
-  onResponse: (text) => renderReply(text),
-});
+const [calculation] = builtinTools([BuiltinTool.calculate]);
+const answer = await calculation.execute({ expression: `6*7` });
 ```
 
-`builtins: false` disables every built-in. A tool is only offered to the model
-when the model accepts tools, so the default set costs nothing on the CPU
-engine.
-
-### Custom tools
-
-`ChatInput.tools` is the extension point, with no registration and no global
-state. Each mention is appended after the built-ins and offered in the same
-conversation.
+| Export | Description |
+| ------ | ----------- |
+| `builtinTools(names, config?)` | Returns the requested tools in the order given. |
+| `calculateTool` | Evaluates an arithmetic expression, fully local. |
+| `currencyTool` | Converts between fiat, metals and coins through the CoinExams feed. |
+| `webSearchTool(config?)` | Searches Wikipedia by default, or DuckDuckGo. |
+| `BuiltinTool` | `websearch`, `calculate` or `currency`. |
+| `WebSearchProvider` | `wikipedia` or `duckduckgo`. |
 
-```ts
-import { createChat } from "@degreesign/chat";
-
-const cancel = createChat({
-  messages,
-  tools: [
-    {
-      name: "lookup_order",
-      description: "Read one order from the shop.",
-      parameters: {
-        type: "object",
-        properties: {
-          id: { type: "string", description: "Order id" },
-        },
-        required: ["id"],
-      },
-      execute: async ({ id }) => await shop.order(String(id)),
-    },
-  ],
-  onToolCall: (call) => renderToolStart(call),
-  onToolResult: (result) => renderToolEnd(result),
-  onResponse: (text) => renderReply(text),
-});
-```
+Each tool has `name`, `description`, `parameters` (`ChatToolSchema`) and
+`execute(args)`, which returns a JSON-safe `ChatToolValue` or throws. `ChatTool`
+is that whole shape, and `ChatToolCall` / `ChatToolResult` describe a call and
+its outcome for a host that records them.
 
-- `name` is required and unique. A host tool named `websearch`, `calculate` or
-  `currency` replaces that built-in.
-- `description` and `parameters` reach the model as written.
-- `execute` receives the parsed arguments and may return a value or a promise.
-  A thrown error becomes a tool error the model reads, and `onToolResult`
-  receives `error`.
-- Tools and callbacks are captured when the conversation is created. Rebuilding
-  the array with the same functions and declarations reuses the conversation;
-  changing a declaration or a function opens a new one and pays one history
-  prefill.
-- The package cannot abort a running `execute`. A cancel stops generation and
-  discards its result.
-- The package neither clamps nor times out a host result. Keep it small: three
-  declarations already cost roughly 200 to 250 of the 4096 context tokens.
-
-### Search
-
-`websearch` sends one query and returns a short list of `title`, `url` and
-`snippet`.
-
-| `WebSearchConfig` | Default | Meaning |
-| ----------------- | ------- | ------- |
-| `provider` | Wikipedia | `WebSearchProvider.wikipedia` or `.duckduckgo`. |
-| `language` | `en` | Wikipedia edition, two or three letters plus an optional region. |
-| `limit` | 3 | Hits asked of the provider, clamped 1 to 20. |
-| `snippetLength` | 400 | Characters kept per snippet. |
-| `timeout` | 8000 | Request budget in milliseconds. |
-
-Wikipedia is the default because its REST search has CORS `*`, no key and a
-predictable result shape. DuckDuckGo returns an instant answer and related
-topics, and many queries have neither, so it can return an empty list. Both
-endpoints are public and keyless.
-
-### Calculator
-
-`calculate` accepts `+`, `-`, `*`, `/`, `%`, `^` and parentheses, and returns
-`{ expression, result }`.
-
-- `×`, `÷` and `−` are normalized, and thousands commas and spaces are removed.
-- No implicit multiplication: write `2*(3+4)`.
-- No functions: use `^0.5` for a square root.
-- `%` is a postfix division by 100, so `200*15%` is 30 and `200+10%` is 200.1.
-- Unbalanced parentheses, division by zero, an unknown character, an expression
-  over 200 characters and a non-finite result are errors.
-- The parser is hand written. The package never uses `eval` or `new Function`.
-
-### Currency
-
-`currency` reads one public price file published by [CoinExams](https://coinexams.com)
-and answers from it.
-
-- Every rate is quoted against `EUR`, which is always 1.
-- Fiat and metals come from the fiat section. Crypto comes from the coin
-  section, which wins when a symbol appears in both.
-- Metals are `XAU`, `XAG`, `XPT` and `XPD`, quoted per gram. A zero or missing
-  quote is unavailable.
-- Arguments are `from` (required), `to` (default `EUR`) and `amount` (default 1).
-- A result carries `from`, `to`, `amount`, `rate`, `result`, `updatedAt` and
-  `stale`, plus `previousRate`, `change` and `changePercent` when the feed has a
-  24-hour value for both symbols.
-
-The feed is cached on the device under `degreesign-chat-prices-v1` in
-`localStorage`. Fiat and metals refresh at most hourly, crypto at most every
-five minutes, and concurrent calls share one fetch. A failed refresh keeps the
-previous snapshot, serves it with `stale: true` and waits 30 seconds before the
-next attempt. `navigator.onLine === false` skips the fetch and serves the cache.
-With no cache and no network the tool reports `Prices unavailable offline`.
-
-### Privacy
-
-Search sends the model's query to the chosen provider, and currency fetches the
-public price file. Nothing else leaves the device, and no key is sent. To keep a
-call fully local, pass `builtins: [BuiltinTool.calculate]`, which computes on
-device.
+`webSearchTool` takes `WebSearchConfig`: `provider`, a Wikipedia `language`
+edition, `limit` results, `snippetLength` and a `timeout` in milliseconds. The
+search and currency tools fetch over the network; `calculate` does not.
 
 ## Status
 
@@ -438,12 +323,12 @@ device.
 
 | Field | Description |
 | ----- | ----------- |
+| `model?` | The build that runs after the mobile swap. |
 | `availability` | `ChatStatus.online`, `.away` or `.offline`, derived from `status`. |
 | `status` | `LlmStatus`: `idle`, `downloading`, `ready`, `error` or `unsupported`. |
 | `backend` | `LlmBackend.cpu`, `.gpu` or `.none`. |
-| `supportsImages` | Whether the requested model accepts images. |
-| `supportsAudio` | Whether the requested model accepts audio. |
-| `supportsTools` | Whether the requested model accepts tool declarations. |
+| `supportsImages` | Whether the model accepts images on this device. |
+| `supportsAudio` | Whether the model accepts audio on this device. |
 | `ready` | Whether a model is loaded and accepts a reply. |
 | `loading` | Whether a download or load is in flight. |
 | `requesting` | Whether a reply is streaming right now. |
@@ -458,12 +343,6 @@ A stream that never produces its first chunk ends with an error after 180
 seconds instead of waiting forever. Once a chunk has arrived, 30 seconds of
 silence ends the stream and keeps the text already delivered.
 
-A lost WebGPU device is rebuilt once: the package drops the dead engine and its
-device, reloads the LiteRT wasm, retries the turn on the next smaller context
-window (4096, 2048, 1024) and reports the reply normally. When no rebuild is
-possible the runtime ends as `error` with `backend: none`, so the host can fall
-back to the CPU model.
-
 ## Logging
 
 Console output stays off by default. Pass `logging: true` in a call to receive
@@ -473,15 +352,18 @@ without it goes quiet again.
 
 ## Models
 
-| `ChatModelId` | Name | Reasoning | Images | Audio | Tools | CPU | WebGPU |
-| ------------- | ---- | --------- | ------ | ----- | ----- | --- | ------ |
-| `qwen3_vl_2b` | Qwen3-VL 2B | Yes | Yes | No | No | Yes | No |
-| `gemma4_e2b` | Gemma 4 E2B | Yes | Desktop | Desktop | Yes | No | Yes |
+| `ChatModelId` | Name | Reasoning | Images | Audio | CPU | WebGPU |
+| ------------- | ---- | --------- | ------ | ----- | --- | ------ |
+| `qwen3_vl_2b` | Qwen3-VL 2B | Yes | Yes | No | Yes | No |
+| `gemma4_e2b` | Gemma 4 E2B | Yes | Yes | Yes | No | Yes |
+| `gemma4_e2b_limited` | Gemma 4 E2B limited | Yes | No | No | No | Mobile |
 
-A phone or tablet asking for Gemma gets the browser build,
-`gemma-4-E2B-it-gpu.litertlm`, which is text only. It has no vision or audio
-encoder, so `supportsImages` and `supportsAudio` report `false` there. Use
-`qwen3_vl_2b` for images on mobile.
+A phone or tablet asking for any Gemma id gets `gemma4_e2b_limited`,
+`gemma-4-E2B-it-gpu.litertlm`, which is text only. A desktop asking for the
+limited id gets the full `gemma4_e2b` build instead. The build that actually
+runs is always the one in `ChatStatusSnapshot.model`. The limited build has no
+vision or audio encoder, so `supportsImages` and `supportsAudio` report `false`
+there. Use `qwen3_vl_2b` for images on mobile.
 
 The first call downloads the model before its engine loads it. Later calls
 reuse the loaded runtime. Only one model stays in memory. An interrupted
@@ -496,7 +378,7 @@ Gemma 4 WebGPU path. Use the GPU model when images need to be fast.
 
 Gemma 4 E2B downloads `gemma-4-E2B-it.litertlm`, about 2.6 GB, on a desktop. It
 runs on the WebGPU engine with its vision and audio encoders in the same file,
-so an image or audio prompt does not download a projector. A phone or tablet
+so an image or audio prompt does not download a projector. `gemma4_e2b_limited`
 instead downloads the 2.0 GB `gemma-4-E2B-it-gpu.litertlm`, the precompiled
 GPU_ARTISAN build Google ships for browsers. The smaller file is what keeps a
 mobile tab alive at the end of the model load.
@@ -684,16 +566,9 @@ const useReply = () => {
 | `ChatStatusSnapshot` | Availability, engine status, backend, progress and request state. |
 | `LlmLimits` | Token, prompt, image, audio and thread budgets, all overridable. |
 | `WllamaAssets` | Wasm, compat wasm and compat worker URLs. |
-| `ChatTool` | One tool: `name`, `description`, `parameters` and `execute`. |
-| `ChatToolSchema` | The JSON-schema subset a tool parameter declares. |
-| `ChatToolValue` | A JSON-safe argument or result value. |
-| `ChatToolCall` | One model call: `id`, `name` and parsed `arguments`. |
-| `ChatToolResult` | A finished call, with `result` or `error`. |
-| `WebSearchConfig` | Provider, language, limit, snippet length and timeout. |
-| `WebSearchResult` | One hit: `title`, `url` and `snippet`. |
 
 The public enums are `ChatModelId`, `LlmRole`, `ChatStatus`, `LlmStatus`,
-`LlmBackend`, `LlmPhase`, `BuiltinTool` and `WebSearchProvider`.
+`LlmBackend` and `LlmPhase`.
 
 ## Architecture
 
@@ -717,22 +592,23 @@ No. The host passes the full prompt on every call and keeps the reply.
 
 Yes, on models with vision support. Put image URLs in a user turn's `images`
 array. Qwen3-VL 2B accepts images on the CPU engine and Gemma 4 E2B accepts
-images on the desktop WebGPU engine. On a phone or tablet Gemma runs the
-text-only browser build, so use `qwen3_vl_2b` for mobile images. Each image is
-center-cropped to a square and resized to 288 x 288 before the engine sees it.
-The WebGPU engine encodes that crop at 384 x 384 with the smallest Gemma 4
-vision budget. A model without vision drops images when the turn also has text;
-an image-only turn reports `Model does not accept images`.
+images on the desktop WebGPU engine. On a phone or tablet Gemma resolves to
+`gemma4_e2b_limited`, the text-only browser build, so use `qwen3_vl_2b` for
+mobile images. Each image is center-cropped to a square and resized to 288 x 288
+before the engine sees it. The WebGPU engine encodes that crop at 384 x 384
+with the smallest Gemma 4 vision budget. A model without vision drops images
+when the turn also has text; an image-only turn reports
+`Model does not accept images`.
 
 ### Does it support audio?
 
 Yes, on models with audio support. Put an audio URL in a user turn's `audio`
 array. Gemma 4 E2B accepts WAV, MP3 and FLAC on the desktop WebGPU engine, and a
 short 16 kHz mono WAV is the best input. `limits.maxAudio` caps the clips
-(default 1). Audio is desktop only; the mobile browser build has no audio
-encoder. The package does not transcode, so the host supplies one of those
-formats. A model without audio drops the clip when the turn also has text; an
-audio-only turn reports `Model does not accept audio`.
+(default 1). Audio is desktop only; `gemma4_e2b_limited` has no audio encoder.
+The package does not transcode, so the host supplies one of those formats. A
+model without audio drops the clip when the turn also has text; an audio-only
+turn reports `Model does not accept audio`.
 
 ### Does it need a server?
 
@@ -741,11 +617,10 @@ includes no server component.
 
 ### Does it have runtime dependencies?
 
-No runtime dependencies. `@wllama/wllama`, `@wllama/wllama-compat`,
-`@litert-lm/core` and `@degreesign/utils` are build-time dependencies, bundled
-into the dynamic engine chunks, the chat bundle and their wasm assets, so
-consumers resolve no engine import and download no engine code beyond the chunk
-they use.
+No runtime dependencies. `@wllama/wllama`, `@wllama/wllama-compat` and
+`@litert-lm/core` are build-time dependencies, bundled into the dynamic engine
+chunks and their wasm assets, so consumers resolve no engine import and
+download no engine code beyond the chunk they use.
 
 ### Where are the models stored?
 
@@ -760,7 +635,7 @@ Qwen3-VL 2B supports reasoning and images on the CPU. Gemma 4 E2B supports
 reasoning, images and audio on desktop WebGPU, with much faster media prompts
 but a larger download and a slower first compile. Use Qwen for broad browser
 support and for mobile images. Use Gemma on a desktop with Chromium WebGPU, or
-on a phone for text with the smaller browser build.
+on a phone for text, where it resolves to `gemma4_e2b_limited`.
 
 ## Licensing