@juspay/neurolink 12.20.2 → 12.21.0

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

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * NeuroLink CLI Decide Command
+ *
+ * Calls `NeuroLink.decide()` — the third inference type, alongside `generate`
+ * and `stream`. Takes a `state` plus a map of named typed questions and
+ * prints one calibrated answer per question. See src/lib/types/decision.ts
+ * for the full vocabulary.
+ *
+ * Credentials are env-only here, exactly as every other CLI command: the
+ * decision provider (TypeSafe) reads `TYPESAFE_API_KEY` itself.
+ */
+import type { CommandModule } from "yargs";
+import type { CliDecideArgs } from "../../types/index.js";
+export declare const decideCommand: CommandModule<object, CliDecideArgs>;
+/**
+ * Create decide command factory for CLICommandFactory-style registration,
+ * matching the EvaluateCommandFactory pattern.
+ */
+export declare class DecideCommandFactory {
+    static createDecideCommand(): CommandModule;
+}

package/dist/cli/commands/decide.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+/**
+ * NeuroLink CLI Decide Command
+ *
+ * Calls `NeuroLink.decide()` — the third inference type, alongside `generate`
+ * and `stream`. Takes a `state` plus a map of named typed questions and
+ * prints one calibrated answer per question. See src/lib/types/decision.ts
+ * for the full vocabulary.
+ *
+ * Credentials are env-only here, exactly as every other CLI command: the
+ * decision provider (TypeSafe) reads `TYPESAFE_API_KEY` itself.
+ */
+import chalk from "chalk";
+import ora from "ora";
+import fs from "node:fs";
+import { NeuroLink } from "../../neurolink.js";
+import { readDecisionChoice } from "../../utils/decisionAnswers.js";
+import { calculateCost, hasPricing } from "../../utils/pricing.js";
+import { logger } from "../../utils/logger.js";
+const VALID_QUESTION_TYPES = new Set(["boolean", "choice", "score"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Validates that parsed JSON is a non-empty map of `{ type, ... }` question
+ * objects. Runs before any provider work — a malformed `--questions` payload
+ * must never reach the network.
+ */
+function isDecisionQuestionMap(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    const ids = Object.keys(value);
+    return (ids.length > 0 &&
+        ids.every((id) => {
+            const question = value[id];
+            return (isRecord(question) &&
+                typeof question.type === "string" &&
+                VALID_QUESTION_TYPES.has(question.type));
+        }));
+}
+/** `state` is the raw text, or its parsed JSON when that JSON is an object or array. */
+function parseState(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (isRecord(parsed) || Array.isArray(parsed)) {
+            // Single assertion (CLAUDE.md rule 14 allows this) — `isRecord`/
+            // `Array.isArray` narrow `unknown` down to a structural shape TS can't
+            // itself equate with the recursive `DecisionInput` union.
+            return parsed;
+        }
+    }
+    catch {
+        // Not JSON — treat as plain text.
+    }
+    return raw;
+}
+function isDecisionErrorCause(value) {
+    return (isRecord(value) &&
+        typeof value.kind === "string" &&
+        typeof value.message === "string");
+}
+const ERROR_KIND_MESSAGES = {
+    authentication: "Authentication failed — check the decision provider's API key.",
+    invalid_request: "The decision provider rejected the request as invalid.",
+    max_tokens_exceeded: "The decision request exceeded the provider's token limit.",
+    rate_limit: "The decision provider is rate-limiting requests — try again shortly.",
+    overloaded: "The decision provider is overloaded — try again shortly.",
+    server: "The decision provider returned a server error.",
+    timeout: "The decision request timed out.",
+    network: "A network error occurred while calling the decision provider.",
+};
+/** One clean line describing a `decide()` failure — never a stack trace. */
+function describeDecideError(error) {
+    const cause = error instanceof Error
+        ? error.cause
+        : undefined;
+    if (isDecisionErrorCause(cause)) {
+        const generic = ERROR_KIND_MESSAGES[cause.kind];
+        if (!generic) {
+            return cause.message;
+        }
+        // The provider's own text is what says which field or question was
+        // rejected, so it is kept alongside the generic line.
+        const detail = cause.message.trim();
+        return detail && detail !== generic ? `${generic} (${detail})` : generic;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes("No decision provider is configured")) {
+        return "No decision provider is configured. Set TYPESAFE_API_KEY, or AI_GATEWAY_API_KEY for the Vercel AI Gateway route.";
+    }
+    return message;
+}
+function formatNumber(value) {
+    return value.toFixed(2);
+}
+function formatAnswerLine(id, answers) {
+    const answer = answers[id];
+    if (!answer) {
+        return `${id}: (no answer)`;
+    }
+    switch (answer.type) {
+        case "boolean":
+            return `${id}: probability ${formatNumber(answer.probability)}`;
+        case "choice": {
+            const reading = readDecisionChoice(answers, id);
+            if (!reading) {
+                return `${id}: (unreadable choice answer)`;
+            }
+            const alternatives = reading.ranked
+                .filter((entry) => entry.name !== reading.choice)
+                .slice(0, 2)
+                .map((entry) => `${entry.name} (${formatNumber(entry.probability)})`)
+                .join(", ");
+            return (`${id}: choice ${reading.choice}, confidence ${formatNumber(reading.confidence)}` +
+                (alternatives ? `, alternatives: ${alternatives}` : ""));
+        }
+        case "score":
+            return `${id}: score ${formatNumber(answer.score)}, confidence ${formatNumber(answer.confidence)}`;
+        default:
+            return `${id}: (unrecognised answer type)`;
+    }
+}
+function printTextResult(result) {
+    for (const id of Object.keys(result.answers)) {
+        logger.always(formatAnswerLine(id, result.answers));
+    }
+    logger.always("");
+    logger.always(chalk.gray(`Model: ${result.model}`));
+    logger.always(chalk.gray(`Latency: ${result.latencyMs}ms`));
+    if (hasPricing(result.provider, result.model)) {
+        const cost = calculateCost(result.provider, result.model, {
+            input: result.usage.inputTokens,
+            output: result.usage.outputTokens,
+            total: result.usage.inputTokens + result.usage.outputTokens,
+        });
+        logger.always(chalk.gray(`Cost: $${cost.toFixed(6)}`));
+    }
+}
+function readQuestionsSource(argv) {
+    if (argv.questionsFile) {
+        return fs.readFileSync(argv.questionsFile, "utf-8");
+    }
+    if (!argv.questions) {
+        // Unreachable given the exactly-one-of check in the handler; keeps this
+        // function sound on its own rather than asserting the type away.
+        throw new Error("No questions source provided.");
+    }
+    return argv.questions;
+}
+function resolveState(argv) {
+    if (argv.stateFile) {
+        return parseState(fs.readFileSync(argv.stateFile, "utf-8"));
+    }
+    if (argv.state) {
+        return parseState(argv.state);
+    }
+    return undefined;
+}
+export const decideCommand = {
+    command: "decide [state]",
+    describe: "Get typed, calibrated judgements from a decision model (no free text)",
+    builder: (yargs) => yargs
+        .positional("state", {
+        type: "string",
+        describe: "The content to judge (or use --state-file)",
+    })
+        .option("state-file", {
+        type: "string",
+        describe: "Path to a file holding the state (text or JSON)",
+    })
+        .option("questions", {
+        type: "string",
+        describe: "Inline JSON map of questions (exactly one of this or --questions-file)",
+    })
+        .option("questions-file", {
+        type: "string",
+        describe: "Path to a JSON file holding the questions map",
+    })
+        .option("provider", {
+        type: "string",
+        describe: "Decision provider to use",
+    })
+        .option("model", {
+        type: "string",
+        describe: "Overrides the provider's configured model for this call",
+    })
+        .option("timeout", {
+        type: "number",
+        describe: "Timeout in milliseconds",
+    })
+        .option("format", {
+        type: "string",
+        alias: ["f", "output-format"],
+        describe: "Output format",
+        choices: ["text", "json"],
+        default: "text",
+    })
+        .option("debug", {
+        type: "boolean",
+        alias: ["v", "verbose"],
+        default: false,
+        describe: "Enable debug logging (written to stderr when --format json is used)",
+    })
+        .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"),
+    handler: async (argv) => {
+        const outputFormat = argv.format ?? "text";
+        // --- Validate before any provider work ---------------------------------
+        if (!!argv.questions === !!argv.questionsFile) {
+            logger.error(chalk.red("Error: pass exactly one of --questions or --questions-file."));
+            process.exit(1);
+        }
+        let questionsRaw;
+        try {
+            questionsRaw = readQuestionsSource(argv);
+        }
+        catch (error) {
+            logger.error(chalk.red(`Error: could not read questions — ${error instanceof Error ? error.message : String(error)}`));
+            process.exit(1);
+        }
+        let parsedQuestions;
+        try {
+            parsedQuestions = JSON.parse(questionsRaw);
+        }
+        catch {
+            const flag = argv.questionsFile ? "--questions-file" : "--questions";
+            logger.error(chalk.red(`Error: ${flag} is not valid JSON.`));
+            process.exit(1);
+        }
+        if (argv.timeout !== undefined &&
+            !(Number.isFinite(argv.timeout) && argv.timeout > 0)) {
+            logger.error(chalk.red("Error: --timeout must be a positive number of milliseconds."));
+            process.exit(1);
+        }
+        if (!isDecisionQuestionMap(parsedQuestions)) {
+            logger.error(chalk.red('Error: questions must be a non-empty object of { type: "boolean" | "choice" | "score", ... }.'));
+            process.exit(1);
+        }
+        let state;
+        try {
+            state = resolveState(argv);
+        }
+        catch (error) {
+            logger.error(chalk.red(`Error: could not read state file — ${error instanceof Error ? error.message : String(error)}`));
+            process.exit(1);
+        }
+        if (state === undefined) {
+            logger.error(chalk.red("Error: provide state as a positional argument or via --state-file."));
+            process.exit(1);
+        }
+        // --- Provider work -------------------------------------------------
+        const spinner = outputFormat === "json" ? null : ora("Deciding...").start();
+        try {
+            const neurolink = new NeuroLink();
+            const result = await neurolink.decide({
+                state,
+                questions: parsedQuestions,
+                provider: argv.provider,
+                model: argv.model,
+                timeoutMs: argv.timeout,
+            });
+            spinner?.succeed("Decision complete");
+            if (outputFormat === "json") {
+                logger.always(JSON.stringify(result, null, 2));
+            }
+            else {
+                printTextResult(result);
+            }
+        }
+        catch (error) {
+            spinner?.fail("Decision failed");
+            logger.error(chalk.red(`Error: ${describeDecideError(error)}`));
+            process.exit(1);
+        }
+    },
+};
+/**
+ * Create decide command factory for CLICommandFactory-style registration,
+ * matching the EvaluateCommandFactory pattern.
+ */
+export class DecideCommandFactory {
+    static createDecideCommand() {
+        return decideCommand;
+    }
+}
+//# sourceMappingURL=decide.js.map

package/dist/cli/parser.js

@@ -29,6 +29,7 @@ import { proxyPeerCommand } from "./commands/proxyPeer.js";
 import { proxyExposeCommand } from "./commands/proxyExpose.js";
 import { proxyReplayCommand } from "./commands/proxyReplay.js";
 import { EvaluateCommandFactory } from "./commands/evaluate.js";
+import { DecideCommandFactory } from "./commands/decide.js";
 import { TaskCommandFactory } from "./commands/task.js";
 import { AutoresearchCommandFactory } from "./commands/autoresearch.js";
 import { voiceServerCommand } from "./commands/voiceServer.js";
@@ -72,6 +73,9 @@ export function initializeCliParser() {
             // Always set to false when debug is not enabled (including when not provided)
             process.env.NEUROLINK_DEBUG = "false";
         }
+        // With --format json, stdout carries the payload; a debug or info
+        // line there would make it unparseable, so diagnostics go to stderr.
+        logger.setDiagnosticsToStderr(argv.format === "json");
         // Keep existing quiet middleware
         if (process.env.NEUROLINK_QUIET === "true" &&
             typeof argv.quiet === "undefined") {
@@ -164,6 +168,8 @@ export function initializeCliParser() {
         .command(UsageCommandFactory.createUsageCommands())
         // Stream Text Command - Using CLICommandFactory
         .command(CLICommandFactory.createStreamCommand())
+        // Decide Command - typed, calibrated judgements (no free text)
+        .command(DecideCommandFactory.createDecideCommand())
         // Batch Processing Command - Using CLICommandFactory
         .command(CLICommandFactory.createBatchCommand())
         // Provider Command Group - Using CLICommandFactory

package/dist/neurolink.js

@@ -4019,6 +4019,12 @@ Current user's request: ${currentInput}`;
         const sessionId = typeof opt.context?.sessionId === "string"
             ? opt.context.sessionId
             : undefined;
+        // Routing runs before conversation memory is loaded, so only the history
+        // the caller passed in is countable here.
+        const sessionBound = sessionId !== undefined;
+        const priorMessageCount = Array.isArray(opt.conversationMessages)
+            ? opt.conversationMessages.length
+            : undefined;
         try {
             const decision = await this.classifierRouter.route({
                 prompt: promptText,
@@ -4027,6 +4033,8 @@ Current user's request: ${currentInput}`;
                 requiresVision,
                 thinkingLevel,
                 sessionId,
+                sessionBound,
+                priorMessageCount,
             });
             if (!decision) {
                 return;

package/dist/routing/classifierStrategies.js

@@ -295,6 +295,9 @@ export async function classifyJev(input, decide, timeoutMs, candidates, threshol
     // are already assembled by the caller. Sending them costs almost nothing
     // and they are exactly what distinguishes a long tool-using request from a
     // short conversational one.
+    // Continuity is sent as `session_bound` / `prior_messages`, never as the
+    // raw sessionId: the id is an opaque identifier that tells a third-party
+    // model nothing, so it stays in-process.
     const result = await decide({
         state: {
             request: (input.prompt ?? "").slice(0, 8000),
@@ -302,6 +305,10 @@ export async function classifyJev(input, decide, timeoutMs, candidates, threshol
             has_tools_available: input.hasTools ?? false,
             request_includes_images: input.requiresVision ?? false,
             caller_requested_thinking: input.thinkingLevel ?? "none",
+            session_bound: input.sessionBound ?? false,
+            ...(typeof input.priorMessageCount === "number"
+                ? { prior_messages: input.priorMessageCount }
+                : {}),
         },
         questions,
         timeoutMs,

package/dist/types/classifierRouter.d.ts

@@ -296,6 +296,10 @@ export type ClassifierRouterInput = {
     requiresVision?: boolean;
     thinkingLevel?: string;
     sessionId?: string;
+    /** Whether this request is tied to a session, independent of the (withheld) session id itself. */
+    sessionBound?: boolean;
+    /** Number of prior conversation messages the caller supplied, when known. */
+    priorMessageCount?: number;
 };
 /** Enriched per-model metadata used while ranking pool members. */
 export type ClassifierModelMeta = {

package/dist/types/cli.d.ts

@@ -1296,6 +1296,18 @@ export type AutoresearchInitArgs = {
     provider?: string;
     model?: string;
 };
+/** Arguments for `neurolink decide` — the third inference type's CLI surface. */
+export type CliDecideArgs = {
+    state?: string;
+    stateFile?: string;
+    questions?: string;
+    questionsFile?: string;
+    provider?: string;
+    model?: string;
+    timeout?: number;
+    format?: "text" | "json";
+    debug?: boolean;
+};
 /** Base options shared across all `neurolink evaluate` subcommands. */
 export type BaseEvaluateArgs = {
     json?: boolean;

package/dist/utils/logger.d.ts

@@ -19,6 +19,7 @@ declare class NeuroLinkLogger {
     private logs;
     private maxLogs;
     private isDebugMode;
+    private diagnosticsToStderr;
     private eventEmitter?;
     constructor();
     /**
@@ -49,6 +50,14 @@ declare class NeuroLinkLogger {
      * @param level - The minimum log level to process ("debug", "info", "warn", or "error")
      */
     setLogLevel(level: LogLevel): void;
+    /**
+     * Routes debug and info output to stderr instead of stdout. The CLI turns
+     * this on for `--format json`, where stdout carries the payload and any
+     * diagnostic line in it would make the output unparseable.
+     *
+     * @param enabled - True to send debug/info to stderr; false restores stdout
+     */
+    setDiagnosticsToStderr(enabled: boolean): void;
     /**
      * Determines whether a message with the given log level should be processed.
      * This method considers both the configured log level and the current debug mode.
@@ -222,6 +231,7 @@ export declare const logger: {
     table: (data: unknown) => void;
     shouldLog: (level: LogLevel) => boolean;
     setLogLevel: (level: LogLevel) => void;
+    setDiagnosticsToStderr: (enabled: boolean) => void;
     getLogs: (level?: LogLevel) => LogEntry[];
     clearLogs: () => void;
     setEventEmitter: (emitter: {

package/dist/utils/logger.js

@@ -36,11 +36,24 @@ const UPPERCASE_LOG_LEVELS = {
     warn: "WARN",
     error: "ERROR",
 };
+const FORMAT_FLAGS = ["--format", "-f", "--output-format"];
+/**
+ * True when the process was started with JSON output requested. Read from
+ * argv on every write, like the `--debug` check in `shouldLog`: modules log
+ * while they are still being imported, before the CLI middleware that calls
+ * `setDiagnosticsToStderr` has run.
+ */
+function argvRequestsJsonOutput() {
+    const argv = process.argv;
+    return argv.some((arg, index) => (FORMAT_FLAGS.includes(arg) && argv[index + 1] === "json") ||
+        FORMAT_FLAGS.some((flag) => arg === `${flag}=json`));
+}
 class NeuroLinkLogger {
     logLevel = "info";
     logs = [];
     maxLogs = 1000;
     isDebugMode;
+    diagnosticsToStderr = false;
     eventEmitter;
     constructor() {
         // Cache debug mode check to avoid repeated array searches
@@ -86,6 +99,16 @@ class NeuroLinkLogger {
     setLogLevel(level) {
         this.logLevel = level;
     }
+    /**
+     * Routes debug and info output to stderr instead of stdout. The CLI turns
+     * this on for `--format json`, where stdout carries the payload and any
+     * diagnostic line in it would make the output unparseable.
+     *
+     * @param enabled - True to send debug/info to stderr; false restores stdout
+     */
+    setDiagnosticsToStderr(enabled) {
+        this.diagnosticsToStderr = enabled;
+    }
     /**
      * Determines whether a message with the given log level should be processed.
      * This method considers both the configured log level and the current debug mode.
@@ -209,9 +232,10 @@ class NeuroLinkLogger {
      * @param data - Optional additional data to log.
      */
     outputToConsole(level, prefix, message, data) {
+        const toStderr = this.diagnosticsToStderr || argvRequestsJsonOutput();
         const logMethod = {
-            debug: console.debug,
-            info: console.info,
+            debug: toStderr ? console.error : console.debug,
+            info: toStderr ? console.error : console.info,
             warn: console.warn,
             error: console.error,
         }[level];
@@ -467,6 +491,7 @@ export const logger = {
     shouldLog: (level) => neuroLinkLogger.shouldLog(level),
     // Expose structured logging methods
     setLogLevel: (level) => neuroLinkLogger.setLogLevel(level),
+    setDiagnosticsToStderr: (enabled) => neuroLinkLogger.setDiagnosticsToStderr(enabled),
     getLogs: (level) => neuroLinkLogger.getLogs(level),
     clearLogs: () => neuroLinkLogger.clearLogs(),
     setEventEmitter: (emitter) => neuroLinkLogger.setEventEmitter(emitter),