@molecule/api-ai-decisions-jeff 1.0.0

package/dist/index.js

@@ -0,0 +1,78 @@
+/**
+ * Jeff decisions provider for molecule.dev — typed decisions from the
+ * open-weights Jeff models on a `jeff-serve` host you run.
+ *
+ * Jeff (github.com/firelex/jeff; code MIT, weights Apache-2.0) is a family of
+ * fine-tunes of Qwen3.5-0.8B, Qwen3.5-2B and Gemma 4 E2B that answer
+ * `choice`, `score` and yes/no questions with a probability per option — no
+ * text generation. Its maker reports ~22 ms per request for the 0.8B on an
+ * NVIDIA RTX PRO 6000 and ~28 ms on an Apple M4 Max. `jeff-serve` speaks
+ * TypeSafe Jev's `/v1/systemone` protocol, so swapping to
+ * `@molecule/api-ai-decisions-jev` or `-laya` is a one-line change.
+ *
+ * @example
+ * ```bash
+ * # Run the model server (NVIDIA GPU, or Apple silicon with JEFF_BACKEND=mlx)
+ * git clone https://github.com/firelex/jeff && cd jeff && uv sync
+ * uv hf download mstrasser/Jeff-Qwen3.5-0.8B --local-dir checkpoints/jeff-0.8b
+ * JEFF_API_KEY=change-me JEFF_CHECKPOINT=checkpoints/jeff-0.8b PORT=8000 uv run jeff-serve
+ * ```
+ *
+ * ```typescript
+ * import { setProvider, requireProvider } from '@molecule/api-ai-decisions'
+ * import { provider } from '@molecule/api-ai-decisions-jeff'
+ *
+ * setProvider(provider) // reads JEFF_URL + JEFF_API_KEY on first use
+ *
+ * const { answers } = await requireProvider().decide({
+ *   state: 'My card was charged twice, please refund one of them',
+ *   questions: {
+ *     queue: { type: 'choice', instructions: 'Which team?', criteria: { billing: 'charges, refunds', tech: 'bugs, login' } },
+ *     refund: { type: 'yesNo', instructions: 'The customer wants a refund.' },
+ *   },
+ * })
+ * answers.queue.choice       // 'billing'
+ * answers.refund.probability // 0.95
+ * ```
+ *
+ * @remarks
+ * - **You run the model.** `JEFF_URL` (default `http://localhost:8000`) points
+ *   at a `jeff-serve` host. Its code defaults to port 8000 but its README
+ *   examples use `PORT=8765` — set `JEFF_URL` to match. `jeff-serve` binds
+ *   `127.0.0.1` unless you set `JEFF_HOST`. Set `JEFF_API_KEY` on BOTH sides to
+ *   require a bearer token; without it anyone who can reach the server can use it.
+ * - **`model` is required on the wire and is NOT a checkpoint picker.** The
+ *   server accepts only `'jeff'`, `'jeff-latest'` (the default here) or its own
+ *   name, rejects anything else with a 422, and always answers with the ONE
+ *   checkpoint it loaded (`JEFF_CHECKPOINT`). Never pass a Jev model id. Run a
+ *   second server to use a second checkpoint.
+ * - **At most 26 `choice` options** with the released checkpoints (options are
+ *   coded A–Z; the server refuses more). `score` takes 2–10 levels. This bond
+ *   refuses both before sending — shortlist long option lists first. Raise
+ *   `createProvider({ maxOptions })` only for a checkpoint whose `/health`
+ *   reports a higher `max_options`.
+ * - **One request at a time.** A busy server answers 529 + `Retry-After: 1`
+ *   and a loading one 503; this bond retries 429/502/503/504/529 up to 3 times.
+ *   Errors carry the HTTP `status`.
+ * - **English text only.** Use `@molecule/api-ai-decisions-laya`'s multilingual
+ *   checkpoint for other languages.
+ * - **Images:** up to 4 PNG/JPEG/WebP `images` are forwarded, but only the
+ *   PyTorch backend reads them (`/health` → `modalities`); the Apple MLX
+ *   backend is text-only, and the maker publishes no image accuracy figures.
+ *   For image questions prefer `@molecule/api-ai-decisions-intern-decision`.
+ * - **Small models don't reason.** Expect fast choices between options you
+ *   describe, not multi-step logic (the 0.8B scores 68% on BIG-Bench Hard vs
+ *   Jev's 94%). Describe each option's consequences in plain words.
+ * - **Calibrate on your own data.** The checkpoints carry one fitted
+ *   temperature from the maker's training mix; recalibrate on labelled samples
+ *   of your inputs and gate on `minConfidence`. See the core's remarks.
+ * - Use the core's `setProvider`, not `bond('ai-decisions', …)` directly.
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+export * from './wire.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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"}

package/dist/provider.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Jeff implementation of `AIDecisionsProvider`.
+ *
+ * Talks to a self-hosted `jeff-serve` over its `POST /v1/systemone` route
+ * (the TypeSafe Jev wire protocol), so the open-weights Jeff models answer
+ * typed decisions on your own hardware.
+ *
+ * @module
+ */
+import './secrets.js';
+import type { AIDecisionsProvider } from '@molecule/api-ai-decisions';
+import type { JeffConfig } from './types.js';
+/** `jeff-serve`'s default bind (`PORT` defaults to 8000; its README examples use 8765). */
+export declare const DEFAULT_JEFF_URL = "http://localhost:8000";
+/** A model id every `jeff-serve` accepts; it answers with the checkpoint it loaded. */
+export declare const DEFAULT_JEFF_MODEL = "jeff-latest";
+/** Most `choice` options the released Jeff checkpoints answer (options are coded A–Z). */
+export declare const DEFAULT_JEFF_MAX_OPTIONS = 26;
+/** `jeff-serve`'s bounds on a `score` question's levels. */
+export declare const JEFF_SCORE_LEVELS: {
+    readonly min: 2;
+    readonly max: 10;
+};
+/** Most images `jeff-serve` accepts per request. */
+export declare const JEFF_MAX_IMAGES = 4;
+/** Image media types `jeff-serve` decodes. */
+export declare const JEFF_IMAGE_TYPES: readonly string[];
+/**
+ * Creates a Jeff decisions provider.
+ *
+ * @param config - Base URL, API key, model id and option limit.
+ * @returns An `AIDecisionsProvider` backed by a `jeff-serve` host.
+ */
+export declare function createProvider(config?: JeffConfig): AIDecisionsProvider;
+/**
+ * The provider implementation — lazy, so env vars are read on first use.
+ */
+export declare const provider: AIDecisionsProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EACV,mBAAmB,EAKpB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAG5C,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB,0BAA0B,CAAA;AAEvD,uFAAuF;AACvF,eAAO,MAAM,kBAAkB,gBAAgB,CAAA;AAE/C,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAE1C,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB;;;CAA+B,CAAA;AAE7D,oDAAoD;AACpD,eAAO,MAAM,eAAe,IAAI,CAAA;AAEhC,8CAA8C;AAC9C,eAAO,MAAM,gBAAgB,EAAE,SAAS,MAAM,EAA8C,CAAA;AAwG5F;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,mBAAmB,CAEvE;AAGD;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,mBASrB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,135 @@
+/**
+ * Jeff implementation of `AIDecisionsProvider`.
+ *
+ * Talks to a self-hosted `jeff-serve` over its `POST /v1/systemone` route
+ * (the TypeSafe Jev wire protocol), so the open-weights Jeff models answer
+ * typed decisions on your own hardware.
+ *
+ * @module
+ */
+// Side-effect import: registers this bond's secret definitions.
+import './secrets.js';
+import { fromWireResponse, postSystemOne, toWireQuestions } from './wire.js';
+/** `jeff-serve`'s default bind (`PORT` defaults to 8000; its README examples use 8765). */
+export const DEFAULT_JEFF_URL = 'http://localhost:8000';
+/** A model id every `jeff-serve` accepts; it answers with the checkpoint it loaded. */
+export const DEFAULT_JEFF_MODEL = 'jeff-latest';
+/** Most `choice` options the released Jeff checkpoints answer (options are coded A–Z). */
+export const DEFAULT_JEFF_MAX_OPTIONS = 26;
+/** `jeff-serve`'s bounds on a `score` question's levels. */
+export const JEFF_SCORE_LEVELS = { min: 2, max: 10 };
+/** Most images `jeff-serve` accepts per request. */
+export const JEFF_MAX_IMAGES = 4;
+/** Image media types `jeff-serve` decodes. */
+export const JEFF_IMAGE_TYPES = ['image/png', 'image/jpeg', 'image/webp'];
+/**
+ * Refuses, before any request, what `jeff-serve` would reject with a bare 422:
+ * too many `choice` options, a `score` outside 2–10 levels, too many or
+ * unsupported images.
+ *
+ * @param questions - The questions keyed by id.
+ * @param images - The images, if any.
+ * @param maxOptions - Most `choice` options the checkpoint answers.
+ */
+function checkLimits(questions, images, maxOptions) {
+    for (const [id, q] of Object.entries(questions)) {
+        if (q.type === 'choice') {
+            const count = Object.keys(q.criteria ?? {}).length;
+            if (count < 1 || count > maxOptions) {
+                throw new Error(`ai-decisions-jeff: question "${id}" has ${count} options; Jeff answers 1–${maxOptions}. Shortlist the options first, or split the question.`);
+            }
+        }
+        else if (q.type === 'score') {
+            const count = q.criteria?.length ?? 0;
+            if (count < JEFF_SCORE_LEVELS.min || count > JEFF_SCORE_LEVELS.max) {
+                throw new Error(`ai-decisions-jeff: question "${id}" has ${count} score levels; Jeff answers ${JEFF_SCORE_LEVELS.min}–${JEFF_SCORE_LEVELS.max}.`);
+            }
+        }
+    }
+    if (images.length > JEFF_MAX_IMAGES) {
+        throw new Error(`ai-decisions-jeff: ${images.length} images passed; jeff-serve accepts at most ${JEFF_MAX_IMAGES}.`);
+    }
+    for (const image of images) {
+        if (!JEFF_IMAGE_TYPES.includes(image.mimeType)) {
+            throw new Error(`ai-decisions-jeff: image type "${image.mimeType}" is not supported; use ${JEFF_IMAGE_TYPES.join(', ')}.`);
+        }
+    }
+}
+/**
+ * Jeff decisions provider over HTTP.
+ */
+class JeffDecisionsProvider {
+    name = 'jeff';
+    baseUrl;
+    apiKey;
+    model;
+    maxOptions;
+    /**
+     * Creates the provider.
+     *
+     * @param config - Provider configuration; env vars fill anything omitted.
+     */
+    constructor(config = {}) {
+        this.baseUrl = (config.baseUrl || process.env.JEFF_URL || DEFAULT_JEFF_URL).replace(/\/+$/, '');
+        this.apiKey = config.apiKey ?? (process.env.JEFF_API_KEY || undefined);
+        this.model = config.model || DEFAULT_JEFF_MODEL;
+        this.maxOptions = config.maxOptions ?? DEFAULT_JEFF_MAX_OPTIONS;
+    }
+    /**
+     * Answers every question about `input.state` in one request.
+     *
+     * @param input - The state, questions and options.
+     * @returns One typed answer per question id.
+     */
+    async decide(input) {
+        if (input.state === undefined || input.state === null) {
+            throw new Error('ai-decisions: decide() requires a `state`');
+        }
+        if (!input.questions || Object.keys(input.questions).length === 0) {
+            throw new Error('ai-decisions: decide() requires at least one question');
+        }
+        const images = input.images ?? [];
+        checkLimits(input.questions, images, this.maxOptions);
+        const body = await postSystemOne({
+            url: `${this.baseUrl}/v1/systemone`,
+            apiKey: this.apiKey,
+            body: {
+                model: input.model || this.model,
+                state: input.state,
+                questions: toWireQuestions(input.questions),
+                ...(images.length
+                    ? { images: images.map((image) => `data:${image.mimeType};base64,${image.data}`) }
+                    : {}),
+            },
+            signal: input.signal,
+            label: 'Jeff',
+        });
+        return fromWireResponse(input.questions, body, input.minConfidence);
+    }
+}
+/**
+ * Creates a Jeff decisions provider.
+ *
+ * @param config - Base URL, API key, model id and option limit.
+ * @returns An `AIDecisionsProvider` backed by a `jeff-serve` host.
+ */
+export function createProvider(config) {
+    return new JeffDecisionsProvider(config);
+}
+let _provider = null;
+/**
+ * The provider implementation — lazy, so env vars are read on first use.
+ */
+export const provider = new Proxy({}, {
+    get(_, prop, receiver) {
+        if (!_provider)
+            _provider = createProvider();
+        return Reflect.get(_provider, prop, receiver);
+    },
+    set(_, prop, value) {
+        if (!_provider)
+            _provider = createProvider();
+        return Reflect.set(_provider, prop, value);
+    },
+});
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"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"}

