graphai 0.0.12 → 0.1.1

package/lib/node.d.ts

@@ -0,0 +1,50 @@
+import type { GraphAI, GraphData } from "./graphai";
+import { NodeDataParams, ResultData, DataSource, ComputedNodeData, StaticNodeData, NodeState } from "./type";
+import { TransactionLog } from "./transaction_log";
+export declare class Node {
+    readonly nodeId: string;
+    readonly waitlist: Set<string>;
+    state: NodeState;
+    result: ResultData | undefined;
+    protected graph: GraphAI;
+    protected log: TransactionLog;
+    constructor(nodeId: string, graph: GraphAI);
+    asString(): string;
+    protected onSetResult(): void;
+}
+export declare class ComputedNode extends Node {
+    readonly graphId: string;
+    readonly isResult: boolean;
+    readonly params: NodeDataParams;
+    readonly nestedGraph?: GraphData;
+    readonly retryLimit: number;
+    retryCount: number;
+    readonly agentId?: string;
+    readonly timeout?: number;
+    error?: Error;
+    transactionId: undefined | number;
+    sources: Record<string, DataSource>;
+    readonly anyInput: boolean;
+    inputs: Array<string>;
+    pendings: Set<string>;
+    readonly isStaticNode = false;
+    readonly isComputedNode = true;
+    constructor(graphId: string, nodeId: string, data: ComputedNodeData, graph: GraphAI);
+    isReadyNode(): boolean;
+    private retry;
+    removePending(nodeId: string): void;
+    private isCurrentTransaction;
+    private executeTimeout;
+    execute(): Promise<void>;
+    private prepareExecute;
+    private errorProcess;
+}
+export declare class StaticNode extends Node {
+    value?: ResultData;
+    readonly update?: string;
+    readonly isResult: boolean;
+    readonly isStaticNode = true;
+    readonly isComputedNode = false;
+    constructor(nodeId: string, data: StaticNodeData, graph: GraphAI);
+    injectValue(value: ResultData, injectFrom?: string): void;
+}

package/lib/node.js

