@juspay/neurolink 12.37.5 → 12.38.1

package/dist/providers/systemOneDecision.js

@@ -1,9 +1,11 @@
 import { BaseProvider } from "../core/baseProvider.js";
-import { PROVIDER_DESCRIPTORS_BY_NAME } from "../factories/providerDescriptors.js";
+import { listMediaDecisionProviders, PROVIDER_DESCRIPTORS_BY_NAME, } from "../factories/providerDescriptors.js";
 import { isNeuroLink } from "../neurolink.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { ProviderError } from "../types/index.js";
+import { prepareDecisionMedia } from "../utils/decisionMedia.js";
 import { logger } from "../utils/logger.js";
+import { redactUrlsInText } from "../utils/logSanitize.js";
 import { estimateTokens, serializeForEstimate, } from "../utils/tokenEstimation.js";
 /**
  * Generous enough for a cold start (measured at 2.0–2.7s after idle on Jev)
@@ -128,6 +130,25 @@ export function describeValidationErrors(detail) {
         .slice(0, 5);
     return fields.join("; ") || "unspecified field";
 }
+/**
+ * A LiteLLM proxy echoes credentials back in its error texts, in more than one
+ * wording: a masked key plus its hash on a rejected key, the whole key when it
+ * does not look like a LiteLLM key, a key hash on a rate limit. None of it
+ * belongs in an error message or a log, whatever the wording, so the
+ * configured key, anything shaped like a LiteLLM key, any long hex run and any
+ * embedded `data:` URL are all removed.
+ */
+export function redactCredentials(message, apiKey) {
+    const withoutKey = apiKey
+        ? message.split(apiKey).join("[redacted]")
+        : message;
+    return withoutKey
+        .replace(/\.?\s*Received API Key\s*=[\s\S]*$/, "")
+        .replace(/\bsk-[A-Za-z0-9._-]+/g, "[redacted]")
+        .replace(/\b[0-9a-f]{32,}\b/gi, "[redacted]")
+        .replace(/data:[a-z]+\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/gi, "[media]")
+        .trim();
+}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * `estimateTokens` assumes ~4 characters per token. That holds for English
@@ -281,7 +302,9 @@ export class SystemOneDecisionProvider extends BaseProvider {
             id,
             this.encodeQuestion(question),
         ]));
-        const body = JSON.stringify(this.buildDecisionBody(request.state, wireQuestions, resolvedModel));
+        const media = await this.prepareMedia(request);
+        const body = JSON.stringify(this.buildDecisionBody(request.state, wireQuestions, resolvedModel, media));
+        this.assertWithinRequestBytes(body);
         const timeoutMs = request.timeoutMs ??
             this.getDescriptorDecideMs() ??
             this.defaultTimeout ??
