@matatbread/matbot-provider-webllm 0.0.0-stage → 0.5.0
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.
- package/LICENSE +201 -0
- package/README.md +205 -2
- package/package.json +48 -3
- package/src/adapter.ts +316 -0
- package/src/format.ts +434 -0
- package/src/index.ts +13 -0
- package/src/models.ts +138 -0
- package/src/webllm.ts +204 -0
- package/src/window.ts +161 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 Mat Woolf
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
package/README.md
CHANGED
|
@@ -1,3 +1,206 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @matatbread/matbot-provider-webllm
|
|
2
2
|
|
|
3
|
-
This
|
|
3
|
+
This is a [matbot](https://github.com/MatAtBread/matbot) plugin.
|
|
4
|
+
|
|
5
|
+
**Prototype.** A provider adapter that runs open-weight models in the page, on the GPU, through
|
|
6
|
+
[WebLLM](https://github.com/mlc-ai/web-llm). It needs no endpoint and no key, and makes no network calls
|
|
7
|
+
once the model is cached. It is browser-only and needs WebGPU.
|
|
8
|
+
|
|
9
|
+
The library is not a dependency. It is imported from a CDN (WebLLM 0.2.85, pinned) the first time this
|
|
10
|
+
provider is used, so an install that never picks it pays nothing. It runs in a module worker, so the page
|
|
11
|
+
stays responsive while the model works.
|
|
12
|
+
|
|
13
|
+
The browser bundle's setup wizard offers it as a self-contained adapter with `Qwen3-4B-q4f16_1-MLC`.
|
|
14
|
+
Configured by hand:
|
|
15
|
+
|
|
16
|
+
```json
|
|
17
|
+
"providers": {
|
|
18
|
+
"qwen": { "module": "@matatbread/matbot-provider-webllm", "model": "Qwen3-4B-q4f16_1-MLC" }
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
`model` is any WebLLM prebuilt model id, e.g. `Qwen3-8B-q4f16_1-MLC` (~5.7 GB of GPU memory) or
|
|
23
|
+
`Qwen3-1.7B-q4f16_1-MLC` (~2 GB). Only one model is kept loaded. A different one replaces it once no call is
|
|
24
|
+
still using the old one.
|
|
25
|
+
|
|
26
|
+
The id is checked before anything downloads:
|
|
27
|
+
- an id WebLLM does not know is refused, naming the closest ones;
|
|
28
|
+
- a model not trained on this adapter's tool format is refused while tools are offered (see below);
|
|
29
|
+
- a `q4f16` build on a GPU without the `shader-f16` feature is refused, naming its `q4f32` build.
|
|
30
|
+
|
|
31
|
+
### Which models can call tools
|
|
32
|
+
|
|
33
|
+
WebLLM records nothing about this. Its `functionCallingModelIds` concerns its own `tools` path, which this
|
|
34
|
+
adapter does not use. What matters here is whether a family was trained on the Hermes
|
|
35
|
+
`<tool_call>{"name": …, "arguments": …}` format, as read off each family's published chat template. The
|
|
36
|
+
constraint can force a valid call only once a model writes `<tool_call>`, and one never trained on it rarely
|
|
37
|
+
does.
|
|
38
|
+
|
|
39
|
+
| Family | Tool calls here | Why |
|
|
40
|
+
|---|---|---|
|
|
41
|
+
| Qwen3, Qwen2.5, Qwen2.5-Coder | yes | Hermes-style JSON in the template |
|
|
42
|
+
| Hermes-2-Pro, Hermes-2-Theta, Hermes-3 | yes | the format's origin; documented on the model cards |
|
|
43
|
+
| Qwen3.5 | no | calls tools in XML (`<function=…><parameter=…>`); supportable later via WebLLM's `qwen_xml_parameter` tag |
|
|
44
|
+
| Qwen2.5-Math | no | shares Qwen2.5's template, but is a maths specialist |
|
|
45
|
+
| Llama 3.x, Mistral, Ministral | no | formats of their own |
|
|
46
|
+
| Qwen2, DeepSeek-R1 distills, Phi, Gemma, SmolLM2, others | no | no tool format |
|
|
47
|
+
|
|
48
|
+
That is 39 of WebLLM 0.2.85's models. With tools offered, any other is refused, naming the closest one that
|
|
49
|
+
qualifies. With `parameters.tools: false`, any chat model may be used for plain conversation.
|
|
50
|
+
|
|
51
|
+
A refused request leaves the loaded model alone.
|
|
52
|
+
|
|
53
|
+
## `webllm_models`
|
|
54
|
+
|
|
55
|
+
The plugin also registers a tool for choosing among models:
|
|
56
|
+
|
|
57
|
+
- **`list`** describes the models the library can run that can call tools (above), smallest first. Detail costs context, and a small
|
|
58
|
+
model's window is the scarcest thing here: a full row for each would cost far more than the ids. So:
|
|
59
|
+
- **`matched`**: full rows, only for the models a call selects. A row gives the id, the GPU memory needed
|
|
60
|
+
(`vramMB`), whether this GPU has the features it needs (`runsHere`), and whether it is `downloaded` or
|
|
61
|
+
`loaded`. A call selects with `query` (words that all appear in the id, e.g. `"qwen3 4b"`) and/or
|
|
62
|
+
`downloaded: true`.
|
|
63
|
+
- **`others`**: just the ids (about 400 tokens for all 39), given when the call selects nothing,
|
|
64
|
+
or when its selection matches nothing. A model that searched for something that is not in any id
|
|
65
|
+
(`"webllm"`) gets the ids it can search, not an empty list.
|
|
66
|
+
- **`hint`**: says which of these happened and how to narrow.
|
|
67
|
+
- **`delete`** removes a downloaded model from this origin's cache to free its storage.
|
|
68
|
+
|
|
69
|
+
To switch a profile, pass a listed id to the `provider` tool's `update`.
|
|
70
|
+
|
|
71
|
+
The list is WebLLM's own (`prebuiltAppConfig`), not a directory on Hugging Face. Hugging Face's `mlc-ai`
|
|
72
|
+
organisation has far more converted weights (Qwen3 14B and 32B among them), but a model also needs a model
|
|
73
|
+
library compiled for WebLLM's version, and only the listed ones have one. The tool reads through the
|
|
74
|
+
library and cache the provider last used, so it sees the same models and downloads.
|
|
75
|
+
|
|
76
|
+
The tool is registered when the plugin loads. matbot loads a provider's module on its first use, so the
|
|
77
|
+
tool appears once a WebLLM profile has answered once, or straight away if the plugin is loaded explicitly.
|
|
78
|
+
|
|
79
|
+
## Parameters
|
|
80
|
+
|
|
81
|
+
| key | meaning |
|
|
82
|
+
|---|---|
|
|
83
|
+
| `contextWindow` | Tokens. Default 8192. WebLLM's own default for Qwen3 is 4096, which matbot's system context and tool list can fill alone. A larger window costs GPU memory. |
|
|
84
|
+
| `thinking` | `true` lets Qwen3 reason before answering, streamed as `thinking`. Off by default, because on a laptop GPU it is most of the wait. |
|
|
85
|
+
| `tools` | `false` offers no tools. |
|
|
86
|
+
| `lenientCalls` | `false` stops a call written without its `<tool_call>` tags from being read as a call (see below). On by default. |
|
|
87
|
+
| `cache` | Where weights are kept: `cache`, `indexeddb`, `opfs` or `cross-origin`. Defaults to `indexeddb` for a page opened from `file://`, where Cache Storage is unavailable, and to WebLLM's default otherwise. |
|
|
88
|
+
| `library` | Another WebLLM build to import, as an ES module URL. |
|
|
89
|
+
| `maxTokens`, `temperature`, `topP`, `stopSequences` | Passed through. |
|
|
90
|
+
|
|
91
|
+
## Tool calls
|
|
92
|
+
|
|
93
|
+
WebLLM's own `tools` support is not used. It is hard-wired to two 2024 Hermes models. It refuses a system
|
|
94
|
+
message of the caller's, so matbot's system context could not be sent. And it forces every reply to be a
|
|
95
|
+
JSON array of calls, so the model can never simply answer.
|
|
96
|
+
|
|
97
|
+
Instead the adapter does what the models are trained on. Tools are described in the system prompt in Qwen's
|
|
98
|
+
format (`<tools>…</tools>`), and the model calls one with `<tool_call>{"name": …, "arguments": …}</tool_call>`.
|
|
99
|
+
A WebLLM *structural tag* constrains everything after `<tool_call>`:
|
|
100
|
+
|
|
101
|
+
- each tool's opening text includes its name, so only an existing tool can be called;
|
|
102
|
+
- its arguments must satisfy that tool's `inputSchema`.
|
|
103
|
+
|
|
104
|
+
Text outside a call is unconstrained, so the model still writes prose. The constraint enforces shape (keys,
|
|
105
|
+
types, enums, required fields), not the content of a free string. It is reliable on models trained on this
|
|
106
|
+
format: Qwen and Hermes.
|
|
107
|
+
|
|
108
|
+
The constraint only ever applies *after* the literal `<tool_call>`, so the tags themselves have to come from
|
|
109
|
+
the model — and on small models they often do not. Measured on `Qwen3-1.7B-q4f16_1-MLC`, asked what tools it
|
|
110
|
+
had, the whole reply was:
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
<think>
|
|
114
|
+
|
|
115
|
+
</think>
|
|
116
|
+
|
|
117
|
+
{"name": "tool_search", "arguments": {"query": "List the tools I have"}}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
A complete, well-formed call with the two tags its prompt showed it missing. The grammar never fired, and the
|
|
121
|
+
call arrived as JSON in a text bubble. So a reply is read for what it means, not only for what it was told to
|
|
122
|
+
write:
|
|
123
|
+
|
|
124
|
+
- **A call with no `<tool_call>` around it** is read as a call: `{"name": …, "arguments": …}`, or a `[…]` of
|
|
125
|
+
them. It must name its `arguments`, which is what separates a call from a JSON example in prose. Any prose
|
|
126
|
+
in front of it is kept, and is emitted first. `parameters.lenientCalls: false` turns this off for a model
|
|
127
|
+
found to write JSON examples as prose — though an example is a shape, not a call, and is ignored either way.
|
|
128
|
+
- **A call ends reasoning.** Qwen3 opens `<think>` and, when it decides to call, may write the call without
|
|
129
|
+
closing the block; vLLM's own Qwen3 parser treats `<tool_call>` as the implicit end of reasoning for that
|
|
130
|
+
reason. Without it the whole call arrives as `thinking` — invisible when `thinking` is off.
|
|
131
|
+
- **A call that will not parse is not called.** It is shown as the model wrote it, as the reply's text. An
|
|
132
|
+
unreadable call has no arguments, and running the tool with `{}` instead turns a formatting slip into a real
|
|
133
|
+
side effect — a tool that ran on nothing and returned its own error or a dump of its defaults, which then
|
|
134
|
+
reads as the model's answer. The model also meets its own attempt in history, and can correct it.
|
|
135
|
+
- **A call the reply ended inside** (cut off by `maxTokens`) is reported as a `truncated` tool call, which
|
|
136
|
+
matbot answers with an error result rather than executing. If the JSON had already closed and only
|
|
137
|
+
`</tool_call>` was cut, it is an ordinary call: the arguments are whole.
|
|
138
|
+
- **`arguments` as a JSON string** (`"arguments": "{"query": "x"}"`) is normalised to the object the tool
|
|
139
|
+
declared. Qwen's own template accepts both, and the small builds use either. A trailing comma before a
|
|
140
|
+
closing bracket is repaired — but only for a body that does not already parse, so an argument value that
|
|
141
|
+
legitimately contains `,}` is never rewritten.
|
|
142
|
+
|
|
143
|
+
History is rendered the way Qwen's chat template renders it: calls as `<tool_call>` blocks after the
|
|
144
|
+
assistant's text, results as `<tool_response>` blocks in a user turn. Rendering is deterministic, so WebLLM
|
|
145
|
+
can reuse its prefill whenever a request extends the previous conversation exactly. A tool round or a new
|
|
146
|
+
turn then prefills only what is new.
|
|
147
|
+
|
|
148
|
+
## Long conversations
|
|
149
|
+
|
|
150
|
+
The model's context window (8192 tokens by default) is much smaller than a remote provider's. A session
|
|
151
|
+
moved here from Claude or GPT would otherwise fail with WebLLM's `ContextWindowSizeExceededError`. A single
|
|
152
|
+
large tool result does the same: it fills most of the window, and the next turn has room for little else.
|
|
153
|
+
So when a conversation does not fit, two things happen, cheapest loss first:
|
|
154
|
+
|
|
155
|
+
1. **Large tool results in earlier turns are shortened.** A result over 800 characters keeps its first 400,
|
|
156
|
+
plus a note of how much was left out and that calling the tool again shows the whole of it. That is the
|
|
157
|
+
bulk the model has already read and answered from. Who asked what, and what was decided, survives. The
|
|
158
|
+
current turn is never shortened: its latest result may be what the model is answering from.
|
|
159
|
+
2. **The oldest turns are left out** only if that is not enough.
|
|
160
|
+
|
|
161
|
+
Either way:
|
|
162
|
+
|
|
163
|
+
- **The session is unchanged.** Switching back to a large-window provider sends everything again.
|
|
164
|
+
- **Whole turns only.** A turn is a user message and everything after it, so a tool call is never parted
|
|
165
|
+
from its result. The current turn is always kept.
|
|
166
|
+
- **Room for the reply.** The budget is the window minus `maxTokens` (or 1024).
|
|
167
|
+
- **Estimated size.** WebLLM has no way to count tokens ahead of a request, so size is estimated from
|
|
168
|
+
rendered length at 3 characters per token. If WebLLM still refuses at prefill, which is before any output,
|
|
169
|
+
the call is re-fitted with a stricter estimate, up to twice.
|
|
170
|
+
- **A stable start.** Once a conversation needs shortening, that is remembered for it, and a turn's shortened
|
|
171
|
+
form never changes. When turns must go, the cut leaves a quarter of the budget spare and is remembered too. That keeps the start of what is sent unchanged for several turns, which is
|
|
172
|
+
what lets WebLLM reuse its prefill; a cut that moved every turn would re-read the whole window every time.
|
|
173
|
+
- **The model is told.** A shortened result says so itself. A line in the system prompt says how many
|
|
174
|
+
earlier turns it cannot see, and to say so rather than guess. The user sees a console warning listing both.
|
|
175
|
+
|
|
176
|
+
If the system prompt, the tools and the current turn alone do not fit, the call fails with an error naming
|
|
177
|
+
the remedies: a larger `contextWindow`, fewer tools, or a new conversation.
|
|
178
|
+
|
|
179
|
+
### Open: shorten or summarise
|
|
180
|
+
|
|
181
|
+
Leaving turns out is the simplest strategy that avoids the error, not a settled design. The alternatives:
|
|
182
|
+
|
|
183
|
+
- **Shorten (what this does).** Shrinking old tool results, then dropping turns. Cheap and exact, and stable
|
|
184
|
+
enough for prefill reuse. Everything in the
|
|
185
|
+
omitted turns is gone as far as the model is concerned.
|
|
186
|
+
- **Summarise, recursively.** The gist of what is cut survives, but each summary is a generation pass by the
|
|
187
|
+
same small model, out of the same small window. Summaries of summaries drift. And every new summary changes
|
|
188
|
+
the start of the prompt, so prefill reuse is lost unless summaries are made in fixed chunks at the cut.
|
|
189
|
+
It also belongs outside this adapter. A model answering from a summary that is in no session breaks
|
|
190
|
+
matbot's rule that the session is the record. A `contribute` hook that stores its summary as a marker
|
|
191
|
+
would be visible, durable, and usable by any small-window provider.
|
|
192
|
+
- **Fetch on demand.** Leave turns out, but let the model ask for them. The note already says they exist;
|
|
193
|
+
a tool that reads them back (`session_action get`, or a search over the session) would keep the window
|
|
194
|
+
small and fetch only what a question needs. It depends on the model knowing when to look, which is the
|
|
195
|
+
weakest skill of a small one.
|
|
196
|
+
|
|
197
|
+
These can combine: shorten always, summarise or fetch for what is cut.
|
|
198
|
+
|
|
199
|
+
## Known gaps
|
|
200
|
+
|
|
201
|
+
- Not yet run against a real WebLLM engine. It was exercised only against a fake that follows WebLLM's types.
|
|
202
|
+
- No images or audio. They are replaced by a note. WebLLM's vision models (Phi-3.5-vision) are not wired in.
|
|
203
|
+
- The schema is compiled into a grammar on each request that offers tools. A large tool list may make that
|
|
204
|
+
noticeable.
|
|
205
|
+
- First use downloads several GB from Hugging Face and GitHub. The download is cached per origin, so the
|
|
206
|
+
same model is fetched again for a different host.
|
package/package.json
CHANGED
|
@@ -1,6 +1,51 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@matatbread/matbot-provider-webllm",
|
|
3
|
-
"
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
"matbotRuntime": [
|
|
4
|
+
"browser"
|
|
5
|
+
],
|
|
6
|
+
"version": "0.5.0",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=24.0.0"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"src"
|
|
12
|
+
],
|
|
13
|
+
"description": "Provider adapter running open-weight models (Qwen3 by default) in the page on the GPU through WebLLM, loaded from a CDN on first use. No endpoint, no key. Prototype.",
|
|
14
|
+
"keywords": [
|
|
15
|
+
"matbot",
|
|
16
|
+
"matbot-plugin",
|
|
17
|
+
"matbot-provider",
|
|
18
|
+
"webllm",
|
|
19
|
+
"webgpu",
|
|
20
|
+
"qwen",
|
|
21
|
+
"on-device",
|
|
22
|
+
"llm",
|
|
23
|
+
"ai",
|
|
24
|
+
"agent"
|
|
25
|
+
],
|
|
26
|
+
"license": "Apache-2.0",
|
|
27
|
+
"type": "module",
|
|
28
|
+
"exports": {
|
|
29
|
+
".": "./src/index.ts"
|
|
30
|
+
},
|
|
31
|
+
"repository": {
|
|
32
|
+
"type": "git",
|
|
33
|
+
"url": "git+https://github.com/MatAtBread/matbot.git",
|
|
34
|
+
"directory": "plugins/providers/webllm"
|
|
35
|
+
},
|
|
36
|
+
"publishConfig": {
|
|
37
|
+
"access": "public"
|
|
38
|
+
},
|
|
39
|
+
"peerDependencies": {
|
|
40
|
+
"@matatbread/matbot-plugin-api": "^0.5.0",
|
|
41
|
+
"@matatbread/matbot-core": "^0.5.0"
|
|
42
|
+
},
|
|
43
|
+
"devDependencies": {
|
|
44
|
+
"typescript": "^6.0.3",
|
|
45
|
+
"@matatbread/matbot-plugin-api": "^0.5.0",
|
|
46
|
+
"@matatbread/matbot-core": "^0.5.0"
|
|
47
|
+
},
|
|
48
|
+
"scripts": {
|
|
49
|
+
"typecheck": "tsc --noEmit"
|
|
50
|
+
}
|
|
6
51
|
}
|