@juspay/neurolink 9.82.0 → 9.84.0

package/dist/lib/utils/tokenUtils.js

@@ -101,6 +101,23 @@ export function extractCacheReadTokens(usage) {
     }
     return undefined;
 }
+/**
+ * Extract cache read token count from the OVERLAPPING-convention nested path
+ * used by OpenAI / DeepSeek / NIM / OpenAI-compatible providers:
+ * `usage.prompt_tokens_details.cached_tokens`.
+ *
+ * Unlike {@link extractCacheReadTokens} (non-overlapping Anthropic/Vertex
+ * convention where cache tokens are reported SEPARATELY from input), the value
+ * returned here is a SUBSET already included in `prompt_tokens`. Callers that
+ * use this value MUST subtract it from `input` to avoid double-counting.
+ */
+export function extractCachedInputTokensOverlapping(usage) {
+    const cached = usage.prompt_tokens_details?.cached_tokens;
+    if (typeof cached === "number" && cached > 0) {
+        return cached;
+    }
+    return undefined;
+}
 /**
  * Calculate cache savings percentage
  *
@@ -149,13 +166,27 @@ export function extractTokenUsage(result, options = {}) {
     // Handle nested usage object (some providers wrap usage in a usage property)
     const usage = result.usage && typeof result.usage === "object" ? result.usage : result;
     // Extract base token counts
-    const input = extractInputTokens(usage);
+    let input = extractInputTokens(usage);
     const output = extractOutputTokens(usage);
     const total = extractTotalTokens(usage, input, output);
     // Extract optional token fields
     const reasoning = extractReasoningTokens(usage);
     const cacheCreationTokens = extractCacheCreationTokens(usage);
-    const cacheReadTokens = extractCacheReadTokens(usage);
+    let cacheReadTokens = extractCacheReadTokens(usage);
+    // Overlapping-convention fallback (OpenAI/DeepSeek/NIM/OpenAI-compatible):
+    // when no non-overlapping cache-read field was present, look for the nested
+    // `prompt_tokens_details.cached_tokens`. That value is a SUBSET already
+    // included in `input`, so we must subtract it from `input` to avoid
+    // double-counting (and to let calculateCost apply the cheaper cacheRead rate
+    // to the cached portion). Only do this when cached <= input so a malformed
+    // response can never produce negative input or inflate the total.
+    if (cacheReadTokens === undefined) {
+        const overlappingCached = extractCachedInputTokensOverlapping(usage);
+        if (overlappingCached !== undefined && overlappingCached <= input) {
+            cacheReadTokens = overlappingCached;
+            input = Math.max(0, input - overlappingCached);
+        }
+    }
     // Calculate cache savings if enabled
     const cacheSavingsPercent = calculateCacheSavings
         ? calculateCacheSavingsPercent(cacheReadTokens, input)

package/dist/lib/utils/tripwireEvaluator.d.ts

@@ -0,0 +1,73 @@
+/**
+ * TripwireEvaluator - Standalone health-check utility
+ *
+ * Evaluates blocking conditions against LLM response data to detect
+ * runtime issues such as empty responses, high latency, max tokens hit,
+ * and repetition loops.
+ *
+ * This module has no dependency on the processor pipeline system and can
+ * be used independently.
+ *
+ * @module utils/tripwireEvaluator
+ */
+import type { TripwireData, TripwireConfig, TripwireResult } from "../types/index.js";
+/**
+ * Manages and evaluates tripwire conditions against LLM response data.
+ *
+ * @example
+ * ```typescript
+ * const evaluator = createDefaultTripwireEvaluator();
+ *
+ * const result = evaluator.evaluate({
+ *   responseText: "",
+ *   latencyMs: 45000,
+ *   finishReason: "length",
+ * });
+ *
+ * if (result.triggered && result.action === "abort") {
+ *   throw new Error(result.message);
+ * }
+ * ```
+ */
+export declare class TripwireEvaluator {
+    private tripwires;
+    /**
+     * Register a tripwire. Replaces any existing tripwire with the same id.
+     */
+    register(tripwire: TripwireConfig): void;
+    /**
+     * Remove a registered tripwire by id.
+     * @returns true if the tripwire was found and removed, false otherwise.
+     */
+    unregister(id: string): boolean;
+    /**
+     * Evaluate all tripwires and return the highest-priority triggered result.
+     *
+     * Priority order: "abort" > "warn" > "log"
+     *
+     * Bug fix (C1): The original implementation returned on the FIRST triggered
+     * tripwire regardless of action, which meant a "warn" registered before an
+     * "abort" would mask the abort. This implementation evaluates ALL tripwires
+     * and promotes the highest-severity action.
+     */
+    evaluate(data: TripwireData): TripwireResult;
+    /**
+     * Evaluate all tripwires and return every triggered result.
+     */
+    evaluateAll(data: TripwireData): TripwireResult[];
+    /**
+     * Return a shallow copy of all registered tripwires.
+     */
+    getTripwires(): TripwireConfig[];
+}
+/**
+ * All built-in tripwires in default registration order.
+ *
+ * Registration order does not affect priority — `evaluate()` always promotes
+ * the highest-severity action ("abort" > "warn" > "log").
+ */
+export declare const commonTripwires: TripwireConfig[];
+/**
+ * Create a TripwireEvaluator pre-loaded with all built-in tripwires.
+ */
+export declare function createDefaultTripwireEvaluator(): TripwireEvaluator;