@@ -369,6 +392,7 @@ export class SystemOneDecisionProvider extends BaseProvider {
                     requestId,
                     latencyMs,
                     upstreamMs,
+                    ...(media ? { mediaBytes: media.bytes } : {}),
                 };
             }
             catch (error) {
@@ -381,7 +405,7 @@ export class SystemOneDecisionProvider extends BaseProvider {
                 const isTimeout = error instanceof Error && error.name === "TimeoutError";
                 lastError = {
                     kind: aborted ? "network" : isTimeout ? "timeout" : "network",
-                    message: error instanceof Error ? error.message : String(error),
+                    message: redactCredentials(redactUrlsInText(error instanceof Error ? error.message : String(error)), this.decisionApiKey()),
                     retryable: !aborted,
                 };
                 if (aborted || attempt === this.maxRetries) {
@@ -396,6 +420,41 @@ export class SystemOneDecisionProvider extends BaseProvider {
             retryable: false,
         });
     }
+    /**
+     * Turn the request's images and video into data URLs, or refuse it. Refused
+     * as a non-retryable `invalid_request`: resending the same media cannot help.
+     */
+    async prepareMedia(request) {
+        const limits = PROVIDER_DESCRIPTORS_BY_NAME.get(this.providerName)?.decisionLimits;
+        const prepared = await prepareDecisionMedia(request, limits?.media, this.vendorLabel(), listMediaDecisionProviders());
+        if (prepared.status === "refused") {
+            throw this.decisionError({
+                kind: "invalid_request",
+                message: prepared.message,
+                retryable: false,
+            });
+        }
+        return prepared.media;
+    }
+    /**
+     * The encoded body, not just the media, is what the server's size limit
+     * applies to.
+     */
+    assertWithinRequestBytes(body) {
+        const limit = PROVIDER_DESCRIPTORS_BY_NAME.get(this.providerName)
+            ?.decisionLimits?.media?.maxRequestBytes;
+        if (limit === undefined) {
+            return;
+        }
+        const bytes = Buffer.byteLength(body);
+        if (bytes > limit) {
+            throw this.decisionError({
+                kind: "invalid_request",
+                message: `The request is ${bytes} bytes; ${this.vendorLabel()} accepts at most ${limit}. Send fewer or smaller images, or a shorter video.`,
+                retryable: false,
+            });
+        }
+    }
     /**
      * Refuse a request the model cannot read in full. An encoder cuts the state
      * off past its window without saying so, so without this a decision would
@@ -407,7 +466,8 @@ export class SystemOneDecisionProvider extends BaseProvider {
             return;
         }
         const label = this.vendorLabel();
-        if (questionCount > limits.maxQuestions) {
+        if (limits.maxQuestions !== undefined &&
+            questionCount > limits.maxQuestions) {
             throw this.decisionError({
                 kind: "max_tokens_exceeded",
                 message: `${label} accepts at most ${limits.maxQuestions} questions per request; this one has ${questionCount}. Ask fewer, or use a decision provider without this cap.`,

package/dist/providers/xor.d.ts

@@ -0,0 +1,48 @@
+import type { DecisionError, DecisionPreparedMedia, DecisionState, NeurolinkCredentials } from "../types/index.js";
+import { SystemOneDecisionProvider } from "./systemOneDecision.js";
+/**
+ * XOR Provider — the `decide` inference type only.
+ *
+ * XOR is Juspay's open-weights "System One" decision model, post-trained from
+ * Qwen3.6-35B-A3B: the same typed `noul` / `choice` / `score` questions as
+ * TypeSafe's Jev, on the same wire, in one batched pass. Unlike Jev and Laya it
+ * also reads images and one video. The request loop, retries, auth circuit
+ * breaker and answer parsing are shared with every decision provider in
+ * {@link SystemOneDecisionProvider}.
+ *
+ * @see https://huggingface.co/juspay/xor
+ */
+export declare class XorProvider extends SystemOneDecisionProvider {
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(modelName?: string, sdk?: unknown, _region?: string, credentials?: NeurolinkCredentials["xor"]);
+    protected getDefaultModel(): string;
+    protected vendorLabel(): string;
+    protected vendorDisplayName(): string;
+    protected decisionApiKey(): string;
+    protected missingKeyMessage(): string;
+    protected missingConfigMessage(): string | undefined;
+    protected decisionEndpoint(): string;
+    protected decisionHeaders(): Record<string, string>;
+    /**
+     * `model` is always sent. A LiteLLM proxy checks team access against the
+     * body's `model`, and refuses a request that names none. `images` is
+     * omitted rather than sent empty, which the server rejects.
+     */
+    protected buildDecisionBody(state: DecisionState, questions: Record<string, Record<string, unknown>>, model: string, media?: DecisionPreparedMedia): Record<string, unknown>;
+    /**
+     * A 403 is deliberately NOT `authentication`: on a LiteLLM proxy it means the
+     * team's allow-list lacks the model, which an admin can fix at any time, and
+     * `authentication` would trip the per-instance breaker and keep XOR disabled
+     * until restart even after access is granted. A 402 (a budget) is the same
+     * kind of fixable gap. `DecisionErrorKind` has no billing kind, so both map
+     * to `invalid_request`.
+     */
+    protected parseDecisionError(status: number, payload: unknown, requestId: string | undefined): DecisionError;
+    /**
+     * XOR's server sets `x-request-id` and `x-typesafe-request-id` to one value.
+     * A proxy in front may replace or drop them, so its own call id is the last
+     * resort.
+     */
+    protected readRequestId(headers: Headers): string | undefined;
+}

package/dist/providers/xor.js

@@ -0,0 +1,192 @@
+import { XorModels } from "../constants/enums.js";
+import { logger } from "../utils/logger.js";
+import { redactUrlForError } from "../utils/logSanitize.js";
+import { getProviderModel } from "../utils/providerConfig.js";
+import { describeValidationErrors, isRecord, redactCredentials, SystemOneDecisionProvider, } from "./systemOneDecision.js";
+const XOR_ROUTE = "/v1/systemone";
+/**
+ * XOR_BASE_URL is the origin of a deployment, but a `LITELLM_BASE_URL`-style
+ * value ends in `/v1`, which the route already carries. Both spellings reduce
+ * to the same base.
+ */
+function normalizeBaseURL(raw) {
+    return raw.replace(/\/+$/, "").replace(/\/v1$/i, "");
+}
+/** What a 500 says when the prefill was too long for the model to read. */
+const CONTEXT_LENGTH_MESSAGE = /(context|prefill|prompt).{0,40}(length|limit|too long|exceed)|(too long|exceeds?).{0,40}(context|tokens)/i;
+/**
+ * A base URL that cannot work is refused up front, and its text is never
+ * repeated: `fetch` rejects a URL with userinfo and echoes it in the error, the
+ * route is appended after a query string or fragment, and any of them can hold a
+ * credential.
+ */
+function baseURLProblem(baseURL) {
+    const fix = "Set XOR_BASE_URL or pass credentials.xor.baseURL to the origin, and give the key through XOR_API_KEY or credentials.xor.apiKey.";
+    try {
+        const url = new URL(baseURL);
+        // `new URL()` accepts any scheme, so a host:port with no scheme parses as
+        // one (`xor.internal:8080` has the scheme `xor.internal:`) and would reach
+        // `fetch` as a network error instead of this message.
+        if (url.protocol !== "https:" && url.protocol !== "http:") {
+            return `The XOR base URL must start with https:// or http://. ${fix}`;
+        }
+        return url.username || url.password || url.search || url.hash
+            ? `The XOR base URL must not carry credentials, a query string or a fragment. ${fix}`
+            : undefined;
+    }
+    catch {
+        return `The XOR base URL is not a valid absolute URL. ${fix}`;
+    }
+}
+function xorErrorKind(status, message) {
+    if (status === 401) {
+        return "authentication";
+    }
+    if (status === 413) {
+        return "max_tokens_exceeded";
+    }
+    if (status === 429) {
+        return "rate_limit";
+    }
+    if (status === 503) {
+        return "overloaded";
+    }
+    if (status >= 500) {
+        return CONTEXT_LENGTH_MESSAGE.test(message)
+            ? "max_tokens_exceeded"
+            : "server";
+    }
+    return "invalid_request";
+}
+/**
+ * Two envelopes reach the client. A LiteLLM proxy answers its own rejections
+ * (a bad key, a team without the model, a budget) as
+ * `{"error":{"message","type","code"}}`; XOR's own server answers as
+ * `{"error":"<string>"}` — a shape that neither TypeSafe's nor Laya's parser
+ * recognises, since both require `body.error` to be an object. FastAPI's
+ * `{"detail":…}` is read too, in case something in front speaks it.
+ */
+function readXorErrorMessage(body) {
+    if (!isRecord(body)) {
+        return undefined;
+    }
+    const { error, detail } = body;
+    if (isRecord(error) &&
+        typeof error.message === "string" &&
+        error.message.length > 0) {
+        return error.message;
+    }
+    if (typeof error === "string" && error.length > 0) {
+        return error;
+    }
+    if (Array.isArray(detail)) {
+        return `Request failed validation — ${describeValidationErrors(detail)}`;
+    }
+    return typeof detail === "string" && detail.length > 0 ? detail : undefined;
+}
+/**
+ * XOR Provider — the `decide` inference type only.
+ *
+ * XOR is Juspay's open-weights "System One" decision model, post-trained from
+ * Qwen3.6-35B-A3B: the same typed `noul` / `choice` / `score` questions as
+ * TypeSafe's Jev, on the same wire, in one batched pass. Unlike Jev and Laya it
+ * also reads images and one video. The request loop, retries, auth circuit
+ * breaker and answer parsing are shared with every decision provider in
+ * {@link SystemOneDecisionProvider}.
+ *
+ * @see https://huggingface.co/juspay/xor
+ */
+export class XorProvider extends SystemOneDecisionProvider {
+    apiKey;
+    baseURL;
+    constructor(modelName, sdk, _region, credentials) {
+        super(modelName, "xor", sdk);
+        this.apiKey =
+            credentials?.apiKey?.trim() || (process.env.XOR_API_KEY?.trim() ?? "");
+        // No built-in endpoint: XOR is reached at a deployment or through a proxy
+        // route to one, so the base URL comes only from config. `||`, not `??`, so
+        // a blank one counts as unset.
+        this.baseURL = normalizeBaseURL(credentials?.baseURL?.trim() || process.env.XOR_BASE_URL?.trim() || "");
+        // A base URL with `user:pass@` or a `?token=` is refused when a request is
+        // made, but it is redacted here as well so a misconfigured value cannot leak
+        // through this line either.
+        logger.debug("XOR Provider initialized (decide only)", {
+            modelName: this.modelName,
+            baseURL: this.baseURL ? redactUrlForError(this.baseURL) : "(not set)",
+        });
+    }
+    getDefaultModel() {
+        return getProviderModel("XOR_MODEL", XorModels.XOR_1_1);
+    }
+    vendorLabel() {
+        return "XOR";
+    }
+    vendorDisplayName() {
+        return "XOR";
+    }
+    decisionApiKey() {
+        return this.apiKey;
+    }
+    missingKeyMessage() {
+        return "XOR requires an API key. Set XOR_API_KEY or pass credentials.xor.apiKey.";
+    }
+    missingConfigMessage() {
+        return this.baseURL
+            ? baseURLProblem(this.baseURL)
+            : "XOR requires a base URL. Set XOR_BASE_URL or pass credentials.xor.baseURL.";
+    }
+    decisionEndpoint() {
+        return `${this.baseURL}${XOR_ROUTE}`;
+    }
+    decisionHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+        };
+    }
+    /**
+     * `model` is always sent. A LiteLLM proxy checks team access against the
+     * body's `model`, and refuses a request that names none. `images` is
+     * omitted rather than sent empty, which the server rejects.
+     */
+    buildDecisionBody(state, questions, model, media) {
+        return {
+            model,
+            state,
+            questions,
+            ...(media && media.images.length > 0 ? { images: media.images } : {}),
+            ...(media?.video ? { video: media.video } : {}),
+        };
+    }
+    /**
+     * A 403 is deliberately NOT `authentication`: on a LiteLLM proxy it means the
+     * team's allow-list lacks the model, which an admin can fix at any time, and
+     * `authentication` would trip the per-instance breaker and keep XOR disabled
+     * until restart even after access is granted. A 402 (a budget) is the same
+     * kind of fixable gap. `DecisionErrorKind` has no billing kind, so both map
+     * to `invalid_request`.
+     */
+    parseDecisionError(status, payload, requestId) {
+        const fallback = `XOR request failed with HTTP ${status}`;
+        const message = redactCredentials(readXorErrorMessage(payload) ?? fallback, this.apiKey) || fallback;
+        const kind = xorErrorKind(status, message);
+        return {
+            kind,
+            message,
+            status,
+            requestId,
+            retryable: kind === "rate_limit" || kind === "overloaded" || kind === "server",
+        };
+    }
+    /**
+     * XOR's server sets `x-request-id` and `x-typesafe-request-id` to one value.
+     * A proxy in front may replace or drop them, so its own call id is the last
+     * resort.
+     */
+    readRequestId(headers) {
+        return (headers.get("x-request-id") ??
+            headers.get("x-typesafe-request-id") ??
+            headers.get("x-litellm-call-id") ??
+            undefined);
+    }
+}

