nexus-ai-pro 2.18.0 → 2.20.2

package/dist/decisions/core.d.ts

@@ -0,0 +1,525 @@
+/**
+ * Typed decisions: questions a model answers with a yes or no, a choice, or a score, each with its
+ * probabilities and a confidence read from them, so software acts on an answer without parsing text.
+ */
+import type { CacheAdapter } from '../cache/adapters.js';
+import type { OperationLifecycleLike, ProviderCallContext } from '../types/lifecycle.js';
+import type { ResponseCost } from '../types/response.js';
+import type { RunKind } from '../types/tracing.js';
+/** The kinds of question there are: a yes or no, a choice among options, or a score on levels. */
+export type DecisionQuestionType = 'yes-no' | 'choice' | 'score';
+/** A question answered yes or no, with the probability that it is yes. */
+export interface YesNoQuestion {
+    /** Discriminates the question. */
+    type: 'yes-no';
+    /** The question, or a statement that is true or false, such as "The customer asks for a refund." */
+    question?: string;
+    /** What counts as yes and as no, when the question alone leaves it open. */
+    criteria?: {
+        yes?: string;
+        no?: string;
+    };
+}
+/** A question answered by one of its options, with each option's probability. */
+export interface ChoiceQuestion<K extends string = string> {
+    /** Discriminates the question. */
+    type: 'choice';
+    /** The question, such as "Which team should handle this?". */
+    question?: string;
+    /** The options, by name, each with what it means, or only their names. Up to 255. */
+    options: readonly K[] | Readonly<Record<K, string>>;
+}
+/** A question answered on an ordered rubric: level 0 first, with each level's probability. */
+export interface ScoreQuestion {
+    /** Discriminates the question. */
+    type: 'score';
+    /** The question, such as "How urgent is this?". */
+    question?: string;
+    /** What each level means, lowest first. Two to ten. */
+    levels: readonly string[];
+}
+/** Any question. */
+export type DecisionQuestion = YesNoQuestion | ChoiceQuestion | ScoreQuestion;
+/** Questions by the names their answers come back under. */
+export type DecisionQuestions = Record<string, DecisionQuestion>;
+/** What every question of a decision is about: text, or any JSON value. */
+export type DecisionState = string | Record<string, unknown> | readonly unknown[];
+/** A yes-or-no question's answer. */
+export interface YesNoAnswer {
+    /** Discriminates the answer. */
+    type: 'yes-no';
+    /** Whether it is yes: the probability is at least one half. */
+    yes: boolean;
+    /** The probability that it is yes, from 0 to 1. */
+    probability: number;
+    /** How far the probability is from an even chance, from 0 to 1: `|2p - 1|`. */
+    confidence: number;
+}
+/** A choice question's answer. */
+export interface ChoiceAnswer<K extends string = string> {
+    /** Discriminates the answer. */
+    type: 'choice';
+    /** The most probable option; of equally probable ones, the first given. */
+    choice: K;
+    /** Every option's probability, summing to 1. */
+    probabilities: Record<K, number>;
+    /**
+     * How far the top probability is above an even split, from 0 to 1: `(pmax - 1/n) / (1 - 1/n)` of
+     * `n` options.
+     */
+    confidence: number;
+}
+/** A score question's answer. */
+export interface ScoreAnswer {
+    /** Discriminates the answer. */
+    type: 'score';
+    /** The probability-weighted level, which may fall between two. */
+    score: number;
+    /** The most probable level; of equally probable ones, the lowest. */
+    level: number;
+    /** Each level's probability, lowest first, summing to 1. */
+    probabilities: number[];
+    /**
+     * How close the probability sits around the most probable level, from 0 to 1: one less the
+     * probability-weighted distance from it, over that distance for an even spread, and 0 at an even
+     * spread or wider.
+     */
+    confidence: number;
+}
+/** Any answer. */
+export type DecisionAnswer = YesNoAnswer | ChoiceAnswer | ScoreAnswer;
+/** The options of a choice question, as a union of their names. */
+type OptionsOf<O> = O extends readonly (infer K)[] ? K : keyof O;
+/** The answer a question gets: a choice's answer names only its options. */
+export type AnswerOf<Q> = Q extends YesNoQuestion ? YesNoAnswer : Q extends {
+    type: 'choice';
+    options: infer O;
+} ? ChoiceAnswer<Extract<OptionsOf<O>, string>> : Q extends ScoreQuestion ? ScoreAnswer : DecisionAnswer;
+/** Answers by their questions' names, each typed by its question. */
+export type DecisionAnswers<Q extends DecisionQuestions> = {
+    [K in keyof Q]: AnswerOf<Q[K]>;
+};
+/** A decision: questions about one state, answered together and each in isolation. */
+export interface DecisionRequest<Q extends DecisionQuestions = DecisionQuestions> {
+    /** What every question is about. */
+    state: DecisionState;
+    /** The questions, by the names their answers come back under. */
+    questions: Q;
+    /** The provider to ask. Defaults to the manager's default, then the first registered. */
+    provider?: string;
+    /** The model to ask. Defaults to the provider's own. */
+    model?: string;
+    /** The tenant it is for: its credentials, regions, and budget apply. */
+    tenantId?: string;
+    /** Stops the call. */
+    signal?: AbortSignal;
+    /** Labels for the trace and the audit log. Never include the state's private data. */
+    metadata?: Record<string, unknown>;
+    /** `false` asks the provider even when the cache holds an answer. */
+    cache?: boolean;
+}
+/** What a decision used, where the provider reports it. */
+export interface DecisionUsage {
+    /** Input tokens. */
+    inputTokens?: number;
+    /** Output tokens. */
+    outputTokens?: number;
+    /** Model calls made, for a provider that asks a completion model. */
+    calls?: number;
+}
+/** A decision's answers, and who gave them. */
+export interface DecisionResult<Q extends DecisionQuestions = DecisionQuestions> {
+    /** The answers, by question name. */
+    answers: DecisionAnswers<Q>;
+    /** The provider that answered. */
+    provider: string;
+    /** The model that answered, as the provider names it. */
+    model: string;
+    /** What it used. */
+    usage?: DecisionUsage;
+    /** What it cost, when the provider or the manager's prices price it. */
+    cost?: ResponseCost;
+    /** How long it took, in milliseconds. */
+    latencyMs: number;
+    /** True when the answers came from the cache. */
+    cached?: boolean;
+}
+/** A question as a provider receives it: a choice's options in order, each with its description. */
+export type DecisionProviderQuestion = YesNoQuestion | {
+    type: 'choice';
+    question?: string;
+    options: Array<{
+        name: string;
+        description?: string;
+    }>;
+} | ScoreQuestion;
+/** What a provider is asked. */
+export interface DecisionProviderRequest {
+    /** The model to ask. */
+    model: string;
+    /** What every question is about. */
+    state: DecisionState;
+    /** The questions, by name. */
+    questions: Record<string, DecisionProviderQuestion>;
+}
+/** A provider's probabilities for one question, from which the answer and its confidence are read. */
+export type DecisionDistribution = {
+    type: 'yes-no';
+    yes: number;
+} | {
+    type: 'choice';
+    probabilities: Record<string, number>;
+} | {
+    type: 'score';
+    probabilities: readonly number[];
+};
+/** What a provider answers. */
+export interface DecisionProviderResult {
+    /** The model that answered, when it differs from the one asked, as an alias resolves. */
+    model?: string;
+    /** Each question's probabilities, by name. */
+    distributions: Record<string, DecisionDistribution>;
+    /** What it used. */
+    usage?: DecisionUsage;
+    /** What it cost, when the provider reports it. */
+    cost?: ResponseCost;
+}
+/** What a decision provider takes. */
+export interface DecisionProviderCapabilities {
+    /** The kinds of question it answers. */
+    types: readonly DecisionQuestionType[];
+    /** Most options a choice may have. */
+    maxOptions: number;
+    /** Most levels a score may have. */
+    maxLevels: number;
+    /** Most questions one decision may ask, when it has a limit. */
+    maxQuestions?: number;
+    /** The model asked when a request names none. */
+    defaultModel: string;
+    /** The models it serves, when it lists them. */
+    models?: readonly string[];
+}
+/** Identifies a decision provider and what it takes. */
+export interface DecisionProviderInfo {
+    /** Its name, which results carry. */
+    name: string;
+    /** What it takes. */
+    capabilities: DecisionProviderCapabilities;
+    /**
+     * True for a provider whose calls are charged where they are made, such as one asking a client's
+     * own completions: its decisions report their cost, and hold and charge nothing to the budget again.
+     */
+    chargedByItsCalls?: boolean;
+}
+/** What every decision call receives: how to stop, the request's id, and the tenant's credential. */
+export interface DecisionCallContext {
+    /** Stops the call. */
+    signal: AbortSignal;
+    /** The request's id, for logs and traces. */
+    requestId: string;
+    /** The tenant it is for. */
+    tenantId?: string;
+    /**
+     * The tenant's credential for a provider, with a credential resolver: an adapter sends it in place
+     * of the key it was configured with.
+     */
+    credential?: ProviderCallContext['credential'];
+}
+/** A backend that answers decisions: a decision model, a completion model, or a stand-in. */
+export interface DecisionProvider {
+    /** What it is and takes. */
+    readonly info: DecisionProviderInfo;
+    /** Answers every question of a decision. */
+    decide(request: DecisionProviderRequest, context: DecisionCallContext): Promise<DecisionProviderResult>;
+}
+/** Why a decision failed. */
+export type DecisionErrorCode = 'DECISION_NO_PROVIDER' | 'DECISION_UNSUPPORTED' | 'DECISION_INVALID' | 'DECISION_FAILED';
+/** Raised for a decision no provider can serve, a question that is malformed, or a provider's failure. */
+export declare class DecisionError extends Error {
+    /**
+     * A stable code: `DECISION_NO_PROVIDER`, `DECISION_UNSUPPORTED` (a provider cannot take the
+     * question), `DECISION_INVALID` (the request, or an answer, is malformed), or `DECISION_FAILED`.
+     */
+    readonly code: DecisionErrorCode;
+    /** Whether asking again, or another provider, may help: a timeout or an overloaded service may. */
+    readonly retryable: boolean;
+    /** The HTTP status a provider answered with, when it did. */
+    readonly status?: number | undefined;
+    constructor(message: string, 
+    /**
+     * A stable code: `DECISION_NO_PROVIDER`, `DECISION_UNSUPPORTED` (a provider cannot take the
+     * question), `DECISION_INVALID` (the request, or an answer, is malformed), or `DECISION_FAILED`.
+     */
+    code: DecisionErrorCode, 
+    /** Whether asking again, or another provider, may help: a timeout or an overloaded service may. */
+    retryable?: boolean, 
+    /** The HTTP status a provider answered with, when it did. */
+    status?: number | undefined);
+}
+/** A yes-or-no answer's confidence: how far its probability is from an even chance, `|2p - 1|`. */
+export declare function yesNoConfidence(probability: number): number;
+/**
+ * A choice's confidence, from its options' probabilities: how far the top one is above an even split,
+ * `(pmax - 1/n) / (1 - 1/n)`. One option is certain.
+ */
+export declare function choiceConfidence(probabilities: readonly number[]): number;
+/**
+ * A score's confidence, from its levels' probabilities: one less the probability-weighted distance
+ * from the most probable level, over that distance for an even spread, and 0 at an even spread or
+ * wider. One level is certain.
+ */
+export declare function scoreConfidence(probabilities: readonly number[]): number;
+/**
+ * An answer from a provider's probabilities for one question: normalized to sum to 1, with its
+ * confidence read the same way whichever provider gave them. Throws `DecisionError`
+ * `DECISION_INVALID` for probabilities that do not fit the question.
+ */
+export declare function decisionAnswer(question: DecisionProviderQuestion, distribution: DecisionDistribution): DecisionAnswer;
+/** What to do with an answer: act on it, have a person review it, or neither. */
+export type GateOutcome = 'act' | 'review' | 'abstain';
+/** The confidences a gate acts at, and has reviewed at. */
+export interface GateThresholds {
+    /** At or above this confidence, act. */
+    act: number;
+    /** At or above this, and below `act`, a person reviews it; below it, abstain. Defaults to 0. */
+    review?: number;
+}
+/**
+ * Turns an answer's confidence into what to do: act at or above `act`, have a person review it at or
+ * above `review`, and abstain below. Set the thresholds by risk, and choose them with `calibrate()`
+ * on the application's own labelled examples.
+ */
+export declare function gate(answer: {
+    confidence: number;
+}, thresholds: GateThresholds): GateOutcome;
+/** One answer whose right answer is known, and whether it was right. */
+export interface CalibrationSample {
+    /** The answer. */
+    answer: DecisionAnswer;
+    /** Whether it was right, as `answeredRight()` reads it. */
+    correct: boolean;
+}
+/** Answers that gave their own answer a probability in one range, and how often they were right. */
+export interface CalibrationBin {
+    /** The range's lower bound, included. */
+    from: number;
+    /** Its upper bound, excluded, except for the last range's 1. */
+    to: number;
+    /** How many answers fell in it. */
+    count: number;
+    /** The mean probability they gave their own answers. */
+    probability: number;
+    /** The share of them that were right. */
+    accuracy: number;
+}
+/** Options for `calibrate()`. */
+export interface CalibrateOptions {
+    /** How many equal ranges of probability to count in. Defaults to 10. */
+    bins?: number;
+    /** The accuracy the threshold must hold: the share of answers at or above it that are right. */
+    targetAccuracy?: number;
+    /** The fewest answers the threshold must keep, so one lucky answer does not choose it. Defaults to 10. */
+    minSamples?: number;
+}
+/** How well answers' probabilities tracked how often they were right, and the threshold that holds the target. */
+export interface CalibrationReport {
+    /** How many answers were counted. */
+    samples: number;
+    /** The share of all of them that were right. */
+    accuracy: number;
+    /**
+     * The expected calibration error: the bins' gaps between the probability answers gave themselves and
+     * how often they were right, weighted by their counts. 0 when answers are as often right as they say.
+     */
+    expectedCalibrationError: number;
+    /** The answers by range of probability, empty ranges left out. */
+    bins: CalibrationBin[];
+    /**
+     * The lowest confidence at which the answers at or above it reach `targetAccuracy`, keeping at least
+     * `minSamples`: the `act` threshold for a gate. Absent when no threshold reaches it.
+     */
+    threshold?: number;
+    /** The share of answers at or above `threshold`: how much a gate there acts on. */
+    coverage?: number;
+}
+/**
+ * The probability an answer gives its own answer: a yes or no's `max(p, 1 - p)`, a choice's for its
+ * option, and a score's for its level. Its confidence measures how far that is above an even spread.
+ */
+export declare function answerProbability(answer: DecisionAnswer): number;
+/**
+ * Measures how well answers' probabilities track how often they are right, and, with
+ * `targetAccuracy`, chooses the gate threshold that holds it. Answers are calibrated when those that
+ * give their answer 0.8 are right about 80% of the time. The threshold is on confidence, which gates
+ * act on: it holds on answers like these, not on a different kind of question or state.
+ */
+export declare function calibrate(samples: readonly CalibrationSample[], options?: CalibrateOptions): CalibrationReport;
+/**
+ * Whether an answer is right: a yes-or-no or a choice by its answer, and a score by its most probable
+ * level, or by its weighted score within `tolerance` levels when one is given.
+ */
+export declare function answeredRight(answer: DecisionAnswer, expected: boolean | string | number, options?: {
+    tolerance?: number;
+}): boolean;
+/** A decision model's price, in US dollars per million tokens. */
+export interface DecisionPrice {
+    /** Per million input tokens. */
+    inputPerMillion: number;
+    /** Per million output tokens. Defaults to 0. */
+    outputPerMillion?: number;
+}
+/**
+ * Bundled decision prices, by model name or a prefix of it: TypeSafe AI's Jev at its published
+ * price, $42 per billion input tokens, with output free, as of 2026-10-24.
+ */
+export declare const DECISION_PRICES: Readonly<Record<string, DecisionPrice>>;
+/**
+ * What a decision cost, from its usage and the model's price; `undefined` for a model without a price
+ * or usage without tokens, never zero.
+ */
+export declare function priceDecision(model: string, usage: DecisionUsage | undefined, prices?: Readonly<Record<string, DecisionPrice>>): ResponseCost | undefined;
+/** A decision's run in a trace, as decisions finish it. */
+export interface DecisionRunLike {
+    /** Finishes the run with its answers, usage, and cost, or its error. */
+    finish(options?: {
+        outputs?: unknown;
+        error?: unknown;
+        usage?: Record<string, number>;
+        cost?: number;
+        model?: string;
+        provider?: string;
+    }): Promise<void>;
+}
+/** A tracer, or the part of one decisions use: a run per decision, with the provider's calls inside it. */
+export interface DecisionTracerLike {
+    /** Starts a run. */
+    startRun(options: {
+        name: string;
+        kind?: RunKind;
+        inputs?: unknown;
+        metadata?: Record<string, unknown>;
+        model?: string;
+        provider?: string;
+    }): DecisionRunLike;
+    /** Runs `fn` with the run in scope, so a model call inside it, through a traced client, nests beneath. */
+    within<T>(handle: DecisionRunLike, fn: () => T): T;
+}
+/** Configuration for `DecisionManager`. */
+export interface DecisionConfig {
+    /** Providers, by name. */
+    providers?: Record<string, DecisionProvider>;
+    /** The provider a request that names none goes to. Otherwise the first registered. */
+    defaultProvider?: string;
+    /**
+     * Providers to ask, in order, when the one asked fails in a way another may not: a timeout, a
+     * refused connection, or an overloaded service. A malformed request fails at once.
+     */
+    fallbacks?: readonly string[];
+    /** Prices by model or prefix, beside the bundled ones. */
+    prices?: Readonly<Record<string, DecisionPrice>>;
+    /**
+     * Keeps each decision's answers, so the same questions about the same state are answered once: a
+     * `CacheAdapter`, such as the memory, Redis, or SQLite one, and how long they keep (a day).
+     */
+    cache?: {
+        store: CacheAdapter<CachedDecision>;
+        ttlSeconds?: number;
+    };
+}
+/** A decision's answers as the cache keeps them. */
+export interface CachedDecision {
+    /** The answers, by question name. */
+    answers: Record<string, DecisionAnswer>;
+    /** The provider that answered. */
+    provider: string;
+    /** The model that answered. */
+    model: string;
+    /** What it used. */
+    usage?: DecisionUsage;
+}
+/** What the manager runs on. */
+export interface DecisionRuntime {
+    /**
+     * Runs every decision as one operation of a client's lifecycle, family `decision`: pass
+     * `ai.lifecycle`, so it is authorized, budgeted, rate limited, and audited, on the tenant's key.
+     */
+    lifecycle?: OperationLifecycleLike;
+    /** Records each decision as a run of kind `decision`, with its answers, usage, and cost. */
+    tracer?: DecisionTracerLike;
+}
+/**
+ * Decisions behind one handle: each goes to the provider named, the default, or the first
+ * registered, with failover to `fallbacks`, a cache, and every call inside a client's lifecycle.
+ *
+ * ```ts
+ * const decisions = new DecisionManager(
+ *   { providers: { jev: new TypeSafeDecisionProvider({ apiKey }) }, fallbacks: ['gpt'] },
+ *   { lifecycle: ai.lifecycle },
+ * );
+ * const { answers } = await decisions.decide({
+ *   state: ticket,
+ *   questions: {
+ *     team: { type: 'choice', options: { billing: 'Charges and invoices', technical: 'Errors and outages' } },
+ *     urgent: { type: 'yes-no', question: 'Does the customer need an answer today?' },
+ *   },
+ * });
+ * if (gate(answers.team, { act: 0.8 }) === 'act') route(answers.team.choice);
+ * ```
+ */
+export declare class DecisionManager {
+    private readonly config;
+    private readonly runtime;
+    private readonly providers;
+    constructor(config?: DecisionConfig, runtime?: DecisionRuntime);
+    /** Registers a provider under a name. Returns the manager, for chaining. */
+    registerDecisionProvider(name: string, provider: DecisionProvider): this;
+    /** Whether a provider is registered. */
+    hasDecisionProvider(name: string): boolean;
+    /** Every registered provider's name. */
+    listDecisionProviders(): string[];
+    /**
+     * Answers every question of a decision, each typed by its question: a choice's answer names only
+     * its options. Throws `DecisionError` when the request is malformed or no provider can answer.
+     */
+    decide<const Q extends DecisionQuestions>(request: DecisionRequest<Q>): Promise<DecisionResult<Q>>;
+    private ask;
+    private prices;
+}
+/** Answers a decision with one provider, outside any manager: no failover, cache, or lifecycle. */
+export declare function decide<const Q extends DecisionQuestions>(provider: DecisionProvider, request: Omit<DecisionRequest<Q>, 'provider'>): Promise<DecisionResult<Q>>;
+/** A question whose right answer is known, for `runDecisionConformance()`. */
+export interface DecisionConformanceCase {
+    /** What the question is about. */
+    state: DecisionState;
+    /** The question. */
+    question: DecisionQuestion;
+    /** The right answer: a yes or no, a choice's option, or a score's level. */
+    expected: boolean | string | number;
+}
+/** Options for `runDecisionConformance()`. */
+export interface DecisionConformanceOptions {
+    /** The model to ask. Defaults to the provider's own. */
+    model?: string;
+    /**
+     * Questions whose answers are known, each of which must be answered right. A stand-in that answers
+     * as it is told passes without them; a real model is held to them.
+     */
+    cases?: readonly DecisionConformanceCase[];
+}
+/** How a provider did against the decision contract. */
+export interface DecisionConformanceReport {
+    /** The provider. */
+    provider: string;
+    /** Checks that passed. */
+    passed: string[];
+    /** Checks that failed, each with why. */
+    failures: string[];
+}
+/**
+ * Checks a provider against the decision contract: its capabilities are coherent; each question type
+ * it declares comes back as probabilities that fit the question; several questions in one decision
+ * each get their own answer; a stopped call is not answered; and every case is answered right. Never
+ * throws; failures are listed.
+ */
+export declare function runDecisionConformance(provider: DecisionProvider, options?: DecisionConformanceOptions): Promise<DecisionConformanceReport>;
+export {};