@juspay/neurolink 9.82.0 → 9.84.0

package/dist/lib/agent/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Agent Module - Multi-Agent Networks for NeuroLink
+ *
+ * This module provides multi-agent orchestration capabilities:
+ * - Agent: Individual agent with specialized instructions and tools
+ * - AgentNetwork: Multi-agent orchestration using agents-as-tools pattern
+ *
+ * Types for this module live in src/lib/types/agentNetwork.ts and are
+ * re-exported via the central barrel at src/lib/types/index.ts.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { Agent, AgentNetwork } from '@juspay/neurolink';
+ *
+ * const neurolink = new NeuroLink();
+ *
+ * // Create a network with multiple agents
+ * const network = neurolink.createNetwork({
+ *   name: 'Content Team',
+ *   agents: [
+ *     { id: 'researcher', name: 'Researcher', description: '...', instructions: '...' },
+ *     { id: 'writer', name: 'Writer', description: '...', instructions: '...' }
+ *   ]
+ * });
+ *
+ * // Execute the network
+ * const result = await network.execute({
+ *   message: 'Write an article about AI trends'
+ * });
+ * ```
+ */
+export { Agent } from "./agent.js";
+export { AgentNetwork } from "./agentNetwork.js";
+export { directAgentTools, getAvailableToolNames, getToolsForCategory, } from "./directTools.js";
+export { buildConfidencePrompt, buildMultiStepPlanningPrompt, buildRoutingPrompt, parseRoutingResponse, ROUTING_PROMPTS, } from "./prompts/routingPrompts.js";
+export { AgentCoordinator, TaskDistributor } from "./coordination/index.js";
+export { MessageBus } from "./communication/index.js";
+export { NetworkOrchestrator, NetworkTopology, TopologyBuilder, } from "./orchestration/index.js";

package/dist/lib/agent/index.js

@@ -0,0 +1,45 @@
+/**
+ * Agent Module - Multi-Agent Networks for NeuroLink
+ *
+ * This module provides multi-agent orchestration capabilities:
+ * - Agent: Individual agent with specialized instructions and tools
+ * - AgentNetwork: Multi-agent orchestration using agents-as-tools pattern
+ *
+ * Types for this module live in src/lib/types/agentNetwork.ts and are
+ * re-exported via the central barrel at src/lib/types/index.ts.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { Agent, AgentNetwork } from '@juspay/neurolink';
+ *
+ * const neurolink = new NeuroLink();
+ *
+ * // Create a network with multiple agents
+ * const network = neurolink.createNetwork({
+ *   name: 'Content Team',
+ *   agents: [
+ *     { id: 'researcher', name: 'Researcher', description: '...', instructions: '...' },
+ *     { id: 'writer', name: 'Writer', description: '...', instructions: '...' }
+ *   ]
+ * });
+ *
+ * // Execute the network
+ * const result = await network.execute({
+ *   message: 'Write an article about AI trends'
+ * });
+ * ```
+ */
+// Core agent classes
+export { Agent } from "./agent.js";
+export { AgentNetwork } from "./agentNetwork.js";
+// Direct tools (existing)
+export { directAgentTools, getAvailableToolNames, getToolsForCategory, } from "./directTools.js";
+// Routing prompts and utilities
+export { buildConfidencePrompt, buildMultiStepPlanningPrompt, buildRoutingPrompt, parseRoutingResponse, ROUTING_PROMPTS, } from "./prompts/routingPrompts.js";
+// Coordination module
+export { AgentCoordinator, TaskDistributor } from "./coordination/index.js";
+// Communication module
+export { MessageBus } from "./communication/index.js";
+// Orchestration module
+export { NetworkOrchestrator, NetworkTopology, TopologyBuilder, } from "./orchestration/index.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/agent/orchestration/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Network Orchestration Module
+ *
+ * Provides high-level orchestration capabilities for agent networks.
+ *
+ * Types for this module live in src/lib/types/agentNetwork.ts and are
+ * re-exported via the central barrel at src/lib/types/index.ts.
+ */
+export { NetworkOrchestrator } from "./orchestrator.js";
+export { NetworkTopology, TopologyBuilder } from "./topology.js";

