@juspay/neurolink 12.43.3 → 12.44.0

package/dist/providers/perplexityDecider.js

@@ -0,0 +1,373 @@
+import { PerplexityDeciderModels } from "../constants/enums.js";
+import { sniffImageMimeType } from "../utils/imageDetection.js";
+import { logger } from "../utils/logger.js";
+import { redactUrlForError } from "../utils/logSanitize.js";
+import { getProviderModel } from "../utils/providerConfig.js";
+import { isRecord, redactCredentials, SystemOneDecisionProvider, } from "./systemOneDecision.js";
+const PERPLEXITY_DEFAULT_BASE_URL = "https://api.perplexity.ai";
+const PERPLEXITY_ROUTE = "/v1/decisions";
+// The same attribution the Perplexity text provider sends (see
+// configuredOpenAICompat.ts): Perplexity asks to identify NeuroLink on its own
+// API host only, so a custom endpoint gets no such header.
+const PERPLEXITY_API_HOST = "api.perplexity.ai";
+const PERPLEXITY_INTEGRATION = "neurolink";
+/** The only image formats the API reads; anything else is a 400. */
+const SUPPORTED_IMAGE_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/webp",
+]);
+const IMAGE_TILE_PIXELS = 32;
+const MAX_IMAGE_TILES = 2048;
+/**
+ * Added to the descriptor's `decideMs` for each question. Latency follows the
+ * question count as well as the state: 128 minimal questions took 8.9 s on a
+ * 12,000-token request, about 65 ms for each after the first, so a request at
+ * the 128-question cap would otherwise outlast a flat 10 s and be retried into
+ * the same wait.
+ */
+const TIMEOUT_MS_PER_QUESTION = 100;
+/**
+ * The override is an origin, but the API's own documentation spells its server
+ * as `https://api.perplexity.ai/v1`, and the route already carries `/v1`. Both
+ * spellings reduce to the same base.
+ */
+function normalizeBaseURL(raw) {
+    return raw.replace(/\/+$/, "").replace(/\/v1$/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 PERPLEXITY_DECIDER_BASE_URL or pass credentials.perplexityDecider.baseURL to an origin, or leave both unset to use ${PERPLEXITY_DEFAULT_BASE_URL}.`;
+    try {
+        const url = new URL(baseURL);
+        // `new URL()` accepts any scheme, so a host:port with no scheme parses as
+        // one and would reach `fetch` as a network error instead of this message.
+        if (url.protocol !== "https:" && url.protocol !== "http:") {
+            return `The Perplexity base URL must start with https:// or http://. ${fix}`;
+        }
+        return url.username || url.password || url.search || url.hash
+            ? `The Perplexity base URL must not carry credentials, a query string or a fragment. ${fix}`
+            : undefined;
+    }
+    catch {
+        return `The Perplexity base URL is not a valid absolute URL. ${fix}`;
+    }
+}
+function isPerplexityApiHost(baseURL) {
+    try {
+        return new URL(baseURL).hostname === PERPLEXITY_API_HOST;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The model server answers input past its limit with a 400, not the 413 the
+ * gateway documents, so the kind comes from the text. `error.code` cannot be
+ * used: it is a string, a number or null depending on which layer answered.
+ */
+const OVER_LENGTH_MESSAGE = /exceeds or equals model's maximum context length/i;
+/**
+ * Only 401 is `authentication`, and so only 401 trips the breaker. Every other
+ * 4xx is something the caller or an account owner can fix without restarting
+ * the process, so it is a non-retried `invalid_request` rather than a latch.
+ * A 5xx and a 504 (the model not answering in time) are retryable.
+ */
+function perplexityErrorKind(status, message) {
+    if (status === 401) {
+        return "authentication";
+    }
+    if (status === 413 || (status === 400 && OVER_LENGTH_MESSAGE.test(message))) {
+        return "max_tokens_exceeded";
+    }
+    if (status === 429) {
+        return "rate_limit";
+    }
+    if (status === 503) {
+        return "overloaded";
+    }
+    return status >= 500 ? "server" : "invalid_request";
+}
+/**
+ * `{"error":{"message","type","code","param"}}`. A 404 and a 405 have an empty
+ * body and a 504 can be an HTML page, so a body that is not that envelope reads
+ * as undefined and the caller falls back to the status. `param` names the
+ * offending field on some 400s.
+ */
+function readPerplexityErrorMessage(body) {
+    if (!isRecord(body) || !isRecord(body.error)) {
+        return undefined;
+    }
+    const { message, param } = body.error;
+    if (typeof message !== "string" || message.length === 0) {
+        return undefined;
+    }
+    return typeof param === "string" && param !== "" && !message.includes(param)
+        ? `${message} (field: ${param})`
+        : message;
+}
+function readPngSize(bytes) {
+    return bytes.length >= 24 && bytes.toString("ascii", 12, 16) === "IHDR"
+        ? { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) }
+        : undefined;
+}
+/** Walks the marker segments to the first frame header (SOF0-SOF15). */
+function readJpegSize(bytes) {
+    let offset = 2;
+    while (offset + 4 <= bytes.length) {
+        if (bytes[offset] !== 0xff) {
+            return undefined;
+        }
+        const marker = bytes[offset + 1];
+        if (marker === 0xff) {
+            offset += 1;
+        }
+        else if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd8)) {
+            offset += 2;
+        }
+        else if (marker === 0xd9 || marker === 0xda) {
+            return undefined;
+        }
+        else if (marker >= 0xc0 &&
+            marker <= 0xcf &&
+            marker !== 0xc4 &&
+            marker !== 0xc8 &&
+            marker !== 0xcc) {
+            return offset + 9 <= bytes.length
+                ? {
+                    height: bytes.readUInt16BE(offset + 5),
+                    width: bytes.readUInt16BE(offset + 7),
+                }
+                : undefined;
+        }
+        else {
+            offset += 2 + bytes.readUInt16BE(offset + 2);
+        }
+    }
+    return undefined;
+}
+function readWebpSize(bytes) {
+    if (bytes.length < 30) {
+        return undefined;
+    }
+    switch (bytes.toString("ascii", 12, 16)) {
+        case "VP8X":
+            return {
+                width: 1 + bytes.readUIntLE(24, 3),
+                height: 1 + bytes.readUIntLE(27, 3),
+            };
+        case "VP8L": {
+            const bits = bytes.readUInt32LE(21);
+            return bytes[20] === 0x2f
+                ? { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 }
+                : undefined;
+        }
+        case "VP8 ":
+            return {
+                width: bytes.readUInt16LE(26) & 0x3fff,
+                height: bytes.readUInt16LE(28) & 0x3fff,
+            };
+        default:
+            return undefined;
+    }
+}
+function readImageSize(bytes) {
+    switch (sniffImageMimeType(bytes)) {
+        case "image/png":
+            return readPngSize(bytes);
+        case "image/jpeg":
+            return readJpegSize(bytes);
+        case "image/webp":
+            return readWebpSize(bytes);
+        default:
+            return undefined;
+    }
+}
+/**
+ * Why this image cannot be sent, or undefined when it can. The data URL is
+ * never repeated: it is megabytes of base64.
+ *
+ * The size check exists because the API does not refuse an oversized image: it
+ * holds the request for about a minute and then answers 504. An image whose
+ * dimensions cannot be read is sent as is.
+ */
+function imageProblem(dataUrl, position) {
+    const header = /^data:([a-z]+\/[a-z0-9.+-]+);base64,/i.exec(dataUrl);
+    if (!header || !SUPPORTED_IMAGE_TYPES.has(header[1].toLowerCase())) {
+        return `Image ${position} is not a PNG, JPEG or WebP image, the only formats Perplexity reads.`;
+    }
+    const size = readImageSize(Buffer.from(dataUrl.slice(header[0].length), "base64"));
+    if (!size) {
+        return undefined;
+    }
+    const tiles = Math.round(size.width / IMAGE_TILE_PIXELS) *
+        Math.round(size.height / IMAGE_TILE_PIXELS);
+    return tiles > MAX_IMAGE_TILES
+        ? `Image ${position} is ${size.width}x${size.height} pixels; Perplexity reads at most ${MAX_IMAGE_TILES} tiles of ${IMAGE_TILE_PIXELS}x${IMAGE_TILE_PIXELS} pixels per image (1440x1440 and 2048x1024 fit), and a larger one stalls until the request times out. Resize it first.`
+        : undefined;
+}
+/**
+ * The API takes a string, an object or an array as `state`, so a number or a
+ * boolean is sent as its text.
+ */
+function wireState(state) {
+    return typeof state === "number" || typeof state === "boolean"
+        ? String(state)
+        : state;
+}
+/**
+ * Perplexity Provider — the `decide` inference type only.
+ *
+ * `pplx-decider-v1-27b` answers the same typed `noul` / `choice` / `score`
+ * questions as the other decision providers, in one batched pass, and also reads
+ * images. It is a hosted API with a public endpoint, so unlike the self-hosted
+ * providers it needs only a key. The request loop, retries, auth circuit
+ * breaker and answer parsing are shared with every decision provider in
+ * {@link SystemOneDecisionProvider}.
+ *
+ * The key is the same `PERPLEXITY_API_KEY` the Sonar text provider reads, so a
+ * host that has configured that provider has also configured this one.
+ *
+ * @see https://docs.perplexity.ai/api-reference/decisions-post
+ */
+export class PerplexityDeciderProvider extends SystemOneDecisionProvider {
+    apiKey;
+    baseURL;
+    constructor(modelName, sdk, _region, credentials) {
+        super(modelName, "perplexity-decider", sdk);
+        this.apiKey =
+            credentials?.apiKey?.trim() ||
+                (process.env.PERPLEXITY_API_KEY?.trim() ?? "");
+        // `||`, not `??`, so a blank override counts as unset.
+        this.baseURL = normalizeBaseURL(credentials?.baseURL?.trim() ||
+            process.env.PERPLEXITY_DECIDER_BASE_URL?.trim() ||
+            PERPLEXITY_DEFAULT_BASE_URL);
+        // A base URL that `baseURLProblem` refuses is not logged at all: it can
+        // carry `user:pass@` or a `?token=`, and `redactUrlForError` cannot be
+        // trusted with one that has no scheme, because `user:pass@host:80` parses as
+        // the scheme `user:` and is rebuilt with the password intact.
+        logger.debug("Perplexity decision provider initialized (decide only)", {
+            modelName: this.modelName,
+            baseURL: baseURLProblem(this.baseURL)
+                ? "(invalid)"
+                : redactUrlForError(this.baseURL),
+        });
+    }
+    getDefaultModel() {
+        return getProviderModel("PERPLEXITY_DECIDER_MODEL", PerplexityDeciderModels.PPLX_DECIDER_V1_27B);
+    }
+    vendorLabel() {
+        return "Perplexity";
+    }
+    vendorDisplayName() {
+        return "Perplexity Decisions";
+    }
+    decisionApiKey() {
+        return this.apiKey;
+    }
+    missingKeyMessage() {
+        return "Perplexity requires an API key. Set PERPLEXITY_API_KEY or pass credentials.perplexityDecider.apiKey.";
+    }
+    missingConfigMessage() {
+        return baseURLProblem(this.baseURL);
+    }
+    decisionEndpoint() {
+        return `${this.baseURL}${PERPLEXITY_ROUTE}`;
+    }
+    decisionHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            ...(isPerplexityApiHost(this.baseURL)
+                ? { "X-Pplx-Integration": PERPLEXITY_INTEGRATION }
+                : {}),
+        };
+    }
+    /**
+     * `model` is always sent: the API answers 400 to a request that names none.
+     * Images travel inside `state`, which becomes an array of the caller's state
+     * followed by one OpenAI-style `image_url` part per image; the API has no
+     * separate images field and rejects unknown ones.
+     */
+    buildDecisionBody(state, questions, model, media) {
+        const images = media?.images ?? [];
+        if (images.length === 0) {
+            return { model, state: wireState(state), questions };
+        }
+        images.forEach((dataUrl, index) => {
+            const problem = imageProblem(dataUrl, index + 1);
+            if (problem) {
+                throw this.decisionError({
+                    kind: "invalid_request",
+                    message: problem,
+                    retryable: false,
+                });
+            }
+        });
+        const content = Array.isArray(state)
+            ? state
+            : state === ""
+                ? []
+                : [wireState(state)];
+        return {
+            model,
+            state: [
+                ...content,
+                ...images.map((url) => ({ type: "image_url", image_url: { url } })),
+            ],
+            questions,
+        };
+    }
+    parseDecisionError(status, payload, requestId) {
+        const fallback = `Perplexity request failed with HTTP ${status}`;
+        // Strip anything shaped like a Perplexity key as well as the configured
+        // one. Keys carry `_` and `-`, so the class includes them. A key has 48
+        // characters after the prefix, and the floor sits well under that but above
+        // any model name: the 400 that rejects `pplx-decider-v1-27b-latest` has to
+        // keep naming it.
+        const message = redactCredentials(readPerplexityErrorMessage(payload) ?? fallback, this.apiKey)
+            .replace(/\bpplx-[A-Za-z0-9_-]{30,}/g, "[redacted]")
+            .trim() || fallback;
+        const kind = perplexityErrorKind(status, message);
+        return {
+            kind,
+            message,
+            status,
+            requestId,
+            retryable: kind === "rate_limit" || kind === "overloaded" || kind === "server",
+        };
+    }
+    /**
+     * A 401, a 404 and a 504 carry no request id, so this is undefined for them.
+     */
+    readRequestId(headers) {
+        return headers.get("x-request-id") ?? undefined;
+    }
+    defaultTimeoutMs(questionCount) {
+        const allowance = this.getDescriptorDecideMs();
+        return allowance === undefined
+            ? undefined
+            : allowance + questionCount * TIMEOUT_MS_PER_QUESTION;
+    }
+    /**
+     * `Retry-After` is whole seconds on a 429, or an HTTP date. Anything else, a
+     * zero and a date already past all read as undefined, so the retry takes the
+     * default backoff instead of going out at once. `Number()` is not used: it
+     * reads "0x10" as 16 and "1e3" as 1,000.
+     */
+    readRetryAfterMs(headers) {
+        const raw = headers.get("retry-after")?.trim();
+        if (!raw) {
+            return undefined;
+        }
+        const ms = /^\d+$/.test(raw)
+            ? Number(raw) * 1000
+            : Date.parse(raw) - Date.now();
+        return Number.isFinite(ms) && ms > 0 ? Math.ceil(ms) : undefined;
+    }
+}

