@molecule/api-ai-decisions-jeff 1.0.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 +115 -0
- package/README.md +385 -0
- package/dist/browser-guard.d.ts +2 -0
- package/dist/browser-guard.d.ts.map +1 -0
- package/dist/browser-guard.js +19 -0
- package/dist/browser-guard.js.map +1 -0
- package/dist/index.d.ts +78 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +78 -0
- package/dist/index.js.map +1 -0
- package/dist/provider.d.ts +39 -0
- package/dist/provider.d.ts.map +1 -0
- package/dist/provider.js +135 -0
- package/dist/provider.js.map +1 -0
- package/dist/secrets.d.ts +11 -0
- package/dist/secrets.d.ts.map +1 -0
- package/dist/secrets.js +27 -0
- package/dist/secrets.js.map +1 -0
- package/dist/types.d.ts +27 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +7 -0
- package/dist/types.js.map +1 -0
- package/dist/wire.d.ts +91 -0
- package/dist/wire.d.ts.map +1 -0
- package/dist/wire.js +198 -0
- package/dist/wire.js.map +1 -0
- package/package.json +54 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
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
|
+
|
|
39
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
40
|
+
form, that is based on (or derived from) the Work and for which the
|
|
41
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
42
|
+
represent, as a whole, an original work of authorship.
|
|
43
|
+
|
|
44
|
+
"Contribution" shall mean any work of authorship, including the
|
|
45
|
+
original version of the Work and any modifications or additions
|
|
46
|
+
to that Work, that is intentionally submitted to the Licensor for
|
|
47
|
+
inclusion in the Work by the copyright owner or by an individual or
|
|
48
|
+
Legal Entity authorized to submit on behalf of the copyright owner.
|
|
49
|
+
|
|
50
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
51
|
+
on behalf of whom a Contribution has been received by the Licensor and
|
|
52
|
+
subsequently incorporated within the Work.
|
|
53
|
+
|
|
54
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
55
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
56
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
57
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
58
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
59
|
+
Work and such Derivative Works in Source or Object form.
|
|
60
|
+
|
|
61
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
62
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
63
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
64
|
+
patent license to make, have made, use, offer to sell, sell, import,
|
|
65
|
+
and otherwise transfer the Work.
|
|
66
|
+
|
|
67
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
68
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
69
|
+
modifications, and in Source or Object form, provided that You
|
|
70
|
+
meet the following conditions:
|
|
71
|
+
|
|
72
|
+
(a) You must give any other recipients of the Work or
|
|
73
|
+
Derivative Works a copy of this License; and
|
|
74
|
+
|
|
75
|
+
(b) You must cause any modified files to carry prominent notices
|
|
76
|
+
stating that You changed the files; and
|
|
77
|
+
|
|
78
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
79
|
+
that You distribute, all copyright, patent, trademark, and
|
|
80
|
+
attribution notices from the Source form of the Work,
|
|
81
|
+
excluding those notices that do not pertain to any part of
|
|
82
|
+
the Derivative Works; and
|
|
83
|
+
|
|
84
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
85
|
+
distribution, then any Derivative Works that You distribute must
|
|
86
|
+
include a readable copy of the attribution notices contained
|
|
87
|
+
within such NOTICE file.
|
|
88
|
+
|
|
89
|
+
5. Submission of Contributions.
|
|
90
|
+
|
|
91
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
92
|
+
names, trademarks, service marks, or product names of the Licensor.
|
|
93
|
+
|
|
94
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
95
|
+
agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
|
|
96
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
|
|
97
|
+
|
|
98
|
+
8. Limitation of Liability. In no event and under no legal theory shall
|
|
99
|
+
any Contributor be liable to You for damages.
|
|
100
|
+
|
|
101
|
+
9. Accepting Warranty or Additional Liability.
|
|
102
|
+
|
|
103
|
+
Copyright 2026 Molecule Dev, Inc.
|
|
104
|
+
|
|
105
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
106
|
+
you may not use this file except in compliance with the License.
|
|
107
|
+
You may obtain a copy of the License at
|
|
108
|
+
|
|
109
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
110
|
+
|
|
111
|
+
Unless required by applicable law or agreed to in writing, software
|
|
112
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
113
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
114
|
+
See the License for the specific language governing permissions and
|
|
115
|
+
limitations under the License.
|
package/README.md
ADDED
|
@@ -0,0 +1,385 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-09-29T13:48:35.638Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
9
|
+
# @molecule/api-ai-decisions-jeff
|
|
10
|
+
|
|
11
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
12
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
13
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
14
|
+
|
|
15
|
+
Jeff decisions provider for molecule.dev — typed decisions from the
|
|
16
|
+
open-weights Jeff models on a `jeff-serve` host you run.
|
|
17
|
+
|
|
18
|
+
Jeff (github.com/firelex/jeff; code MIT, weights Apache-2.0) is a family of
|
|
19
|
+
fine-tunes of Qwen3.5-0.8B, Qwen3.5-2B and Gemma 4 E2B that answer
|
|
20
|
+
`choice`, `score` and yes/no questions with a probability per option — no
|
|
21
|
+
text generation. Its maker reports ~22 ms per request for the 0.8B on an
|
|
22
|
+
NVIDIA RTX PRO 6000 and ~28 ms on an Apple M4 Max. `jeff-serve` speaks
|
|
23
|
+
TypeSafe Jev's `/v1/systemone` protocol, so swapping to
|
|
24
|
+
`@molecule/api-ai-decisions-jev` or `-laya` is a one-line change.
|
|
25
|
+
|
|
26
|
+
## Quick Start
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
# Run the model server (NVIDIA GPU, or Apple silicon with JEFF_BACKEND=mlx)
|
|
30
|
+
git clone https://github.com/firelex/jeff && cd jeff && uv sync
|
|
31
|
+
uv hf download mstrasser/Jeff-Qwen3.5-0.8B --local-dir checkpoints/jeff-0.8b
|
|
32
|
+
JEFF_API_KEY=change-me JEFF_CHECKPOINT=checkpoints/jeff-0.8b PORT=8000 uv run jeff-serve
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
import { setProvider, requireProvider } from '@molecule/api-ai-decisions'
|
|
37
|
+
import { provider } from '@molecule/api-ai-decisions-jeff'
|
|
38
|
+
|
|
39
|
+
setProvider(provider) // reads JEFF_URL + JEFF_API_KEY on first use
|
|
40
|
+
|
|
41
|
+
const { answers } = await requireProvider().decide({
|
|
42
|
+
state: 'My card was charged twice, please refund one of them',
|
|
43
|
+
questions: {
|
|
44
|
+
queue: {
|
|
45
|
+
type: 'choice',
|
|
46
|
+
instructions: 'Which team?',
|
|
47
|
+
criteria: { billing: 'charges, refunds', tech: 'bugs, login' },
|
|
48
|
+
},
|
|
49
|
+
refund: { type: 'yesNo', instructions: 'The customer wants a refund.' },
|
|
50
|
+
},
|
|
51
|
+
})
|
|
52
|
+
answers.queue.choice // 'billing'
|
|
53
|
+
answers.refund.probability // 0.95
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Type
|
|
57
|
+
|
|
58
|
+
`provider`
|
|
59
|
+
|
|
60
|
+
## Installation
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
npm install @molecule/api-ai-decisions-jeff @molecule/api-ai-decisions @molecule/api-secrets
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## API
|
|
67
|
+
|
|
68
|
+
### Interfaces
|
|
69
|
+
|
|
70
|
+
#### `JeffConfig`
|
|
71
|
+
|
|
72
|
+
Configuration for the Jeff decisions provider.
|
|
73
|
+
|
|
74
|
+
```typescript
|
|
75
|
+
interface JeffConfig {
|
|
76
|
+
/** Base URL of the `jeff-serve` host. Defaults to `JEFF_URL`, then `http://localhost:8000`. */
|
|
77
|
+
baseUrl?: string
|
|
78
|
+
/** Bearer token, when the server sets `JEFF_API_KEY`. Defaults to the `JEFF_API_KEY` env var. */
|
|
79
|
+
apiKey?: string
|
|
80
|
+
/**
|
|
81
|
+
* Model id sent on every request. `jeff-serve` REQUIRES one and accepts only
|
|
82
|
+
* `'jeff'`, `'jeff-latest'` or its own name (e.g. `'jeff-qwen3.5-0.8b'`) —
|
|
83
|
+
* it answers with whichever checkpoint it loaded. Defaults to `'jeff-latest'`.
|
|
84
|
+
*/
|
|
85
|
+
model?: string
|
|
86
|
+
/**
|
|
87
|
+
* Most `choice` options the loaded checkpoint answers (the server's `/health`
|
|
88
|
+
* reports it as `max_options`). Defaults to 26 — the Jeff models released on
|
|
89
|
+
* 2026-09-28. Raise it only for a checkpoint trained on more.
|
|
90
|
+
*/
|
|
91
|
+
maxOptions?: number
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
#### `PostOptions`
|
|
96
|
+
|
|
97
|
+
Options for {@link postSystemOne}.
|
|
98
|
+
|
|
99
|
+
```typescript
|
|
100
|
+
interface PostOptions {
|
|
101
|
+
/** Full endpoint URL. */
|
|
102
|
+
url: string
|
|
103
|
+
/** Bearer token, if any. */
|
|
104
|
+
apiKey?: string
|
|
105
|
+
/** Request body. */
|
|
106
|
+
body: Record<string, unknown>
|
|
107
|
+
/** Abort signal. */
|
|
108
|
+
signal?: AbortSignal
|
|
109
|
+
/** Label for error messages (`'Jeff'`). */
|
|
110
|
+
label: string
|
|
111
|
+
/** Max retries on a retryable status (default 3). */
|
|
112
|
+
maxRetries?: number
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
#### `WireAnswer`
|
|
117
|
+
|
|
118
|
+
One answer as received on the wire (only the fields we read).
|
|
119
|
+
|
|
120
|
+
```typescript
|
|
121
|
+
interface WireAnswer {
|
|
122
|
+
type?: string
|
|
123
|
+
choice?: string
|
|
124
|
+
score?: number
|
|
125
|
+
noul?: number
|
|
126
|
+
probabilities?: Record<string, number>
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
#### `WireQuestion`
|
|
131
|
+
|
|
132
|
+
One question as sent on the wire.
|
|
133
|
+
|
|
134
|
+
```typescript
|
|
135
|
+
interface WireQuestion {
|
|
136
|
+
type: 'choice' | 'score' | 'noul'
|
|
137
|
+
instructions: string
|
|
138
|
+
criteria?: Record<string, string> | string[]
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
#### `WireResponse`
|
|
143
|
+
|
|
144
|
+
The response body (only the fields we read).
|
|
145
|
+
|
|
146
|
+
```typescript
|
|
147
|
+
interface WireResponse {
|
|
148
|
+
model?: string
|
|
149
|
+
answers?: Record<string, WireAnswer>
|
|
150
|
+
usage?: { input_tokens?: number; output_tokens?: number }
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Functions
|
|
155
|
+
|
|
156
|
+
#### `createProvider(config)`
|
|
157
|
+
|
|
158
|
+
Creates a Jeff decisions provider.
|
|
159
|
+
|
|
160
|
+
```typescript
|
|
161
|
+
function createProvider(config?: JeffConfig): AIDecisionsProvider
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
- `config` — Base URL, API key, model id and option limit.
|
|
165
|
+
|
|
166
|
+
**Returns:** An `AIDecisionsProvider` backed by a `jeff-serve` host.
|
|
167
|
+
|
|
168
|
+
#### `fromWireAnswer(id, question, wire, minConfidence)`
|
|
169
|
+
|
|
170
|
+
Converts one wire answer into the core's answer for `question`.
|
|
171
|
+
|
|
172
|
+
```typescript
|
|
173
|
+
function fromWireAnswer(
|
|
174
|
+
id: string,
|
|
175
|
+
question: DecisionQuestion,
|
|
176
|
+
wire: WireAnswer | undefined,
|
|
177
|
+
minConfidence?: number,
|
|
178
|
+
): DecisionAnswer
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
- `id` — The question id (for error messages).
|
|
182
|
+
- `question` — The question that was asked.
|
|
183
|
+
- `wire` — The wire answer.
|
|
184
|
+
- `minConfidence` — Optional low-confidence threshold.
|
|
185
|
+
|
|
186
|
+
**Returns:** The typed answer.
|
|
187
|
+
|
|
188
|
+
#### `fromWireResponse(questions, body, minConfidence)`
|
|
189
|
+
|
|
190
|
+
Converts a whole wire response into the core's result.
|
|
191
|
+
|
|
192
|
+
```typescript
|
|
193
|
+
function fromWireResponse(questions: Q, body: WireResponse, minConfidence?: number): DecideResult<Q>
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
- `questions` — The questions that were asked.
|
|
197
|
+
- `body` — The parsed response body.
|
|
198
|
+
- `minConfidence` — Optional low-confidence threshold.
|
|
199
|
+
|
|
200
|
+
**Returns:** The typed result.
|
|
201
|
+
|
|
202
|
+
#### `postSystemOne(opts)`
|
|
203
|
+
|
|
204
|
+
POSTs a `/v1/systemone` request with retry on 429/5xx-busy, honouring
|
|
205
|
+
`Retry-After`. Throws an Error carrying `status` on a non-2xx response.
|
|
206
|
+
|
|
207
|
+
```typescript
|
|
208
|
+
function postSystemOne(opts: PostOptions): Promise<WireResponse>
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
- `opts` — Request options.
|
|
212
|
+
|
|
213
|
+
**Returns:** The parsed response body.
|
|
214
|
+
|
|
215
|
+
#### `toWireQuestions(questions)`
|
|
216
|
+
|
|
217
|
+
Converts the core's questions into wire questions (`yesNo` → `noul`).
|
|
218
|
+
|
|
219
|
+
```typescript
|
|
220
|
+
function toWireQuestions(questions: Record<string, DecisionQuestion>): Record<string, WireQuestion>
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
- `questions` — The questions keyed by id.
|
|
224
|
+
|
|
225
|
+
**Returns:** The wire `questions` object.
|
|
226
|
+
|
|
227
|
+
### Constants
|
|
228
|
+
|
|
229
|
+
#### `aiDecisionsJeffSecretDefinitions`
|
|
230
|
+
|
|
231
|
+
Secret definitions used by the Jeff decisions bond.
|
|
232
|
+
|
|
233
|
+
```typescript
|
|
234
|
+
const aiDecisionsJeffSecretDefinitions: SecretDefinition[]
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
#### `DEFAULT_JEFF_MAX_OPTIONS`
|
|
238
|
+
|
|
239
|
+
Most `choice` options the released Jeff checkpoints answer (options are coded A–Z).
|
|
240
|
+
|
|
241
|
+
```typescript
|
|
242
|
+
const DEFAULT_JEFF_MAX_OPTIONS: 26
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
#### `DEFAULT_JEFF_MODEL`
|
|
246
|
+
|
|
247
|
+
A model id every `jeff-serve` accepts; it answers with the checkpoint it loaded.
|
|
248
|
+
|
|
249
|
+
```typescript
|
|
250
|
+
const DEFAULT_JEFF_MODEL: 'jeff-latest'
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
#### `DEFAULT_JEFF_URL`
|
|
254
|
+
|
|
255
|
+
`jeff-serve`'s default bind (`PORT` defaults to 8000; its README examples use 8765).
|
|
256
|
+
|
|
257
|
+
```typescript
|
|
258
|
+
const DEFAULT_JEFF_URL: 'http://localhost:8000'
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
#### `JEFF_IMAGE_TYPES`
|
|
262
|
+
|
|
263
|
+
Image media types `jeff-serve` decodes.
|
|
264
|
+
|
|
265
|
+
```typescript
|
|
266
|
+
const JEFF_IMAGE_TYPES: readonly string[]
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
#### `JEFF_MAX_IMAGES`
|
|
270
|
+
|
|
271
|
+
Most images `jeff-serve` accepts per request.
|
|
272
|
+
|
|
273
|
+
```typescript
|
|
274
|
+
const JEFF_MAX_IMAGES: 4
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
#### `JEFF_SCORE_LEVELS`
|
|
278
|
+
|
|
279
|
+
`jeff-serve`'s bounds on a `score` question's levels.
|
|
280
|
+
|
|
281
|
+
```typescript
|
|
282
|
+
const JEFF_SCORE_LEVELS: { readonly min: 2; readonly max: 10 }
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
#### `provider`
|
|
286
|
+
|
|
287
|
+
The provider implementation — lazy, so env vars are read on first use.
|
|
288
|
+
|
|
289
|
+
```typescript
|
|
290
|
+
const provider: AIDecisionsProvider
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
## Core Interface
|
|
294
|
+
|
|
295
|
+
Implements `@molecule/api-ai-decisions` interface.
|
|
296
|
+
|
|
297
|
+
## Bond Wiring
|
|
298
|
+
|
|
299
|
+
Setup function to register this provider with the core interface:
|
|
300
|
+
|
|
301
|
+
```typescript
|
|
302
|
+
import { setProvider } from '@molecule/api-ai-decisions'
|
|
303
|
+
import { provider } from '@molecule/api-ai-decisions-jeff'
|
|
304
|
+
|
|
305
|
+
export function setupAiDecisionsJeff(): void {
|
|
306
|
+
setProvider(provider)
|
|
307
|
+
}
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
## Injection Notes
|
|
311
|
+
|
|
312
|
+
### Requirements
|
|
313
|
+
|
|
314
|
+
Peer dependencies:
|
|
315
|
+
|
|
316
|
+
- `@molecule/api-ai-decisions` ^1.1.0
|
|
317
|
+
- `@molecule/api-secrets` ^1.0.1
|
|
318
|
+
|
|
319
|
+
### Environment Variables
|
|
320
|
+
|
|
321
|
+
- `JEFF_URL` _(optional)_ — Jeff server URL
|
|
322
|
+
- Setup: The base URL of your jeff-serve host (clone github.com/firelex/jeff, uv sync, download a checkpoint, then JEFF_CHECKPOINT=<dir> uv run jeff-serve). Defaults to http://localhost:8000.
|
|
323
|
+
- Get it here: [https://github.com/firelex/jeff#readme](https://github.com/firelex/jeff#readme)
|
|
324
|
+
- Example: `http://localhost:8000`
|
|
325
|
+
- `JEFF_API_KEY` _(optional)_ — Jeff server API key
|
|
326
|
+
- Setup: The bearer token your jeff-serve host requires, if you set JEFF_API_KEY on the server.
|
|
327
|
+
- Get it here: [https://github.com/firelex/jeff#readme](https://github.com/firelex/jeff#readme)
|
|
328
|
+
- Example: `a-long-random-string`
|
|
329
|
+
|
|
330
|
+
### Runtime Dependencies
|
|
331
|
+
|
|
332
|
+
- `@molecule/api-ai-decisions`
|
|
333
|
+
- `@molecule/api-secrets`
|
|
334
|
+
|
|
335
|
+
- **You run the model.** `JEFF_URL` (default `http://localhost:8000`) points
|
|
336
|
+
at a `jeff-serve` host. Its code defaults to port 8000 but its README
|
|
337
|
+
examples use `PORT=8765` — set `JEFF_URL` to match. `jeff-serve` binds
|
|
338
|
+
`127.0.0.1` unless you set `JEFF_HOST`. Set `JEFF_API_KEY` on BOTH sides to
|
|
339
|
+
require a bearer token; without it anyone who can reach the server can use it.
|
|
340
|
+
- **`model` is required on the wire and is NOT a checkpoint picker.** The
|
|
341
|
+
server accepts only `'jeff'`, `'jeff-latest'` (the default here) or its own
|
|
342
|
+
name, rejects anything else with a 422, and always answers with the ONE
|
|
343
|
+
checkpoint it loaded (`JEFF_CHECKPOINT`). Never pass a Jev model id. Run a
|
|
344
|
+
second server to use a second checkpoint.
|
|
345
|
+
- **At most 26 `choice` options** with the released checkpoints (options are
|
|
346
|
+
coded A–Z; the server refuses more). `score` takes 2–10 levels. This bond
|
|
347
|
+
refuses both before sending — shortlist long option lists first. Raise
|
|
348
|
+
`createProvider({ maxOptions })` only for a checkpoint whose `/health`
|
|
349
|
+
reports a higher `max_options`.
|
|
350
|
+
- **One request at a time.** A busy server answers 529 + `Retry-After: 1`
|
|
351
|
+
and a loading one 503; this bond retries 429/502/503/504/529 up to 3 times.
|
|
352
|
+
Errors carry the HTTP `status`.
|
|
353
|
+
- **English text only.** Use `@molecule/api-ai-decisions-laya`'s multilingual
|
|
354
|
+
checkpoint for other languages.
|
|
355
|
+
- **Images:** up to 4 PNG/JPEG/WebP `images` are forwarded, but only the
|
|
356
|
+
PyTorch backend reads them (`/health` → `modalities`); the Apple MLX
|
|
357
|
+
backend is text-only, and the maker publishes no image accuracy figures.
|
|
358
|
+
For image questions prefer `@molecule/api-ai-decisions-intern-decision`.
|
|
359
|
+
- **Small models don't reason.** Expect fast choices between options you
|
|
360
|
+
describe, not multi-step logic (the 0.8B scores 68% on BIG-Bench Hard vs
|
|
361
|
+
Jev's 94%). Describe each option's consequences in plain words.
|
|
362
|
+
- **Calibrate on your own data.** The checkpoints carry one fitted
|
|
363
|
+
temperature from the maker's training mix; recalibrate on labelled samples
|
|
364
|
+
of your inputs and gate on `minConfidence`. See the core's remarks.
|
|
365
|
+
- Use the core's `setProvider`, not `bond('ai-decisions', …)` directly.
|
|
366
|
+
|
|
367
|
+
## E2E Tests
|
|
368
|
+
|
|
369
|
+
Integration checklist — drive the real UI (live preview, no mocks), adapt
|
|
370
|
+
each item to this app's actual screens/flows, and check every box off one
|
|
371
|
+
by one. A box you can't check is an integration bug to fix — not a skip:
|
|
372
|
+
|
|
373
|
+
- [ ] Each flow that makes a decision (routing, triage, moderation, a
|
|
374
|
+
guardrail) runs it from the real UI, and the answer DRIVES what happens
|
|
375
|
+
next (the item lands in the chosen queue, the badge shows, the action is
|
|
376
|
+
blocked) — not just printed.
|
|
377
|
+
- [ ] Both directions: a clearly-billing input routes to billing AND a
|
|
378
|
+
clearly-technical one routes elsewhere. One label for every input is a
|
|
379
|
+
broken integration.
|
|
380
|
+
- [ ] A low-confidence answer takes the app's fallback path (human review,
|
|
381
|
+
"unsure" state) instead of being acted on.
|
|
382
|
+
- [ ] Provider errors (service down, bad key) show a visible, recoverable
|
|
383
|
+
state — never a blank screen or an unhandled rejection.
|
|
384
|
+
- [ ] The call runs server-side: no provider request or key in the browser's
|
|
385
|
+
Network tab.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Browser guard — `@molecule/api-ai-decisions-jeff` is SERVER-ONLY.
|
|
3
|
+
*
|
|
4
|
+
* Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
|
|
5
|
+
* Evaluating a server package in a browser bundle is always an import-graph mistake
|
|
6
|
+
* (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
|
|
7
|
+
* ("Buffer is not defined") far from the culprit. Throwing here names the package and
|
|
8
|
+
* the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
|
|
9
|
+
* unaffected: the throw requires browser globals AND the absence of a node runtime.
|
|
10
|
+
*/
|
|
11
|
+
const g = globalThis;
|
|
12
|
+
if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
|
|
13
|
+
throw new Error('@molecule/api-ai-decisions-jeff is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
|
|
14
|
+
'from server code (a server route/function or your API), or dynamic-import it inside ' +
|
|
15
|
+
'the server handler — never from components or shared client modules, and never ' +
|
|
16
|
+
'polyfill Buffer/process to silence this.');
|
|
17
|
+
}
|
|
18
|
+
export {};
|
|
19
|
+
//# sourceMappingURL=browser-guard.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,0GAA0G;QACxG,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Jeff decisions provider for molecule.dev — typed decisions from the
|
|
3
|
+
* open-weights Jeff models on a `jeff-serve` host you run.
|
|
4
|
+
*
|
|
5
|
+
* Jeff (github.com/firelex/jeff; code MIT, weights Apache-2.0) is a family of
|
|
6
|
+
* fine-tunes of Qwen3.5-0.8B, Qwen3.5-2B and Gemma 4 E2B that answer
|
|
7
|
+
* `choice`, `score` and yes/no questions with a probability per option — no
|
|
8
|
+
* text generation. Its maker reports ~22 ms per request for the 0.8B on an
|
|
9
|
+
* NVIDIA RTX PRO 6000 and ~28 ms on an Apple M4 Max. `jeff-serve` speaks
|
|
10
|
+
* TypeSafe Jev's `/v1/systemone` protocol, so swapping to
|
|
11
|
+
* `@molecule/api-ai-decisions-jev` or `-laya` is a one-line change.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* ```bash
|
|
15
|
+
* # Run the model server (NVIDIA GPU, or Apple silicon with JEFF_BACKEND=mlx)
|
|
16
|
+
* git clone https://github.com/firelex/jeff && cd jeff && uv sync
|
|
17
|
+
* uv hf download mstrasser/Jeff-Qwen3.5-0.8B --local-dir checkpoints/jeff-0.8b
|
|
18
|
+
* JEFF_API_KEY=change-me JEFF_CHECKPOINT=checkpoints/jeff-0.8b PORT=8000 uv run jeff-serve
|
|
19
|
+
* ```
|
|
20
|
+
*
|
|
21
|
+
* ```typescript
|
|
22
|
+
* import { setProvider, requireProvider } from '@molecule/api-ai-decisions'
|
|
23
|
+
* import { provider } from '@molecule/api-ai-decisions-jeff'
|
|
24
|
+
*
|
|
25
|
+
* setProvider(provider) // reads JEFF_URL + JEFF_API_KEY on first use
|
|
26
|
+
*
|
|
27
|
+
* const { answers } = await requireProvider().decide({
|
|
28
|
+
* state: 'My card was charged twice, please refund one of them',
|
|
29
|
+
* questions: {
|
|
30
|
+
* queue: { type: 'choice', instructions: 'Which team?', criteria: { billing: 'charges, refunds', tech: 'bugs, login' } },
|
|
31
|
+
* refund: { type: 'yesNo', instructions: 'The customer wants a refund.' },
|
|
32
|
+
* },
|
|
33
|
+
* })
|
|
34
|
+
* answers.queue.choice // 'billing'
|
|
35
|
+
* answers.refund.probability // 0.95
|
|
36
|
+
* ```
|
|
37
|
+
*
|
|
38
|
+
* @remarks
|
|
39
|
+
* - **You run the model.** `JEFF_URL` (default `http://localhost:8000`) points
|
|
40
|
+
* at a `jeff-serve` host. Its code defaults to port 8000 but its README
|
|
41
|
+
* examples use `PORT=8765` — set `JEFF_URL` to match. `jeff-serve` binds
|
|
42
|
+
* `127.0.0.1` unless you set `JEFF_HOST`. Set `JEFF_API_KEY` on BOTH sides to
|
|
43
|
+
* require a bearer token; without it anyone who can reach the server can use it.
|
|
44
|
+
* - **`model` is required on the wire and is NOT a checkpoint picker.** The
|
|
45
|
+
* server accepts only `'jeff'`, `'jeff-latest'` (the default here) or its own
|
|
46
|
+
* name, rejects anything else with a 422, and always answers with the ONE
|
|
47
|
+
* checkpoint it loaded (`JEFF_CHECKPOINT`). Never pass a Jev model id. Run a
|
|
48
|
+
* second server to use a second checkpoint.
|
|
49
|
+
* - **At most 26 `choice` options** with the released checkpoints (options are
|
|
50
|
+
* coded A–Z; the server refuses more). `score` takes 2–10 levels. This bond
|
|
51
|
+
* refuses both before sending — shortlist long option lists first. Raise
|
|
52
|
+
* `createProvider({ maxOptions })` only for a checkpoint whose `/health`
|
|
53
|
+
* reports a higher `max_options`.
|
|
54
|
+
* - **One request at a time.** A busy server answers 529 + `Retry-After: 1`
|
|
55
|
+
* and a loading one 503; this bond retries 429/502/503/504/529 up to 3 times.
|
|
56
|
+
* Errors carry the HTTP `status`.
|
|
57
|
+
* - **English text only.** Use `@molecule/api-ai-decisions-laya`'s multilingual
|
|
58
|
+
* checkpoint for other languages.
|
|
59
|
+
* - **Images:** up to 4 PNG/JPEG/WebP `images` are forwarded, but only the
|
|
60
|
+
* PyTorch backend reads them (`/health` → `modalities`); the Apple MLX
|
|
61
|
+
* backend is text-only, and the maker publishes no image accuracy figures.
|
|
62
|
+
* For image questions prefer `@molecule/api-ai-decisions-intern-decision`.
|
|
63
|
+
* - **Small models don't reason.** Expect fast choices between options you
|
|
64
|
+
* describe, not multi-step logic (the 0.8B scores 68% on BIG-Bench Hard vs
|
|
65
|
+
* Jev's 94%). Describe each option's consequences in plain words.
|
|
66
|
+
* - **Calibrate on your own data.** The checkpoints carry one fitted
|
|
67
|
+
* temperature from the maker's training mix; recalibrate on labelled samples
|
|
68
|
+
* of your inputs and gate on `minConfidence`. See the core's remarks.
|
|
69
|
+
* - Use the core's `setProvider`, not `bond('ai-decisions', …)` directly.
|
|
70
|
+
*
|
|
71
|
+
* @module
|
|
72
|
+
*/
|
|
73
|
+
export * from './browser-guard.js';
|
|
74
|
+
export * from './provider.js';
|
|
75
|
+
export * from './secrets.js';
|
|
76
|
+
export * from './types.js';
|
|
77
|
+
export * from './wire.js';
|
|
78
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA"}
|