@juspay/neurolink 13.4.9 → 13.5.0

package/dist/types/decision.d.ts

@@ -53,6 +53,13 @@ export type DecisionChoiceQuestion = {
     type: "choice";
     instructions: DecisionInput;
     criteria: Readonly<Record<string, DecisionInput | null>>;
+    /**
+     * True adds an option named `unknown` the model picks when none of the
+     * criteria fits; the answer then carries `unknown: true`. Only a provider
+     * whose `decisionLimits.questionTypes` lists `"choice-unknown"` accepts it,
+     * and no criteria key may be named `unknown` alongside it.
+     */
+    unknown?: boolean;
 };
 /**
  * Rate against an ordered rubric. The answer is the **0-based index**, so a
@@ -63,7 +70,24 @@ export type DecisionScoreQuestion = {
     instructions: DecisionInput;
     criteria: readonly (DecisionInput | null)[];
 };
-export type DecisionQuestion = DecisionBooleanQuestion | DecisionChoiceQuestion | DecisionScoreQuestion;
+/**
+ * Extract one typed field from the state: an amount, a reference, a name. Only
+ * a provider whose `decisionLimits.questionTypes` lists `"value"` accepts it.
+ */
+export type DecisionValueQuestion = {
+    type: "value";
+    instructions: DecisionInput;
+    /** The type of the extracted value. Omitted means `string`. */
+    dtype?: "string" | "int" | "float";
+    /** A regular expression the extracted text must match. */
+    pattern?: string;
+};
+export type DecisionQuestion = DecisionBooleanQuestion | DecisionChoiceQuestion | DecisionScoreQuestion | DecisionValueQuestion;
+/**
+ * What a provider may be asked, per question. `"choice-unknown"` is a `choice`
+ * question that sets `unknown: true`.
+ */
+export type DecisionQuestionType = DecisionQuestion["type"] | "choice-unknown";
 /** Questions keyed by an id you choose; answers return under the same ids. */
 export type DecisionQuestionMap = Readonly<Record<string, DecisionQuestion>>;
 export type DecisionBooleanAnswer = {
@@ -79,24 +103,34 @@ export type DecisionChoiceAnswer = {
     probabilities: Readonly<Record<string, number>>;
     /** Calibrated certainty, 0–1, derived from the distribution. */
     confidence: number;
+    /** True when the question set `unknown` and the model picked it. */
+    unknown?: boolean;
 };
 export type DecisionScoreAnswer = {
     type: "score";
     /** Probability-weighted level index; lands between levels. */
     score: number;
-    /** Level index (as a string key) → the description supplied. */
+    /** Level index (as a string key) → the description supplied; a level that was not a string is given as its JSON text. */
     legend: Readonly<Record<string, string>>;
     /** Level index (as a string key) → probability. */
     probabilities: Readonly<Record<string, number>>;
     confidence: number;
 };
-export type DecisionAnswer = DecisionBooleanAnswer | DecisionChoiceAnswer | DecisionScoreAnswer;
+export type DecisionValueAnswer = {
+    type: "value";
+    /** The extracted value: a number for `int` / `float`, else a string. Null when the model abstained. */
+    value: string | number | null;
+    confidence: number;
+    /** True when the model found nothing to extract; `value` is then null. */
+    unknown?: boolean;
+};
+export type DecisionAnswer = DecisionBooleanAnswer | DecisionChoiceAnswer | DecisionScoreAnswer | DecisionValueAnswer;
 export type DecisionAnswerMap = Readonly<Record<string, DecisionAnswer>>;
 export type DecisionUsage = {
     inputTokens: number;
     outputTokens: number;
 };
-/** An image or video as the caller supplies it: raw bytes, a file path, or a data URL. */
+/** An image, video or audio clip as the caller supplies it: raw bytes, a file path, or a data URL. */
 export type DecisionMediaSource = Buffer | string;
 export type DecisionRequest = {
     state: DecisionState;
@@ -109,6 +143,11 @@ export type DecisionRequest = {
     images?: readonly DecisionMediaSource[];
     /** One video, in the same forms. Sending images as well is allowed. */
     video?: DecisionMediaSource;
+    /**
+     * One audio clip, in the same forms (a `data:audio/…;base64,` URL). Only a
+     * provider whose `decisionLimits.media.audio` is set accepts it.
+     */
+    audio?: DecisionMediaSource;
     /** Overrides the provider's configured model for this call only. */
     model?: string;
     signal?: AbortSignal;
@@ -127,7 +166,7 @@ export type DecisionResult = {
     latencyMs: number;
     /** Server-side time behind the edge; isolates model time from network. */
     upstreamMs?: number;
-    /** Encoded size of the images and video sent. Absent for a text-only request. */
+    /** Encoded size of the images, video and audio sent. Absent for a text-only request. */
     mediaBytes?: number;
 };
 /**
@@ -147,6 +186,16 @@ export type DecisionLimits = {
     maxStateTokens: number;
     /** Absent when the provider has no cap on questions per request. */
     maxQuestions?: number;
+    /**
+     * The question types the provider reads. Absent means `boolean`, `choice`
+     * and `score`; a request asking anything else is refused before any network
+     * call, whether or not the limits are advisory.
+     */
+    questionTypes?: readonly DecisionQuestionType[];
+    /** Most levels one `score` question may have. Absent means no local cap. */
+    maxScoreLevels?: number;
+    /** Most options one `choice` question may have. Absent means no local cap. */
+    maxChoiceOptions?: number;
     /**
      * Tokens charged per non-ASCII character. The default estimate assumes ~4
      * characters per token, which holds for English and is several times too
@@ -208,9 +257,15 @@ export type DecisionLimitsReading = {
     maxStateTokens: number;
     /**
      * Absent when the provider caps a request by tokens (or bytes) rather
-     * than by question count — TypeSafe and XOR; `Infinity` is never used.
+     * than by question count — TypeSafe; `Infinity` is never used.
      */
     maxQuestions?: number;
+    /** Present only when the descriptor declares it; absent means `boolean`, `choice` and `score`. */
+    questionTypes?: readonly DecisionQuestionType[];
+    /** Most levels one `score` question may have; absent means no local cap. */
+    maxScoreLevels?: number;
+    /** Most options one `choice` question may have; absent means no local cap. */
+    maxChoiceOptions?: number;
     nonAsciiTokensPerChar?: number;
     /** Tokens charged per ASCII digit; see {@link DecisionLimits.digitTokensPerChar}. */
     digitTokensPerChar?: number;
@@ -241,19 +296,36 @@ export type DecisionMediaLimits = {
     video: boolean;
     /** Ceiling on the encoded request body, in bytes. */
     maxRequestBytes: number;
+    /** Whether one audio clip is accepted, and how much of it the model hears. Absent means no audio. */
+    audio?: DecisionAudioLimits;
+};
+export type DecisionAudioLimits = {
+    /**
+     * Seconds of audio the model reads. A clip whose length can be read from its
+     * header (WAV, FLAC, Ogg) and runs longer is refused, since the rest would be cut
+     * off without a word.
+     */
+    maxSeconds: number;
 };
 /** An image's size in pixels, read from its header. */
 export type DecisionImageDimensions = {
     width: number;
     height: number;
 };
-/** Media after preparation: everything is a `data:` URL, ready for the wire. */
+/** Media after preparation: images and video are `data:` URLs, ready for the wire. */
 export type DecisionPreparedMedia = {
     images: string[];
     video?: string;
-    /** Encoded size of every URL above. */
+    audio?: DecisionPreparedAudio;
+    /** Encoded size of everything above. */
     bytes: number;
 };
+/** An audio clip as the wire takes it: raw base64 and the container it was sniffed as. */
+export type DecisionPreparedAudio = {
+    data: string;
+    format: DecisionAudioFormat;
+};
+export type DecisionAudioFormat = "wav" | "flac" | "ogg" | "mp3";
 /**
  * Discriminated by a string literal, not a boolean: the package is also
  * compiled without strictNullChecks, where a boolean discriminant does not
@@ -266,8 +338,8 @@ export type DecisionMediaResult = {
     status: "refused";
     message: string;
 };
-export type DecisionMediaKind = "image" | "video";
-/** One image or video turned into a data URL, or the reason it could not be. Same literal-discriminant rule as above. */
+export type DecisionMediaKind = "image" | "video" | "audio";
+/** One image, video or audio clip turned into a data URL, or the reason it could not be. Same literal-discriminant rule as above. */
 export type DecisionMediaConversion = {
     status: "ok";
     dataUrl: string;
@@ -283,6 +355,21 @@ export type DecisionMediaFileRead = {
     status: "error";
     message: string;
 };
+/**
+ * A caller's media source resolved for one kind: bytes to identify (a Buffer
+ * or a file read from disk), a `data:` URL of that kind as given, or the reason
+ * it is refused.
+ */
+export type DecisionMediaSourceRead = {
+    status: "buffer";
+    buffer: Buffer;
+} | {
+    status: "dataUrl";
+    dataUrl: string;
+} | {
+    status: "error";
+    message: string;
+};
 /**
  * Why a decision call failed, normalised across vendors. TypeSafe alone
  * returns two different error envelopes, so a provider must flatten them.
@@ -318,6 +405,11 @@ export type DecisionChoiceReading = {
         name: string;
         probability: number;
     }[];
+    /**
+     * True when the question set `unknown` and the model picked it: `choice` is
+     * then `"unknown"`, which is none of the question's own options.
+     */
+    unknown: boolean;
 };
 export type DecisionScoreReading = {
     score: number;
@@ -325,6 +417,12 @@ export type DecisionScoreReading = {
     legend: Readonly<Record<string, string>>;
     probabilities: Readonly<Record<string, number>>;
 };
+export type DecisionValueReading = {
+    value: string | number | null;
+    confidence: number;
+    /** True when the model abstained; `value` is then null. */
+    unknown: boolean;
+};
 /**
  * What `NeuroLink.decide()` accepts: a decision request plus the usual
  * provider/credential selection every inference type shares.
@@ -543,6 +641,8 @@ export type DecideMedia = {
     imagesKey: string;
     /** Written only when the request carries a video; required exactly when `decisionLimits.media.video` is true. */
     videoKey?: string;
+    /** Written only when the request carries audio, as `{ data, format }`; required exactly when `decisionLimits.media.audio` is set. */
+    audioKey?: string;
 };
 /**
  * Says when a decide provider's key may be used as the default decision
@@ -580,6 +680,13 @@ export type DecideAmbientKeyCredentialField = {
     /** The field in that slice. Only `baseURL` is read today. */
     field: "baseURL";
 };
+/** See `DecideBlock.capableModel`. */
+export type DecideCapableModel = {
+    /** A key of the entry's `models.catalog`. */
+    model: string;
+    /** Question types that send a request to `model`; media always does. */
+    questionTypes: readonly DecisionQuestionType[];
+};
 /** What a dialect lays out as one request body. */
 export type DecisionDialectBody = {
     readonly state: DecisionState;

package/dist/types/providerCatalog.d.ts

@@ -4,7 +4,7 @@
  * src/lib/providers/catalog/<id>.json file per provider is the single
  * source of truth; see docs/superpowers/plans/2026-08-28-provider-json-catalog-spec.md.
  */
-import type { DecideAmbientKeyGuard, DecideDialectName, DecideMedia, DecisionErrorKind, DecisionLimits } from "./decision.js";
+import type { DecideAmbientKeyGuard, DecideCapableModel, DecideDialectName, DecideMedia, DecisionErrorKind, DecisionLimits } from "./decision.js";
 export type CatalogPricingPerMTok = {
     input: number;
     output: number;
@@ -338,6 +338,15 @@ export type DecideBlock = {
     stateEncoding?: "text";
     /** Body keys for images and video, after `model`, `state` and `questions`. Omitted means the body never carries media. */
     media?: DecideMedia;
+    /**
+     * A model the request is sent to instead of the default when the call names
+     * no model, no model variable is set, and the request carries media or a
+     * question of one of `questionTypes`. Its `decisionLimits` row is the one
+     * checked. For a text default that cannot read those requests, whose server
+     * would otherwise hand them to this model behind its back, with a smaller
+     * window than the one checked. Omitted means the default model is always sent.
+     */
+    capableModel?: DecideCapableModel;
     /**
      * Keeps a key found only in the environment from becoming the default
      * decision provider when it plainly belongs to something else. Omitted means
@@ -368,6 +377,8 @@ export type DecideCatalogJson = {
     };
     timeouts?: {
         decideMs?: number;
+        /** Added to `decideMs` per 1,000 estimated state tokens, for a model whose latency grows with the state. */
+        decideMsPerKStateTokens?: number;
     };
     decisionLimits?: DecisionLimits;
     decide: DecideBlock;

package/dist/types/providers.d.ts

@@ -2459,6 +2459,8 @@ export type ProviderDescriptor = {
         generateMs?: number;
         streamMs?: number;
         decideMs?: number;
+        /** Added to `decideMs` per 1,000 estimated state tokens. */
+        decideMsPerKStateTokens?: number;
     };
     /**
      * What a `decide` provider can read. Absent means the provider leaves size

package/dist/utils/decisionAnswers.d.ts

@@ -7,7 +7,7 @@
  *
  * @module utils/decisionAnswers
  */
-import type { DecisionAnswerMap, DecisionBooleanGate, DecisionChoiceReading, DecisionQuestion, DecisionResult, DecisionScoreReading, ProviderDescriptor } from "../types/index.js";
+import type { DecisionAnswerMap, DecisionBooleanGate, DecisionChoiceReading, DecisionQuestion, DecisionResult, DecisionScoreReading, DecisionValueReading, ProviderDescriptor } from "../types/index.js";
 /**
  * Read a yes/no answer as a probability.
  *
@@ -24,6 +24,12 @@ export declare function readDecisionBoolean(answers: DecisionAnswerMap, id: stri
  */
 export declare function readDecisionChoice(answers: DecisionAnswerMap, id: string): DecisionChoiceReading | undefined;
 export declare function readDecisionScore(answers: DecisionAnswerMap, id: string): DecisionScoreReading | undefined;
+/**
+ * Read an extracted value. `value` is null and `unknown` true when the model
+ * found nothing to extract, which is an answer, not a missing one: undefined
+ * still means the id is absent or the answer was another type.
+ */
+export declare function readDecisionValue(answers: DecisionAnswerMap, id: string): DecisionValueReading | undefined;
 /**
  * A yes/no answer carries no confidence of its own, so certainty has to be
  * inferred from how far the probability sits from a coin flip. 0.5 → 0, and

package/dist/utils/decisionAnswers.js

@@ -34,7 +34,13 @@ export function readDecisionChoice(answers, id) {
     const ranked = Object.entries(probabilities)
         .map(([name, probability]) => ({ name, probability }))
         .sort((a, b) => b.probability - a.probability);
-    return { choice, confidence, probabilities, ranked };
+    return {
+        choice,
+        confidence,
+        probabilities,
+        ranked,
+        unknown: answer.unknown === true,
+    };
 }
 export function readDecisionScore(answers, id) {
     const answer = answers[id];
@@ -44,6 +50,22 @@ export function readDecisionScore(answers, id) {
     const { score, confidence, legend, probabilities } = answer;
     return { score, confidence, legend, probabilities };
 }
+/**
+ * Read an extracted value. `value` is null and `unknown` true when the model
+ * found nothing to extract, which is an answer, not a missing one: undefined
+ * still means the id is absent or the answer was another type.
+ */
+export function readDecisionValue(answers, id) {
+    const answer = answers[id];
+    if (answer?.type !== "value") {
+        return undefined;
+    }
+    return {
+        value: answer.value,
+        confidence: answer.confidence,
+        unknown: answer.unknown === true || answer.value === null,
+    };
+}
 /**
  * A yes/no answer carries no confidence of its own, so certainty has to be
  * inferred from how far the probability sits from a coin flip. 0.5 → 0, and
@@ -136,6 +158,15 @@ export function stripHostAnswers(result, hostIdByWireId) {
     return { ...result, answers };
 }
 const isRecordValue = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function compilesAsRegex(pattern) {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Whether `value` is something a decision model accepts as content: a
  * string, number or boolean, or an array or plain object of the same.
@@ -198,7 +229,17 @@ function isWellFormedDecisionQuestion(value) {
         case "choice":
             return (isRecordValue(value.criteria) &&
                 Object.keys(value.criteria).length >= 2 &&
-                Object.values(value.criteria).every((rubric) => rubric === null || isDecisionInput(rubric)));
+                Object.values(value.criteria).every((rubric) => rubric === null || isDecisionInput(rubric)) &&
+                (value.unknown === undefined || typeof value.unknown === "boolean"));
+        case "value":
+            return ((value.dtype === undefined ||
+                value.dtype === "string" ||
+                value.dtype === "int" ||
+                value.dtype === "float") &&
+                (value.pattern === undefined ||
+                    (typeof value.pattern === "string" &&
+                        value.pattern.length > 0 &&
+                        compilesAsRegex(value.pattern))));
         case "score":
             return (Array.isArray(value.criteria) &&
                 value.criteria.length >= 2 &&

package/dist/utils/decisionLimits.d.ts

@@ -11,7 +11,7 @@
  *
  * @module utils/decisionLimits
  */
-import type { DecisionLimits, DecisionLimitsReading, DecisionState, ProviderDescriptor } from "../types/index.js";
+import type { DecisionLimits, DecisionLimitsReading, DecisionQuestion, DecisionQuestionType, DecisionState, ProviderDescriptor } from "../types/index.js";
 /**
  * Estimate how many tokens a decision model will read from `state`.
  *
@@ -37,3 +37,15 @@ export declare function estimateDecisionStateTokens(state: DecisionState, limits
  * limits.
  */
 export declare function resolveDecisionLimitsReading(descriptor: Pick<ProviderDescriptor, "name" | "decisionLimits">, model: string): DecisionLimitsReading | null;
+/** What a provider reads when its limits list no `questionTypes`. */
+export declare const DEFAULT_DECISION_QUESTION_TYPES: readonly DecisionQuestionType[];
+/** The type a question needs a provider to read; a `choice` with `unknown` on needs `choice-unknown`. */
+export declare function decisionQuestionTypeOf(question: DecisionQuestion): DecisionQuestionType;
+/**
+ * Why a provider with these limits cannot be asked `question`, or undefined
+ * when it can. Applies whether or not the limits are advisory: a question type
+ * the server does not know is refused outright, never answered from a guess.
+ * `limits` is null for a provider that declares no limits at all, which reads
+ * the default types and has no per-question caps.
+ */
+export declare function unsupportedDecisionQuestion(question: DecisionQuestion, limits: Pick<DecisionLimitsReading, "questionTypes" | "maxScoreLevels" | "maxChoiceOptions"> | null): string | undefined;

package/dist/utils/decisionLimits.js

@@ -94,10 +94,19 @@ export function resolveDecisionLimitsReading(descriptor, model) {
         model,
         maxStateTokens: modelLimits?.maxStateTokens ?? limits.maxStateTokens,
         // Absent for a provider that caps by tokens or bytes rather than by
-        // question count (TypeSafe, XOR).
+        // question count (TypeSafe).
         ...(limits.maxQuestions !== undefined
             ? { maxQuestions: limits.maxQuestions }
             : {}),
+        ...(limits.questionTypes !== undefined
+            ? { questionTypes: [...limits.questionTypes] }
+            : {}),
+        ...(limits.maxScoreLevels !== undefined
+            ? { maxScoreLevels: limits.maxScoreLevels }
+            : {}),
+        ...(limits.maxChoiceOptions !== undefined
+            ? { maxChoiceOptions: limits.maxChoiceOptions }
+            : {}),
         ...(nonAsciiTokensPerChar !== undefined ? { nonAsciiTokensPerChar } : {}),
         // Not model-overridable — `models` only carries `maxStateTokens` and
         // `nonAsciiTokensPerChar` — so these three come from the base limits only.
@@ -114,3 +123,45 @@ export function resolveDecisionLimitsReading(descriptor, model) {
         enforcedLocally: limits.advisory !== true,
     };
 }
+/** What a provider reads when its limits list no `questionTypes`. */
+export const DEFAULT_DECISION_QUESTION_TYPES = ["boolean", "choice", "score"];
+/** The type a question needs a provider to read; a `choice` with `unknown` on needs `choice-unknown`. */
+export function decisionQuestionTypeOf(question) {
+    return question.type === "choice" && question.unknown === true
+        ? "choice-unknown"
+        : question.type;
+}
+/**
+ * Why a provider with these limits cannot be asked `question`, or undefined
+ * when it can. Applies whether or not the limits are advisory: a question type
+ * the server does not know is refused outright, never answered from a guess.
+ * `limits` is null for a provider that declares no limits at all, which reads
+ * the default types and has no per-question caps.
+ */
+export function unsupportedDecisionQuestion(question, limits) {
+    const types = limits?.questionTypes ?? DEFAULT_DECISION_QUESTION_TYPES;
+    const type = decisionQuestionTypeOf(question);
+    if (!types.includes(type)) {
+        return type === "choice-unknown"
+            ? "a choice with unknown: true is not accepted"
+            : `the question type "${type}" is not accepted (accepted: ${types.join(", ")})`;
+    }
+    if (question.type === "choice") {
+        const keys = Object.keys(question.criteria);
+        if (question.unknown === true && keys.includes("unknown")) {
+            return 'a choice with unknown: true cannot also name an option "unknown"';
+        }
+        const options = keys.length + (question.unknown === true ? 1 : 0);
+        const max = limits?.maxChoiceOptions;
+        if (max !== undefined && options > max) {
+            return `a choice may have at most ${max} options${question.unknown === true ? ", counting unknown" : ""}; this one has ${options}`;
+        }
+    }
+    if (question.type === "score") {
+        const max = limits?.maxScoreLevels;
+        if (max !== undefined && question.criteria.length > max) {
+            return `a score may have at most ${max} levels; this one has ${question.criteria.length}`;
+        }
+    }
+    return undefined;
+}

package/dist/utils/decisionMedia.d.ts

@@ -1,9 +1,11 @@
 import type { DecisionMediaLimits, DecisionMediaResult, DecisionMediaSource } from "../types/index.js";
 /**
- * Turn the caller's images and video into `data:` URLs, or say why not.
- * Runs before any request, so every refusal costs nothing and none is retried.
+ * Turn the caller's images and video into `data:` URLs, and an audio clip into
+ * `{ data, format }`, or say why not. Runs before any request, so every
+ * refusal costs nothing and none is retried.
  */
 export declare function prepareDecisionMedia(request: {
     images?: readonly DecisionMediaSource[];
     video?: DecisionMediaSource;
+    audio?: DecisionMediaSource;
 }, limits: DecisionMediaLimits | undefined, vendor: string, alternatives: readonly string[]): Promise<DecisionMediaResult>;