package/dist/providers/systemOneDecision.d.ts

@@ -69,6 +69,18 @@ export declare abstract class SystemOneDecisionProvider extends BaseProvider {
      * every SDK exposing it call it `boolean`.
      */
     protected encodeQuestion(question: DecisionQuestion): Record<string, unknown>;
+    /**
+     * How long a rate-limited or unavailable response asks the caller to wait.
+     * Undefined keeps the default backoff. A wait longer than what is left of the
+     * attempt's timeout is not taken: the error is thrown at once, so a fail-open
+     * consumer is not held for the length of a vendor's cooldown.
+     */
+    protected readRetryAfterMs(_headers: Headers): number | undefined;
+    /**
+     * The per-attempt timeout when the caller sets none. A provider whose latency
+     * grows with the number of questions scales the descriptor's allowance here.
+     */
+    protected defaultTimeoutMs(_questionCount: number): number | undefined;
     /** 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;

package/dist/providers/systemOneDecision.js

@@ -149,7 +149,28 @@ export function redactCredentials(message, apiKey) {
         .replace(/data:[a-z]+\/[a-z0-9.+-]+;base64,[A-Za-z0-9+/=]+/gi, "[media]")
         .trim();
 }
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Rejects with the signal's reason when it aborts, so a caller tearing a turn
+ * down is not held, nor its process kept alive, for the length of a vendor's
+ * Retry-After wait. The half-second backoff after a transport error is waited
+ * out without a signal: a rejection there would leave the catch block that is
+ * already handling that error.
+ */
+const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason);
+        return;
+    }
+    const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    function onAbort() {
+        clearTimeout(timer);
+        reject(signal?.reason);
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+});
 /**
  * `estimateTokens` assumes ~4 characters per token. That holds for English
  * and is several times too generous for other scripts on an English
@@ -214,6 +235,22 @@ export class SystemOneDecisionProvider extends BaseProvider {
         }
         return question;
     }
+    /**
+     * How long a rate-limited or unavailable response asks the caller to wait.
+     * Undefined keeps the default backoff. A wait longer than what is left of the
+     * attempt's timeout is not taken: the error is thrown at once, so a fail-open
+     * consumer is not held for the length of a vendor's cooldown.
+     */
+    readRetryAfterMs(_headers) {
+        return undefined;
+    }
+    /**
+     * The per-attempt timeout when the caller sets none. A provider whose latency
+     * grows with the number of questions scales the descriptor's allowance here.
+     */
+    defaultTimeoutMs(_questionCount) {
+        return this.getDescriptorDecideMs();
+    }
     /** Per-question confidence a transport reports outside the answer objects. */
     reportedConfidence(_payload) {
         return {};
@@ -306,7 +343,7 @@ export class SystemOneDecisionProvider extends BaseProvider {
         const body = JSON.stringify(this.buildDecisionBody(request.state, wireQuestions, resolvedModel, media));
         this.assertWithinRequestBytes(body);
         const timeoutMs = request.timeoutMs ??
-            this.getDescriptorDecideMs() ??
+            this.defaultTimeoutMs(questionEntries.length) ??
             this.defaultTimeout ??
             DEFAULT_DECISION_TIMEOUT_MS;
         let lastError;
@@ -346,7 +383,14 @@ export class SystemOneDecisionProvider extends BaseProvider {
                     if (!lastError.retryable || attempt === this.maxRetries) {
                         throw this.decisionError(lastError);
                     }
-                    await sleep(2 ** attempt * 250 + Math.random() * 250);
+                    const retryAfterMs = this.readRetryAfterMs(response.headers);
+                    // The wait comes out of this attempt's own budget, so a slow answer
+                    // with a long Retry-After cannot be followed by a second full attempt.
+                    if (retryAfterMs !== undefined &&
+                        retryAfterMs > timeoutMs - (Date.now() - startedAt)) {
+                        throw this.decisionError(lastError);
+                    }
+                    await sleep(retryAfterMs ?? 2 ** attempt * 250 + Math.random() * 250, request.signal);
                     continue;
                 }
                 if (!isRecord(payload) || !isRecord(payload.answers)) {
@@ -426,7 +470,7 @@ export class SystemOneDecisionProvider extends BaseProvider {
      */
     async prepareMedia(request) {
         const limits = PROVIDER_DESCRIPTORS_BY_NAME.get(this.providerName)?.decisionLimits;
-        const prepared = await prepareDecisionMedia(request, limits?.media, this.vendorLabel(), listMediaDecisionProviders());
+        const prepared = await prepareDecisionMedia(request, limits?.media, this.vendorLabel(), listMediaDecisionProviders({ video: request.video !== undefined }));
         if (prepared.status === "refused") {
             throw this.decisionError({
                 kind: "invalid_request",

package/dist/types/classifierRouter.d.ts

@@ -26,7 +26,8 @@ export type ClassifierDifficulty = "trivial" | "simple" | "moderate" | "hard" |
  *   *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`, `LAYA_API_KEY` with
- *   `LAYA_BASE_URL`, or `XOR_API_KEY` with `XOR_BASE_URL`), otherwise
+ *   `LAYA_BASE_URL`, `XOR_API_KEY` with `XOR_BASE_URL`, or
+ *   `PERPLEXITY_API_KEY`), otherwise
  *   `heuristic`.
  */
 export type ClassifierStrategyKind = "heuristic" | "llm" | "jev" | "auto";
@@ -187,10 +188,11 @@ 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`, `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.
+     * (`TYPESAFE_API_KEY`, `LAYA_API_KEY` with `LAYA_BASE_URL`,
+     * `XOR_API_KEY` with `XOR_BASE_URL`, or `PERPLEXITY_API_KEY`) and "heuristic"
+     * otherwise, so configuring one upgrades routing without any code change.
+     * Behaviour for callers with no key is unchanged. `PERPLEXITY_API_KEY` is also
+     * the Perplexity text provider's key, so it counts here too.
      */
     classifier?: ClassifierStrategyKind;
     /** Model used by the "llm" strategy. Defaults to provider/model auto. */

package/dist/types/cli.d.ts

@@ -1727,7 +1727,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, LAYA_API_KEY with
-     * LAYA_BASE_URL, or XOR_API_KEY with XOR_BASE_URL) and "heuristic" otherwise.
+     * LAYA_BASE_URL, XOR_API_KEY with XOR_BASE_URL, or PERPLEXITY_API_KEY) and
+     * "heuristic" otherwise.
      */
     classifierStrategy?: string;
     /**

package/dist/types/decision.d.ts

@@ -169,6 +169,11 @@ export type DecisionMediaLimits = {
     /** Ceiling on the encoded request body, in bytes. */
     maxRequestBytes: 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. */
 export type DecisionPreparedMedia = {
     images: string[];

package/dist/types/providers.d.ts

@@ -568,6 +568,17 @@ export type NeurolinkCredentials = {
         apiKey?: string;
         baseURL?: string;
     };
+    /**
+     * Perplexity Decisions API — the `decide` inference type. The key is the same
+     * `PERPLEXITY_API_KEY` the `perplexity` text provider reads, but this slice
+     * is separate so the two cannot be mixed up. `baseURL` is optional and
+     * defaults to `https://api.perplexity.ai`; requests go to
+     * `<baseURL>/v1/decisions`.
+     */
+    perplexityDecider?: {
+        apiKey?: string;
+        baseURL?: string;
+    };
 };
 /**
  * Voyage AI /embeddings response shape.

package/dist/utils/modelChoices.js

@@ -2,7 +2,7 @@
  * Centralized model choices for CLI commands
  * Derives choices from model enums to ensure consistency
  */
-import { AIProviderName, OpenAIModels, AnthropicModels, GoogleAIModels, BedrockModels, VertexModels, OllamaModels, AzureOpenAIModels, LiteLLMModels, SageMakerModels, OpenRouterModels, NvidiaNimModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, TypeSafeModels, LayaModels, XorModels, ReplicateModels, } from "../constants/enums.js";
+import { AIProviderName, OpenAIModels, AnthropicModels, GoogleAIModels, BedrockModels, VertexModels, OllamaModels, AzureOpenAIModels, LiteLLMModels, SageMakerModels, OpenRouterModels, NvidiaNimModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, TypeSafeModels, LayaModels, XorModels, PerplexityDeciderModels, ReplicateModels, } from "../constants/enums.js";
 import { getCatalogJsonEntries } from "../providers/catalog/loader.js";
 /**
  * Looks up the JSON catalog entry for a provider, if it is one of the 11
@@ -393,6 +393,12 @@ const TOP_MODELS_CONFIG = {
             description: "Recommended - XOR 1.1, decision model that also reads images and video",
         },
     ],
+    [AIProviderName.PERPLEXITY_DECIDER]: [
+        {
+            model: PerplexityDeciderModels.PPLX_DECIDER_V1_27B,
+            description: "Recommended - Perplexity decision model that also reads images",
+        },
+    ],
     [AIProviderName.AUTO]: [],
 };
 /**
@@ -434,6 +440,7 @@ export const DEFAULT_MODELS = {
     [AIProviderName.TYPESAFE]: TypeSafeModels.JEV_LATEST,
     [AIProviderName.LAYA]: LayaModels.TYPED_DECISIONS,
     [AIProviderName.XOR]: XorModels.XOR_1_1,
+    [AIProviderName.PERPLEXITY_DECIDER]: PerplexityDeciderModels.PPLX_DECIDER_V1_27B,
 };
 /**
  * Model enum mappings for getAllModels.
@@ -468,6 +475,7 @@ const MODEL_ENUMS = {
     [AIProviderName.TYPESAFE]: TypeSafeModels,
     [AIProviderName.LAYA]: LayaModels,
     [AIProviderName.XOR]: XorModels,
+    [AIProviderName.PERPLEXITY_DECIDER]: PerplexityDeciderModels,
     [AIProviderName.AUTO]: null,
 };
 /**

package/dist/utils/pricing.js

@@ -780,6 +780,14 @@ const PRICING = {
         _default: { input: 0.042 / 1_000_000, output: 0 },
         "jev-latest": { input: 0.042 / 1_000_000, output: 0 },
     },
+    "perplexity-decider": {
+        // The Decisions API bills $0.04 per million INPUT tokens (image tokens
+        // included) and charges nothing for output or per request. `output: 0` is
+        // a price, not a token count, so do not "correct" it from
+        // `usage.output_tokens`. Rate from the API reference (checked 2026-10-02).
+        _default: { input: 0.04 / 1_000_000, output: 0 },
+        "pplx-decider-v1-27b": { input: 0.04 / 1_000_000, output: 0 },
+    },
     stability: {
         // Stability AI bills per image; symbolic per-token rate.
         _default: { input: 0, output: 0.04 / 1_000 },

package/dist/utils/providerConfig.d.ts

@@ -410,3 +410,9 @@ export declare function createLayaConfig(): ProviderConfigOptions;
  * built-in endpoint: XOR_BASE_URL is required alongside the key.
  */
 export declare function createXorConfig(): ProviderConfigOptions;
+/**
+ * Perplexity Decisions API — the `decide` inference type, not the Sonar text
+ * models. It reads the same PERPLEXITY_API_KEY as the `perplexity` text
+ * provider and has a public endpoint, so the key alone configures it.
+ */
+export declare function createPerplexityDeciderConfig(): ProviderConfigOptions;

package/dist/utils/providerConfig.js

@@ -1358,3 +1358,21 @@ export function createXorConfig() {
         ],
     };
 }
+/**
+ * Perplexity Decisions API — the `decide` inference type, not the Sonar text
+ * models. It reads the same PERPLEXITY_API_KEY as the `perplexity` text
+ * provider and has a public endpoint, so the key alone configures it.
+ */
+export function createPerplexityDeciderConfig() {
+    return {
+        providerName: "Perplexity Decisions",
+        envVarName: "PERPLEXITY_API_KEY",
+        setupUrl: "https://console.perplexity.ai",
+        description: "API key for the Perplexity Decisions API",
+        instructions: [
+            "1. Create an API key in the Perplexity console (https://console.perplexity.ai)",
+            "2. Set PERPLEXITY_API_KEY; it is the same key the Perplexity text provider reads, so setting it also lets decide() use Perplexity when no other decision provider is configured",
+            "3. Optionally set PERPLEXITY_DECIDER_BASE_URL to an origin other than https://api.perplexity.ai (NeuroLink calls <base>/v1/decisions)",
+        ],
+    };
+}