frontend-agent 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +45 -77
  2. package/package.json +3 -2
package/README.md CHANGED
@@ -1,95 +1,63 @@
1
1
  # frontend-agent
2
2
 
3
- Drive the **LFM2.5-230M frontend-agent** model in the browser - a tiny, on-device web agent that
4
- calls real tools and answers grounded in retrieved context. Fully typed, framework-agnostic, loads
5
- the GGUF from Hugging Face via [wllama](https://github.com/ngxson/wllama) (no server-side inference).
3
+ [Demo - Github Pages](https://lajosbencz.github.io/frontend-agent/)
6
4
 
7
- The model is trained for **patterns, not facts**: you supply the tools and the grounding context at
8
- runtime, and the library reproduces the exact v1.0.0 model contract (system prompt, tool-call format,
9
- tool-result shapes, and a GBNF grammar that pins tool ids to real search results at decode time).
5
+ A generic English **web/front-end agent** built on [LiquidAI LFM2.5-230M](https://huggingface.co/LiquidAI/LFM2.5-230M), small enough to run
6
+ **entirely in the browser** (edge / local inference via [wllama](https://github.com/ngxson/wllama), no server-side model). It doesn't
7
+ just chat - it calls real tools to act on a page (search, navigate, cart operations) and answers
8
+ questions grounded in retrieved context.
10
9
 
11
- ## Install
10
+ **Trained for patterns, not lexical knowledge.** The weights hold *behaviors* - tool selection,
11
+ argument binding, reference tracking, RAG-grounded answering, clean refusal - not any specific
12
+ catalog or domain facts. Meaning and grounding are supplied **at runtime**: the host injects a
13
+ compact catalog hint and serves retrieval as a `search_*` tool, and the model grounds strictly in
14
+ what it is given. Swap the site, swap the injected context - the same model works, no retraining.
12
15
 
13
- ```bash
14
- npm i frontend-agent @wllama/wllama
15
- npm i minisearch stemmer # optional: the in-browser RAG adapter (./rag)
16
- ```
16
+ ## Repo map
17
17
 
18
- ## Quickstart
19
-
20
- ```ts
21
- import { createAgent, buildRegistry, WllamaEngine, buildSystemPrompt } from 'frontend-agent'
22
- import { referenceTools } from 'frontend-agent/reference'
23
- import { LocalMiniSearchRAG } from 'frontend-agent/rag'
24
-
25
- const rag = new LocalMiniSearchRAG({ catalog, knowledge }) // your indexed data
26
- const tools = referenceTools({
27
- rag,
28
- cart: myCartHandlers, // add/remove/view/clear over your own state
29
- navigate: (target, id) => router.push(pathFor(target, id)),
30
- })
31
- const registry = buildRegistry(tools) // schemas + handlers, what createAgent expects
32
-
33
- const engine = new WllamaEngine({
34
- // loads https://huggingface.co/lazos/lfm2.5-230m-frontend-agent/resolve/main/...-v1.0.0-Q6_K.gguf
35
- model: { repo: 'lazos/lfm2.5-230m-frontend-agent', version: 'v1.0.0', quant: 'Q6_K' },
36
- wllamaAssets, // wllama single/multi-thread WASM URLs
37
- onProgress: (p) => {},
38
- })
39
-
40
- const session = createAgent({
41
- engine,
42
- tools: registry,
43
- systemPrompt: () => buildSystemPrompt({ persona, catalogHint: () => rag.hint(6), toolSchemas: registry.schemas }),
44
- })
45
-
46
- session.on((e) => {
47
- if (e.type === 'assistant') console.log(e.text)
48
- })
49
-
50
- // one entry point - feed it from a text box, an API, or a speech-to-text transcript:
51
- await session.submit('do you have any espresso grinders?')
52
- session.abort() // cancel an in-flight turn
18
+ ```
19
+ frontend-agent/ npm workspaces root
20
+ ├─ packages/frontend-agent/ frontend-agent - the TS client library that drives the model
21
+ └─ demo/ Nuxt demo: three storefronts (BrewCraft/Emporium/Vendor) consuming it
53
22
  ```
54
23
 
55
- `submit(text)` is the whole input channel - the library is agnostic to where the text comes from.
56
- Wire your own source (typed box, an external API, or a speech-to-text engine like Whisper) and call
57
- `submit` with the resulting text. The demo shows a Whisper → `submit` voice path.
58
-
59
- ## Model source
24
+ **Client library** - [`frontend-agent`](packages/frontend-agent) is a fully-typed,
25
+ framework-agnostic TypeScript package for driving the model in any web app: `createAgent(...)` returns
26
+ a session with a single `submit(text)` feed point, tool-calling + GBNF id-grounding, a configurable
27
+ Hugging Face model source, and optional RAG adapters.
60
28
 
61
- `WllamaEngine`'s `model` resolves a Hugging Face GGUF by default:
62
- `https://huggingface.co/{repo}/resolve/main/{repo-basename}-{version}-{quant}.gguf`. Override any of
63
- `{ repo, version, quant }`, or pass `modelUrl` to self-host. Cross-origin loading under COOP/COEP
64
- requires the page to be cross-origin-isolated; the HF `resolve` CDN sends permissive CORS.
29
+ **Demo** - [`demo/`](demo) is the reference consumer: three storefronts sharing one on-device
30
+ assistant. See [`demo/README.md`](demo/README.md).
65
31
 
66
- ## Cross-origin isolation (multi-threading)
32
+ ## How it works
67
33
 
68
- wllama runs **multi-threaded** when the page is cross-origin isolated (`SharedArrayBuffer`), and
69
- **falls back to single-thread** otherwise - slower, but works with no action required. To enable
70
- threads, make the page cross-origin isolated by either:
34
+ - **RAG as a tool** - retrieval is a `search_*` tool the model calls; it grounds answers in the
35
+ results and refuses when they don't contain the answer. Backend-agnostic (BM25, vector, hybrid).
36
+ - **Tool-list randomization at training time** - tool names and argument keys were permuted per
37
+ training example, so the model reads the injected schema rather than memorizing a fixed toolset.
38
+ - **Held-out-domain eval** - the model was evaluated on verticals never seen in training; the demo's
39
+ BrewCraft domain is itself held out, proving the generalization thesis end to end.
71
40
 
72
- - serving it with `Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy:
73
- require-corp` (or `credentialless`) headers, or
74
- - on a static host that can't set headers (e.g. GitHub Pages), registering a COI service worker such
75
- as [`coi-serviceworker`](https://github.com/gzuidhof/coi-serviceworker) - the demo does this.
41
+ ## Quickstart
76
42
 
77
- The library deliberately **does not register a service worker** - an SW hijacks your whole origin's
78
- fetches and is a deployment concern you own. Note: under COEP `require-corp`, the cross-origin HF
79
- model load needs the response to send CORP or be fetched CORS/credentialless; `coi-serviceworker`'s
80
- **credentialless** mode handles this (so threads + the HF default compose on Pages).
43
+ ```bash
44
+ npm install
45
+ npm run build -w frontend-agent
46
+ npm run dev -w demo # http://localhost:3000
47
+ ```
81
48
 
82
- ## Exports
49
+ The assistant downloads its GGUF once from Hugging Face (cached in the browser via OPFS) on first
50
+ activation - no server-side inference.
83
51
 
84
- - `.` - core: `createAgent`, `buildRegistry`, `WllamaEngine`, `StubEngine`, `buildSystemPrompt`,
85
- `parseToolCalls`, `renderToolCalls`, `buildToolGrammar`, and all types.
86
- - `./reference` - `referenceTools({ rag, cart, navigate })`: the 7 canonical tools
87
- (search_catalog, search_knowledge, add/remove/view/clear cart, navigate) with trained result shapes.
88
- - `./rag` - `LocalMiniSearchRAG` (in-browser BM25) + `createRagClient` (bring-your-own `POST /search`).
52
+ ## Licensing
89
53
 
90
- Input is source-agnostic: `session.submit(text)` is the only feed point - connect a text box, an API,
91
- or a speech-to-text transcript. (The library ships no STT/TTS; the demo shows a Whisper voice path.)
54
+ - **Code & docs** - Apache-2.0 ([`LICENSE`](LICENSE)).
55
+ - **Model weights** - a derivative of `LiquidAI/LFM2.5-230M`, so they inherit the **LFM Open License
56
+ v1.0** (permissive, with a commercial-revenue cap; attribution to LiquidAI required). Cannot be
57
+ relicensed.
92
58
 
93
- ## License
59
+ ## Authoring
94
60
 
95
- Apache-2.0. The model weights it drives are under the LFM Open License v1.0 (see the model repo).
61
+ This repository was substantially authored with the following models, under human direction and review:
62
+ - Qwen3 Coder 30B A3B Q4_K_M (local Ollama)
63
+ - Claude Opus 4.8 (Anthropic)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "frontend-agent",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Drive the LFM2.5-230M frontend-agent model in the browser: tool-calling + RAG-grounded answering, fully typed. Loads the GGUF from Hugging Face via wllama.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",
@@ -46,7 +46,8 @@
46
46
  "scripts": {
47
47
  "build": "tsup",
48
48
  "typecheck": "tsc --noEmit",
49
- "test": "vitest run"
49
+ "test": "vitest run",
50
+ "prepack": "cp ../../README.md ./README.md"
50
51
  },
51
52
  "peerDependencies": {
52
53
  "@wllama/wllama": ">=3.5.0",