@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 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,2 @@
1
+ export {};
2
+ //# sourceMappingURL=browser-guard.d.ts.map
@@ -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"}
@@ -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"}