package/dist/types/classifierRouter.d.ts

@@ -25,8 +25,9 @@ export type ClassifierDifficulty = "trivial" | "simple" | "moderate" | "hard" |
  * - `jev` — TypeSafe's System One model; one ~400ms round trip that returns a
  *   *calibrated* confidence rather than a self-reported one.
  * - `auto` — `jev` when a decision provider is configured, in the environment
- *   or in SDK credentials (`TYPESAFE_API_KEY`, or `LAYA_API_KEY` with
- *   `LAYA_BASE_URL`), otherwise `heuristic`.
+ *   or in SDK credentials (`TYPESAFE_API_KEY`, `LAYA_API_KEY` with
+ *   `LAYA_BASE_URL`, or `XOR_API_KEY` with `XOR_BASE_URL`), otherwise
+ *   `heuristic`.
  */
 export type ClassifierStrategyKind = "heuristic" | "llm" | "jev" | "auto";
 /**
@@ -186,8 +187,8 @@ export type ClassifierRouterConfig = {
     /**
      * Classification strategy. Default: "auto" — which resolves to "jev" when a
      * decision provider is configured, in the environment or in SDK credentials
-     * (`TYPESAFE_API_KEY`, or `LAYA_API_KEY` with `LAYA_BASE_URL`) and
-     * "heuristic" otherwise, so configuring one
+     * (`TYPESAFE_API_KEY`, `LAYA_API_KEY` with `LAYA_BASE_URL`, or
+     * `XOR_API_KEY` with `XOR_BASE_URL`) and "heuristic" otherwise, so configuring one
      * upgrades routing without any code change. Behaviour for callers with no
      * key is unchanged.
      */