@@ -0,0 +1,218 @@
+"use strict";
+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 transaction_log_1 = require("./transaction_log");
+class Node {
+    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.graph = graph;
+        this.log = new transaction_log_1.TransactionLog(nodeId);
+    }
+    asString() {
+        return `${this.nodeId}: ${this.state} ${[...this.waitlist]}`;
+    }
+    // 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);
+            }
+        });
+    }
+}
+exports.Node = Node;
+class ComputedNode extends Node {
+    constructor(graphId, nodeId, data, graph) {
+        super(nodeId, graph);
+        this.retryCount = 0;
+        this.sources = {}; // data sources.
+        this.isStaticNode = false;
+        this.isComputedNode = true;
+        this.graphId = graphId;
+        this.params = data.params ?? {};
+        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.sources = (data.inputs ?? []).reduce((tmp, input) => {
+            const source = (0, utils_1.parseNodeName)(input);
+            tmp[source.nodeId] = source;
+            return tmp;
+        }, {});
+        this.inputs = Object.keys(this.sources);
+        this.pendings = new Set(this.inputs);
+        this.log.initForComputedNode(this);
+    }
+    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.inputs.reduce((count, nodeId) => {
+                const source = this.sources[nodeId];
+                const [result] = this.graph.resultsOf([source], this.anyInput);
+                return result === undefined ? count : count + 1;
+            }, 0);
+            if (!this.anyInput || counter > 0) {
+                return true;
+            }
+        }
+        return false;
+    }
+    // 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.result = undefined;
+            this.error = error;
+            this.transactionId = undefined; // This is necessary for timeout case
+            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) {
+        if (this.anyInput) {
+            const [result] = this.graph.resultsOf([this.sources[nodeId]], this.anyInput);
+            if (result) {
+                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 previousResults = this.graph
+            .resultsOf(this.inputs.map((input) => {
+            return this.sources[input];
+        }), this.anyInput)
+            .filter((result) => {
+            // Remove undefined if anyInput flag is set.
+            return !this.anyInput || result !== undefined;
+        });
+        const transactionId = Date.now();
+        this.prepareExecute(transactionId, previousResults);
+        if (this.timeout && this.timeout > 0) {
+            setTimeout(() => {
+                this.executeTimeout(transactionId);
+            }, this.timeout);
+        }
+        try {
+            const callback = this.graph.getCallback(this.agentId);
+            const localLog = [];
+            const context = {
+                params: this.params,
+                inputs: previousResults,
+                debugInfo: {
+                    nodeId: this.nodeId,
+                    retry: this.retryCount,
+                    verbose: this.graph.verbose,
+                },
+                log: localLog,
+            };
+            // 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;
+            }
+            this.state = type_1.NodeState.Completed;
+            this.result = result;
+            this.log.onComplete(this, this.graph, localLog);
+            this.onSetResult();
+            this.graph.onExecutionComplete(this);
+        }
+        catch (error) {
+            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, data, graph) {
+        super(nodeId, graph);
+        this.isStaticNode = true;
+        this.isComputedNode = false;
+        this.value = data.value;
+        this.update = data.update;
+        this.isResult = data.isResult ?? false;
+    }
+    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.d.ts

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

package/lib/task.js

@@ -0,0 +1,63 @@
+"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, callback) {
+        this.taskQueue.push({ node, callback });
+        this.dequeueTaskIfPossible();
+    }
+    // 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() {
+        if (this.runningNodes.size === this.concurrency) {
+            this.concurrency++;
+            console.warn("WARNING: increasing concurrenty to", 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/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.inputs;
+        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

@@ -0,0 +1,77 @@
+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",
+    Completed = "completed",
+    Injected = "injected",
+    Dispatched = "dispatched"
+}
+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 StaticNodeData = {
+    value: ResultData;
+    update?: string;
+    isResult?: boolean;
+};
+export type ComputedNodeData = {
+    agentId: string;
+    inputs?: Array<string>;
+    anyInput?: boolean;
+    params?: NodeDataParams;
+    retry?: number;
+    timeout?: number;
+    graph?: GraphData;
+    isResult?: boolean;
+};
+export type NodeData = StaticNodeData | ComputedNodeData;
+export type LoopData = {
+    count?: number;
+    while?: string;
+};
+export type GraphData = {
+    nodes: Record<string, NodeData>;
+    concurrency?: number;
+    loop?: LoopData;
+    verbose?: boolean;
+};
+export type AgentFunctionContext<ParamsType, InputDataType> = {
+    params: NodeDataParams<ParamsType>;
+    inputs: Array<InputDataType>;
+    debugInfo: {
+        verbose: boolean;
+        nodeId: string;
+        retry: number;
+    };
+    graphData?: GraphData;
+    agents?: AgentFunctionDictonary;
+    log?: TransactionLog[];
+    taskManager?: TaskManager;
+};
+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 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

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeState = void 0;
+var NodeState;
+(function (NodeState) {
+    NodeState["Waiting"] = "waiting";
+    NodeState["Queued"] = "queued";
+    NodeState["Executing"] = "executing";
+    NodeState["Failed"] = "failed";
+    NodeState["TimedOut"] = "timed-out";
+    NodeState["Completed"] = "completed";
+    NodeState["Injected"] = "injected";
+    NodeState["Dispatched"] = "dispatched";
+})(NodeState || (exports.NodeState = NodeState = {}));

package/lib/utils/utils.d.ts

@@ -1 +1,5 @@
+import { DataSource } from "../type";
 export declare const sleep: (milliseconds: number) => Promise<unknown>;
+export declare const parseNodeName: (inputNodeId: string) => DataSource;
+export declare function assert(condition: boolean, message: string, isWarn?: boolean): asserts condition;
+export declare const isObject: (x: unknown) => boolean;

package/lib/utils/utils.js

@@ -1,7 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sleep = void 0;
+exports.isObject = exports.assert = exports.parseNodeName = exports.sleep = void 0;
 const sleep = async (milliseconds) => {
     return await new Promise((resolve) => setTimeout(resolve, milliseconds));
 };
 exports.sleep = sleep;
+const parseNodeName = (inputNodeId) => {
+    const parts = inputNodeId.split(".");
+    if (parts.length == 1) {
+        return { nodeId: parts[0] };
+    }
+    return { nodeId: parts[0], propId: parts[1] };
+};
+exports.parseNodeName = parseNodeName;
+function assert(condition, message, isWarn = false) {
+    if (!condition) {
+        if (!isWarn) {
+            throw new Error(message);
+        }
+        console.warn("warn: " + message);
+    }
+}
+exports.assert = assert;
+const isObject = (x) => {
+    return x !== null && typeof x === "object";
+};
+exports.isObject = isObject;

package/lib/validator.d.ts

@@ -0,0 +1,2 @@
+import { GraphData } from "./type";
+export declare const validateGraphData: (data: GraphData, agentIds: string[]) => boolean;