package/dist/secrets.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Jeff secret definitions — self-registered at import time so the runtime
+ * secrets registry (`@molecule/api-secrets`) can drive boot-time configuration
+ * reports and actionable "not configured" errors.
+ *
+ * @module
+ */
+import type { SecretDefinition } from '@molecule/api-secrets';
+/** Secret definitions used by the Jeff decisions bond. */
+export declare const aiDecisionsJeffSecretDefinitions: SecretDefinition[];
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,0DAA0D;AAC1D,eAAO,MAAM,gCAAgC,EAAE,gBAAgB,EAiB9D,CAAA"}

package/dist/secrets.js

@@ -0,0 +1,27 @@
+/**
+ * Jeff secret definitions — self-registered at import time so the runtime
+ * secrets registry (`@molecule/api-secrets`) can drive boot-time configuration
+ * reports and actionable "not configured" errors.
+ *
+ * @module
+ */
+import { registerSecrets } from '@molecule/api-secrets';
+/** Secret definitions used by the Jeff decisions bond. */
+export const aiDecisionsJeffSecretDefinitions = [
+    {
+        key: 'JEFF_URL',
+        description: 'Jeff server URL — 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.',
+        helpUrl: 'https://github.com/firelex/jeff#readme',
+        required: false,
+        example: 'http://localhost:8000',
+    },
+    {
+        key: 'JEFF_API_KEY',
+        description: 'Jeff server API key — The bearer token your jeff-serve host requires, if you set JEFF_API_KEY on the server.',
+        helpUrl: 'https://github.com/firelex/jeff#readme',
+        required: false,
+        example: 'a-long-random-string',
+    },
+];
+registerSecrets(aiDecisionsJeffSecretDefinitions);
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,gCAAgC,GAAuB;IAClE;QACE,GAAG,EAAE,UAAU;QACf,WAAW,EACT,0MAA0M;QAC5M,OAAO,EAAE,wCAAwC;QACjD,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,uBAAuB;KACjC;IACD;QACE,GAAG,EAAE,cAAc;QACnB,WAAW,EACT,8GAA8G;QAChH,OAAO,EAAE,wCAAwC;QACjD,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,sBAAsB;KAChC;CACF,CAAA;AAED,eAAe,CAAC,gCAAgC,CAAC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Jeff decisions provider configuration.
+ *
+ * @module
+ */
+/**
+ * Configuration for the Jeff decisions provider.
+ */
+export interface JeffConfig {
+    /** Base URL of the `jeff-serve` host. Defaults to `JEFF_URL`, then `http://localhost:8000`. */
+    baseUrl?: string;
+    /** Bearer token, when the server sets `JEFF_API_KEY`. Defaults to the `JEFF_API_KEY` env var. */
+    apiKey?: string;
+    /**
+     * Model id sent on every request. `jeff-serve` REQUIRES one and accepts only
+     * `'jeff'`, `'jeff-latest'` or its own name (e.g. `'jeff-qwen3.5-0.8b'`) —
+     * it answers with whichever checkpoint it loaded. Defaults to `'jeff-latest'`.
+     */
+    model?: string;
+    /**
+     * Most `choice` options the loaded checkpoint answers (the server's `/health`
+     * reports it as `max_options`). Defaults to 26 — the Jeff models released on
+     * 2026-09-28. Raise it only for a checkpoint trained on more.
+     */
+    maxOptions?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Jeff decisions provider configuration.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/wire.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The `/v1/systemone` wire protocol (TypeSafe Jev, copied by `jeff-serve`) ↔
+ * the `@molecule/api-ai-decisions` types.
+ *
+ * Wire facts (github.com/firelex/jeff `src/jeff/server.py`, `types.py`,
+ * `model.py`): request `{ model, state, questions: { <id>: { type: 'choice'|'score'|'noul', instructions?, criteria } }, images? }`
+ * — `model` is REQUIRED and must be `jeff`, `jeff-latest` or the server's own
+ * name; `choice` criteria is `{ label: description }`, `score` criteria a list
+ * of 2–10 levels, `noul` criteria optional `{ true, false }`; `images` is up to
+ * 4 PNG/JPEG/WebP `data:` URLs. Answers carry `choice` + `probabilities` keyed
+ * by label, `score` (expected level) + `probabilities` keyed `"0".."k-1"`, or
+ * `noul` (P(true)). Vendor `confidence` fields are ignored: the core defines
+ * `confidence` as the probability of the reported answer, computed here from
+ * the distribution.
+ *
+ * @module
+ */
+import type { DecideResult, DecisionAnswer, DecisionQuestion } from '@molecule/api-ai-decisions';
+/** One question as sent on the wire. */
+export interface WireQuestion {
+    type: 'choice' | 'score' | 'noul';
+    instructions: string;
+    criteria?: Record<string, string> | string[];
+}
+/** One answer as received on the wire (only the fields we read). */
+export interface WireAnswer {
+    type?: string;
+    choice?: string;
+    score?: number;
+    noul?: number;
+    probabilities?: Record<string, number>;
+}
+/** The response body (only the fields we read). */
+export interface WireResponse {
+    model?: string;
+    answers?: Record<string, WireAnswer>;
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+    };
+}
+/**
+ * Converts the core's questions into wire questions (`yesNo` → `noul`).
+ *
+ * @param questions - The questions keyed by id.
+ * @returns The wire `questions` object.
+ */
+export declare function toWireQuestions(questions: Record<string, DecisionQuestion>): Record<string, WireQuestion>;
+/**
+ * Converts one wire answer into the core's answer for `question`.
+ *
+ * @param id - The question id (for error messages).
+ * @param question - The question that was asked.
+ * @param wire - The wire answer.
+ * @param minConfidence - Optional low-confidence threshold.
+ * @returns The typed answer.
+ */
+export declare function fromWireAnswer(id: string, question: DecisionQuestion, wire: WireAnswer | undefined, minConfidence?: number): DecisionAnswer;
+/**
+ * Converts a whole wire response into the core's result.
+ *
+ * @param questions - The questions that were asked.
+ * @param body - The parsed response body.
+ * @param minConfidence - Optional low-confidence threshold.
+ * @returns The typed result.
+ */
+export declare function fromWireResponse<Q extends Record<string, DecisionQuestion>>(questions: Q, body: WireResponse, minConfidence?: number): DecideResult<Q>;
+/** Options for {@link postSystemOne}. */
+export interface PostOptions {
+    /** Full endpoint URL. */
+    url: string;
+    /** Bearer token, if any. */
+    apiKey?: string;
+    /** Request body. */
+    body: Record<string, unknown>;
+    /** Abort signal. */
+    signal?: AbortSignal;
+    /** Label for error messages (`'Jeff'`). */
+    label: string;
+    /** Max retries on a retryable status (default 3). */
+    maxRetries?: number;
+}
+/**
+ * POSTs a `/v1/systemone` request with retry on 429/5xx-busy, honouring
+ * `Retry-After`. Throws an Error carrying `status` on a non-2xx response.
+ *
+ * @param opts - Request options.
+ * @returns The parsed response body.
+ */
+export declare function postSystemOne(opts: PostOptions): Promise<WireResponse>;
+//# sourceMappingURL=wire.d.ts.map