package/dist/types/cli.d.ts

@@ -1310,6 +1310,10 @@ export type CliDecideArgs = {
     stateFile?: string;
     questions?: string;
     questionsFile?: string;
+    /** Image files (or data: URLs) for a provider that reads images. */
+    image?: string[];
+    /** One video file (or data: URL) for a provider that reads video. */
+    video?: string;
     provider?: string;
     model?: string;
     timeout?: number;
@@ -1722,8 +1726,8 @@ export type CliClassifierRouterFlags = {
     /**
      * Strategy: "auto" (default), "heuristic", "llm" or "jev"
      * (--classifier-strategy). "auto" resolves to "jev" when a decision
-     * provider is configured (TYPESAFE_API_KEY, or LAYA_API_KEY with
-     * LAYA_BASE_URL) and "heuristic" otherwise.
+     * provider is configured (TYPESAFE_API_KEY, LAYA_API_KEY with
+     * LAYA_BASE_URL, or XOR_API_KEY with XOR_BASE_URL) and "heuristic" otherwise.
      */
     classifierStrategy?: string;
     /**

package/dist/types/decision.d.ts

@@ -95,9 +95,19 @@ 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. */
+export type DecisionMediaSource = Buffer | string;
 export type DecisionRequest = {
     state: DecisionState;
     questions: DecisionQuestionMap;
+    /**
+     * Images the model reads alongside `state`. Each is a Buffer, a local file
+     * path or a `data:image/…;base64,` URL; an http(s) URL is refused. Only a
+     * provider whose descriptor declares `decisionLimits.media` accepts them.
+     */
+    images?: readonly DecisionMediaSource[];
+    /** One video, in the same forms. Sending images as well is allowed. */
+    video?: DecisionMediaSource;
     /** Overrides the provider's configured model for this call only. */
     model?: string;
     signal?: AbortSignal;
@@ -116,6 +126,8 @@ 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. */
+    mediaBytes?: number;
 };
 /**
  * Input a decision provider can actually read, declared on its descriptor.
@@ -132,7 +144,8 @@ export type DecisionLimits = {
      * name — so it should be the tightest window the provider has.
      */
     maxStateTokens: number;
-    maxQuestions: number;
+    /** Absent when the provider has no cap on questions per request. */
+    maxQuestions?: number;
     /**
      * Tokens charged per non-ASCII character. The default estimate assumes ~4
      * characters per token, which holds for English and is several times too
@@ -145,6 +158,52 @@ export type DecisionLimits = {
         maxStateTokens: number;
         nonAsciiTokensPerChar?: number;
     }>>;
+    /** What the provider accepts besides text. Absent means text only. */
+    media?: DecisionMediaLimits;
+};
+export type DecisionMediaLimits = {
+    /** Most images one request may carry. */
+    maxImages: number;
+    /** Whether a video is accepted (at most one). */
+    video: boolean;
+    /** Ceiling on the encoded request body, in bytes. */
+    maxRequestBytes: number;
+};
+/** Media after preparation: everything is a `data:` URL, ready for the wire. */
+export type DecisionPreparedMedia = {
+    images: string[];
+    video?: string;
+    /** Encoded size of every URL above. */
+    bytes: number;
+};
+/**
+ * Discriminated by a string literal, not a boolean: the package is also
+ * compiled without strictNullChecks, where a boolean discriminant does not
+ * narrow.
+ */
+export type DecisionMediaResult = {
+    status: "prepared";
+    media: DecisionPreparedMedia | undefined;
+} | {
+    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 DecisionMediaConversion = {
+    status: "ok";
+    dataUrl: string;
+} | {
+    status: "error";
+    message: string;
+};
+/** A media file read from disk, or the reason it could not be. */
+export type DecisionMediaFileRead = {
+    status: "ok";
+    buffer: Buffer;
+} | {
+    status: "error";
+    message: string;
 };
 /**
  * Why a decision call failed, normalised across vendors. TypeSafe alone

package/dist/types/openaiCompatible.d.ts

@@ -255,6 +255,16 @@ export type StreamLoopArgs = {
      * schema was requested, or when tools suppress it.
      */
     responseFormat?: OpenAICompatResponseFormat;
+    /**
+     * Fired once per step that echoes a `model` field on the wire (SSE
+     * `chunk.model`, captured by `parseSSEStream` into `OpenAICompatSSEResult.model`).
+     * Lets the caller learn what the SERVER actually served, distinct from the
+     * pre-call resolved/requested `modelId` — a gateway or router can rewrite
+     * an alias to a concrete model id. Not called when a step's response omits
+     * `model` (some backends don't echo it), so the caller must keep its own
+     * fallback.
+     */
+    onModelObserved?: (model: string) => void;
 };
 export type OpenAICompatBuildBodyArgs = {
     modelId: string;

package/dist/types/providers.d.ts

@@ -322,6 +322,16 @@ export type NeurolinkCredentials = {
         apiKey?: string;
         baseURL?: string;
     };
+    /**
+     * XOR (Juspay, open weights) — the `decide` inference type. There is no
+     * built-in endpoint: `baseURL` (or XOR_BASE_URL) is required, pointing at the
+     * origin of an XOR deployment or a proxy route to one; requests go to
+     * `<baseURL>/v1/systemone`.
+     */
+    xor?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
 };
 /**
  * Voyage AI /embeddings response shape.

package/dist/utils/decisionMedia.d.ts

@@ -0,0 +1,9 @@
+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.
+ */
+export declare function prepareDecisionMedia(request: {
+    images?: readonly DecisionMediaSource[];
+    video?: DecisionMediaSource;
+}, limits: DecisionMediaLimits | undefined, vendor: string, alternatives: readonly string[]): Promise<DecisionMediaResult>;