@juspay/neurolink 12.43.3 → 12.44.0

package/dist/cli/commands/decide.d.ts

@@ -9,7 +9,7 @@
  *
  * Credentials are env-only here, exactly as every other CLI command: the
  * decision provider reads its own settings (TYPESAFE_API_KEY, LAYA_API_KEY and
- * LAYA_BASE_URL, or XOR_API_KEY and XOR_BASE_URL) itself.
+ * LAYA_BASE_URL, XOR_API_KEY and XOR_BASE_URL, or PERPLEXITY_API_KEY) itself.
  */
 import type { CommandModule } from "yargs";
 import type { CliDecideArgs } from "../../types/index.js";

package/dist/cli/commands/decide.js

@@ -9,7 +9,7 @@
  *
  * Credentials are env-only here, exactly as every other CLI command: the
  * decision provider reads its own settings (TYPESAFE_API_KEY, LAYA_API_KEY and
- * LAYA_BASE_URL, or XOR_API_KEY and XOR_BASE_URL) itself.
+ * LAYA_BASE_URL, XOR_API_KEY and XOR_BASE_URL, or PERPLEXITY_API_KEY) itself.
  */
 import chalk from "chalk";
 import ora from "ora";
@@ -191,7 +191,7 @@ export const decideCommand = {
         type: "string",
         array: true,
         nargs: 1,
-        describe: "Image for the model to read: a file path or a data: URL. Repeat for several (XOR takes up to 8)",
+        describe: "Image for the model to read: a file path or a data: URL. Repeat for several (XOR and Perplexity take up to 8)",
     })
         .option("video", {
         type: "string",
@@ -217,7 +217,7 @@ export const decideCommand = {
     })
         .example('$0 decide "Refund request for a damaged item" --questions \'{"urgent":{"type":"boolean","instructions":"Is this urgent?"}}\'', "Ask a single yes/no question")
         .example("$0 decide --state-file ticket.json --questions-file questions.json --format json", "Read state and questions from files, emit raw JSON")
-        .example('$0 decide "What color is this?" --provider xor --image ./photo.png --questions \'{"color":{"type":"choice","instructions":"What color is the image?","criteria":{"red":"red","blue":"blue"}}}\'', "Ask about an image (XOR only)"),
+        .example('$0 decide "What color is this?" --provider xor --image ./photo.png --questions \'{"color":{"type":"choice","instructions":"What color is the image?","criteria":{"red":"red","blue":"blue"}}}\'', "Ask about an image (XOR and Perplexity read images)"),
     handler: async (argv) => {
         const outputFormat = argv.format ?? "text";
         // --- Validate before any provider work ---------------------------------

package/dist/cli/commands/setup.js

@@ -20,7 +20,7 @@ import { handleGCPSetup } from "./setup-gcp.js";
 import { handleHuggingFaceSetup } from "./setup-huggingface.js";
 import { handleMistralSetup } from "./setup-mistral.js";
 import { PROVIDER_DESCRIPTORS_BY_NAME } from "../../factories/providerDescriptors.js";
-import { createCohereConfig, createDeepSeekConfig, createIdeogramConfig, createJinaConfig, createNvidiaNimConfig, createOpenAICompatibleConfig, createRecraftConfig, createReplicateConfig, createStabilityConfig, createVoyageConfig, createTypeSafeConfig, createLayaConfig, createXorConfig, satisfiesFallbacks, } from "../../utils/providerConfig.js";
+import { createCohereConfig, createDeepSeekConfig, createIdeogramConfig, createJinaConfig, createNvidiaNimConfig, createOpenAICompatibleConfig, createRecraftConfig, createReplicateConfig, createStabilityConfig, createVoyageConfig, createTypeSafeConfig, createLayaConfig, createXorConfig, createPerplexityDeciderConfig, satisfiesFallbacks, } from "../../utils/providerConfig.js";
 import { getCatalogJsonEntries, buildCatalogConfigOptions, } from "../../providers/catalog/loader.js";
 // Provider information database
 const PROVIDERS = [
@@ -171,6 +171,7 @@ export const EXTRA_PROVIDER_CONFIGS = {
     typesafe: createTypeSafeConfig(),
     laya: createLayaConfig(),
     xor: createXorConfig(),
+    "perplexity-decider": createPerplexityDeciderConfig(),
     ...Object.fromEntries(getCatalogJsonEntries()
         .filter((e) => e.id !== "mistral")
         .map((e) => [e.id, buildCatalogConfigOptions(e)])),

package/dist/cli/factories/commandFactory.js

@@ -616,7 +616,7 @@ export class CLICommandFactory {
         },
         classifierStrategy: {
             type: "string",
-            description: "Classifier strategy: 'auto' (default — 'jev' when a decision provider is configured, such as TYPESAFE_API_KEY, LAYA_API_KEY with LAYA_BASE_URL, or XOR_API_KEY with XOR_BASE_URL, else 'heuristic'), 'heuristic' (no LLM), 'llm' (a cheap model picks per prompt), or 'jev' (a System One decision model — TypeSafe Jev, Laya or XOR — with calibrated confidence).",
+            description: "Classifier strategy: 'auto' (default — 'jev' when a decision provider is configured, such as TYPESAFE_API_KEY, LAYA_API_KEY with LAYA_BASE_URL, XOR_API_KEY with XOR_BASE_URL, or PERPLEXITY_API_KEY, else 'heuristic'), 'heuristic' (no LLM), 'llm' (a cheap model picks per prompt), or 'jev' (a System One decision model — TypeSafe Jev, Laya, XOR or Perplexity — with calibrated confidence).",
             choices: ["auto", "heuristic", "llm", "jev"],
             alias: "classifier-strategy",
         },

package/dist/constants/enums.d.ts

@@ -109,6 +109,11 @@ export declare enum AIProviderName {
     LAYA = "laya",
     /** XOR (Juspay, open weights) — serves the `decide` inference type only. */
     XOR = "xor",
+    /**
+     * Perplexity Decisions API (`pplx-decider-v1-27b`) — serves the `decide`
+     * inference type only. Distinct from `PERPLEXITY`, the Sonar text provider.
+     */
+    PERPLEXITY_DECIDER = "perplexity-decider",
     AUTO = "auto"
 }
 /**
@@ -1764,3 +1769,11 @@ export declare enum LayaModels {
 export declare enum XorModels {
     XOR_1_1 = "xor-1.1"
 }
+/**
+ * Perplexity decision models. Hand-written: the Decisions API is a Tier-3
+ * provider, so it is not in the provider catalog and codegen never touches
+ * this. The API serves one model and answers 400 to a missing or unknown one.
+ */
+export declare enum PerplexityDeciderModels {
+    PPLX_DECIDER_V1_27B = "pplx-decider-v1-27b"
+}

package/dist/constants/enums.js

@@ -115,6 +115,11 @@ export var AIProviderName;
     AIProviderName["LAYA"] = "laya";
     /** XOR (Juspay, open weights) — serves the `decide` inference type only. */
     AIProviderName["XOR"] = "xor";
+    /**
+     * Perplexity Decisions API (`pplx-decider-v1-27b`) — serves the `decide`
+     * inference type only. Distinct from `PERPLEXITY`, the Sonar text provider.
+     */
+    AIProviderName["PERPLEXITY_DECIDER"] = "perplexity-decider";
     AIProviderName["AUTO"] = "auto";
 })(AIProviderName || (AIProviderName = {}));
 /**
@@ -2084,3 +2089,12 @@ export var XorModels;
 (function (XorModels) {
     XorModels["XOR_1_1"] = "xor-1.1";
 })(XorModels || (XorModels = {}));
+/**
+ * Perplexity decision models. Hand-written: the Decisions API is a Tier-3
+ * provider, so it is not in the provider catalog and codegen never touches
+ * this. The API serves one model and answers 400 to a missing or unknown one.
+ */
+export var PerplexityDeciderModels;
+(function (PerplexityDeciderModels) {
+    PerplexityDeciderModels["PPLX_DECIDER_V1_27B"] = "pplx-decider-v1-27b";
+})(PerplexityDeciderModels || (PerplexityDeciderModels = {}));

package/dist/factories/providerDescriptors.d.ts

@@ -30,8 +30,14 @@ export declare const DECISION_PROVIDERS: readonly ProviderDescriptor[];
  * internal consumer treats as "carry on exactly as before".
  */
 export declare function resolveDefaultDecisionProvider(credentials?: NeurolinkCredentials): string | undefined;
-/** Names of the decision providers that accept images or video. */
-export declare function listMediaDecisionProviders(): string[];
+/**
+ * Names of the decision providers that accept images, or, with `video`, the
+ * ones that accept video too: a hint that names a provider which would refuse
+ * the same request is worse than none.
+ */
+export declare function listMediaDecisionProviders(needs?: {
+    video?: boolean;
+}): string[];
 /**
  * The variables that would configure each decision provider, one clause per
  * provider in precedence order, e.g. "TYPESAFE_API_KEY or AI_GATEWAY_API_KEY

package/dist/factories/providerDescriptors.js

@@ -1,5 +1,5 @@
 import { AIProviderName } from "../constants/enums.js";
-import { GoogleAIModels, OpenAIModels, AnthropicModels, VertexModels, OllamaModels, LiteLLMModels, NvidiaNimModels, OpenRouterModels, CohereModels, VoyageModels, TypeSafeModels, LayaModels, XorModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, ReplicateModels, } from "../constants/enums.js";
+import { GoogleAIModels, OpenAIModels, AnthropicModels, VertexModels, OllamaModels, LiteLLMModels, NvidiaNimModels, OpenRouterModels, CohereModels, VoyageModels, TypeSafeModels, LayaModels, XorModels, PerplexityDeciderModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, ReplicateModels, } from "../constants/enums.js";
 import { API_KEY_FORMATS } from "../utils/providerConfig.js";
 import { getCatalogJsonEntries, catalogCredentialsKey, catalogEnvVar, } from "../providers/catalog/loader.js";
 import { DEFAULT_INFERENCE_KINDS } from "../types/index.js";
@@ -451,7 +451,7 @@ const HAND_DESCRIPTORS = [
         timeouts: { decideMs: 5000 },
         setupUrl: "https://console.typesafe.ai/keys",
     },
-    // Laya MUST stay after TypeSafe, and XOR after Laya.
+    // Laya MUST stay after TypeSafe, XOR after Laya, and Perplexity after XOR.
     // resolveDefaultDecisionProvider() returns the first configured
     // DECISION_PROVIDERS entry, in this order, so a host configured for several
     // keeps Jev for every built-in consumer and reaches the others only by
@@ -543,6 +543,69 @@ const HAND_DESCRIPTORS = [
         },
         setupUrl: "https://huggingface.co/juspay/xor",
     },
+    {
+        name: AIProviderName.PERPLEXITY_DECIDER,
+        aliases: [],
+        credentialsKey: "perplexityDecider",
+        envVars: {
+            // The same key the `perplexity` text provider reads, so an ambient
+            // PERPLEXITY_API_KEY configures this provider too. It sits after XOR in
+            // this list, which is what keeps that from displacing any other decision
+            // provider a host has configured.
+            apiKey: "PERPLEXITY_API_KEY",
+            // Optional: the API is hosted at a public endpoint, so a key alone is
+            // enough and there is no extraRequired.
+            baseURL: "PERPLEXITY_DECIDER_BASE_URL",
+            model: "PERPLEXITY_DECIDER_MODEL",
+        },
+        defaultModel: PerplexityDeciderModels.PPLX_DECIDER_V1_27B,
+        // Serves only `decide`, like the other decision providers — the one
+        // declaration that keeps it out of every generation code path, and out of
+        // the way of the `perplexity` text provider.
+        inferenceKinds: ["decide"],
+        toolSupport: "none",
+        localRuntime: false,
+        healthCheck: "env-only",
+        // Deliberately NO autoSelectPriority / autoSelectPreference /
+        // defaultHealthSweepPriority, for the same reason as TypeSafe above.
+        //
+        // Measured live: 4s at 65,000 input tokens, 10s at 146,000 and 23s at
+        // 251,000 (faster than linear: about 17,000, 15,000 and 11,000 tokens a
+        // second), plus about 65 ms for each question after the first (128 minimal
+        // questions took 8.9s). 10s is the allowance for the state and covers every
+        // one the window below admits except log text or number arrays close to it;
+        // the provider adds 100 ms a question on top, so a request at the
+        // 128-question cap waits about 22.8s. A larger state passes a per-call
+        // `timeoutMs`.
+        timeouts: { decideMs: 10_000 },
+        // The server reads 262,144 input tokens in all and answers an over-long
+        // request with an explicit 400, never a silent truncation. The state and the
+        // questions were measured to count toward it; images are billed as input
+        // tokens and presumably count too. The window below is deliberately lower: a
+        // state of 100,000 tokens takes about 7s of the 10s above (interpolated from
+        // those points), and a much larger one would outlast it and be retried into
+        // the same wait. The estimate is about four characters per token. Measured
+        // on 40,000-character samples: English prose 4.3, TypeScript 3.8, a minified
+        // JSON catalog 3.4, log lines with timestamps and ids 1.35 and arrays of
+        // numbers 1.2. Only the last two run low enough to pass the window and still
+        // be refused by the server; JSON is under-counted by about 13%. A request
+        // over the window fails locally as max_tokens_exceeded, which every consumer
+        // treats as "carry on as before". 128 questions is the documented cap,
+        // confirmed live.
+        // Non-ASCII text is charged at the measured rate for CJK (0.46 tokens per
+        // code point) and Devanagari (0.44), not for emoji (2.6), because an
+        // over-charge silently shuts every non-Latin caller out while an
+        // under-charge is caught by that 400.
+        decisionLimits: {
+            maxStateTokens: 100_000,
+            maxQuestions: 128,
+            nonAsciiTokensPerChar: 0.5,
+            // Images only; the API has no video input. A ninth image in one request
+            // is refused with a 400, and the 32 MiB body is the documented cap.
+            media: { maxImages: 8, video: false, maxRequestBytes: 32 * 1024 * 1024 },
+        },
+        setupUrl: "https://console.perplexity.ai",
+    },
 ];
 /**
  * Builds a ProviderDescriptor for every JSON-catalog provider. Every field
@@ -678,9 +741,16 @@ function isDecisionProviderConfigured(descriptor, credentials) {
 export function resolveDefaultDecisionProvider(credentials) {
     return DECISION_PROVIDERS.find((descriptor) => isDecisionProviderConfigured(descriptor, credentials))?.name;
 }
-/** Names of the decision providers that accept images or video. */
-export function listMediaDecisionProviders() {
-    return DECISION_PROVIDERS.filter((descriptor) => descriptor.decisionLimits?.media !== undefined).map((descriptor) => descriptor.name);
+/**
+ * Names of the decision providers that accept images, or, with `video`, the
+ * ones that accept video too: a hint that names a provider which would refuse
+ * the same request is worse than none.
+ */
+export function listMediaDecisionProviders(needs) {
+    return DECISION_PROVIDERS.filter((descriptor) => {
+        const media = descriptor.decisionLimits?.media;
+        return media !== undefined && (!needs?.video || media.video);
+    }).map((descriptor) => descriptor.name);
 }
 /**
  * The variables that would configure each decision provider, one clause per

package/dist/factories/providerRegistry.js

@@ -1,6 +1,6 @@
 import { ProviderFactory } from "./providerFactory.js";
 import { logger } from "../utils/logger.js";
-import { AIProviderName, GoogleAIModels, OpenAIModels, AnthropicModels, VertexModels, OllamaModels, LiteLLMModels, NvidiaNimModels, OpenRouterModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, TypeSafeModels, LayaModels, XorModels, ReplicateModels, } from "../constants/enums.js";
+import { AIProviderName, GoogleAIModels, OpenAIModels, AnthropicModels, VertexModels, OllamaModels, LiteLLMModels, NvidiaNimModels, OpenRouterModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, TypeSafeModels, LayaModels, XorModels, PerplexityDeciderModels, ReplicateModels, } from "../constants/enums.js";
 import { PROVIDER_DESCRIPTORS_BY_NAME } from "./providerDescriptors.js";
 import { OPENAI_COMPAT_CATALOG } from "../providers/openaiCompatCatalog.js";
 import { providerChoicesFor } from "./mediaHandlerCatalog.js";
@@ -250,6 +250,16 @@ export class ProviderRegistry {
                 const { XorProvider } = await import("../providers/xor.js");
                 return new XorProvider(modelName, sdk, undefined, xorCreds);
             }, process.env.XOR_MODEL || XorModels.XOR_1_1, [], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.XOR));
+            // Register the Perplexity Decisions API — a `decide` provider reached at
+            // Perplexity's public endpoint. Its descriptor declares inferenceKinds:
+            // ["decide"], so nothing in the generation fallback chain can reach it,
+            // and it is registered apart from the `perplexity` text provider.
+            ProviderFactory.registerProvider(AIProviderName.PERPLEXITY_DECIDER, async (modelName, _providerName, sdk, _region, credentials) => {
+                const perplexityDeciderCreds = credentials;
+                const { PerplexityDeciderProvider } = await import("../providers/perplexityDecider.js");
+                return new PerplexityDeciderProvider(modelName, sdk, undefined, perplexityDeciderCreds);
+            }, process.env.PERPLEXITY_DECIDER_MODEL ||
+                PerplexityDeciderModels.PPLX_DECIDER_V1_27B, [], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.PERPLEXITY_DECIDER));
             logger.debug("All AI providers registered successfully");
             // ===== MEDIA HANDLER REGISTRATION =====
             // Single registration path (Task 11): each ecosystem barrel (voice,

package/dist/models/manifestRegistry.js

@@ -22,6 +22,7 @@ import { groqManifest } from "./manifests/groq.js";
 import { typesafeManifest } from "./manifests/typesafe.js";
 import { layaManifest } from "./manifests/laya.js";
 import { xorManifest } from "./manifests/xor.js";
+import { perplexityDeciderManifest } from "./manifests/perplexityDecider.js";
 import { cohereManifest } from "./manifests/cohere.js";
 import { togetherAiManifest } from "./manifests/together-ai.js";
 import { fireworksManifest } from "./manifests/fireworks.js";
@@ -122,6 +123,7 @@ export const MANIFEST_REGISTRY = {
     typesafe: typesafeManifest,
     laya: layaManifest,
     xor: xorManifest,
+    "perplexity-decider": perplexityDeciderManifest,
     cerebras: catalogManifest("cerebras"),
     sambanova: catalogManifest("sambanova"),
     cohere: cohereManifest,

package/dist/models/manifests/perplexityDecider.d.ts

@@ -0,0 +1,14 @@
+import type { ProviderModelManifest } from "../../types/index.js";
+/**
+ * Perplexity Decisions API — the `decide` inference type, not text generation,
+ * and not the Sonar models of the `perplexity` text provider.
+ *
+ * `contextWindow` is the documented ceiling on input tokens per request,
+ * shared by the state, every question and every image. `vision` describes
+ * `generate()` input, which this provider does not serve; its image input is
+ * `DecisionRequest.images`.
+ *
+ * `maxOutputTokens` is required by the manifest type but has no honest value
+ * for a model that emits no text, so a small non-zero figure is used.
+ */
+export declare const perplexityDeciderManifest: ProviderModelManifest;

package/dist/models/manifests/perplexityDecider.js

@@ -0,0 +1,32 @@
+/**
+ * Perplexity Decisions API — the `decide` inference type, not text generation,
+ * and not the Sonar models of the `perplexity` text provider.
+ *
+ * `contextWindow` is the documented ceiling on input tokens per request,
+ * shared by the state, every question and every image. `vision` describes
+ * `generate()` input, which this provider does not serve; its image input is
+ * `DecisionRequest.images`.
+ *
+ * `maxOutputTokens` is required by the manifest type but has no honest value
+ * for a model that emits no text, so a small non-zero figure is used.
+ */
+export const perplexityDeciderManifest = {
+    defaultContextWindow: 262_144,
+    models: {
+        _default: {
+            aliases: [],
+            contextWindow: 262_144,
+            maxOutputTokens: 256,
+            vision: false,
+            functionCalling: false,
+        },
+        "pplx-decider-v1-27b": {
+            aliases: [],
+            displayName: "Perplexity Decider v1 27B",
+            contextWindow: 262_144,
+            maxOutputTokens: 256,
+            vision: false,
+            functionCalling: false,
+        },
+    },
+};

package/dist/providers/perplexityDecider.d.ts

@@ -0,0 +1,50 @@
+import type { DecisionError, DecisionPreparedMedia, DecisionState, NeurolinkCredentials } from "../types/index.js";
+import { SystemOneDecisionProvider } from "./systemOneDecision.js";
+/**
+ * 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 declare class PerplexityDeciderProvider extends SystemOneDecisionProvider {
+    private readonly apiKey;
+    private readonly baseURL;
+    constructor(modelName?: string, sdk?: unknown, _region?: string, credentials?: NeurolinkCredentials["perplexityDecider"]);
+    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: 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.
+     */
+    protected buildDecisionBody(state: DecisionState, questions: Record<string, Record<string, unknown>>, model: string, media?: DecisionPreparedMedia): Record<string, unknown>;
+    protected parseDecisionError(status: number, payload: unknown, requestId: string | undefined): DecisionError;
+    /**
+     * A 401, a 404 and a 504 carry no request id, so this is undefined for them.
+     */
+    protected readRequestId(headers: Headers): string | undefined;
+    protected defaultTimeoutMs(questionCount: number): number | undefined;
+    /**
+     * `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.
+     */
+    protected readRetryAfterMs(headers: Headers): number | undefined;
+}