letsdecide 0.0.0-stage → 0.3.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 +202 -0
- package/README.md +80 -3
- package/conformance.d.ts +21 -0
- package/conformance.js +91 -0
- package/index.d.ts +247 -0
- package/index.js +378 -0
- package/middleware.d.ts +98 -0
- package/middleware.js +385 -0
- package/package.json +30 -6
- package/pkg/letsdecide_wasm.d.ts +68 -0
- package/pkg/letsdecide_wasm.js +488 -0
- package/pkg/letsdecide_wasm_bg.wasm +0 -0
- package/pkg/letsdecide_wasm_bg.wasm.d.ts +19 -0
package/index.js
ADDED
|
@@ -0,0 +1,378 @@
|
|
|
1
|
+
import init, * as core from "./pkg/letsdecide_wasm.js";
|
|
2
|
+
|
|
3
|
+
const { build, parse } = core;
|
|
4
|
+
|
|
5
|
+
export class LetsDecideError extends Error {
|
|
6
|
+
constructor({ code, message, status, retry_after_ms, retryable, details }) {
|
|
7
|
+
super(message);
|
|
8
|
+
this.name = "LetsDecideError";
|
|
9
|
+
this.code = code;
|
|
10
|
+
this.status = status ?? undefined;
|
|
11
|
+
this.retryAfterMs = retry_after_ms ?? undefined;
|
|
12
|
+
this.retryable = retryable;
|
|
13
|
+
// Safe to log: names, ids, counts, MIME types. Never keys or content.
|
|
14
|
+
this.details = details ?? undefined;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
// The core returns {ok} or {error}; unwrap or throw.
|
|
19
|
+
function unwrap(json) {
|
|
20
|
+
const out = JSON.parse(json);
|
|
21
|
+
if (out.error) throw new LetsDecideError(out.error);
|
|
22
|
+
return out.ok;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
let ready;
|
|
26
|
+
let loaded = false;
|
|
27
|
+
/** Loads the WASM once. Pass bytes or a module where `fetch(url)` isn't available (e.g. Node). */
|
|
28
|
+
export function initialize(wasm) {
|
|
29
|
+
return (ready ??= init({ module_or_path: wasm }).then(
|
|
30
|
+
(m) => ((loaded = true), m),
|
|
31
|
+
(e) => {
|
|
32
|
+
ready = undefined; // a failed load can be retried
|
|
33
|
+
if (wasm === undefined && import.meta.url.startsWith("file:")) {
|
|
34
|
+
throw new Error(
|
|
35
|
+
"letsdecide: could not load the WASM from a file: URL (Node's fetch can't). " +
|
|
36
|
+
"Pass the bytes: new Client(config, { wasm }). See the README.",
|
|
37
|
+
{ cause: e },
|
|
38
|
+
);
|
|
39
|
+
}
|
|
40
|
+
throw e;
|
|
41
|
+
},
|
|
42
|
+
));
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Built-in provider names; custom providers can't take them without `replace`. */
|
|
46
|
+
export const BUILTIN = ["jev", "clef", "gemini", "openai", "systemone"];
|
|
47
|
+
|
|
48
|
+
const NAME = /^[a-z0-9_-]{1,64}$/;
|
|
49
|
+
const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
|
|
50
|
+
|
|
51
|
+
function nameTaken(name) {
|
|
52
|
+
return new LetsDecideError({
|
|
53
|
+
code: "InvalidRequest",
|
|
54
|
+
message: `provider \`${name}\` is already registered; list it in \`replace\` to override it`,
|
|
55
|
+
retryable: false,
|
|
56
|
+
details: { reason: "name_taken", provider: name },
|
|
57
|
+
});
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Tags core errors with the provider; wraps anything else as `ProviderError`. */
|
|
61
|
+
function fromUserCode(name, e) {
|
|
62
|
+
if (e instanceof LetsDecideError) {
|
|
63
|
+
if (e.details && e.details.provider === undefined) e.details.provider = name;
|
|
64
|
+
return e;
|
|
65
|
+
}
|
|
66
|
+
if (e?.name === "AbortError") return e; // cancellation stays cancellation
|
|
67
|
+
// Never serialise the user's message: it may hold bodies or keys.
|
|
68
|
+
const err = new LetsDecideError({
|
|
69
|
+
code: "ProviderError",
|
|
70
|
+
message: `custom provider \`${name}\` threw ${e?.constructor?.name ?? typeof e}`,
|
|
71
|
+
retryable: false,
|
|
72
|
+
});
|
|
73
|
+
err.provider = name;
|
|
74
|
+
// Non-enumerable and not `cause`, so loggers and `util.inspect` don't print it.
|
|
75
|
+
Object.defineProperty(err, "original", { value: e, enumerable: false });
|
|
76
|
+
return err;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** `config.headers` (object or pairs) as pairs, after the codec's own; same name replaces. */
|
|
80
|
+
function withHeaders(headers, extra) {
|
|
81
|
+
const out = (headers ?? []).filter(([k]) => !extra.some(([e]) => e.toLowerCase() === k.toLowerCase()));
|
|
82
|
+
for (const [k, v] of extra) {
|
|
83
|
+
if (!HEADER_NAME.test(k) || /[\r\n\0]/.test(v)) {
|
|
84
|
+
throw new LetsDecideError({
|
|
85
|
+
code: "InvalidRequest",
|
|
86
|
+
message: "a header in `headers` is not valid",
|
|
87
|
+
retryable: false,
|
|
88
|
+
details: { reason: "invalid_config", field: "headers" },
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
out.push([k, v]);
|
|
92
|
+
}
|
|
93
|
+
return out;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
const pairs = (h = []) => (Array.isArray(h) ? h : Object.entries(h ?? {}));
|
|
97
|
+
|
|
98
|
+
/** Client-wide settings. Everything else is per provider. */
|
|
99
|
+
const SHARED = ["byProvider", "headers"];
|
|
100
|
+
const PER_PROVIDER = ["apiKey", "accessToken", "baseUrl", "accountId", "headers", "options"];
|
|
101
|
+
|
|
102
|
+
/** How deep engines may call back into the client (a panel of panels...). */
|
|
103
|
+
export const MAX_DEPTH = 4;
|
|
104
|
+
const DEPTH = Symbol("letsdecide.depth");
|
|
105
|
+
|
|
106
|
+
// Config values may be functions (sync or async), resolved on every call.
|
|
107
|
+
const resolve = async (v) => (typeof v === "function" ? await v() : v);
|
|
108
|
+
|
|
109
|
+
/** Validates `request` (and checks it against `capabilities`, if given). Throws `LetsDecideError`. */
|
|
110
|
+
export async function validate(request, capabilities = null, { wasm } = {}) {
|
|
111
|
+
await initialize(wasm);
|
|
112
|
+
unwrap(core.validate(JSON.stringify(request), JSON.stringify(capabilities)));
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** Checks a canonical `response` against `request`; returns it with defaults filled. */
|
|
116
|
+
export async function check(request, response, { wasm } = {}) {
|
|
117
|
+
await initialize(wasm);
|
|
118
|
+
return unwrap(core.check(JSON.stringify(request), JSON.stringify(response)));
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** The error a built-in adapter would raise for this non-2xx reply (`{status, headers, body}`). */
|
|
122
|
+
export async function classifyHttp(response, { wasm } = {}) {
|
|
123
|
+
await initialize(wasm);
|
|
124
|
+
const out = unwrap(core.classify_http(JSON.stringify({
|
|
125
|
+
status: response.status,
|
|
126
|
+
headers: pairs(response.headers),
|
|
127
|
+
body: response.body ?? "",
|
|
128
|
+
})));
|
|
129
|
+
return new LetsDecideError(out);
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** Capabilities of a built-in `"provider/model"`. */
|
|
133
|
+
export async function capabilities(model, { wasm } = {}) {
|
|
134
|
+
await initialize(wasm);
|
|
135
|
+
return unwrap(core.capabilities(model));
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
export class Client {
|
|
139
|
+
/**
|
|
140
|
+
* @param config `{ byProvider, headers }`. `byProvider`: settings per provider prefix,
|
|
141
|
+
* `{ gemini: { apiKey }, clef: { accessToken, accountId }, acme: { options } }`; a provider
|
|
142
|
+
* only ever sees its own entry. Any value may be a function (sync or async), called on every
|
|
143
|
+
* request, e.g. to refresh an OAuth token. `headers`: sent to every provider (tracing,
|
|
144
|
+
* gateways); never put secrets there.
|
|
145
|
+
* @param opts `{ fetch, wasm, providers, engines, dialects, replace }`. `providers`: custom HTTP
|
|
146
|
+
* codecs `{ build, parse, capabilities? }` by name. `engines`: custom `{ decide,
|
|
147
|
+
* capabilities? }` by name (local models, mocks). `dialects`: providers described as data,
|
|
148
|
+
* e.g. `{ acme: { extends: "jev", base_url, path } }`. `replace`: built-in names they may
|
|
149
|
+
* override (e.g. a patched `gemini` dialect).
|
|
150
|
+
*/
|
|
151
|
+
constructor(config = {}, { fetch = globalThis.fetch, wasm, providers = {}, engines = {}, dialects = {}, replace = [] } = {}) {
|
|
152
|
+
for (const k of Object.keys(config)) {
|
|
153
|
+
if (!SHARED.includes(k)) {
|
|
154
|
+
const hint = PER_PROVIDER.includes(k) ? `set it per provider: byProvider.<name>.${k}` : "unknown setting";
|
|
155
|
+
throw new LetsDecideError({
|
|
156
|
+
code: "InvalidRequest",
|
|
157
|
+
message: `config \`${k}\`: ${hint}`,
|
|
158
|
+
retryable: false,
|
|
159
|
+
details: { reason: "invalid_config", field: k },
|
|
160
|
+
});
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
for (const [name, own] of Object.entries(config.byProvider ?? {})) {
|
|
164
|
+
const bad = Object.keys(own ?? {}).find((k) => !PER_PROVIDER.includes(k));
|
|
165
|
+
if (bad) {
|
|
166
|
+
throw new LetsDecideError({
|
|
167
|
+
code: "InvalidRequest",
|
|
168
|
+
message: `byProvider.${name}: unknown setting \`${bad}\``,
|
|
169
|
+
retryable: false,
|
|
170
|
+
details: { reason: "invalid_config", field: "byProvider", provider: name },
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
this.cfg = config;
|
|
175
|
+
this.fetch = fetch;
|
|
176
|
+
this.wasm = wasm;
|
|
177
|
+
this.custom = new Map();
|
|
178
|
+
const fromDialects = Object.fromEntries(
|
|
179
|
+
Object.entries(dialects).map(([n, spec]) => {
|
|
180
|
+
try {
|
|
181
|
+
return [n, dialectCodec(spec)];
|
|
182
|
+
} catch (e) {
|
|
183
|
+
throw fromUserCode(n, e);
|
|
184
|
+
}
|
|
185
|
+
}),
|
|
186
|
+
);
|
|
187
|
+
for (const [kind, table] of [["codec", providers], ["engine", engines], ["codec", fromDialects]]) {
|
|
188
|
+
for (const [name, impl] of Object.entries(table)) {
|
|
189
|
+
if (!NAME.test(name)) {
|
|
190
|
+
throw new LetsDecideError({
|
|
191
|
+
code: "InvalidRequest",
|
|
192
|
+
message: "provider names must match `[a-z0-9_-]{1,64}`",
|
|
193
|
+
retryable: false,
|
|
194
|
+
details: { reason: "invalid_config", field: "name" },
|
|
195
|
+
});
|
|
196
|
+
}
|
|
197
|
+
if (this.custom.has(name) || (BUILTIN.includes(name) && !replace.includes(name))) throw nameTaken(name);
|
|
198
|
+
const needs = kind === "codec" ? ["build", "parse"] : ["decide"];
|
|
199
|
+
for (const fn of needs) {
|
|
200
|
+
if (typeof impl?.[fn] !== "function") throw new TypeError(`${kind} \`${name}\` needs a \`${fn}\` function`);
|
|
201
|
+
}
|
|
202
|
+
this.custom.set(name, { kind, impl });
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** Settings for one provider: its own `byProvider` entry plus the shared headers. */
|
|
208
|
+
async #config(name) {
|
|
209
|
+
const own = this.cfg.byProvider?.[name] ?? {};
|
|
210
|
+
const shared = pairs(await resolve(this.cfg.headers));
|
|
211
|
+
const mine = pairs(await resolve(own.headers));
|
|
212
|
+
return {
|
|
213
|
+
apiKey: await resolve(own.apiKey),
|
|
214
|
+
accessToken: await resolve(own.accessToken),
|
|
215
|
+
baseUrl: await resolve(own.baseUrl),
|
|
216
|
+
accountId: await resolve(own.accountId),
|
|
217
|
+
// The provider's own headers win over shared ones with the same name.
|
|
218
|
+
headers: [...shared.filter(([k]) => !mine.some(([m]) => m.toLowerCase() === k.toLowerCase())), ...mine],
|
|
219
|
+
options: (await resolve(own.options)) ?? {},
|
|
220
|
+
};
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
/** Capabilities of any `"provider/model"`: built-in via the core, custom from the provider. */
|
|
224
|
+
async capabilities(model) {
|
|
225
|
+
await initialize(this.wasm);
|
|
226
|
+
const name = model.slice(0, model.indexOf("/"));
|
|
227
|
+
const custom = name && this.custom.get(name);
|
|
228
|
+
if (custom) return custom.impl.capabilities ?? {};
|
|
229
|
+
return unwrap(core.capabilities(model));
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
async #send(http, signal) {
|
|
233
|
+
const res = await this.fetch(http.url, {
|
|
234
|
+
method: http.method,
|
|
235
|
+
headers: Object.fromEntries(http.headers),
|
|
236
|
+
body: http.body,
|
|
237
|
+
signal,
|
|
238
|
+
});
|
|
239
|
+
return { status: res.status, headers: [...res.headers], body: await res.text() };
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** `model`: "provider/model". `request`: `{ input, questions, media? }`. */
|
|
243
|
+
async decide(model, request, { signal, [DEPTH]: depth = 0 } = {}) {
|
|
244
|
+
await initialize(this.wasm);
|
|
245
|
+
const name = model.slice(0, model.indexOf("/"));
|
|
246
|
+
const custom = name && this.custom.get(name);
|
|
247
|
+
if (custom) return this.#decideCustom(name, model.slice(name.length + 1), custom, request, signal, depth);
|
|
248
|
+
const req = JSON.stringify(request);
|
|
249
|
+
const cfg = await this.#config(name);
|
|
250
|
+
const config = JSON.stringify(coreConfig(cfg));
|
|
251
|
+
const http = unwrap(build(model, req, config));
|
|
252
|
+
const response = await this.#send(http, signal);
|
|
253
|
+
return unwrap(parse(model, req, JSON.stringify(response)));
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
// Same guarantees as built-ins: validate first, check the answer after.
|
|
257
|
+
async #decideCustom(name, model, { kind, impl }, request, signal, depth) {
|
|
258
|
+
const tag = (e) => fromUserCode(name, e);
|
|
259
|
+
if (!model) throw new LetsDecideError({ code: "InvalidRequest", message: "model must look like `provider/model`", retryable: false });
|
|
260
|
+
try {
|
|
261
|
+
unwrap(core.validate(JSON.stringify(request), JSON.stringify(impl.capabilities ?? null)));
|
|
262
|
+
} catch (e) {
|
|
263
|
+
throw tag(e);
|
|
264
|
+
}
|
|
265
|
+
let out;
|
|
266
|
+
if (kind === "engine") {
|
|
267
|
+
try {
|
|
268
|
+
if (depth >= MAX_DEPTH) {
|
|
269
|
+
throw new LetsDecideError({
|
|
270
|
+
code: "InvalidRequest",
|
|
271
|
+
message: `engines nested more than ${MAX_DEPTH} deep (does an engine call itself?)`,
|
|
272
|
+
retryable: false,
|
|
273
|
+
details: { reason: "invalid_config", field: "engines" },
|
|
274
|
+
});
|
|
275
|
+
}
|
|
276
|
+
// Engines may call other models through the client (e.g. a panel's members).
|
|
277
|
+
const decide = (m, r, o = {}) => this.decide(m, r, { signal, ...o, [DEPTH]: depth + 1 });
|
|
278
|
+
out = await impl.decide(model, request, { signal, decide });
|
|
279
|
+
} catch (e) {
|
|
280
|
+
throw tag(e);
|
|
281
|
+
}
|
|
282
|
+
} else {
|
|
283
|
+
const cfg = await this.#config(name);
|
|
284
|
+
let http;
|
|
285
|
+
try {
|
|
286
|
+
http = await impl.build(model, request, cfg);
|
|
287
|
+
http = { method: http.method ?? "POST", url: http.url, headers: withHeaders(pairs(http.headers), cfg.headers), body: http.body };
|
|
288
|
+
} catch (e) {
|
|
289
|
+
throw tag(e);
|
|
290
|
+
}
|
|
291
|
+
const response = await this.#send(http, signal);
|
|
292
|
+
try {
|
|
293
|
+
out = await impl.parse(request, response);
|
|
294
|
+
} catch (e) {
|
|
295
|
+
throw tag(e);
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
try {
|
|
299
|
+
// Checked fields win; extra fields an engine adds are kept, unchecked.
|
|
300
|
+
return { ...out, ...unwrap(core.check(JSON.stringify(request), JSON.stringify(out))) };
|
|
301
|
+
} catch (e) {
|
|
302
|
+
throw tag(e);
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
/** Config as the core takes it (snake_case). */
|
|
308
|
+
const coreConfig = (c) => ({
|
|
309
|
+
api_key: c.apiKey,
|
|
310
|
+
access_token: c.accessToken,
|
|
311
|
+
base_url: c.baseUrl,
|
|
312
|
+
account_id: c.accountId,
|
|
313
|
+
headers: c.headers,
|
|
314
|
+
options: c.options,
|
|
315
|
+
});
|
|
316
|
+
|
|
317
|
+
/**
|
|
318
|
+
* A dialect run by the core, as a codec. Validated when the client is made if the core is
|
|
319
|
+
* already loaded (`await initialize()` first), otherwise on first use.
|
|
320
|
+
*/
|
|
321
|
+
function dialectCodec(spec) {
|
|
322
|
+
let resolved;
|
|
323
|
+
const get = () => (resolved ??= JSON.stringify(unwrap(core.resolve_dialect(JSON.stringify(spec)))));
|
|
324
|
+
if (loaded) get();
|
|
325
|
+
return {
|
|
326
|
+
get capabilities() {
|
|
327
|
+
return JSON.parse(get()).capabilities;
|
|
328
|
+
},
|
|
329
|
+
build(model, request, config) {
|
|
330
|
+
return unwrap(core.build_dialect(get(), model, JSON.stringify(request), JSON.stringify(coreConfig(config))));
|
|
331
|
+
},
|
|
332
|
+
parse(request, response) {
|
|
333
|
+
return unwrap(core.parse_dialect(get(), JSON.stringify(request), JSON.stringify(response)));
|
|
334
|
+
},
|
|
335
|
+
};
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
/** A built-in dialect (`jev`, `clef`, `gemini`, `openai`, `systemone`) as JSON, to read or extend. */
|
|
339
|
+
export async function dialect(name, { wasm } = {}) {
|
|
340
|
+
await initialize(wasm);
|
|
341
|
+
return unwrap(core.dialect(name));
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
/** Validates a dialect and expands `extends`; throws `LetsDecideError` on a bad one. */
|
|
345
|
+
export async function resolveDialect(spec, { wasm } = {}) {
|
|
346
|
+
await initialize(wasm);
|
|
347
|
+
return unwrap(core.resolve_dialect(JSON.stringify(spec)));
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
/**
|
|
351
|
+
* A deterministic engine for tests: no network, no keys. Answers each question with
|
|
352
|
+
* `answers[id]` if given, else a neutral answer (yes/no 0.5, first option, middle level).
|
|
353
|
+
*/
|
|
354
|
+
export function mockEngine({ answers = {}, model = "mock", probabilitySource = "provider" } = {}) {
|
|
355
|
+
return {
|
|
356
|
+
capabilities: { media: ["image/*", "audio/*", "video/*", "application/pdf"] },
|
|
357
|
+
async decide(_model, request) {
|
|
358
|
+
const out = {};
|
|
359
|
+
for (const [id, q] of Object.entries(request.questions)) {
|
|
360
|
+
if (answers[id]) {
|
|
361
|
+
out[id] = answers[id];
|
|
362
|
+
} else if (q.kind === "yesno") {
|
|
363
|
+
out[id] = { kind: "yesno", probability: 0.5 };
|
|
364
|
+
} else {
|
|
365
|
+
const ids = q.kind === "choice" ? Object.keys(q.options).sort() : q.levels.map((l) => l.id);
|
|
366
|
+
const p = 1 / ids.length;
|
|
367
|
+
const probabilities = Object.fromEntries(ids.map((i) => [i, p]));
|
|
368
|
+
out[id] = q.kind === "choice"
|
|
369
|
+
? { kind: "choice", choice: ids[0], confidence: p, probabilities }
|
|
370
|
+
: { kind: "score", value: (ids.length - 1) / 2, confidence: p, probabilities };
|
|
371
|
+
}
|
|
372
|
+
}
|
|
373
|
+
return { model, answers: out, input_tokens: null, probability_source: probabilitySource };
|
|
374
|
+
},
|
|
375
|
+
};
|
|
376
|
+
}
|
|
377
|
+
|
|
378
|
+
export * from "./middleware.js";
|
package/middleware.d.ts
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import type { Answer, DecisionRequest, DecisionResponse, Client, LetsDecideError } from "./index.js";
|
|
2
|
+
|
|
3
|
+
export type DecideOptions = { signal?: AbortSignal };
|
|
4
|
+
export type Decide = (model: string, request: DecisionRequest, options?: DecideOptions) => Promise<DecisionResponse>;
|
|
5
|
+
export type Middleware = (next: Decide) => Decide;
|
|
6
|
+
export type Calibrator = (p: number) => number;
|
|
7
|
+
|
|
8
|
+
declare module "./index" {
|
|
9
|
+
interface DecisionResponse {
|
|
10
|
+
/** Calls made, including failed ones. Set by `retry` and `fallback`. */
|
|
11
|
+
attempts?: number;
|
|
12
|
+
/** The requested model, when a fallback model answered. */
|
|
13
|
+
fellBackFrom?: string;
|
|
14
|
+
/** The requested model, when a hedged call answered. */
|
|
15
|
+
hedgedFrom?: string;
|
|
16
|
+
/** Number of requests `split` sent. */
|
|
17
|
+
parts?: number;
|
|
18
|
+
/** Set by `split` when parts were answered by different models. */
|
|
19
|
+
models?: string[];
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export type Calibrated = { probability: number } | { probabilities: Record<string, number>; confidence: number };
|
|
24
|
+
export type CalibratedAnswer = Answer & { calibrated?: Calibrated };
|
|
25
|
+
|
|
26
|
+
export interface Comparison {
|
|
27
|
+
/** Share of comparable questions that agree; `null` when none are comparable. */
|
|
28
|
+
agreement: number | null;
|
|
29
|
+
questions: Record<string, { agree: boolean; delta?: number }>;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface ShadowResult {
|
|
33
|
+
model: string;
|
|
34
|
+
shadowModel: string;
|
|
35
|
+
request: DecisionRequest;
|
|
36
|
+
primary: DecisionResponse;
|
|
37
|
+
shadow?: DecisionResponse;
|
|
38
|
+
error?: LetsDecideError;
|
|
39
|
+
comparison?: Comparison;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export function compose(client: Pick<Client, "decide">, ...middleware: Middleware[]): Decide;
|
|
43
|
+
export function retry(options?: {
|
|
44
|
+
maxAttempts?: number;
|
|
45
|
+
baseMs?: number;
|
|
46
|
+
/** Longest wait, including a server `Retry-After`. Default 30000. */
|
|
47
|
+
maxMs?: number;
|
|
48
|
+
/** Injectable for tests. Should reject when `signal` aborts. */
|
|
49
|
+
sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
|
|
50
|
+
}): Middleware;
|
|
51
|
+
/** Tries `model`, then each of `models`, on retryable or `Unsupported` errors. */
|
|
52
|
+
export function fallback(models: string[]): Middleware;
|
|
53
|
+
/** Starts another call after `delayMs` (default 1000) or a recoverable failure; first answer wins. */
|
|
54
|
+
export function hedge(options?: { delayMs?: number; models?: string[] }): Middleware;
|
|
55
|
+
/** Splits over-limit requests by question and merges the answers. */
|
|
56
|
+
export function split(options?: { maxQuestions?: number | ((model: string) => number | undefined); concurrency?: number }): Middleware;
|
|
57
|
+
/** Mirrors traffic to `model` in the background and reports both answers. */
|
|
58
|
+
export function shadow(options: {
|
|
59
|
+
model: string;
|
|
60
|
+
onResult: (result: ShadowResult) => void;
|
|
61
|
+
/** Share of requests mirrored, 0..1. Default 1. */
|
|
62
|
+
sample?: number;
|
|
63
|
+
random?: () => number;
|
|
64
|
+
}): Middleware;
|
|
65
|
+
export function compare(a: DecisionResponse, b: DecisionResponse): Comparison;
|
|
66
|
+
/** Adds `calibrated` to each answer; raw values are unchanged. */
|
|
67
|
+
export function calibrate(calibrators: Calibrator | Record<string, Calibrator>): Middleware;
|
|
68
|
+
/** Isotonic fit from `[predicted, outcome]` pairs (outcome 0 or 1). */
|
|
69
|
+
export function fitIsotonic(samples: [number, number][]): Calibrator;
|
|
70
|
+
export function brierScore(samples: [number, number][]): number | null;
|
|
71
|
+
export function observe(hooks?: {
|
|
72
|
+
onStart?: (e: { model: string; request: DecisionRequest }) => void;
|
|
73
|
+
onEnd?: (e: { model: string; request: DecisionRequest; response: DecisionResponse; durationMs: number }) => void;
|
|
74
|
+
onError?: (e: { model: string; request: DecisionRequest; error: unknown; durationMs: number }) => void;
|
|
75
|
+
now?: () => number;
|
|
76
|
+
}): Middleware;
|
|
77
|
+
|
|
78
|
+
/** One model in a `fanOut`. */
|
|
79
|
+
export type FanOutMember = string | { model: string; enabled?: boolean };
|
|
80
|
+
|
|
81
|
+
/** What happened to one member. `skipped`: it can't take the request (`Unsupported`, no call made). */
|
|
82
|
+
export type FanOutResult = (
|
|
83
|
+
| { response: DecisionResponse }
|
|
84
|
+
| { error: LetsDecideError | Error }
|
|
85
|
+
| { skipped: true }
|
|
86
|
+
| { timedOut: true }
|
|
87
|
+
) & { ms: number };
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Asks several models the same request at once and returns every result, keyed by model.
|
|
91
|
+
* Nothing is merged. Bad member lists throw `RangeError` before any call.
|
|
92
|
+
*/
|
|
93
|
+
export function fanOut(
|
|
94
|
+
decide: Decide,
|
|
95
|
+
request: DecisionRequest,
|
|
96
|
+
members: FanOutMember[],
|
|
97
|
+
options?: { timeoutMs?: number; signal?: AbortSignal },
|
|
98
|
+
): Promise<Record<string, FanOutResult>>;
|