graphai 0.1.0 → 0.1.2

package/lib/node.js

@@ -3,177 +3,207 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StaticNode = exports.ComputedNode = exports.Node = void 0;
 const type_1 = require("./type");
 const utils_1 = require("./utils/utils");
-const log_1 = require("./log");
+const transaction_log_1 = require("./transaction_log");
 class Node {
-    constructor(nodeId, forkIndex, data, graph) {
-        this.sources = {}; // data sources.
+    constructor(nodeId, graph) {
         this.waitlist = new Set(); // List of nodes which need data from this node.
         this.state = type_1.NodeState.Waiting;
         this.result = undefined;
         this.nodeId = nodeId;
-        this.forkIndex = forkIndex;
-        this.anyInput = data.anyInput ?? false;
-        this.inputs = (data.inputs ?? []).map((input) => {
-            const source = (0, utils_1.parseNodeName)(input);
-            this.sources[source.nodeId] = source;
-            return source.nodeId;
-        });
-        this.pendings = new Set(this.inputs);
-        this.fork = data.fork;
         this.graph = graph;
+        this.log = new transaction_log_1.TransactionLog(nodeId);
     }
     asString() {
         return `${this.nodeId}: ${this.state} ${[...this.waitlist]}`;
     }
-    removePending(nodeId) {
-        if (this.anyInput) {
-            const [result] = this.graph.resultsOf([this.sources[nodeId]]);
-            if (result) {
-                this.pendings.clear();
+    // This method is called either as the result of computation (computed node) or
+    // injection (static node).
+    onSetResult() {
+        this.waitlist.forEach((waitingNodeId) => {
+            const waitingNode = this.graph.nodes[waitingNodeId];
+            if (waitingNode.isComputedNode) {
+                waitingNode.removePending(this.nodeId);
+                this.graph.pushQueueIfReadyAndRunning(waitingNode);
             }
-        }
-        else {
-            this.pendings.delete(nodeId);
-        }
-    }
-    setResult(result, state) {
-        this.state = state;
-        this.result = result;
-        this.waitlist.forEach((nodeId) => {
-            const node = this.graph.nodes[nodeId];
-            // Todo: Avoid running before Run()
-            node.removePending(this.nodeId);
         });
     }
 }
 exports.Node = Node;
 class ComputedNode extends Node {
-    constructor(nodeId, forkIndex, data, graph) {
-        super(nodeId, forkIndex, data, graph);
+    constructor(graphId, nodeId, data, graph) {
+        super(nodeId, graph);
         this.retryCount = 0;
         this.isStaticNode = false;
         this.isComputedNode = true;
+        this.graphId = graphId;
         this.params = data.params ?? {};
-        this.agentId = data.agentId ?? graph.agentId;
+        this.nestedGraph = data.graph;
+        this.agentId = data.agentId;
         this.retryLimit = data.retry ?? 0;
         this.timeout = data.timeout;
+        this.isResult = data.isResult ?? false;
+        this.anyInput = data.anyInput ?? false;
+        this.dataSources = (data.inputs ?? []).map(utils_1.parseNodeName);
+        this.pendings = new Set(this.dataSources.map((source) => source.nodeId));
+        this.log.initForComputedNode(this);
     }
-    // for completed
-    pushQueueIfReady() {
-        if (this.pendings.size === 0) {
-            // If input property is specified, we need to ensure that the property value exists.
-            const count = this.inputs.reduce((count, nodeId) => {
-                const source = this.sources[nodeId];
-                if (source.propId) {
-                    const [result] = this.graph.resultsOf([source]);
-                    if (!result) {
-                        return count;
-                    }
-                }
-                return count + 1;
+    isReadyNode() {
+        if (this.state === type_1.NodeState.Waiting && this.pendings.size === 0) {
+            // Count the number of data actually available.
+            // We care it only when this.anyInput is true.
+            // Notice that this logic enables dynamic data-flows.
+            const counter = this.dataSources.reduce((count, source) => {
+                const [result] = this.graph.resultsOf([source], this.anyInput);
+                return result === undefined ? count : count + 1;
             }, 0);
-            if ((this.anyInput && count > 0) || count == this.inputs.length) {
-                this.graph.pushQueue(this);
+            if (!this.anyInput || counter > 0) {
+                return true;
             }
         }
+        return false;
     }
-    // for computed
+    // This private method (only called while executing execute()) performs
+    // the "retry" if specified. The transaction log must be updated before
+    // callling this method.
     retry(state, error) {
+        this.state = state; // this.execute() will update to NodeState.Executing
+        this.log.onError(this, this.graph, error.message);
         if (this.retryCount < this.retryLimit) {
             this.retryCount++;
             this.execute();
         }
         else {
-            this.state = state;
             this.result = undefined;
             this.error = error;
             this.transactionId = undefined; // This is necessary for timeout case
-            this.graph.removeRunning(this);
+            this.graph.onExecutionComplete(this);
         }
     }
+    // This method is called when the data became available on one of nodes,
+    // which this node needs data from.
     removePending(nodeId) {
-        super.removePending(nodeId);
-        if (this.graph.isRunning) {
-            this.pushQueueIfReady();
+        if (this.anyInput) {
+            const results = this.graph.resultsOf(this.dataSources, this.anyInput).filter((result) => {
+                return result !== undefined;
+            });
+            if (results.length > 0) {
+                this.pendings.clear();
+            }
+        }
+        else {
+            this.pendings.delete(nodeId);
+        }
+    }
+    isCurrentTransaction(transactionId) {
+        return this.transactionId === transactionId;
+    }
+    // This private method (called only fro execute) checks if the callback from
+    // the timer came before the completion of agent function call, record it
+    // and attempt to retry (if specified).
+    executeTimeout(transactionId) {
+        if (this.state === type_1.NodeState.Executing && this.isCurrentTransaction(transactionId)) {
+            console.log(`-- ${this.nodeId}: timeout ${this.timeout}`);
+            this.retry(type_1.NodeState.TimedOut, Error("Timeout"));
         }
     }
+    // This method is called when this computed node became ready to run.
+    // It asynchronously calls the associated with agent function and set the result,
+    // then it removes itself from the "running node" list of the graph.
+    // Notice that setting the result of this node may make other nodes ready to run.
     async execute() {
-        const results = this.graph
-            .resultsOf(this.inputs.map((input) => {
-            return this.sources[input];
-        }))
-            .filter((result) => {
+        const previousResults = this.graph.resultsOf(this.dataSources, this.anyInput).filter((result) => {
             // Remove undefined if anyInput flag is set.
             return !this.anyInput || result !== undefined;
         });
         const transactionId = Date.now();
-        const log = (0, log_1.executeLog)(this.nodeId, this.retryCount, transactionId, this.agentId, this.params, results);
-        this.graph.appendLog(log);
-        this.state = type_1.NodeState.Executing;
-        this.transactionId = transactionId;
+        this.prepareExecute(transactionId, previousResults);
         if (this.timeout && this.timeout > 0) {
             setTimeout(() => {
-                if (this.state === type_1.NodeState.Executing && this.transactionId === transactionId) {
-                    console.log(`-- ${this.nodeId}: timeout ${this.timeout}`);
-                    (0, log_1.timeoutLog)(log);
-                    this.retry(type_1.NodeState.TimedOut, Error("Timeout"));
-                }
+                this.executeTimeout(transactionId);
             }, this.timeout);
         }
         try {
             const callback = this.graph.getCallback(this.agentId);
             const localLog = [];
-            const result = await callback({
-                nodeId: this.nodeId,
-                retry: this.retryCount,
+            const context = {
                 params: this.params,
-                inputs: results,
-                forkIndex: this.forkIndex,
-                verbose: this.graph.verbose,
-                agents: this.graph.callbackDictonary,
+                inputs: previousResults,
+                debugInfo: {
+                    nodeId: this.nodeId,
+                    retry: this.retryCount,
+                    verbose: this.graph.verbose,
+                },
                 log: localLog,
-            });
-            if (this.transactionId !== transactionId) {
+            };
+            // NOTE: We use the existence of graph object in the agent-specific params to determine
+            // if this is a nested agent or not.
+            if (this.nestedGraph) {
+                this.graph.taskManager.prepareForNesting();
+                context.taskManager = this.graph.taskManager;
+                context.graphData = this.nestedGraph;
+                context.agents = this.graph.callbackDictonary;
+            }
+            const result = await callback(context);
+            if (this.nestedGraph) {
+                this.graph.taskManager.restoreAfterNesting();
+            }
+            if (!this.isCurrentTransaction(transactionId)) {
+                // This condition happens when the agent function returns
+                // after the timeout (either retried or not).
                 console.log(`-- ${this.nodeId}: transactionId mismatch`);
                 return;
             }
-            (0, log_1.callbackLog)(log, result, localLog);
-            log.state = type_1.NodeState.Completed;
-            this.setResult(result, type_1.NodeState.Completed);
-            this.graph.removeRunning(this);
+            this.state = type_1.NodeState.Completed;
+            this.result = result;
+            this.log.onComplete(this, this.graph, localLog);
+            this.onSetResult();
+            this.graph.onExecutionComplete(this);
         }
         catch (error) {
-            if (this.transactionId !== transactionId) {
-                console.log(`-- ${this.nodeId}: transactionId mismatch(error)`);
-                return;
-            }
-            const isError = error instanceof Error;
-            (0, log_1.errorLog)(log, isError ? error.message : "Unknown");
-            if (isError) {
-                this.retry(type_1.NodeState.Failed, error);
-            }
-            else {
-                console.error(`-- ${this.nodeId}: Unexpecrted error was caught`);
-                this.retry(type_1.NodeState.Failed, Error("Unknown"));
-            }
+            this.errorProcess(error, transactionId);
+        }
+    }
+    // This private method (called only by execute()) prepares the ComputedNode object
+    // for execution, and create a new transaction to record it.
+    prepareExecute(transactionId, inputs) {
+        this.state = type_1.NodeState.Executing;
+        this.log.beforeExecute(this, this.graph, transactionId, inputs);
+        this.transactionId = transactionId;
+    }
+    // This private method (called only by execute) processes an error received from
+    // the agent function. It records the error in the transaction log and handles
+    // the retry if specified.
+    errorProcess(error, transactionId) {
+        console.error(this.agentId + ": error");
+        console.error(error);
+        if (!this.isCurrentTransaction(transactionId)) {
+            console.log(`-- ${this.nodeId}: transactionId mismatch(error)`);
+            return;
+        }
+        if (error instanceof Error) {
+            this.retry(type_1.NodeState.Failed, error);
+        }
+        else {
+            console.error(`-- ${this.nodeId}: Unexpecrted error was caught`);
+            this.retry(type_1.NodeState.Failed, Error("Unknown"));
         }
     }
 }
 exports.ComputedNode = ComputedNode;
 class StaticNode extends Node {
-    constructor(nodeId, forkIndex, data, graph) {
-        super(nodeId, forkIndex, data, graph);
+    constructor(nodeId, data, graph) {
+        super(nodeId, graph);
         this.isStaticNode = true;
         this.isComputedNode = false;
         this.value = data.value;
         this.update = data.update;
+        this.isResult = data.isResult ?? false;
     }
-    // for static
-    injectValue(value) {
-        const log = (0, log_1.injectValueLog)(this.nodeId, value);
-        this.graph.appendLog(log);
-        this.setResult(value, type_1.NodeState.Injected);
-        //console.error("- injectValue called on non-source node.", this.nodeId);
+    injectValue(value, injectFrom) {
+        this.state = type_1.NodeState.Injected;
+        this.result = value;
+        this.log.onInjected(this, this.graph, injectFrom);
+        this.onSetResult();
     }
 }
 exports.StaticNode = StaticNode;

package/lib/task_manager.d.ts

@@ -0,0 +1,20 @@
+import { ComputedNode } from "./node";
+export declare class TaskManager {
+    private concurrency;
+    private taskQueue;
+    private runningNodes;
+    constructor(concurrency: number);
+    private dequeueTaskIfPossible;
+    addTask(node: ComputedNode, graphId: string, callback: (node: ComputedNode) => void): void;
+    isRunning(graphId: string): boolean;
+    onComplete(node: ComputedNode): void;
+    prepareForNesting(): void;
+    restoreAfterNesting(): void;
+    getStatus(verbose?: boolean): {
+        runningNodes?: string[] | undefined;
+        queuedNodes?: string[] | undefined;
+        concurrency: number;
+        queue: number;
+        running: number;
+    };
+}

package/lib/task_manager.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskManager = void 0;
+const utils_1 = require("./utils/utils");
+// TaskManage object controls the concurrency of ComputedNode execution.
+//
+// NOTE: A TaskManager instance will be shared between parent graph and its children
+// when nested agents are involved.
+class TaskManager {
+    constructor(concurrency) {
+        this.taskQueue = [];
+        this.runningNodes = new Set();
+        this.concurrency = concurrency;
+    }
+    // This internal method dequeus a task from the task queue
+    // and call the associated callback method, if the number of
+    // running task is lower than the spcified limit.
+    dequeueTaskIfPossible() {
+        if (this.runningNodes.size < this.concurrency) {
+            const task = this.taskQueue.shift();
+            if (task) {
+                this.runningNodes.add(task.node);
+                task.callback(task.node);
+            }
+        }
+    }
+    // Node will call this method to put itself in the execution queue.
+    // We call the associated callback function when it is dequeued.
+    addTask(node, graphId, callback) {
+        this.taskQueue.push({ node, graphId, callback });
+        this.dequeueTaskIfPossible();
+    }
+    isRunning(graphId) {
+        const count = [...this.runningNodes].filter((node) => {
+            return node.graphId == graphId;
+        }).length;
+        return count > 0 || Array.from(this.taskQueue).filter((data) => data.graphId === graphId).length > 0;
+    }
+    // Node MUST call this method once the execution of agent function is completed
+    // either successfully or not.
+    onComplete(node) {
+        (0, utils_1.assert)(this.runningNodes.has(node), `TaskManager.onComplete node(${node.nodeId}) is not in list`);
+        this.runningNodes.delete(node);
+        this.dequeueTaskIfPossible();
+    }
+    // Node will call this method before it hands the task manager from the graph
+    // to a nested agent. We need to make it sure that there is enough room to run
+    // computed nodes inside the nested graph to avoid a deadlock.
+    prepareForNesting() {
+        this.concurrency++;
+    }
+    restoreAfterNesting() {
+        this.concurrency--;
+    }
+    getStatus(verbose = false) {
+        return {
+            concurrency: this.concurrency,
+            queue: this.taskQueue.length,
+            running: this.runningNodes.size,
+            ...(verbose
+                ? {
+                    runningNodes: Array.from(this.runningNodes).map((node) => node.nodeId),
+                    queuedNodes: this.taskQueue.map((task) => task.node.nodeId),
+                }
+                : {}),
+        };
+    }
+}
+exports.TaskManager = TaskManager;

package/lib/transaction_log.d.ts

@@ -0,0 +1,27 @@
+import { ResultData, NodeDataParams, NodeState } from "./type";
+import type { GraphAI } from "./graphai";
+import type { ComputedNode, StaticNode } from "./node";
+export declare class TransactionLog {
+    nodeId: string;
+    state: NodeState;
+    startTime?: number;
+    endTime?: number;
+    retryCount?: number;
+    agentId?: string;
+    params?: NodeDataParams;
+    inputs?: string[];
+    inputsData?: Array<ResultData>;
+    injectFrom?: string;
+    errorMessage?: string;
+    result?: ResultData;
+    mapIndex?: number;
+    isLoop?: boolean;
+    repeatCount?: number;
+    log?: TransactionLog[];
+    constructor(nodeId: string);
+    initForComputedNode(node: ComputedNode): void;
+    onInjected(node: StaticNode, graph: GraphAI, injectFrom?: string): void;
+    onComplete(node: ComputedNode, graph: GraphAI, localLog: TransactionLog[]): void;
+    beforeExecute(node: ComputedNode, graph: GraphAI, transactionId: number, inputs: ResultData[]): void;
+    onError(node: ComputedNode, graph: GraphAI, errorMessage: string): void;
+}

package/lib/transaction_log.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionLog = void 0;
+const type_1 = require("./type");
+class TransactionLog {
+    constructor(nodeId) {
+        this.nodeId = nodeId;
+        this.state = type_1.NodeState.Waiting;
+    }
+    initForComputedNode(node) {
+        this.agentId = node.agentId;
+        this.params = node.params;
+    }
+    onInjected(node, graph, injectFrom) {
+        const isUpdating = "endTime" in this;
+        this.result = node.result;
+        this.state = node.state;
+        this.endTime = Date.now();
+        this.injectFrom = injectFrom;
+        graph.setLoopLog(this);
+        // console.log(this)
+        if (isUpdating) {
+            graph.updateLog(this);
+        }
+        else {
+            graph.appendLog(this);
+        }
+    }
+    onComplete(node, graph, localLog) {
+        this.result = node.result;
+        this.state = node.state;
+        this.endTime = Date.now();
+        graph.setLoopLog(this);
+        if (localLog.length > 0) {
+            this.log = localLog;
+        }
+        graph.updateLog(this);
+    }
+    beforeExecute(node, graph, transactionId, inputs) {
+        this.state = node.state;
+        this.retryCount = node.retryCount > 0 ? node.retryCount : undefined;
+        this.startTime = transactionId;
+        this.inputs = node.dataSources.map((source) => source.nodeId);
+        this.inputsData = inputs.length > 0 ? inputs : undefined;
+        graph.setLoopLog(this);
+        graph.appendLog(this);
+    }
+    onError(node, graph, errorMessage) {
+        this.state = node.state;
+        this.errorMessage = errorMessage;
+        this.endTime = Date.now();
+        graph.setLoopLog(this);
+        graph.updateLog(this);
+    }
+}
+exports.TransactionLog = TransactionLog;

package/lib/type.d.ts

@@ -1,5 +1,8 @@
+import type { TransactionLog } from "./transaction_log";
+import type { TaskManager } from "./task_manager";
 export declare enum NodeState {
     Waiting = "waiting",
+    Queued = "queued",
     Executing = "executing",
     Failed = "failed",
     TimedOut = "timed-out",
@@ -7,58 +10,68 @@ export declare enum NodeState {
     Injected = "injected",
     Dispatched = "dispatched"
 }
-export type ResultData<ResultType = Record<string, any>> = ResultType | undefined;
-export type ResultDataDictonary<ResultType = Record<string, any>> = Record<string, ResultData<ResultType>>;
-export type NodeDataParams<ParamsType = Record<string, any>> = ParamsType;
+export type DefaultResultData = Record<string, any>;
+export type DefaultInputData = Record<string, any>;
+export type ResultData<ResultType = DefaultResultData> = ResultType | undefined;
+export type ResultDataDictonary<ResultType = DefaultResultData> = Record<string, ResultData<ResultType>>;
+export type DefaultParamsType = Record<string, any>;
+export type NodeDataParams<ParamsType = DefaultParamsType> = ParamsType;
 export type DataSource = {
     nodeId: string;
     propId?: string;
 };
-export type NodeData = {
+export type StaticNodeData = {
+    value: ResultData;
+    update?: string;
+    isResult?: boolean;
+};
+export type ComputedNodeData = {
+    agentId: string;
     inputs?: Array<string>;
     anyInput?: boolean;
     params?: NodeDataParams;
     retry?: number;
     timeout?: number;
-    agentId?: string;
-    fork?: number;
-    value?: ResultData;
-    update?: string;
+    graph?: GraphData;
+    isResult?: boolean;
 };
+export type NodeData = StaticNodeData | ComputedNodeData;
 export type LoopData = {
     count?: number;
     while?: string;
 };
 export type GraphData = {
-    agentId?: string;
     nodes: Record<string, NodeData>;
     concurrency?: number;
     loop?: LoopData;
     verbose?: boolean;
 };
-export type TransactionLog = {
-    nodeId: string;
-    state: NodeState;
-    startTime: number;
-    endTime?: number;
-    retryCount?: number;
-    agentId?: string;
-    params?: NodeDataParams;
-    inputs?: Array<ResultData>;
-    errorMessage?: string;
-    result?: ResultData;
-    log?: TransactionLog[];
-};
-export type AgentFunctionContext<ParamsType, PreviousResultType> = {
-    nodeId: string;
-    forkIndex?: number;
-    retry: number;
+export type AgentFunctionContext<ParamsType, InputDataType> = {
     params: NodeDataParams<ParamsType>;
-    inputs: Array<PreviousResultType>;
-    verbose: boolean;
-    agents: CallbackDictonaryArgs;
-    log: TransactionLog[];
+    inputs: Array<InputDataType>;
+    debugInfo: {
+        verbose: boolean;
+        nodeId: string;
+        retry: number;
+    };
+    graphData?: GraphData;
+    agents?: AgentFunctionDictonary;
+    log?: TransactionLog[];
+    taskManager?: TaskManager;
 };
-export type AgentFunction<ParamsType = Record<string, any>, ResultType = Record<string, any>, PreviousResultType = Record<string, any>> = (context: AgentFunctionContext<ParamsType, PreviousResultType>) => Promise<ResultData<ResultType>>;
+export type AgentFunction<ParamsType = DefaultParamsType, ResultType = DefaultResultData, InputDataType = DefaultInputData> = (context: AgentFunctionContext<ParamsType, InputDataType>) => Promise<ResultData<ResultType>>;
 export type AgentFunctionDictonary = Record<string, AgentFunction<any, any, any>>;
-export type CallbackDictonaryArgs = AgentFunctionDictonary;
+export type AgentFunctionInfo = {
+    name: string;
+    agent: AgentFunction<any, any, any>;
+    mock: AgentFunction<any, any, any>;
+    samples: {
+        inputs: any;
+        params: DefaultParamsType;
+        result: any;
+    }[];
+    description: string;
+    author: string;
+    repository: string;
+    license: string;
+};

package/lib/type.js

@@ -4,6 +4,7 @@ exports.NodeState = void 0;
 var NodeState;
 (function (NodeState) {
     NodeState["Waiting"] = "waiting";
+    NodeState["Queued"] = "queued";
     NodeState["Executing"] = "executing";
     NodeState["Failed"] = "failed";
     NodeState["TimedOut"] = "timed-out";

package/lib/utils/test_agents.d.ts

@@ -0,0 +1,2 @@
+import { AgentFunctionDictonary } from "../graphai";
+export declare const defaultTestAgents: AgentFunctionDictonary;

package/lib/utils/test_agents.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultTestAgents = void 0;
+const experimental_agents_1 = require("../experimental_agents");
+exports.defaultTestAgents = {
+    bypassAgent: experimental_agents_1.bypassAgent,
+    echoAgent: experimental_agents_1.echoAgent,
+    copyMessageAgent: experimental_agents_1.copyMessageAgent,
+    mergeNodeIdAgent: experimental_agents_1.mergeNodeIdAgent,
+    sleeperAgent: experimental_agents_1.sleeperAgent,
+    sleeperAgentDebug: experimental_agents_1.sleeperAgentDebug,
+    stringTemplateAgent: experimental_agents_1.stringTemplateAgent,
+    nestedAgent: experimental_agents_1.nestedAgent,
+    mapAgent: experimental_agents_1.mapAgent,
+    totalAgent: experimental_agents_1.totalAgent,
+    countingAgent: experimental_agents_1.countingAgent,
+    copy2ArrayAgent: experimental_agents_1.copy2ArrayAgent,
+    pushAgent: experimental_agents_1.pushAgent,
+    popAgent: experimental_agents_1.popAgent,
+};

package/lib/utils/test_utils.d.ts

@@ -0,0 +1,12 @@
+import { AgentFunctionInfo } from "../type";
+export declare const defaultTestContext: {
+    debugInfo: {
+        nodeId: string;
+        retry: number;
+        verbose: boolean;
+    };
+    params: {};
+    agents: {};
+    log: never[];
+};
+export declare const agentTestRunner: (agentInfo: AgentFunctionInfo) => Promise<void>;