@juspay/neurolink 12.25.5 → 12.26.1

package/dist/neurolink.js

@@ -34,7 +34,7 @@ import { buildToolRoutingCatalog, buildRoutingQueryFromHistory, resolveToolRouti
 import { ToolRoutingCache } from "./core/toolRoutingCache.js";
 import { DEFAULT_RECENT_TURNS, KnowledgeGroundingEngine, } from "./knowledge/index.js";
 import { AIProviderFactory } from "./core/factory.js";
-import { resolveDefaultDecisionProvider } from "./factories/providerDescriptors.js";
+import { describeDecisionProviderKeys, resolveDefaultDecisionProvider, } from "./factories/providerDescriptors.js";
 import { resolveRequestKind } from "./core/resolveRequestKind.js";
 import { createToolEventPayload } from "./core/toolEvents.js";
 import { ProviderFactory } from "./factories/providerFactory.js";
@@ -966,6 +966,8 @@ export class NeuroLink {
                 // throwing, so an absent or broken decision provider leaves routing
                 // exactly as it was.
                 decide: (decideOptions) => this.tryDecide(decideOptions),
+                // Read lazily: `this.credentials` is assigned later in the constructor.
+                hasDecisionProvider: () => resolveDefaultDecisionProvider(this.credentials) !== undefined,
                 logger: {
                     debug: (message, meta) => logger.debug(message, meta),
                     warn: (message, meta) => logger.warn(message, meta),
@@ -12700,9 +12702,12 @@ Current user's request: ${currentInput}`;
      * @throws when no decision provider is configured, or the call fails
      */
     async decide(options) {
-        const providerName = options.provider ?? resolveDefaultDecisionProvider();
+        // SDK config counts as much as the environment: credentials given to the
+        // constructor or to this call can configure a provider on their own.
+        const providerName = options.provider ??
+            resolveDefaultDecisionProvider(this.resolveCredentials(options.credentials));
         if (!providerName) {
-            throw new Error("No decision provider is configured. Set TYPESAFE_API_KEY, or pass `provider` explicitly.");
+            throw new Error(`No decision provider is configured. Set ${describeDecisionProviderKeys()} (in the environment or in \`credentials\`), or pass \`provider\` explicitly.`);
         }
         const questionCount = Object.keys(options.questions).length;
         // Observability parity with generate()/stream(): an OTEL span for the

package/dist/providers/laya.d.ts

@@ -0,0 +1,40 @@
+import type { DecisionError, DecisionState, NeurolinkCredentials } from "../types/index.js";
+import { SystemOneDecisionProvider } from "./systemOneDecision.js";
+/**
+ * Laya Provider — the `decide` inference type only.
+ *
+ * Laya is Convai Innovations' open-weights "System One" decision model: the
+ * same typed `noul` / `choice` / `score` questions as TypeSafe's Jev, answered
+ * by an encoder in one forward pass, on the same wire. The request loop,
+ * retries, auth circuit breaker and answer parsing are shared with every
+ * decision provider in {@link SystemOneDecisionProvider}.
+ *
+ * Its encoders read far less than Jev: 1,024 tokens on the `typed-decisions`
+ * and `multilingual` checkpoints, 512 on `english`. The descriptor's
+ * `decisionLimits` refuses what does not fit rather than letting the server
+ * cut the state off silently.
+ *
+ * @see https://github.com/NandhaKishorM/laya
+ */
+export declare class LayaProvider extends SystemOneDecisionProvider {
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(modelName?: string, sdk?: unknown, _region?: string, credentials?: NeurolinkCredentials["laya"]);
+    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>;
+    /** `auto` means "let Laya's router choose", which it does when no model is named. */
+    protected buildDecisionBody(state: DecisionState, questions: Record<string, Record<string, unknown>>, model: string): Record<string, unknown>;
+    protected parseDecisionError(status: number, payload: unknown, requestId: string | undefined): DecisionError;
+    protected readRequestId(headers: Headers): string | undefined;
+    /**
+     * The checkpoint that actually answered is `routing.model` — the one Laya's
+     * router picked when the request said `auto`.
+     */
+    protected resolveResponseModel(payload: Record<string, unknown>, requestedModel: string): string;
+}

package/dist/providers/laya.js

@@ -0,0 +1,170 @@
+import { LayaModels } 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, SystemOneDecisionProvider, } from "./systemOneDecision.js";
+/**
+ * LiteLLM 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 and any long hex run are
+ * all removed.
+ */
+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]")
+        .trim();
+}
+/**
+ * Normalise the two envelopes a Laya failure can arrive in.
+ *
+ * LiteLLM's own, `{"error":{"message","type","code"}}`, for anything the proxy
+ * rejects before Laya sees it (a bad key, a rate limit). FastAPI's, from
+ * Laya's server: `{"detail":"..."}` for its own checks (question types, the
+ * question cap) and `{"detail":[{loc,msg,input}]}` for request validation.
+ */
+function parseLayaError(status, body, requestId) {
+    const retryable = status === 429 || status >= 500;
+    const kind = status === 401 || status === 403
+        ? "authentication"
+        : status === 413
+            ? "max_tokens_exceeded"
+            : status === 429
+                ? "rate_limit"
+                : status === 503
+                    ? "overloaded"
+                    : status >= 500
+                        ? "server"
+                        : "invalid_request";
+    const proxyError = isRecord(body) && isRecord(body.error) ? body.error : undefined;
+    if (proxyError &&
+        typeof proxyError.message === "string" &&
+        proxyError.message.length > 0) {
+        return {
+            kind,
+            message: proxyError.message,
+            status,
+            requestId,
+            retryable,
+        };
+    }
+    const detail = isRecord(body) ? body.detail : undefined;
+    if (Array.isArray(detail)) {
+        return {
+            kind: "invalid_request",
+            message: `Request failed validation — ${describeValidationErrors(detail)}`,
+            status,
+            requestId,
+            retryable: false,
+        };
+    }
+    if (typeof detail === "string" && detail.length > 0) {
+        return { kind, message: detail, status, requestId, retryable };
+    }
+    return {
+        kind,
+        message: `Laya request failed with HTTP ${status}`,
+        status,
+        requestId,
+        retryable,
+    };
+}
+/**
+ * Laya Provider — the `decide` inference type only.
+ *
+ * Laya is Convai Innovations' open-weights "System One" decision model: the
+ * same typed `noul` / `choice` / `score` questions as TypeSafe's Jev, answered
+ * by an encoder in one forward pass, on the same wire. The request loop,
+ * retries, auth circuit breaker and answer parsing are shared with every
+ * decision provider in {@link SystemOneDecisionProvider}.
+ *
+ * Its encoders read far less than Jev: 1,024 tokens on the `typed-decisions`
+ * and `multilingual` checkpoints, 512 on `english`. The descriptor's
+ * `decisionLimits` refuses what does not fit rather than letting the server
+ * cut the state off silently.
+ *
+ * @see https://github.com/NandhaKishorM/laya
+ */
+export class LayaProvider extends SystemOneDecisionProvider {
+    apiKey;
+    baseURL;
+    constructor(modelName, sdk, _region, credentials) {
+        super(modelName, "laya", sdk);
+        this.apiKey =
+            credentials?.apiKey?.trim() || (process.env.LAYA_API_KEY?.trim() ?? "");
+        // No built-in endpoint: Laya is self-hosted or reached through a proxy
+        // (a Laya server, or a LiteLLM pass-through route to one), so the base URL
+        // comes only from config. `||`, not `??`, so a blank one counts as unset.
+        this.baseURL = (credentials?.baseURL?.trim() ||
+            process.env.LAYA_BASE_URL?.trim() ||
+            "").replace(/\/+$/, "");
+        // A self-hosted LAYA_BASE_URL can carry `user:pass@` or a `?token=`.
+        logger.debug("Laya Provider initialized (decide only)", {
+            modelName: this.modelName,
+            baseURL: this.baseURL ? redactUrlForError(this.baseURL) : "(not set)",
+        });
+    }
+    getDefaultModel() {
+        return getProviderModel("LAYA_MODEL", LayaModels.TYPED_DECISIONS);
+    }
+    vendorLabel() {
+        return "Laya";
+    }
+    vendorDisplayName() {
+        return "Laya";
+    }
+    decisionApiKey() {
+        return this.apiKey;
+    }
+    missingKeyMessage() {
+        return "Laya requires an API key. Set LAYA_API_KEY or pass credentials.laya.apiKey.";
+    }
+    missingConfigMessage() {
+        return this.baseURL
+            ? undefined
+            : "Laya requires a base URL. Set LAYA_BASE_URL or pass credentials.laya.baseURL.";
+    }
+    decisionEndpoint() {
+        return `${this.baseURL}/predict`;
+    }
+    decisionHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+        };
+    }
+    /** `auto` means "let Laya's router choose", which it does when no model is named. */
+    buildDecisionBody(state, questions, model) {
+        return model === LayaModels.AUTO
+            ? { state, questions }
+            : { model, state, questions };
+    }
+    parseDecisionError(status, payload, requestId) {
+        const parsed = parseLayaError(status, payload, requestId);
+        const message = redactCredentials(parsed.message, this.apiKey);
+        return {
+            ...parsed,
+            message: message || `Laya request failed with HTTP ${status}`,
+        };
+    }
+    readRequestId(headers) {
+        return headers.get("x-litellm-call-id") ?? undefined;
+    }
+    /**
+     * The checkpoint that actually answered is `routing.model` — the one Laya's
+     * router picked when the request said `auto`.
+     */
+    resolveResponseModel(payload, requestedModel) {
+        const routing = payload.routing;
+        if (isRecord(routing) && typeof routing.model === "string") {
+            return routing.model;
+        }
+        return super.resolveResponseModel(payload, requestedModel);
+    }
+}

