toolnexus 0.25.0 → 0.26.0

package/README.md

@@ -136,6 +136,41 @@ const out = await gate(c, state, questions, [
   filter, content and model batteries into `hooks`. A `beforeLLM` hook may return `{ model }` to
   send another model for that turn only.
 
+### Backends, images, cache and helpers
+
+Every default below is a **proposed default, owner to confirm**
+(`openspec/changes/add-classifier-backends`).
+
+```ts
+import { createClassifier, judge, MemoryCache, validateDecision, thresholdBand, chunkQuestions } from "toolnexus"
+
+const c = createClassifier({ backend: "openrouter", cache: new MemoryCache(3_600_000, 1000) })
+const d = await c.state({ note: "listing", photo: { type: "image", mimeType: "image/png", data: b64 } })
+  .evaluate(judge.noul("red", "Is the object in `photo` red?"))         // fails closed on an invalid reply
+const rs = await c.states("a", "b").evaluate(judge.noul("q", "…"))      // [{ decision } | { error }], in order
+```
+
+- `backend`: `typesafe` (default) · `openrouter` (`typesafe/jev-1.14`) · `cloudflare` (`/ai/run`
+  envelope; `${CLOUDFLARE_ACCOUNT_ID}` in the URL expands at call time, errors name it unexpanded)
+  · `vercel` · `custom` (requires `baseUrl` and `supports`). The table is data:
+  `CLASSIFIER_BACKENDS`; `supports: { images }` overrides it per classifier.
+- Images (style `systemone` only): image parts in the state are lifted into `assets` (cloudflare:
+  data URLs). PNG/JPEG, 280–1568 px a side, ≤ 16 MiB each and 32 MiB per request — never resized.
+  A backend without image support throws `ClassifierUnsupported` before any request. A state with
+  no content part is sent byte-identically to before. JS has no distinct part type, so **any**
+  object shaped like a `ContentPart` (`{type:"text",text}`, `{type:"image",mimeType,…}`) inside a
+  systemone state is treated as a part.
+- `cache: { get(key), set(key, value) }` (sync or async, string values) — off when absent; only
+  valid replies are stored; keys follow the served model. A hit sets `decision.cached` and the
+  `classifier.evaluate` event's `cached`. Every such event also carries `questions` and
+  `questionsHash`.
+- Helpers: `validateDecision(questions, decision)` → `Error | undefined`; `thresholdBand(answer,
+  thresholds?)` with `DEFAULT_THRESHOLDS` 0.8 / 0.2 / 0.6 (inclusive; `Bands` stays the `ask`/`gate`
+  default); `chunkQuestions(questions, size)`.
+- Open union: `judge.raw(name, type, instructions, criteria?)` / `raw(...)`; an answer of an
+  unmodelled type decodes to `{ type, value }` (`decision.raw(key)`).
+- `style: "llm"` is **deprecated** — it still works unchanged, with no runtime warning.
+
 ## Media generation
 
 Generate images, video and speech (plus transcription, voice cloning and talking-head video)

package/dist/classifier.d.ts

@@ -1,14 +1,3 @@
-/**
- * Classifier (SPEC.md §8B) — the contract for a JUDGMENT, as `Tool` is the contract for an
- * ACTION. A System One model takes a state plus pre-declared, typed questions and returns
- * calibrated answers with no free text. It has no messages, no tool calling and no streaming,
- * so it never enters the §8 client loop.
- *
- * A classifier INTERPRETS; it never AUTHORISES. Schema validity is not correctness: a decision
- * can be confidently wrong, and "cannot hallucinate" means only that the returned value is in
- * the declared schema. Numeric limits, permission checks and allowlists stay in code. Nothing
- * here is a security control.
- */
 import type { Client } from "./client.js";
 import { type ErrorInfo, type ErrorTier, type MetricEvent } from "./client.js";
 /** The System One endpoint base. */
@@ -24,15 +13,50 @@ export declare const DEFAULT_BATCH_CONCURRENCY = 16;
 /**
  * A named BACKEND: `baseUrl`, `model` and `apiKeyEnv` are only jointly valid, so they travel as
  * a UNIT (ADR 0027 D1). `jev-latest` is TypeSafe's spelling; the gateway spells the same model
- * `typesafe/jev-1.13`, and mixing the two is issue #91.
+ * `typesafe/jev-1.14`, and mixing the two is issue #91. `custom` is a self-hosted System One
+ * endpoint and requires `baseUrl` + `supports` (SPEC §8B "Backends, images, cache and validation").
  */
-export type ClassifierBackend = "typesafe" | "openrouter";
-/** The two servable pairings, as configurations rather than six independently-choosable cells. */
-export declare const CLASSIFIER_BACKENDS: Readonly<Record<ClassifierBackend, {
+export type ClassifierBackend = "typesafe" | "openrouter" | "cloudflare" | "vercel" | "custom";
+/** What a backend+model can take. DATA: a fail-fast for what the table says, never a claim about
+ * the vendor. Override per classifier with `ClassifierOptions.supports`. */
+export interface ClassifierSupports {
+    images: boolean;
+}
+/** One row of the backend table. */
+export interface ClassifierBackendPreset {
+    /** `""` on `custom`, which requires `baseUrl`. May carry `${NAME}`, expanded at call time. */
     baseUrl: string;
     model: string;
     apiKeyEnv: string;
-}>>;
+    /** `systemone`: POST {baseUrl}/systemone. `cloudflare`: POST {baseUrl}, `/ai/run` envelope. */
+    wire: "systemone" | "cloudflare";
+    /** Send `TypeSafe-Danger-Zone-Images: true` when a request carries images. */
+    imagesHeader: boolean;
+    /** The default support for a model on this backend; absent on `custom`. */
+    supports?: (model: string) => ClassifierSupports;
+}
+/** TypeSafe's required opt-in header for image ("danger zone") input. */
+export declare const CLASSIFIER_IMAGES_HEADER = "TypeSafe-Danger-Zone-Images";
+/** Image limits (docs.typesafe.ai/images): checked client-side, never resized. */
+export declare const CLASSIFIER_IMAGE_MIN_SIDE = 280;
+export declare const CLASSIFIER_IMAGE_MAX_SIDE = 1568;
+export declare const CLASSIFIER_IMAGE_MAX_BYTES: number;
+export declare const CLASSIFIER_REQUEST_IMAGE_BYTES: number;
+/**
+ * The backend table (PROPOSED defaults, owner to confirm — design.md PD-1..PD-4). Vercel and
+ * Cloudflare-Jev images stay false until a live probe proves them.
+ */
+export declare const CLASSIFIER_BACKENDS: Readonly<Record<ClassifierBackend, Readonly<ClassifierBackendPreset>>>;
+/**
+ * Raised BEFORE any network call when the backend table says the backend cannot take what the
+ * request carries. Message, exact: `classifier: <backend> (<model>) does not support <feature>`.
+ */
+export declare class ClassifierUnsupported extends Error {
+    readonly backend: string;
+    readonly model: string;
+    readonly feature: string;
+    constructor(backend: string, model: string, feature: string);
+}
 /** Client-side cap on a choice's named options (§8B). */
 export declare const MAX_CHOICE_OPTIONS = 255;
 /** Bounds of a score rubric (§8B). */
@@ -83,8 +107,25 @@ export interface ScoreQuestion {
     instructions: string;
     criteria: string[];
 }
-/** The closed set of question types, discriminated by `type`. */
+/** The modelled question types, discriminated by `type`. */
 export type Question = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+/**
+ * The OPEN end of the question union (§8B): a System One type the library does not model (e.g.
+ * Jev 1.14 `box`), sent as written with no client-side limits. `type` must be non-empty.
+ */
+export interface RawQuestion {
+    type: string;
+    instructions: string;
+    /** Sent verbatim when present, absent otherwise. */
+    criteria?: unknown;
+}
+/** Every question `evaluate` accepts: the modelled three plus a raw one. */
+export type AnyQuestion = Question | RawQuestion;
+/** True when `q` is a raw question (its type is not noul/choice/score). Not a type guard: every
+ * modelled question is structurally a `RawQuestion` too. */
+export declare function isRawQuestion(q: AnyQuestion): boolean;
+/** A raw question, sent as written. */
+export declare function raw(type: string, instructions: string, criteria?: unknown): RawQuestion;
 /** A noul question. Pass `criteria` only when you mean it — absent ≠ empty on the wire. */
 export declare function noul(instructions: string, criteria?: NoulCriteria): NoulQuestion;
 /** A choice question. Every description must say what picking that option would MEAN. */
@@ -98,7 +139,7 @@ export declare function score(instructions: string, criteria: string[]): ScoreQu
  */
 export declare function choiceOver(instructions: string, items: Record<string, string>): ChoiceQuestion;
 /** The wire form of one question — the object itself, minus an absent `criteria`. */
-export declare function questionWire(q: Question): Record<string, unknown>;
+export declare function questionWire(question: AnyQuestion): Record<string, unknown>;
 /**
  * Canonical JSON: object keys sorted recursively in CODE-UNIT (ASCII) order, arrays NEVER
  * reordered, compact separators, and `<>&'"` plus non-ASCII transmitted raw.
@@ -120,7 +161,7 @@ export declare function canonicalJson(value: unknown): string;
  * ways across our own seven runtimes). Do not re-widen this: a caller who needs their state
  * pinned canonicalises it themselves before handing it over.
  */
-export declare function canonicalRequest(model: string, questions: Record<string, Question>): string;
+export declare function canonicalRequest(model: string, questions: Record<string, AnyQuestion>): string;
 /** The probability that a statement holds. NO confidence: the number is the answer. */
 export interface NoulAnswer {
     type: "noul";
@@ -155,6 +196,18 @@ export interface ScoreAnswer {
  * `Answer` (the suspension resolution) — same idea, different seam.
  */
 export type DecisionAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+/**
+ * An answer of a type the library does not model (the open union, §8B). It may appear in
+ * `Decision.answers` at runtime (read it with `decision.raw(key)` or `isRawAnswer`); `value` is the
+ * whole answer object as decoded, `type` included. It is kept out of `DecisionAnswer` so existing
+ * `switch (a.type)` narrowing keeps compiling.
+ */
+export interface RawAnswer {
+    type: string;
+    value: Record<string, unknown>;
+}
+/** True when an answer is a raw (unmodelled-type) answer. */
+export declare function isRawAnswer(a: unknown): a is RawAnswer;
 /** The wire's usage block. `cost` is absent on some backends. */
 export interface ClassifierUsage {
     inputTokens: number;
@@ -178,6 +231,8 @@ export declare class Decision {
      * BACKEND DOES NOT TRANSFER TO ANOTHER.
      */
     readonly calibrated: boolean;
+    /** True when the decision came from `ClassifierOptions.cache` and no request was sent. */
+    readonly cached: boolean;
     constructor(
     /** What actually answered, which may be more specific than the model that was asked for. */
     model: string, answers: Record<string, DecisionAnswer>, usage: ClassifierUsage, 
@@ -186,7 +241,11 @@ export declare class Decision {
      * unless it derived them from provider token probabilities. A THRESHOLD TUNED AGAINST ONE
      * BACKEND DOES NOT TRANSFER TO ANOTHER.
      */
-    calibrated: boolean);
+    calibrated: boolean, 
+    /** True when the decision came from `ClassifierOptions.cache` and no request was sent. */
+    cached?: boolean);
+    /** Typed read of a raw (unmodelled-type) answer. Throws on an absent key or a modelled type. */
+    raw(key: string): RawAnswer;
     /** Typed read. Throws (never returns undefined) on a wrong-type or absent key. */
     noul(key: string): NoulAnswer;
     choice(key: string): ChoiceAnswer;
@@ -210,7 +269,12 @@ export declare function nearUniform(probabilities: Record<string, number>): bool
  * `nearUniform` is derived. A malformed answer is an error, never a repaired one (ADR 0020).
  */
 export declare function decodeDecision(raw: unknown, fallbackModel: string): Decision;
-/** `"systemone" | "llm" | "custom" | "static"` — the same slot as the client's `style`. */
+/**
+ * `"systemone" | "llm" | "custom" | "static"` — the same slot as the client's `style`.
+ *
+ * `"llm"` is DEPRECATED (ADR 0038 D3: System One is the single product wire). It keeps working
+ * byte-identically, as an alias, for at least one minor release; there is no runtime warning.
+ */
 export type ClassifierStyle = "systemone" | "llm" | "custom" | "static";
 /**
  * One entry of the `static` corpus. It is keyed on the canonical request AND the state: several
@@ -220,12 +284,12 @@ export type ClassifierStyle = "systemone" | "llm" | "custom" | "static";
  */
 export interface RecordedDecision {
     state: unknown;
-    questions: Record<string, Question>;
+    questions: Record<string, AnyQuestion>;
     /** The recorded backend response body, verbatim. */
     response: unknown;
 }
 /** The host's own backend (`style: "custom"`). Every wire option is ignored. */
-export type EvaluateFn = (state: unknown, questions: Record<string, Question>, signal?: AbortSignal) => Promise<Decision> | Decision;
+export type EvaluateFn = (state: unknown, questions: Record<string, AnyQuestion>, signal?: AbortSignal) => Promise<Decision> | Decision;
 /**
  * Mirrors §8 `ClientOptions` field-for-field wherever a field makes sense, so a host that has
  * configured one has configured the other.
@@ -233,7 +297,7 @@ export type EvaluateFn = (state: unknown, questions: Record<string, Question>, s
 export interface ClassifierOptions {
     /** Default `"systemone"`. */
     style?: ClassifierStyle;
-    /** A named `baseUrl` + `model` + `apiKeyEnv` pairing (`"typesafe"` | `"openrouter"`), set as a
+    /** A named backend row (`"typesafe"` | `"openrouter"` | `"cloudflare"` | `"vercel"` | `"custom"`), set as a
      * UNIT. Default `"typesafe"`. The three individual options still win where given, for a
      * self-hosted origin — but a known-bad mixture is refused at construction, not 700 ms later
      * as an "Unknown model" 400. */
@@ -277,12 +341,34 @@ export interface ClassifierOptions {
     /** Emits `classifier.evaluate` events into the SAME §8 sink, and carries the
      * degenerate-criteria warning as `classifier.warning`. */
     onMetric?: (ev: MetricEvent) => void;
-    /** `style: "llm"` only — the §8 Client to emulate over. */
+    /** `style: "llm"` only — the §8 Client to emulate over.
+     * @deprecated `style: "llm"` is deprecated (System One is the single wire); it still works. */
     client?: Client;
     /** `style: "custom"` only — the host's own function. */
     evaluate?: EvaluateFn;
     /** `style: "static"` only — the recorded corpus. */
     decisions?: RecordedDecision[];
+    /** Overrides the backend table's support row for this classifier. Required with `backend: "custom"`. */
+    supports?: ClassifierSupports;
+    /** Opt-in answer cache (§8B). Absent ⇒ no caching. Consulted by style `systemone` only; only
+     * replies that pass `validateDecision` are stored. Methods may return values or Promises. */
+    cache?: ClassifierCache;
+}
+/** An injected answer cache. Values are opaque strings: the served model under a model key, the
+ * System One reply body under a decision key. */
+export interface ClassifierCache {
+    get(key: string): string | undefined | null | Promise<string | undefined | null>;
+    set(key: string, value: string): void | Promise<void>;
+}
+/** One state's outcome from `states(...).evaluate`: exactly one of `decision` / `error` is set. */
+export interface BatchResult {
+    decision?: Decision;
+    error?: Error;
+}
+/** A named question (`judge.noul(...)` etc. build these). */
+export interface NamedClassifierQuestion {
+    name: string;
+    question: AnyQuestion;
 }
 /** The whole seam: one verb. */
 export declare class Classifier {
@@ -292,6 +378,9 @@ export declare class Classifier {
     private readonly model;
     private readonly apiKeyEnv;
     private readonly timeoutMs;
+    private readonly backend;
+    private readonly preset;
+    private readonly supports;
     private readonly corpus;
     /** The once-per-question-key set for the degenerate warning, so a per-turn judge does not
      * flood the sink. */
@@ -301,14 +390,33 @@ export declare class Classifier {
      * The whole contract: a state plus typed questions in, a Decision out. Questions are
      * INDEPENDENT — one answer is never context for another.
      */
-    evaluate(state: unknown, questions: Record<string, Question>, signal?: AbortSignal): Promise<Decision>;
+    evaluate(state: unknown, questions: Record<string, AnyQuestion>, signal?: AbortSignal): Promise<Decision>;
+    /**
+     * Binds one state (a VALUE, not a session: nothing is sent until `evaluate`). Its `evaluate`
+     * runs the same path as `evaluate` PLUS fail-closed validation (`validateDecision`).
+     */
+    state(value: unknown, opts?: {
+        signal?: AbortSignal;
+    }): {
+        evaluate(...questions: NamedClassifierQuestion[]): Promise<Decision>;
+    };
+    /**
+     * Binds a batch of states. Its `evaluate` runs `state(v).evaluate` per state, at most 16 in
+     * flight, and returns one `{decision | error}` per state IN ORDER. One state's failure never
+     * fails the batch; only a question-set error (duplicate name) throws, before any request.
+     */
+    states(...values: unknown[]): {
+        evaluate(...questions: NamedClassifierQuestion[]): Promise<BatchResult[]>;
+    };
+    /** The one path. `validate` = fail closed on `validateDecision` (the value builders). */
+    private run;
     /**
      * The same questions over many states (SPEC §8B "Batch"). Each state goes through
      * `evaluate`, at most `concurrency` (default 16) in flight; decisions come back in STATE
      * order. Fails closed: the first failing state's index is named and no decisions return.
      * No states is an error and sends nothing.
      */
-    evaluateBatch(states: readonly unknown[], questions: Record<string, Question>, opts?: {
+    evaluateBatch(states: readonly unknown[], questions: Record<string, AnyQuestion>, opts?: {
         signal?: AbortSignal;
         concurrency?: number;
     }): Promise<Decision[]>;
@@ -319,15 +427,18 @@ export declare class Classifier {
      */
     private reportDegenerate;
     /**
-     * Assembles the request: the canonical model + questions, plus state VERBATIM as the host
-     * supplied it, then the §8 Gap 1 pipeline in §8 order (base → requestParams merge →
-     * bodyTransform → marshal).
+     * Assembles the request for the backend's wire: the canonical model + questions, plus the state
+     * (VERBATIM unless it carried content parts) and, on systemone, `assets`; then the §8 Gap 1
+     * pipeline in §8 order (base → requestParams merge → bodyTransform → marshal).
      */
     private body;
     /** Identifies a recorded decision by the canonical request AND the state. */
     private staticKey;
     private evaluateStatic;
-    private evaluateSystemOne;
+    /** Lift images, apply the support table and the limits — all before any request. */
+    private prepare;
+    /** The systemone style on every backend: lift, check, cache, post, decode. */
+    private evaluateWire;
     /**
      * The one POST, with the §8 retry budget, reusing the client's `ErrorInfo`/`ErrorTier`
      * classifier and the `Retry-After` delay-seconds rule verbatim.
@@ -369,3 +480,50 @@ export declare function degenerateCriteria(criteria: Record<string, string>): st
  * with, or `""` when the pairing is fine.
  */
 export declare function backendMismatch(baseUrl: string, model: string): string;
+/** §8B model key: which model an endpoint + requested model (alias) served last. */
+export declare function classifierModelCacheKey(endpoint: string, model: string): string;
+/** §8B decision key, on the SERVED model. No assets ⇒ the `assets` member is omitted. */
+export declare function classifierDecisionCacheKey(endpoint: string, servedModel: string, state: unknown, assets: Record<string, unknown> | undefined, questions: Record<string, AnyQuestion>): string;
+/** The canonical JSON a decision key hashes (exported for conformance tests). */
+export declare function classifierDecisionCacheKeyBytes(endpoint: string, servedModel: string, state: unknown, assets: Record<string, unknown> | undefined, questions: Record<string, AnyQuestion>): string;
+/**
+ * In-process TTL cache with a size cap (oldest-inserted out first). `ttlMs` 0 = no expiry; `max`
+ * 0 = unbounded. toolnexus persists nothing itself: implement `ClassifierCache` to persist.
+ */
+export declare class MemoryCache implements ClassifierCache {
+    readonly ttlMs: number;
+    readonly max: number;
+    private readonly now;
+    private readonly m;
+    constructor(ttlMs?: number, max?: number, now?: () => number);
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    get size(): number;
+}
+/**
+ * V1: fail closed on a reply that does not answer exactly the questions asked, within their
+ * schema. First failure wins, in the §8B order. Returns the error, or undefined when valid.
+ */
+export declare function validateDecision(questions: Record<string, AnyQuestion>, decision: {
+    answers: Record<string, unknown>;
+}): Error | undefined;
+/** jevx's INCLUSIVE cut-points (T1). They sit alongside `Bands` (exclusive), which stays the
+ * default of `ask` / `gate`. */
+export interface Thresholds {
+    yes: number;
+    no: number;
+    minConfidence: number;
+}
+/** 0.8 / 0.2 / 0.6 (jevx's builtin profile). */
+export declare const DEFAULT_THRESHOLDS: Readonly<Thresholds>;
+/**
+ * The band of one answer under `Thresholds`: noul `p >= yes` ⇒ yes, `p <= no` ⇒ no, else
+ * uncertain; choice/score `confidence >= minConfidence` ⇒ yes, else uncertain. No near-uniform
+ * demotion (that is `Bands`' rule). A raw answer is uncertain.
+ */
+export declare function thresholdBand(answer: DecisionAnswer | RawAnswer, t?: Thresholds): "yes" | "no" | "uncertain";
+/**
+ * Split a question set into chunks of `size`, keys in ASCII order. A helper, not automatic:
+ * joint calibration across a split is unproven, so the host decides to split and merges.
+ */
+export declare function chunkQuestions<Q extends AnyQuestion>(questions: Record<string, Q>, size: number): Record<string, Q>[];