package/dist/lib/agent/orchestration/index.js

@@ -0,0 +1,11 @@
+/**
+ * Network Orchestration Module
+ *
+ * Provides high-level orchestration capabilities for agent networks.
+ *
+ * Types for this module live in src/lib/types/agentNetwork.ts and are
+ * re-exported via the central barrel at src/lib/types/index.ts.
+ */
+export { NetworkOrchestrator } from "./orchestrator.js";
+export { NetworkTopology, TopologyBuilder } from "./topology.js";
+//# sourceMappingURL=index.js.map

package/dist/lib/agent/orchestration/orchestrator.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Network Orchestrator - High-level orchestration of agent networks
+ *
+ * The Orchestrator manages:
+ * - Network lifecycle (creation, execution, shutdown)
+ * - Multi-network coordination
+ * - Network-level policies and constraints
+ * - Resource management and scaling
+ */
+import type { NeuroLink } from "../../neurolink.js";
+import type { AgentNetwork } from "../agentNetwork.js";
+import { MessageBus } from "../communication/message-bus.js";
+import type { AgentNetworkConfig, HierarchicalNetworkConfig, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk, HierarchicalExecutionTrace, CoordinationStrategy, OrchestrationMode, NetworkState, NetworkInfo, OrchestratorConfig } from "../../types/index.js";
+/**
+ * Network Orchestrator - Central controller for agent networks
+ */
+export declare class NetworkOrchestrator {
+    private neurolink;
+    private networks;
+    private networkInfo;
+    private coordinators;
+    private messageBus;
+    private config;
+    private emitter;
+    private executionQueue;
+    private activeExecutions;
+    constructor(neurolink: NeuroLink, config?: OrchestratorConfig);
+    /**
+     * Create a new agent network
+     */
+    createNetwork(config: AgentNetworkConfig, mode?: OrchestrationMode): Promise<AgentNetwork>;
+    /**
+     * Create a hierarchical network
+     */
+    createHierarchicalNetwork(config: HierarchicalNetworkConfig, parentNetworkId?: string): Promise<AgentNetwork>;
+    /**
+     * Get a network by ID
+     */
+    getNetwork(networkId: string): AgentNetwork | undefined;
+    /**
+     * Get network info
+     */
+    getNetworkInfo(networkId: string): NetworkInfo | undefined;
+    /**
+     * Get all networks
+     */
+    getAllNetworks(): NetworkInfo[];
+    /**
+     * Execute a network
+     */
+    executeNetwork(networkId: string, input: NetworkExecutionInput, options?: NetworkExecutionOptions): Promise<NetworkExecutionResult>;
+    /**
+     * Internal network execution
+     */
+    private executeNetworkInternal;
+    /**
+     * Queue an execution request
+     */
+    private queueExecution;
+    /**
+     * Process queued executions
+     */
+    private processExecutionQueue;
+    /**
+     * Stream network execution
+     */
+    streamNetwork(networkId: string, input: NetworkExecutionInput, options?: NetworkExecutionOptions): AsyncIterable<NetworkStreamChunk>;
+    /**
+     * Execute hierarchical network with delegation
+     */
+    executeHierarchical(networkId: string, input: NetworkExecutionInput, options?: NetworkExecutionOptions): Promise<HierarchicalExecutionTrace>;
+    /**
+     * Pause a network
+     */
+    pauseNetwork(networkId: string): void;
+    /**
+     * Resume a network
+     */
+    resumeNetwork(networkId: string): void;
+    /**
+     * Shutdown a network
+     */
+    shutdownNetwork(networkId: string): Promise<void>;
+    /**
+     * Coordinate multiple networks
+     */
+    coordinateNetworks(networkIds: string[], task: string, strategy?: CoordinationStrategy): Promise<Map<string, NetworkExecutionResult>>;
+    /**
+     * Get orchestrator statistics
+     */
+    getStats(): {
+        totalNetworks: number;
+        activeExecutions: number;
+        queuedExecutions: number;
+        totalExecutions: number;
+        networksByState: Record<NetworkState, number>;
+    };
+    /**
+     * Get the shared message bus
+     */
+    getMessageBus(): MessageBus;
+    /**
+     * Subscribe to orchestrator events
+     */
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * Unsubscribe from orchestrator events
+     */
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    /**
+     * Shutdown the orchestrator
+     */
+    shutdown(): Promise<void>;
+}