package/dist/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../src/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAEV,YAAY,EACZ,cAAc,EACd,gBAAgB,EAGjB,MAAM,4BAA4B,CAAA;AAEnC,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;IACjC,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAAA;CAC7C;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACvC;AAED,mDAAmD;AACnD,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACpC,KAAK,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC1D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAC1C,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAuB9B;AAKD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,gBAAgB,EAC1B,IAAI,EAAE,UAAU,GAAG,SAAS,EAC5B,aAAa,CAAC,EAAE,MAAM,GACrB,cAAc,CAiDhB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EACzE,SAAS,EAAE,CAAC,EACZ,IAAI,EAAE,YAAY,EAClB,aAAa,CAAC,EAAE,MAAM,GACrB,YAAY,CAAC,CAAC,CAAC,CAiBjB;AAKD,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,oBAAoB;IACpB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CA8C5E"}

package/dist/wire.js

@@ -0,0 +1,198 @@
+/**
+ * The `/v1/systemone` wire protocol (TypeSafe Jev, copied by `jeff-serve`) ↔
+ * the `@molecule/api-ai-decisions` types.
+ *
+ * Wire facts (github.com/firelex/jeff `src/jeff/server.py`, `types.py`,
+ * `model.py`): request `{ model, state, questions: { <id>: { type: 'choice'|'score'|'noul', instructions?, criteria } }, images? }`
+ * — `model` is REQUIRED and must be `jeff`, `jeff-latest` or the server's own
+ * name; `choice` criteria is `{ label: description }`, `score` criteria a list
+ * of 2–10 levels, `noul` criteria optional `{ true, false }`; `images` is up to
+ * 4 PNG/JPEG/WebP `data:` URLs. Answers carry `choice` + `probabilities` keyed
+ * by label, `score` (expected level) + `probabilities` keyed `"0".."k-1"`, or
+ * `noul` (P(true)). Vendor `confidence` fields are ignored: the core defines
+ * `confidence` as the probability of the reported answer, computed here from
+ * the distribution.
+ *
+ * @module
+ */
+/**
+ * Converts the core's questions into wire questions (`yesNo` → `noul`).
+ *
+ * @param questions - The questions keyed by id.
+ * @returns The wire `questions` object.
+ */
+export function toWireQuestions(questions) {
+    const out = {};
+    for (const [id, q] of Object.entries(questions)) {
+        if (q.type === 'choice') {
+            out[id] = { type: 'choice', instructions: q.instructions, criteria: q.criteria };
+        }
+        else if (q.type === 'score') {
+            out[id] = { type: 'score', instructions: q.instructions, criteria: q.criteria };
+        }
+        else if (q.type === 'yesNo') {
+            const criteria = {};
+            if (q.criteria?.yes)
+                criteria.true = q.criteria.yes;
+            if (q.criteria?.no)
+                criteria.false = q.criteria.no;
+            out[id] = {
+                type: 'noul',
+                instructions: q.instructions,
+                ...(Object.keys(criteria).length ? { criteria } : {}),
+            };
+        }
+        else {
+            throw new Error(`ai-decisions: question "${id}" has unknown type "${q.type}"`);
+        }
+    }
+    return out;
+}
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const clamp01 = (v) => Math.max(0, Math.min(1, v));
+/**
+ * Converts one wire answer into the core's answer for `question`.
+ *
+ * @param id - The question id (for error messages).
+ * @param question - The question that was asked.
+ * @param wire - The wire answer.
+ * @param minConfidence - Optional low-confidence threshold.
+ * @returns The typed answer.
+ */
+export function fromWireAnswer(id, question, wire, minConfidence) {
+    if (!wire || typeof wire !== 'object') {
+        throw new Error(`ai-decisions: the provider returned no answer for question "${id}"`);
+    }
+    let answer;
+    if (question.type === 'choice') {
+        const labels = Object.keys(question.criteria);
+        const probabilities = {};
+        for (const label of labels)
+            probabilities[label] = clamp01(num(wire.probabilities?.[label]));
+        let top = labels[0] ?? '';
+        for (const label of labels)
+            if (probabilities[label] > probabilities[top])
+                top = label;
+        const choice = typeof wire.choice === 'string' && labels.includes(wire.choice) ? wire.choice : top;
+        answer = {
+            type: 'choice',
+            choice,
+            probabilities,
+            confidence: probabilities[choice] ?? 0,
+        };
+    }
+    else if (question.type === 'score') {
+        const probabilities = question.criteria.map((_, i) => clamp01(num(wire.probabilities?.[String(i)])));
+        let level = 0;
+        probabilities.forEach((p, i) => {
+            if (p > probabilities[level])
+                level = i;
+        });
+        const expected = probabilities.reduce((sum, p, i) => sum + p * i, 0);
+        answer = {
+            type: 'score',
+            score: typeof wire.score === 'number' && Number.isFinite(wire.score) ? wire.score : expected,
+            level,
+            probabilities,
+            confidence: probabilities[level] ?? 0,
+        };
+    }
+    else {
+        if (typeof wire.noul !== 'number' || !Number.isFinite(wire.noul)) {
+            throw new Error(`ai-decisions: the provider's answer to "${id}" has no noul probability`);
+        }
+        const probability = clamp01(wire.noul);
+        answer = {
+            type: 'yesNo',
+            probability,
+            answer: probability >= 0.5,
+            confidence: Math.max(probability, 1 - probability),
+        };
+    }
+    if (typeof minConfidence === 'number')
+        answer.lowConfidence = answer.confidence < minConfidence;
+    return answer;
+}
+/**
+ * Converts a whole wire response into the core's result.
+ *
+ * @param questions - The questions that were asked.
+ * @param body - The parsed response body.
+ * @param minConfidence - Optional low-confidence threshold.
+ * @returns The typed result.
+ */
+export function fromWireResponse(questions, body, minConfidence) {
+    const answers = {};
+    for (const [id, q] of Object.entries(questions)) {
+        answers[id] = fromWireAnswer(id, q, body.answers?.[id], minConfidence);
+    }
+    return {
+        answers: answers,
+        ...(typeof body.model === 'string' ? { model: body.model } : {}),
+        ...(body.usage
+            ? {
+                usage: {
+                    inputTokens: num(body.usage.input_tokens),
+                    outputTokens: num(body.usage.output_tokens),
+                },
+            }
+            : {}),
+    };
+}
+/** Statuses worth retrying: rate limit, not ready (503), busy (`jeff-serve` 529 + Retry-After). */
+const RETRYABLE = new Set([429, 502, 503, 504, 529]);
+/**
+ * POSTs a `/v1/systemone` request with retry on 429/5xx-busy, honouring
+ * `Retry-After`. Throws an Error carrying `status` on a non-2xx response.
+ *
+ * @param opts - Request options.
+ * @returns The parsed response body.
+ */
+export async function postSystemOne(opts) {
+    const { url, apiKey, body, signal, label, maxRetries = 3 } = opts;
+    const headers = { 'content-type': 'application/json' };
+    if (apiKey)
+        headers.authorization = `Bearer ${apiKey}`;
+    for (let attempt = 0;; attempt++) {
+        const response = await fetch(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body),
+            signal,
+        });
+        if (response.ok)
+            return (await response.json());
+        if (RETRYABLE.has(response.status) && attempt < maxRetries) {
+            const retryAfter = Number(response.headers.get('retry-after'));
+            const waitMs = Number.isFinite(retryAfter) && retryAfter > 0
+                ? Math.min(retryAfter * 1000, 10_000)
+                : 250 * 2 ** attempt;
+            await new Promise((r) => setTimeout(r, waitMs));
+            continue;
+        }
+        const text = await response.text().catch(() => '');
+        let detail = text.length > 0 && text.length < 300 ? text : `HTTP ${response.status}`;
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed.detail === 'string')
+                detail = parsed.detail;
+            else if (Array.isArray(parsed.detail)) {
+                // FastAPI request validation: [{ loc, msg, type }, …]
+                detail = parsed.detail
+                    .map((item) => [Array.isArray(item.loc) ? item.loc.join('.') : '', item.msg]
+                    .filter(Boolean)
+                    .join(': '))
+                    .join('; ');
+            }
+            else if (typeof parsed.error?.message === 'string')
+                detail = parsed.error.message;
+        }
+        catch (_error) {
+            // Not JSON — keep the raw text (or the status) as the detail.
+        }
+        throw Object.assign(new Error(`${label} decision request failed (${response.status}): ${detail}`), {
+            status: response.status,
+        });
+    }
+}
+//# sourceMappingURL=wire.js.map