package/dist/providers/systemOneDecision.d.ts

@@ -0,0 +1,102 @@
+import type { AIProviderName } from "../constants/enums.js";
+import { BaseProvider } from "../core/baseProvider.js";
+import { ProviderError } from "../types/index.js";
+import type { DecisionError, DecisionQuestion, DecisionRequest, DecisionResult, DecisionState, LanguageModel, StreamOptions, StreamResult, ValidationSchema } from "../types/index.js";
+/**
+ * Generous enough for a cold start (measured at 2.0–2.7s after idle on Jev)
+ * while still bounded. Every internal caller is fail-open, so this only bites
+ * on a genuine stall.
+ */
+export declare const DEFAULT_DECISION_TIMEOUT_MS = 5000;
+export declare const isRecord: (v: unknown) => v is Record<string, unknown>;
+export declare const asNumber: (v: unknown) => number | undefined;
+/**
+ * FastAPI's request-validation envelope, `{"detail":[{loc, msg, input}]}`,
+ * reduced to its field paths and messages. `input` echoes the caller's own
+ * request back — possibly the whole state — so it is never surfaced.
+ */
+export declare function describeValidationErrors(detail: readonly unknown[]): string;
+/**
+ * The shared half of every "System One" decision provider — a model that takes
+ * one `state` plus typed questions and returns one typed answer each, with no
+ * text anywhere.
+ *
+ * Vendors differ in where the request goes, how it is authenticated, what the
+ * body carries and what their error envelopes look like. They do not differ in
+ * anything else, so everything else lives here: the missing-key check, the
+ * auth circuit breaker, the timeout and retry loop, answer parsing and usage.
+ * A new decision provider implements the abstract hooks and nothing more.
+ */
+export declare abstract class SystemOneDecisionProvider extends BaseProvider {
+    protected readonly proxyFetch: typeof fetch;
+    private readonly maxRetries;
+    /**
+     * Set once the key has been rejected. A bad key cannot fix itself, and
+     * without this every later request would pay a full round trip (~265ms
+     * measured on Jev) to be told so again — a permanent tax on the hot path for
+     * a misconfiguration.
+     */
+    private authFailed;
+    protected constructor(modelName: string | undefined, providerName: AIProviderName, sdk: unknown);
+    /** Short vendor name for messages and logs, e.g. "TypeSafe". */
+    protected abstract vendorLabel(): string;
+    /** How the model is named when describing it, e.g. "TypeSafe (Jev)". */
+    protected abstract vendorDisplayName(): string;
+    protected abstract decisionApiKey(): string;
+    protected abstract missingKeyMessage(): string;
+    /**
+     * Why this instance cannot send a request even though it has a key, such as
+     * a provider with no built-in endpoint and none configured. Undefined when
+     * nothing is missing.
+     */
+    protected missingConfigMessage(): string | undefined;
+    protected abstract decisionEndpoint(): string;
+    protected abstract decisionHeaders(): Record<string, string>;
+    protected abstract buildDecisionBody(state: DecisionState, questions: Record<string, Record<string, unknown>>, model: string): Record<string, unknown>;
+    protected abstract parseDecisionError(status: number, payload: unknown, requestId: string | undefined): DecisionError;
+    protected abstract readRequestId(headers: Headers): string | undefined;
+    /**
+     * The System One wire calls the yes/no primitive `noul`; this codebase and
+     * every SDK exposing it call it `boolean`.
+     */
+    protected encodeQuestion(question: DecisionQuestion): Record<string, unknown>;
+    /** Per-question confidence a transport reports outside the answer objects. */
+    protected reportedConfidence(_payload: unknown): Record<string, number>;
+    protected resolveResponseModel(payload: Record<string, unknown>, requestedModel: string): string;
+    /** Extra fields for the credential-rejected warning. */
+    protected diagnosticContext(): Record<string, unknown>;
+    protected getProviderName(): AIProviderName;
+    protected getDefaultDecisionModel(): string | undefined;
+    supportsTools(): boolean;
+    /**
+     * A decision model produces no text, so there is no chat model behind it.
+     * Unreachable while the descriptor declares `inferenceKinds: ["decide"]`;
+     * kept actionable for the case where something routes here anyway.
+     */
+    protected getAISDKModel(): LanguageModel;
+    protected executeStream(_options: StreamOptions, _analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    /**
+     * Must RETURN the error, never throw it (CLAUDE.md rule 6).
+     */
+    protected formatProviderError(error: unknown): Error;
+    /**
+     * Evaluate a state against a batch of typed questions.
+     *
+     * Throws a {@link ProviderError} carrying a normalised {@link DecisionError}
+     * in `cause`. Internal hot paths should prefer `NeuroLink.tryDecide()`,
+     * which returns null instead.
+     */
+    decide(request: DecisionRequest): Promise<DecisionResult>;
+    /**
+     * 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
+     * be made on input the model never saw — and reported as if it had.
+     */
+    private assertWithinDecisionLimits;
+    /**
+     * Wrap a normalised decision failure in the provider error type, keeping
+     * the structured detail reachable via `cause` for callers that branch on
+     * `kind` (authentication vs rate_limit vs max_tokens_exceeded).
+     */
+    protected decisionError(detail: DecisionError): ProviderError;
+}