package/dist/lib/agent/orchestration/orchestrator.js

@@ -0,0 +1,477 @@
+/**
+ * Network Orchestrator - High-level orchestration of agent networks
+ *
+ * The Orchestrator manages:
+ * - Network lifecycle (creation, execution, shutdown)
+ * - Multi-network coordination
+ * - Network-level policies and constraints
+ * - Resource management and scaling
+ */
+import { EventEmitter } from "events";
+import { randomUUID } from "crypto";
+import { AgentCoordinator } from "../coordination/coordinator.js";
+import { MessageBus } from "../communication/message-bus.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * Network Orchestrator - Central controller for agent networks
+ */
+export class NetworkOrchestrator {
+    neurolink;
+    networks = new Map();
+    networkInfo = new Map();
+    coordinators = new Map();
+    messageBus;
+    config;
+    emitter;
+    executionQueue = [];
+    activeExecutions = new Map();
+    constructor(neurolink, config) {
+        this.neurolink = neurolink;
+        this.config = {
+            defaultMode: "autonomous",
+            maxConcurrentExecutions: 5,
+            defaultTimeout: 120000,
+            enableHierarchy: true,
+            maxHierarchyDepth: 3,
+            enableSharedMessageBus: true,
+            resourceLimits: {
+                maxNetworks: 10,
+                maxAgentsPerNetwork: 20,
+                maxTotalAgents: 100,
+            },
+            ...config,
+        };
+        this.emitter = new EventEmitter();
+        this.messageBus = new MessageBus();
+        logger.info("[NetworkOrchestrator] Initialized", {
+            maxConcurrentExecutions: this.config.maxConcurrentExecutions,
+            enableHierarchy: this.config.enableHierarchy,
+        });
+    }
+    /**
+     * Create a new agent network
+     */
+    async createNetwork(config, mode) {
+        // Check resource limits
+        if (this.config.resourceLimits?.maxNetworks &&
+            this.networks.size >= this.config.resourceLimits.maxNetworks) {
+            throw new Error("Maximum number of networks reached");
+        }
+        if (this.config.resourceLimits?.maxAgentsPerNetwork &&
+            config.agents.length > this.config.resourceLimits.maxAgentsPerNetwork) {
+            throw new Error(`Maximum agents per network (${this.config.resourceLimits.maxAgentsPerNetwork}) exceeded`);
+        }
+        if (this.config.resourceLimits?.maxTotalAgents) {
+            const currentTotalAgents = Array.from(this.networkInfo.values()).reduce((sum, info) => sum + info.agentCount, 0);
+            if (currentTotalAgents + config.agents.length >
+                this.config.resourceLimits.maxTotalAgents) {
+                throw new Error(`Maximum total agents (${this.config.resourceLimits.maxTotalAgents}) exceeded`);
+            }
+        }
+        // Create the network via NeuroLink
+        const network = await this.neurolink.createNetwork(config);
+        // Track network info
+        const info = {
+            id: network.id,
+            name: network.name,
+            state: "ready",
+            agentCount: config.agents.length,
+            mode: mode ?? this.config.defaultMode,
+            createdAt: Date.now(),
+            executionCount: 0,
+            childNetworkIds: [],
+        };
+        this.networkInfo.set(network.id, info);
+        this.networks.set(network.id, network);
+        // Create coordinator for the network
+        const coordinator = new AgentCoordinator({
+            strategy: "sequential",
+            maxConcurrency: 3,
+        });
+        for (const agent of network.getAllAgents()) {
+            coordinator.registerAgent(agent);
+        }
+        this.coordinators.set(network.id, coordinator);
+        this.emitter.emit("network:created", {
+            networkId: network.id,
+            name: network.name,
+        });
+        logger.info(`[NetworkOrchestrator] Network created: ${network.name}`, {
+            networkId: network.id,
+            agentCount: config.agents.length,
+        });
+        return network;
+    }
+    /**
+     * Create a hierarchical network
+     */
+    async createHierarchicalNetwork(config, parentNetworkId) {
+        if (!this.config.enableHierarchy) {
+            throw new Error("Hierarchical networks are disabled");
+        }
+        // Check hierarchy constraints
+        if (parentNetworkId) {
+            const parentInfo = this.networkInfo.get(parentNetworkId);
+            if (!parentInfo) {
+                throw new Error(`Parent network not found: ${parentNetworkId}`);
+            }
+            // Check depth
+            let depth = 0;
+            let currentParent = parentInfo;
+            while (currentParent.parentNetworkId) {
+                depth++;
+                currentParent = this.networkInfo.get(currentParent.parentNetworkId);
+                if (depth >= this.config.maxHierarchyDepth) {
+                    throw new Error(`Maximum hierarchy depth (${this.config.maxHierarchyDepth}) exceeded`);
+                }
+            }
+        }
+        const network = await this.createNetwork(config, config.supervisionMode ?? "hierarchical");
+        // Set up hierarchy relationships
+        if (parentNetworkId) {
+            const info = this.networkInfo.get(network.id);
+            info.parentNetworkId = parentNetworkId;
+            const parentInfo = this.networkInfo.get(parentNetworkId);
+            parentInfo.childNetworkIds.push(network.id);
+        }
+        return network;
+    }
+    /**
+     * Get a network by ID
+     */
+    getNetwork(networkId) {
+        return this.networks.get(networkId);
+    }
+    /**
+     * Get network info
+     */
+    getNetworkInfo(networkId) {
+        return this.networkInfo.get(networkId);
+    }
+    /**
+     * Get all networks
+     */
+    getAllNetworks() {
+        return Array.from(this.networkInfo.values());
+    }
+    /**
+     * Execute a network
+     */
+    async executeNetwork(networkId, input, options) {
+        const network = this.networks.get(networkId);
+        if (!network) {
+            throw new Error(`Network not found: ${networkId}`);
+        }
+        const info = this.networkInfo.get(networkId);
+        if (info.state === "paused") {
+            throw new Error(`Network is paused: ${networkId}`);
+        }
+        if (info.state === "shutdown") {
+            throw new Error(`Network is shut down: ${networkId}`);
+        }
+        if (info.state === "executing") {
+            // Queue the execution
+            return this.queueExecution({ networkId, input, options });
+        }
+        // Check concurrent execution limit
+        if (this.activeExecutions.size >= this.config.maxConcurrentExecutions) {
+            return this.queueExecution({ networkId, input, options });
+        }
+        return this.executeNetworkInternal(network, info, input, options);
+    }
+    /**
+     * Internal network execution
+     */
+    async executeNetworkInternal(network, info, input, options) {
+        info.state = "executing";
+        info.executionCount++;
+        const executionPromise = (async () => {
+            try {
+                this.emitter.emit("network:execution:start", {
+                    networkId: network.id,
+                    input,
+                });
+                const result = await network.execute(input, {
+                    ...options,
+                    timeout: options?.timeout ?? this.config.defaultTimeout,
+                });
+                info.lastExecutionAt = Date.now();
+                info.state = "ready";
+                this.emitter.emit("network:execution:complete", {
+                    networkId: network.id,
+                    result,
+                });
+                return result;
+            }
+            catch (error) {
+                info.state = "error";
+                this.emitter.emit("network:execution:error", {
+                    networkId: network.id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+            finally {
+                this.activeExecutions.delete(network.id);
+                this.processExecutionQueue();
+            }
+        })();
+        this.activeExecutions.set(network.id, executionPromise);
+        return executionPromise;
+    }
+    /**
+     * Queue an execution request
+     */
+    async queueExecution(request) {
+        return new Promise((resolve, reject) => {
+            const _queuedRequest = {
+                ...request,
+                resolve,
+                reject,
+            };
+            this.executionQueue.push(_queuedRequest);
+            this.executionQueue.sort((a, b) => {
+                const priorityOrder = { high: 0, normal: 1, low: 2 };
+                return ((priorityOrder[a.priority ?? "normal"] ?? 1) -
+                    (priorityOrder[b.priority ?? "normal"] ?? 1));
+            });
+            this.emitter.emit("execution:queued", { networkId: request.networkId });
+        });
+    }
+    /**
+     * Process queued executions
+     */
+    async processExecutionQueue() {
+        while (this.executionQueue.length > 0 &&
+            this.activeExecutions.size < this.config.maxConcurrentExecutions) {
+            const request = this.executionQueue.shift();
+            const network = this.networks.get(request.networkId);
+            const info = this.networkInfo.get(request.networkId);
+            if (network && info && info.state !== "executing") {
+                // Fire-and-forget: executeNetworkInternal is NOT awaited so the while
+                // loop drains the entire queue synchronously before any launched
+                // execution sets info.state = "executing" (that happens at the first
+                // await inside executeNetworkInternal). This is intentional — it lets
+                // one queue-drain pass start multiple networks in parallel up to
+                // maxConcurrentExecutions.
+                this.executeNetworkInternal(network, info, request.input, request.options)
+                    .then((result) => request.resolve?.(result))
+                    .catch((err) => request.reject?.(err));
+            }
+            else if (request.reject) {
+                request.reject(new Error(`Network unavailable for execution: ${request.networkId}`));
+            }
+        }
+    }
+    /**
+     * Stream network execution
+     */
+    async *streamNetwork(networkId, input, options) {
+        const network = this.networks.get(networkId);
+        if (!network) {
+            throw new Error(`Network not found: ${networkId}`);
+        }
+        const info = this.networkInfo.get(networkId);
+        if (info.state === "paused") {
+            throw new Error(`Network is paused: ${networkId}`);
+        }
+        if (info.state === "shutdown") {
+            throw new Error(`Network is shut down: ${networkId}`);
+        }
+        if (info.state === "executing") {
+            throw new Error(`Network is already executing: ${networkId}. Streaming does not support queuing.`);
+        }
+        if (this.activeExecutions.size >= this.config.maxConcurrentExecutions) {
+            throw new Error(`Maximum concurrent executions (${this.config.maxConcurrentExecutions}) reached. Streaming does not support queuing.`);
+        }
+        info.state = "executing";
+        info.executionCount++;
+        const streamPromise = Promise.resolve(); // placeholder to track in activeExecutions
+        this.activeExecutions.set(networkId, streamPromise);
+        try {
+            yield* network.stream(input, options);
+            info.lastExecutionAt = Date.now();
+        }
+        finally {
+            info.state = "ready";
+            this.activeExecutions.delete(networkId);
+            this.processExecutionQueue();
+        }
+    }
+    /**
+     * Execute hierarchical network with delegation
+     */
+    async executeHierarchical(networkId, input, options) {
+        const network = this.networks.get(networkId);
+        const info = this.networkInfo.get(networkId);
+        if (!network || !info) {
+            throw new Error(`Network not found: ${networkId}`);
+        }
+        const traceId = randomUUID();
+        const trace = {
+            traceId,
+            steps: [],
+            routingDecisions: [],
+            startTime: Date.now(),
+            hierarchyLevel: 0,
+            childTraces: [],
+        };
+        // Calculate hierarchy level
+        let currentInfo = info;
+        while (currentInfo.parentNetworkId) {
+            trace.hierarchyLevel++;
+            trace.parentTraceId = currentInfo.parentNetworkId;
+            currentInfo = this.networkInfo.get(currentInfo.parentNetworkId);
+        }
+        // Execute main network
+        const result = await this.executeNetwork(networkId, input, options);
+        trace.steps = result.trace.steps;
+        trace.routingDecisions = result.trace.routingDecisions;
+        trace.endTime = Date.now();
+        // Execute child networks if needed based on delegation rules
+        for (const childId of info.childNetworkIds) {
+            const childNetwork = this.networks.get(childId);
+            if (childNetwork) {
+                const childTrace = await this.executeHierarchical(childId, { message: result.content, context: input.context }, options);
+                trace.childTraces?.push(childTrace);
+            }
+        }
+        return trace;
+    }
+    /**
+     * Pause a network
+     */
+    pauseNetwork(networkId) {
+        const info = this.networkInfo.get(networkId);
+        if (info && info.state === "ready") {
+            info.state = "paused";
+            this.emitter.emit("network:paused", { networkId });
+        }
+    }
+    /**
+     * Resume a network
+     */
+    resumeNetwork(networkId) {
+        const info = this.networkInfo.get(networkId);
+        if (info && info.state === "paused") {
+            info.state = "ready";
+            this.emitter.emit("network:resumed", { networkId });
+        }
+    }
+    /**
+     * Shutdown a network
+     */
+    async shutdownNetwork(networkId) {
+        const info = this.networkInfo.get(networkId);
+        if (!info) {
+            return;
+        }
+        // Shutdown child networks first
+        for (const childId of info.childNetworkIds) {
+            await this.shutdownNetwork(childId);
+        }
+        // Remove from parent's child list
+        if (info.parentNetworkId) {
+            const parentInfo = this.networkInfo.get(info.parentNetworkId);
+            if (parentInfo) {
+                parentInfo.childNetworkIds = parentInfo.childNetworkIds.filter((id) => id !== networkId);
+            }
+        }
+        info.state = "shutdown";
+        this.networks.delete(networkId);
+        this.networkInfo.delete(networkId);
+        this.coordinators.delete(networkId);
+        this.emitter.emit("network:shutdown", { networkId });
+        logger.info(`[NetworkOrchestrator] Network shutdown: ${networkId}`);
+    }
+    /**
+     * Coordinate multiple networks
+     */
+    async coordinateNetworks(networkIds, task, strategy = "parallel") {
+        const results = new Map();
+        switch (strategy) {
+            case "sequential":
+            case "pipeline": {
+                // Each network receives the previous network's output as its input
+                let currentInput = task;
+                for (const networkId of networkIds) {
+                    const result = await this.executeNetwork(networkId, {
+                        message: currentInput,
+                    });
+                    results.set(networkId, result);
+                    currentInput = result.content;
+                }
+                break;
+            }
+            case "parallel": {
+                await Promise.all(networkIds.map(async (networkId) => {
+                    const result = await this.executeNetwork(networkId, {
+                        message: task,
+                    });
+                    results.set(networkId, result);
+                }));
+                break;
+            }
+            default:
+                throw new Error(`Unsupported coordination strategy: ${strategy}`);
+        }
+        return results;
+    }
+    /**
+     * Get orchestrator statistics
+     */
+    getStats() {
+        const networksByState = {
+            idle: 0,
+            initializing: 0,
+            ready: 0,
+            executing: 0,
+            paused: 0,
+            error: 0,
+            shutdown: 0,
+        };
+        let totalExecutions = 0;
+        for (const info of this.networkInfo.values()) {
+            networksByState[info.state]++;
+            totalExecutions += info.executionCount;
+        }
+        return {
+            totalNetworks: this.networks.size,
+            activeExecutions: this.activeExecutions.size,
+            queuedExecutions: this.executionQueue.length,
+            totalExecutions,
+            networksByState,
+        };
+    }
+    /**
+     * Get the shared message bus
+     */
+    getMessageBus() {
+        return this.messageBus;
+    }
+    /**
+     * Subscribe to orchestrator events
+     */
+    on(event, handler) {
+        this.emitter.on(event, handler);
+    }
+    /**
+     * Unsubscribe from orchestrator events
+     */
+    off(event, handler) {
+        this.emitter.off(event, handler);
+    }
+    /**
+     * Shutdown the orchestrator
+     */
+    async shutdown() {
+        // Shutdown all networks
+        for (const networkId of this.networks.keys()) {
+            await this.shutdownNetwork(networkId);
+        }
+        // Shutdown message bus
+        this.messageBus.shutdown();
+        logger.info("[NetworkOrchestrator] Shutdown complete");
+    }
+}
+//# sourceMappingURL=orchestrator.js.map