toolnexus 0.16.0 → 0.18.0

package/dist/classifier.d.ts

@@ -0,0 +1,334 @@
+/**
+ * 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. */
+export declare const DEFAULT_CLASSIFIER_BASE_URL = "https://api.typesafe.ai/v1";
+/** The floating model alias. Pin it (e.g. `jev-1.13.0`) once thresholds are tuned. */
+export declare const DEFAULT_CLASSIFIER_MODEL = "jev-latest";
+/** The NAME of the env var holding the credential — never the value. */
+export declare const DEFAULT_CLASSIFIER_API_KEY_ENV = "TYPESAFE_API_KEY";
+/** Bounds ONE request; a classifier has no loop to bound. */
+export declare const DEFAULT_CLASSIFIER_TIMEOUT_MS = 10000;
+/** Client-side cap on a choice's named options (§8B). */
+export declare const MAX_CHOICE_OPTIONS = 255;
+/** Bounds of a score rubric (§8B). */
+export declare const MIN_SCORE_LEVELS = 2;
+export declare const MAX_SCORE_LEVELS = 10;
+/**
+ * The ABSOLUTE tolerance on `max|p - 1/n|`, compared INCLUSIVELY (§8B). Pinned across every
+ * port; `examples/judge/near-uniform.json` pins both sides at 0.0499 / 0.0501.
+ */
+export declare const NEAR_UNIFORM_TOLERANCE = 0.05;
+/**
+ * Labels for the true and false cases of a noul question. Absent and empty are DIFFERENT values
+ * and both are preserved on the wire: omit `criteria` entirely and the field is absent; pass
+ * `{ true: "", false: "" }` and it is emitted with empty values.
+ */
+export interface NoulCriteria {
+    true: string;
+    false: string;
+}
+/** The probability that a statement holds, one number in 0..1. It carries NO confidence. */
+export interface NoulQuestion {
+    type: "noul";
+    instructions: string;
+    /** Optional. Omitted ⇒ the field is ABSENT from the request, not null and not {}. */
+    criteria?: NoulCriteria;
+}
+/**
+ * One option from a named set, 1..255 options.
+ *
+ * THE ENCODING OBLIGATION IS THE CALLER'S (§8B, docs/adr/0021 D1): `criteria[id]` is the only
+ * thing that differentiates one option from another to the model. Passing the id itself, an
+ * empty string, or one value repeated is schema-valid, returns HTTP 200 and a well-formed
+ * distribution — and ranks at chance (measured: 17 apples described by consequence, 0/1/0
+ * described by id).
+ */
+export interface ChoiceQuestion {
+    type: "choice";
+    instructions: string;
+    /** option id -> what picking it would MEAN. */
+    criteria: Record<string, string>;
+}
+/**
+ * A rating against an ORDERED rubric of 2..10 levels. The array order IS the level numbering,
+ * so it is never sorted — a "sort everything" canonicaliser silently renumbers the rubric.
+ */
+export interface ScoreQuestion {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+}
+/** The closed set of question types, discriminated by `type`. */
+export type Question = NoulQuestion | ChoiceQuestion | ScoreQuestion;
+/** 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. */
+export declare function choice(instructions: string, criteria: Record<string, string>): ChoiceQuestion;
+/** A score question. The array order IS the level numbering and is never reordered. */
+export declare function score(instructions: string, criteria: string[]): ScoreQuestion;
+/**
+ * Build a choice from any (name, description) pairs — a Tool, a skill, an agent, an A2A card
+ * skill. The description must say what picking that option would MEAN; see the encoding
+ * obligation on `ChoiceQuestion`.
+ */
+export declare function choiceOver(instructions: string, items: Record<string, string>): ChoiceQuestion;
+/**
+ * Canonical JSON: object keys sorted recursively in CODE-UNIT (ASCII) order, arrays NEVER
+ * reordered, compact separators, and `<>&'"` plus non-ASCII transmitted raw.
+ *
+ * Hand-rolled because `JSON.stringify` has no recursive key sort, and its `replacer` ARRAY form
+ * applies one key list at EVERY depth — it cannot express "sort whatever keys are here". The
+ * per-value escaping and number formatting ARE delegated to `JSON.stringify`, which emits the
+ * shortest round-tripping decimal (so 1.21 is "1.21" and integer 0 is "0", not "0.0") and does
+ * not escape `<`, `>`, `&` or non-ASCII.
+ *
+ * `undefined` is ABSENT, never `null`: an object key whose value is undefined is dropped.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * The bytes the byte-identity claim covers: `model` + `questions`.
+ *
+ * `state` is deliberately NOT here. It is transmitted verbatim as the host supplied it and is
+ * OUTSIDE the claim, because numbers do not canonicalise across languages (`-0.0` renders four
+ * 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;
+/** The probability that a statement holds. NO confidence: the number is the answer. */
+export interface NoulAnswer {
+    type: "noul";
+    noul: number;
+}
+/** One option from the offered set, with a probability for EVERY offered option. */
+export interface ChoiceAnswer {
+    type: "choice";
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence: number;
+    /**
+     * DERIVED from `probabilities` on decode and never read from the wire (§8B):
+     * `max|p - 1/n| <= 0.05`, inclusive, `n` = the number of entries in the map.
+     *
+     * ADVISORY, NOT a correctness signal. It detects an encoding that gave the model nothing to
+     * rank on — it cannot distinguish a good encoding from a subtly wrong one. `calibrated`
+     * carries the same caveat.
+     */
+    nearUniform: boolean;
+}
+/** A rating against the ordered rubric. `score` MAY fall between levels (1.21 is a real answer). */
+export interface ScoreAnswer {
+    type: "score";
+    score: number;
+    legend: Record<string, string>;
+    probabilities: Record<string, number>;
+    confidence: number;
+}
+/**
+ * One typed answer, discriminated by `type`. Named `DecisionAnswer` because §10 already owns
+ * `Answer` (the suspension resolution) — same idea, different seam.
+ */
+export type DecisionAnswer = NoulAnswer | ChoiceAnswer | ScoreAnswer;
+/** The wire's usage block. `cost` is absent on some backends. */
+export interface ClassifierUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cost?: number;
+}
+/** The legend in LEVEL order, which the map itself loses ("2" sorts before "10" as a level). */
+export declare function levels(answer: ScoreAnswer): string[];
+/**
+ * One answer per question, keyed by the CALLER's keys. The keys are addressing, not content:
+ * they are never transmitted, so a key may be a tool, skill or agent name verbatim.
+ */
+export declare class Decision {
+    /** What actually answered, which may be more specific than the model that was asked for. */
+    readonly model: string;
+    readonly answers: Record<string, DecisionAnswer>;
+    readonly usage: ClassifierUsage;
+    /**
+     * Whether the probabilities are calibrated. `systemone` reports true; `llm` reports false
+     * unless it derived them from provider token probabilities. A THRESHOLD TUNED AGAINST ONE
+     * BACKEND DOES NOT TRANSFER TO ANOTHER.
+     */
+    readonly calibrated: 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, 
+    /**
+     * Whether the probabilities are calibrated. `systemone` reports true; `llm` reports false
+     * unless it derived them from provider token probabilities. A THRESHOLD TUNED AGAINST ONE
+     * BACKEND DOES NOT TRANSFER TO ANOTHER.
+     */
+    calibrated: boolean);
+    /** Typed read. Throws (never returns undefined) on a wrong-type or absent key. */
+    noul(key: string): NoulAnswer;
+    choice(key: string): ChoiceAnswer;
+    score(key: string): ScoreAnswer;
+    private typed;
+}
+/**
+ * Whether a choice answer's probability map is indistinguishable from flat (§8B):
+ *
+ *     nearUniform  ⇔  max over i of |p_i - 1/n|  <=  0.05
+ *
+ * `n` is the number of ENTRIES IN THE MAP and the values are taken AS RETURNED — not
+ * renormalised, not sorted, not rounded; an offered option absent from the map counts as 0 by
+ * not being an entry. The tolerance is ABSOLUTE (a relative band collapses below the wire's
+ * two-decimal rounding on a 255-option roster) and the comparison is INCLUSIVE. `n === 1` is
+ * trivially uniform. An empty map has no distribution at all and is reported false.
+ */
+export declare function nearUniform(probabilities: Record<string, number>): boolean;
+/**
+ * Decode a backend response into a Decision. The discriminated decode is the single place
+ * `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`. */
+export type ClassifierStyle = "systemone" | "llm" | "custom" | "static";
+/**
+ * One entry of the `static` corpus. It is keyed on the canonical request AND the state: several
+ * recorded entries legitimately share one questions payload and differ only in state (the three
+ * guard bands of `examples/judge/decisions.json` do exactly that), so a corpus keyed on the
+ * canonical request alone cannot tell them apart.
+ */
+export interface RecordedDecision {
+    state: unknown;
+    questions: Record<string, Question>;
+    /** 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;
+/**
+ * Mirrors §8 `ClientOptions` field-for-field wherever a field makes sense, so a host that has
+ * configured one has configured the other.
+ */
+export interface ClassifierOptions {
+    /** Default `"systemone"`. */
+    style?: ClassifierStyle;
+    /** Default `https://api.typesafe.ai/v1`. OpenRouter serves this wire today. */
+    baseUrl?: string;
+    /** Default `"jev-latest"`. Pin it once thresholds are tuned. */
+    model?: string;
+    /** The NAME of the env var holding the credential, never the value — read at call time and
+     * never logged. §8's `apiKey` takes a value; this option deliberately does not. */
+    apiKeyEnv?: string;
+    /** Extra headers. Values expand `${ENV_VAR}` from the environment AT CALL TIME and are NEVER
+     * logged, identically to remote-MCP headers (§2). */
+    headers?: Record<string, string>;
+    /** Bounds ONE request (a classifier has no loop to bound). Default 10 s. */
+    timeoutMs?: number;
+    /** §8 Gap 2 injectable transport. Scope is the classifier path only. */
+    fetch?: typeof fetch;
+    /** Retries on transient errors (`408`/`429`/`500`/`502`/`503`/`504`/`529` + network). Default 2.
+     * Widen the status set with `retryableStatuses`. */
+    retries?: number;
+    /** Base backoff in ms (exponential). Default 500. */
+    retryBaseMs?: number;
+    /**
+     * Extra HTTP statuses to treat as retryable, ADDED to the default set
+     * (`429`/`500`/`502`/`503`/`504`/`529` plus `408` here). It can only widen: a host cannot remove `429` and
+     * lose `Retry-After` handling with it. This sets the DEFAULT classification; `onError` still
+     * runs per attempt and has the final say, so `onError` returning `"fail"` overrides a status
+     * listed here. Example: a Cloudflare-fronted origin that answers `520`–`527`.
+     */
+    retryableStatuses?: readonly number[];
+    /** §8 Resilience. REUSES the client's `ErrorInfo`/`ErrorTier` and the `Retry-After`
+     * delay-seconds rule verbatim — there is no second retry policy, and no `"suspend"` tier. */
+    onError?: (info: ErrorInfo) => ErrorTier;
+    /** §8 Gap 1. Extra top-level keys shallow-merged into the body after the classifier builds its
+     * own; a `requestParams` key WINS on collision. Omit ⇒ body byte-identical. */
+    requestParams?: Record<string, unknown>;
+    /** §8 Gap 1. Receives the assembled body after the `requestParams` merge and returns the body
+     * to send. Order: base body → requestParams merge → bodyTransform → marshal, exactly as §8. */
+    bodyTransform?: (body: Record<string, any>) => Record<string, any> | undefined | void;
+    /** 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. */
+    client?: Client;
+    /** `style: "custom"` only — the host's own function. */
+    evaluate?: EvaluateFn;
+    /** `style: "static"` only — the recorded corpus. */
+    decisions?: RecordedDecision[];
+}
+/** The whole seam: one verb. */
+export declare class Classifier {
+    private readonly opts;
+    private readonly style;
+    private readonly baseUrl;
+    private readonly model;
+    private readonly apiKeyEnv;
+    private readonly timeoutMs;
+    private readonly corpus;
+    /** The once-per-question-key set for the degenerate warning, so a per-turn judge does not
+     * flood the sink. */
+    private readonly warned;
+    constructor(opts: ClassifierOptions);
+    /**
+     * 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>;
+    /**
+     * Emits ONE warning per degenerate question key per classifier, naming the key, and changes
+     * nothing about the request. Repairing would invent option descriptions the caller did not
+     * write, and the library has no way to know what the options mean.
+     */
+    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).
+     */
+    private body;
+    /** Identifies a recorded decision by the canonical request AND the state. */
+    private staticKey;
+    private evaluateStatic;
+    private evaluateSystemOne;
+    /**
+     * The one POST, with the §8 retry budget, reusing the client's `ErrorInfo`/`ErrorTier`
+     * classifier and the `Retry-After` delay-seconds rule verbatim.
+     *
+     * NO CREDENTIAL VALUE AND NO EXPANDED HEADER VALUE APPEARS ON ANY PATH OUT OF HERE: an
+     * authentication failure names the status and the endpoint, nothing else, and a 401/403 body
+     * is never echoed back (a gateway happily reflects a bad Authorization header into its own
+     * 401 text).
+     */
+    private post;
+    /** Credential and `${ENV_VAR}` headers resolve AT CALL TIME. Never logged, never returned. */
+    private requestHeaders;
+    /**
+     * The three question types rendered as ONE structured-output call on any §8 Client — the
+     * vendor-neutral fallback, so a host with no System One credential runs the same questions on
+     * a cheap chat model. `calibrated` is FALSE: the numbers are the model's self-report, not
+     * token probabilities.
+     */
+    private evaluateLLM;
+    private emit;
+    private emitError;
+}
+/** Builds a Classifier, applying the §8B defaults and rejecting a style whose required option
+ * is missing before any call is made. */
+export declare function createClassifier(opts?: ClassifierOptions): Classifier;
+/**
+ * The §8B predicate. Degenerate ⇔ ANY of:
+ *   1. every value is empty (empty string or absent), or
+ *   2. every value equals its own key, or
+ *   3. every value is identical to every other value (n >= 2).
+ *
+ * A single-option choice (n === 1) is NEVER reported: there is nothing to differentiate. Returns
+ * the reason, or "" when the criteria are fine.
+ */
+export declare function degenerateCriteria(criteria: Record<string, string>): string;