package/dist/lib/utils/tripwireEvaluator.js

@@ -0,0 +1,285 @@
+/**
+ * TripwireEvaluator - Standalone health-check utility
+ *
+ * Evaluates blocking conditions against LLM response data to detect
+ * runtime issues such as empty responses, high latency, max tokens hit,
+ * and repetition loops.
+ *
+ * This module has no dependency on the processor pipeline system and can
+ * be used independently.
+ *
+ * @module utils/tripwireEvaluator
+ */
+// ============================================================================
+// TripwireEvaluator
+// ============================================================================
+/**
+ * Manages and evaluates tripwire conditions against LLM response data.
+ *
+ * @example
+ * ```typescript
+ * const evaluator = createDefaultTripwireEvaluator();
+ *
+ * const result = evaluator.evaluate({
+ *   responseText: "",
+ *   latencyMs: 45000,
+ *   finishReason: "length",
+ * });
+ *
+ * if (result.triggered && result.action === "abort") {
+ *   throw new Error(result.message);
+ * }
+ * ```
+ */
+export class TripwireEvaluator {
+    tripwires = [];
+    /**
+     * Register a tripwire. Replaces any existing tripwire with the same id.
+     */
+    register(tripwire) {
+        const existingIndex = this.tripwires.findIndex((t) => t.id === tripwire.id);
+        if (existingIndex !== -1) {
+            this.tripwires[existingIndex] = tripwire;
+        }
+        else {
+            this.tripwires.push(tripwire);
+        }
+    }
+    /**
+     * Remove a registered tripwire by id.
+     * @returns true if the tripwire was found and removed, false otherwise.
+     */
+    unregister(id) {
+        const index = this.tripwires.findIndex((t) => t.id === id);
+        if (index !== -1) {
+            this.tripwires.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Evaluate all tripwires and return the highest-priority triggered result.
+     *
+     * Priority order: "abort" > "warn" > "log"
+     *
+     * Bug fix (C1): The original implementation returned on the FIRST triggered
+     * tripwire regardless of action, which meant a "warn" registered before an
+     * "abort" would mask the abort. This implementation evaluates ALL tripwires
+     * and promotes the highest-severity action.
+     */
+    evaluate(data) {
+        let firstAbort = null;
+        let firstWarn = null;
+        let firstLog = null;
+        for (const tripwire of this.tripwires) {
+            let triggered;
+            try {
+                triggered = tripwire.condition(data);
+            }
+            catch {
+                // Skip tripwires whose condition throws — don't let evaluation errors
+                // block normal operation.
+                continue;
+            }
+            if (!triggered) {
+                continue;
+            }
+            const message = typeof tripwire.message === "function"
+                ? tripwire.message(data)
+                : tripwire.message;
+            const result = {
+                triggered: true,
+                tripwire,
+                message,
+                action: tripwire.action,
+            };
+            if (tripwire.action === "abort" && firstAbort === null) {
+                firstAbort = result;
+            }
+            else if (tripwire.action === "warn" && firstWarn === null) {
+                firstWarn = result;
+            }
+            else if (tripwire.action === "log" && firstLog === null) {
+                firstLog = result;
+            }
+        }
+        if (firstAbort !== null) {
+            return firstAbort;
+        }
+        if (firstWarn !== null) {
+            return firstWarn;
+        }
+        if (firstLog !== null) {
+            return firstLog;
+        }
+        return { triggered: false };
+    }
+    /**
+     * Evaluate all tripwires and return every triggered result.
+     */
+    evaluateAll(data) {
+        const results = [];
+        for (const tripwire of this.tripwires) {
+            let triggered;
+            try {
+                triggered = tripwire.condition(data);
+            }
+            catch {
+                continue;
+            }
+            if (!triggered) {
+                continue;
+            }
+            const message = typeof tripwire.message === "function"
+                ? tripwire.message(data)
+                : tripwire.message;
+            results.push({
+                triggered: true,
+                tripwire,
+                message,
+                action: tripwire.action,
+            });
+        }
+        return results;
+    }
+    /**
+     * Return a shallow copy of all registered tripwires.
+     */
+    getTripwires() {
+        return [...this.tripwires];
+    }
+}
+// ============================================================================
+// Built-in tripwires
+// ============================================================================
+/**
+ * Triggers when the model hit its token output limit (finishReason === "length").
+ */
+const maxTokensTripwire = {
+    id: "max-tokens",
+    name: "Maximum Tokens Hit",
+    description: "Triggers when the model stopped because it reached the token output limit.",
+    action: "abort",
+    condition: (data) => data.finishReason === "length",
+    message: "Model stopped at token limit — response may be truncated.",
+};
+/**
+ * Triggers when the response is empty or only whitespace.
+ */
+const emptyResponseTripwire = {
+    id: "empty-response",
+    name: "Empty Response",
+    description: "Triggers when the model returns an empty or whitespace-only response.",
+    action: "abort",
+    condition: (data) => data.responseText !== undefined && data.responseText.trim().length === 0,
+    message: "Model returned an empty response.",
+};
+/**
+ * Triggers when the response contains highly repetitive phrases.
+ * Uses a sliding-window approach: splits into overlapping 10-word windows and
+ * counts duplicates. If more than 20% of windows are repeated the response is
+ * flagged as a repetition loop.
+ */
+const repetitionLoopTripwire = {
+    id: "repetition-loop",
+    name: "Repetition Loop",
+    description: "Detects when the model is generating repetitive content, indicating a loop.",
+    action: "warn",
+    condition: (data) => {
+        const text = data.responseText;
+        if (!text) {
+            return false;
+        }
+        const words = text.split(/\s+/);
+        if (words.length < 30) {
+            return false;
+        }
+        const windowSize = 10;
+        const windows = new Map();
+        let duplicates = 0;
+        const totalWindows = words.length - windowSize + 1;
+        for (let i = 0; i <= words.length - windowSize; i++) {
+            const window = words.slice(i, i + windowSize).join(" ");
+            const count = (windows.get(window) ?? 0) + 1;
+            windows.set(window, count);
+            if (count > 1) {
+                duplicates++;
+            }
+        }
+        return duplicates / totalWindows > 0.2;
+    },
+    message: "Response contains highly repetitive content — possible generation loop.",
+};
+/**
+ * Triggers when the input text exceeds 100 000 characters.
+ */
+const inputTooLongTripwire = {
+    id: "input-too-long",
+    name: "Input Too Long",
+    description: "Triggers when the input text exceeds the recommended length.",
+    action: "abort",
+    condition: (data) => data.inputText !== undefined && data.inputText.length > 100_000,
+    message: (data) => `Input is ${data.inputText?.length ?? 0} characters — exceeds the 100 000-character limit.`,
+};
+/**
+ * Triggers when the conversation has more than 100 messages.
+ */
+const tooManyMessagesTripwire = {
+    id: "too-many-messages",
+    name: "Too Many Messages",
+    description: "Triggers when the conversation message count exceeds the recommended maximum.",
+    action: "warn",
+    condition: (data) => data.messageCount !== undefined && data.messageCount > 100,
+    message: (data) => `Conversation has ${data.messageCount} messages — consider summarising context.`,
+};
+/**
+ * Triggers when the response text exceeds 50 000 characters.
+ */
+const responseTooLongTripwire = {
+    id: "response-too-long",
+    name: "Response Too Long",
+    description: "Triggers when the response text exceeds the recommended length.",
+    action: "warn",
+    condition: (data) => data.responseText !== undefined && data.responseText.length > 50_000,
+    message: (data) => `Response is ${data.responseText?.length ?? 0} characters — exceeds the 50 000-character limit.`,
+};
+/**
+ * Triggers when the measured end-to-end latency exceeds 30 seconds.
+ */
+const highLatencyTripwire = {
+    id: "high-latency",
+    name: "High Latency",
+    description: "Triggers when the measured response latency exceeds the acceptable threshold.",
+    action: "warn",
+    condition: (data) => data.latencyMs !== undefined && data.latencyMs > 30_000,
+    message: (data) => `Response latency was ${data.latencyMs}ms — exceeds the 30 000ms threshold.`,
+};
+/**
+ * All built-in tripwires in default registration order.
+ *
+ * Registration order does not affect priority — `evaluate()` always promotes
+ * the highest-severity action ("abort" > "warn" > "log").
+ */
+export const commonTripwires = [
+    maxTokensTripwire,
+    emptyResponseTripwire,
+    repetitionLoopTripwire,
+    inputTooLongTripwire,
+    tooManyMessagesTripwire,
+    responseTooLongTripwire,
+    highLatencyTripwire,
+];
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a TripwireEvaluator pre-loaded with all built-in tripwires.
+ */
+export function createDefaultTripwireEvaluator() {
+    const evaluator = new TripwireEvaluator();
+    for (const tripwire of commonTripwires) {
+        evaluator.register(tripwire);
+    }
+    return evaluator;
+}
+//# sourceMappingURL=tripwireEvaluator.js.map

package/dist/neurolink.d.ts

@@ -5,6 +5,7 @@
  * Enhanced AI provider system with natural MCP tool access.
  * Uses real MCP infrastructure for tool discovery and execution.
  */
+import type { AgentDefinition, AgentNetworkConfig, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk } from "./types/index.js";
 import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
@@ -2162,6 +2163,134 @@ export declare class NeuroLink {
      * ```
      */
     getEvaluationPreset(presetName: "safety" | "rag" | "quality" | "comprehensive" | "minimal" | "summarization" | "customerSupport" | "codeGeneration"): Promise<import("./types/index.js").PipelineConfig>;
+    /**
+     * Create an Agent instance for multi-agent orchestration.
+     *
+     * Agents are specialized AI entities with defined instructions, tools, and behavior.
+     * They can be composed into networks for complex task orchestration.
+     *
+     * @param definition - Agent definition specifying behavior and capabilities
+     * @returns A new Agent instance
+     *
+     * @example
+     * ```typescript
+     * const researcher = neurolink.createAgent({
+     *   id: 'researcher',
+     *   name: 'Research Agent',
+     *   description: 'Searches and analyzes information from various sources',
+     *   instructions: 'You are a research assistant. Search thoroughly and cite sources.',
+     *   tools: ['websearchGrounding', 'readFile'],
+     *   model: 'gpt-4o'
+     * });
+     *
+     * const result = await researcher.execute('Find recent AI breakthroughs');
+     * ```
+     *
+     * @see {@link AgentDefinition} for definition options
+     * @see {@link Agent} for agent methods
+     * @since 8.38.0
+     */
+    createAgent(definition: AgentDefinition): Promise<import("./agent/agent.js").Agent>;
+    /**
+     * Create an AgentNetwork for multi-agent orchestration.
+     *
+     * Networks coordinate multiple agents, workflows, and tools with intelligent
+     * LLM-powered routing. The router agent analyzes tasks and delegates to
+     * the most appropriate primitive.
+     *
+     * @param config - Network configuration with agents, workflows, and routing settings
+     * @returns A new AgentNetwork instance
+     *
+     * @example
+     * ```typescript
+     * const network = neurolink.createNetwork({
+     *   name: 'Content Team',
+     *   description: 'Collaborative content creation pipeline',
+     *   agents: [
+     *     {
+     *       id: 'researcher',
+     *       name: 'Researcher',
+     *       description: 'Finds and verifies information',
+     *       instructions: 'Research topics thoroughly...',
+     *     },
+     *     {
+     *       id: 'writer',
+     *       name: 'Writer',
+     *       description: 'Creates engaging content',
+     *       instructions: 'Write clear, engaging content...',
+     *     },
+     *     {
+     *       id: 'editor',
+     *       name: 'Editor',
+     *       description: 'Reviews and improves content',
+     *       instructions: 'Review for clarity and accuracy...',
+     *     }
+     *   ],
+     *   router: {
+     *     model: 'gpt-4o',
+     *     confidenceThreshold: 0.7
+     *   }
+     * });
+     *
+     * const result = await network.execute({
+     *   message: 'Write an article about quantum computing'
+     * });
+     * ```
+     *
+     * @see {@link AgentNetworkConfig} for configuration options
+     * @see {@link AgentNetwork} for network methods
+     * @since 8.38.0
+     */
+    createNetwork(config: AgentNetworkConfig): Promise<import("./agent/agentNetwork.js").AgentNetwork>;
+    /**
+     * Execute an agent network with the given input.
+     *
+     * @param network - The agent network to execute
+     * @param input - Execution input (message and context)
+     * @param options - Optional execution options
+     * @returns Network execution result with content, trace, and usage
+     *
+     * @see {@link NetworkExecutionInput} for input options
+     * @see {@link NetworkExecutionResult} for result structure
+     * @since 8.38.0
+     */
+    executeNetwork(network: import("./agent/agentNetwork.js").AgentNetwork, input: NetworkExecutionInput, options?: NetworkExecutionOptions): Promise<NetworkExecutionResult>;
+    /**
+     * Stream agent network execution with real-time events.
+     *
+     * @param network - The agent network to stream
+     * @param input - Execution input (message and context)
+     * @param options - Optional execution options
+     * @returns Async iterable of network stream chunks
+     *
+     * @see {@link NetworkStreamChunk} for chunk types
+     * @since 8.38.0
+     */
+    streamNetwork(network: import("./agent/agentNetwork.js").AgentNetwork, input: NetworkExecutionInput, options?: NetworkExecutionOptions): AsyncIterable<NetworkStreamChunk>;
+    /**
+     * Create a NetworkOrchestrator for managing multiple agent networks.
+     *
+     * @param config - Orchestrator configuration options
+     * @returns A new NetworkOrchestrator instance
+     * @since 8.38.0
+     */
+    createOrchestrator(config?: import("./types/index.js").OrchestratorConfig): Promise<import("./agent/orchestration/index.js").NetworkOrchestrator>;
+    /**
+     * Create an AgentCoordinator for managing agent coordination strategies.
+     *
+     * @param config - Coordinator configuration options
+     * @returns A new AgentCoordinator instance
+     * @since 8.38.0
+     */
+    createCoordinator(config?: import("./types/index.js").CoordinatorConfig): Promise<import("./agent/coordination/index.js").AgentCoordinator>;
+    /**
+     * Create a MessageBus for inter-agent communication.
+     *
+     * @param config - Message bus configuration options
+     * @returns A new MessageBus instance
+     * @since 8.38.0
+     */
+    createMessageBus(config?: import("./types/index.js").MessageBusConfig): Promise<import("./agent/communication/index.js").MessageBus>;
     /**
      * Dispose of all resources and cleanup connections
      * Call this method when done using the NeuroLink instance to prevent resource leaks