graphai 0.0.11 → 0.1.0

package/README.md

@@ -9,6 +9,7 @@ You just need to describe dependencies among those API calls in a single data fl
 Here is an example:
 
 ```YAML
+agentId: sample
 nodes:
   taskA:
     params:
@@ -37,7 +38,7 @@ const sampleAgentFunction = async (context: AgentFunctionContext) => {
   ...
   const file = fs.readFileSync(pathToYamlFile, "utf8");
   const graphData = YAML.parse(file);
-  const graph = new GraphAI(graphData, sampleAgentFunction);
+  const graph = new GraphAI(graphData, { sample: sampleAgentFunction });
   const results = await graph.run();
   return results["taskC"];
 ```
@@ -48,14 +49,14 @@ As Andrew Ng has described in his article, "[The batch: Issue 242](https://www.d
 
 Building applications that employ these workflows, however, is challenging due to the complexities of managing multiple asynchronous API calls, including error handling, timeouts, retries, and logging. 
 
-GraphAI is designed to simplify this process by decoupling the complexity of multiple asynchronous calls from the application's core logic. It enables developers to model these calls and their dependencies within a single Data Flow Graph, enhancing development and debugging processes. 
+GraphAI is designed to simplify this process by decoupling the complexity of multiple asynchronous calls from the application's core logic. It enables developers to model these calls and their dependencies within a single acyclic Data Flow Graph, enhancing development and debugging processes. 
 
 Furthermore, GraphAI's robust mechanisms for error handling, retry strategies, timeouts, and logging empower developers to concentrate on refining the application logic.
 
 ## Quick Install
 
 ```
-pip install graphai
+npm install graphai
 ```
 
 or
@@ -114,12 +115,43 @@ Key principles:
 
 A Data Flow Graph (DFG) is a JavaScript object, which defines the flow of data. It is typically described in YAML file and loaded at runtime.
 
-A DFG consists of a collection of 'nodes', which contains a series of nested keys representing individual nodes in the data flow. Each node is identified by a unique key (e.g., node1, node2) and can contain several predefined keys (params, inputs, outputs, retry, timeout, source, agentId, result, fork) that dictate the node's behavior and its relationship with other nodes.
+A DFG consists of a collection of 'nodes', which contains a series of nested properties representing individual nodes in the data flow. Each node is identified by a unique key, *nodeId* (e.g., node1, node2) and can contain several predefined properties (params, inputs, retry, timeout, agentId, fork, value, update) that dictate the node's behavior and its relationship with other nodes.
+
+Connections between nodes will be established by references from one not to another, using either its "inputs" or "update" property. The values of those properties are *data sources*. A *data souce* is specified by either the nodeId (e.g., "node1"), or nodeId + propertyId ("node1.item").
 
 ### DFG Structure
 
 - 'nodes': A list of node. Required.
 - 'concurrency': An optional property, which specifies the maximum number of concurrent operations (agent functions to be executed at the same time). The default is 8.
+- 'agentId': An optional property, which specifies the default agent for all the nodes.
+- 'loop': An optional property, which specifies if the graph needs to be executed multiple times. The loop is an JavaScript object, which has two optinoal properties. The *count* property specifies the number of times the graph needs to be executed and the *while* property specifies the condition required to contineu the loop in the form of node name (nodeId) or its property (nodeId.propId). Unlike JavaScript, an empty array will be treated as false.
+
+```
+loop:
+  while: people
+nodes:
+  people:
+    value:
+      - Steve Jobs
+      - Elon Musk
+      - Nikola Tesla
+    update: retriever.array
+  result:
+    value: []
+    update: reducer
+  retriever:
+    agentId: shift
+    inputs: [people]
+  query:
+    agentId: slashgpt
+    params:
+      manifest:
+        prompt: 指定した人について日本語で４００字以内で答えて
+    inputs: [retriever.item]
+  reducer:
+    agentId: push
+    inputs: [result, query.content]
+```
 
 ## Agent
 
@@ -133,19 +165,25 @@ An agent function receives two set of parameters via AgentFunctionContext, agent
 
 ## Node Structure
 
-- 'inputs': An optional list of node identifiers that the current node depends on. This establishes a flow where the current node can only be executed after the completion of the nodes listed under 'inputs'. If this list is empty and the 'source' property is not set, the associated Agent Function will be immediatley executed. 
-- 'source': An optional flag, which specifies if the node is a 'source node' or not. A souce node is a special node, which receives data from either an external code (via GraphAI's injectResult method) or from a 'dispatcher node'.
-- 'result': An optional object, which injects the result into the source node (equivalent to calling the injectResult method).
+There are two types of Node, *computed nodes* and *static nodes*. A *computed node* is associated with an *agent function*, which receives some inputs, performs some computations asynchronously then returns the result (output). A *static node* is a placeholder of a value (just like a variable in programming language), which is injected by an external program, or is retrived from a *data source* (in case of interations). 
+
+A *computed node* have following properties.
+
+- 'agentId': An **required** property, which specifies the id of the *agent function*.
+- 'inputs': An optional list of *data sources* that the current node depends on. This establishes a flow where the current node can only be executed after the completion of the nodes listed under 'inputs'. If this list is empty, the associated *agent function* will be immediatley executed. 
 - 'retry': An optional number, which specifies the maximum number of retries to be made. If the last attempt fails, that return value will be recorded.
 - 'timeout': An optional number, which specifies the maximum waittime in msec. If the associated agent function does not return the value in time, the "Timeout" error will be recorded and the returned value will be discarded. 
-- 'params': An optional parameters to the associated agent function, which are agent specific.
-- 'agentId': An optional parameter, which specifies the id of the agent, when the graph is associated with multiple agents.
+- 'params': An optional property to the associated agent function, which are agent specific.
 - 'fork': An optional paramter, which specifies the number of concurrent transactions to be created for the current node.
-- 'outputs': An optinal property, which specifies the mapping from outputId to nodeId. If this property is set, the node become a special node called "dispatcher". A dispatcher node injects result(s) into specified nodes, enabling the dynamic flow of data.
+
+A *static* node have following properties.
+
+- 'value': An optional property, which specifies the value of this static node (equivalent to calling the injectValue method from outside).
+- 'update': An optional property, which specifies the *data source* after each iteration.
 
 ## GraphAI class
 
-### ```constructor(data: GraphData, callbackDictonary: AgentFunctionDictonary | AgentFunction<any, any, any>)```
+### ```constructor(data: GraphData, callbackDictonary: AgentFunctionDictonary)```
 Initializes a new instance of the GraphAI class with the specified graph data and a dictionary of callback functions.
 
 - ```data: GraphData```: The graph data including nodes and optional concurrency limit.
@@ -172,7 +210,7 @@ Retrieves all transaction logs recorded during the execution of the graph.
 Returns: An array of transaction logs detailing the execution states and outcomes of the nodes within the graph.
 
 ### ```injectResult(nodeId: string, result: ResultData): void```
-Injects a result into a specified node. This is used to manually set the result of a source node, allowing dependent nodes to proceed with execution.
+Injects a result into a specified node. This is used to manually set the result of a static node, allowing dependent nodes to proceed with execution.
 
-- ```nodeId: string```: The ID of the source node into which the result is to be injected.
+- ```nodeId: string```: The ID of the static node into which the result is to be injected.
 - ```result: ResultData```: The result to be injected into the specified node.

package/lib/experimental_agents/array_agents.d.ts

@@ -0,0 +1,4 @@
+import { AgentFunction } from "../graphai";
+export declare const pushAgent: AgentFunction<Record<string, any>, Record<string, any>, Record<string, any>>;
+export declare const popAgent: AgentFunction<Record<string, any>, Record<string, any>, Record<string, any>>;
+export declare const shiftAgent: AgentFunction<Record<string, any>, Record<string, any>, Record<string, any>>;

package/lib/experimental_agents/array_agents.js

@@ -0,0 +1,30 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shiftAgent = exports.popAgent = exports.pushAgent = void 0;
+const deepmerge_1 = __importDefault(require("deepmerge"));
+const pushAgent = async ({ inputs }) => {
+    const [array, item] = (0, deepmerge_1.default)({ inputs }, {}).inputs;
+    // TODO: Validation
+    array.push(item);
+    return array;
+};
+exports.pushAgent = pushAgent;
+const popAgent = async (context) => {
+    const { inputs } = context;
+    const [array] = (0, deepmerge_1.default)({ inputs }, {}).inputs;
+    // TODO: Varidation
+    const item = array.pop();
+    return { array, item };
+};
+exports.popAgent = popAgent;
+const shiftAgent = async (context) => {
+    const { inputs } = context;
+    const [array] = (0, deepmerge_1.default)({ inputs }, {}).inputs;
+    // TODO: Varidation
+    const item = array.shift();
+    return { array, item };
+};
+exports.shiftAgent = shiftAgent;

package/lib/experimental_agents/index.d.ts

@@ -3,3 +3,4 @@ export * from "./slashgpt_agent";
 export * from "./sleeper_agent";
 export * from "./data_agent";
 export * from "./nested_agent";
+export * from "./array_agents";

package/lib/experimental_agents/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./slashgpt_agent"), exports);
 __exportStar(require("./sleeper_agent"), exports);
 __exportStar(require("./data_agent"), exports);
 __exportStar(require("./nested_agent"), exports);
+__exportStar(require("./array_agents"), exports);

package/lib/experimental_agents/nested_agent.js

@@ -2,17 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nestedAgent = void 0;
 const graphai_1 = require("../graphai");
-const nestedAgent = async ({ params, inputs, agents }) => {
+const nestedAgent = async ({ params, inputs, agents, log }) => {
     const graph = new graphai_1.GraphAI(params.graph, agents);
     try {
         // Inject inputs to specified source nodes
         (params.inputNodes ?? []).forEach((nodeId, index) => {
-            graph.injectResult(nodeId, inputs[index]);
+            graph.injectValue(nodeId, inputs[index]);
         });
         const results = await graph.run();
+        log.push(...graph.transactionLogs());
         return results[params.nodeId];
     }
     catch (error) {
+        log.push(...graph.transactionLogs());
         if (error instanceof Error) {
             console.log("Error:", error.message);
         }

package/lib/experimental_agents/slashgpt_agent.js

@@ -14,6 +14,9 @@ const slashGPTAgent = async ({ nodeId, params, inputs, verbose }) => {
     const session = new slashgpt_1.ChatSession(config, params.manifest ?? {});
     const query = params?.query ? [params.query] : [];
     const contents = query.concat(inputs.map((input) => {
+        if (typeof input === "string") {
+            return input;
+        }
         return input.content;
     }));
     session.append_user_question(contents.join("\n"));

package/lib/experimental_agents/sleeper_agent.d.ts

@@ -1,10 +1,10 @@
 import { AgentFunction } from "../graphai";
 export declare const sleeperAgent: AgentFunction<{
     duration: number;
-    result?: Record<string, any>;
+    value?: Record<string, any>;
 }>;
 export declare const sleeperAgentDebug: AgentFunction<{
     duration: number;
-    result?: Record<string, any>;
+    value?: Record<string, any>;
     fail?: boolean;
 }>;

package/lib/experimental_agents/sleeper_agent.js

@@ -11,7 +11,7 @@ const sleeperAgent = async (context) => {
     await (0, utils_1.sleep)(params.duration);
     return inputs.reduce((result, input) => {
         return (0, deepmerge_1.default)(result, input);
-    }, params.result ?? {});
+    }, params.value ?? {});
 };
 exports.sleeperAgent = sleeperAgent;
 const sleeperAgentDebug = async (context) => {
@@ -23,6 +23,6 @@ const sleeperAgentDebug = async (context) => {
     }
     return inputs.reduce((result, input) => {
         return (0, deepmerge_1.default)(result, input);
-    }, params.result ?? {});
+    }, params.value ?? {});
 };
 exports.sleeperAgentDebug = sleeperAgentDebug;

package/lib/graphai.d.ts

@@ -1,106 +1,36 @@
-export declare enum NodeState {
-    Waiting = "waiting",
-    Executing = "executing",
-    Failed = "failed",
-    TimedOut = "timed-out",
-    Completed = "completed",
-    Injected = "injected",
-    Dispatched = "dispatched"
-}
-type ResultData<ResultType = Record<string, any>> = ResultType | undefined;
-type ResultDataDictonary<ResultType = Record<string, any>> = Record<string, ResultData<ResultType>>;
-export type NodeDataParams<ParamsType = Record<string, any>> = ParamsType;
-type NodeData = {
-    inputs?: Array<string>;
-    params?: NodeDataParams;
-    retry?: number;
-    timeout?: number;
-    agentId?: string;
-    fork?: number;
-    source?: boolean;
-    result?: ResultData;
-    outputs?: Record<string, string>;
-};
-export type GraphData = {
-    nodes: Record<string, NodeData>;
-    concurrency?: number;
-    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;
-};
-export type AgentFunctionContext<ParamsType, ResultType, PreviousResultType> = {
-    nodeId: string;
-    forkIndex?: number;
-    retry: number;
-    params: NodeDataParams<ParamsType>;
-    inputs: Array<PreviousResultType>;
-    verbose: boolean;
-    agents: CallbackDictonaryArgs;
-};
-export type AgentFunction<ParamsType = Record<string, any>, ResultType = Record<string, any>, PreviousResultType = Record<string, any>> = (context: AgentFunctionContext<ParamsType, ResultType, PreviousResultType>) => Promise<ResultData<ResultType>>;
-export type AgentFunctionDictonary = Record<string, AgentFunction<any, any, any>>;
-declare class Node {
-    nodeId: string;
-    params: NodeDataParams;
-    inputs: Array<string>;
-    pendings: Set<string>;
-    waitlist: Set<string>;
-    state: NodeState;
-    agentId?: string;
-    fork?: number;
-    forkIndex?: number;
-    result: ResultData;
-    retryLimit: number;
-    retryCount: number;
-    transactionId: undefined | number;
-    timeout?: number;
-    error?: Error;
-    source: boolean;
-    outputs?: Record<string, string>;
-    private graph;
-    constructor(nodeId: string, forkIndex: number | undefined, data: NodeData, graph: GraphAI);
-    asString(): string;
-    private retry;
-    removePending(nodeId: string): void;
-    pushQueueIfReady(): void;
-    injectResult(result: ResultData): void;
-    private setResult;
-    execute(): Promise<void>;
-}
-type GraphNodes = Record<string, Node>;
-export type CallbackDictonaryArgs = AgentFunctionDictonary | AgentFunction<any, any, any>;
+export { AgentFunction, AgentFunctionDictonary, GraphData } from "./type";
+import { AgentFunctionDictonary, GraphData, DataSource, TransactionLog, ResultDataDictonary, ResultData, CallbackDictonaryArgs } from "./type";
+import { ComputedNode, StaticNode } from "./node";
+type GraphNodes = Record<string, ComputedNode | StaticNode>;
 export declare class GraphAI {
+    private data;
     nodes: GraphNodes;
+    agentId?: string;
     callbackDictonary: AgentFunctionDictonary;
     isRunning: boolean;
     private runningNodes;
     private nodeQueue;
     private onComplete;
     private concurrency;
+    private loop?;
+    private repeatCount;
     verbose: boolean;
     private logs;
+    private createNodes;
+    private getValueFromResults;
+    private initializeNodes;
     constructor(data: GraphData, callbackDictonary: CallbackDictonaryArgs);
-    getCallback(_agentId?: string): AgentFunction<any, any, any>;
+    getCallback(agentId?: string): import("./type").AgentFunction<any, any, any>;
     asString(): string;
-    results(): ResultDataDictonary<Record<string, any>>;
+    results(): ResultDataDictonary;
     errors(): Record<string, Error>;
+    private pushReadyNodesIntoQueue;
     run(): Promise<ResultDataDictonary>;
     private runNode;
-    pushQueue(node: Node): void;
-    removeRunning(node: Node): void;
+    pushQueue(node: ComputedNode): void;
+    removeRunning(node: ComputedNode): void;
     appendLog(log: TransactionLog): void;
     transactionLogs(): TransactionLog[];
-    injectResult(nodeId: string, result: ResultData): void;
-    resultsOf(nodeIds: Array<string>): ResultData<Record<string, any>>[];
+    injectValue(nodeId: string, value: ResultData): void;
+    resultsOf(sources: Array<DataSource>): any[];
 }
-export {};

package/lib/graphai.js

@@ -1,201 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GraphAI = exports.NodeState = void 0;
-var NodeState;
-(function (NodeState) {
-    NodeState["Waiting"] = "waiting";
-    NodeState["Executing"] = "executing";
-    NodeState["Failed"] = "failed";
-    NodeState["TimedOut"] = "timed-out";
-    NodeState["Completed"] = "completed";
-    NodeState["Injected"] = "injected";
-    NodeState["Dispatched"] = "dispatched";
-})(NodeState || (exports.NodeState = NodeState = {}));
-class Node {
-    constructor(nodeId, forkIndex, data, graph) {
-        this.waitlist = new Set(); // List of nodes which need data from this node.
-        this.state = NodeState.Waiting;
-        this.result = undefined;
-        this.retryCount = 0;
-        this.nodeId = nodeId;
-        this.forkIndex = forkIndex;
-        this.inputs = data.inputs ?? [];
-        this.pendings = new Set(this.inputs);
-        this.params = data.params ?? {};
-        this.agentId = data.agentId;
-        this.fork = data.fork;
-        this.retryLimit = data.retry ?? 0;
-        this.timeout = data.timeout;
-        this.source = data.source === true;
-        this.outputs = data.outputs;
-        this.graph = graph;
-    }
-    asString() {
-        return `${this.nodeId}: ${this.state} ${[...this.waitlist]}`;
-    }
-    retry(state, error) {
-        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);
-        }
-    }
-    removePending(nodeId) {
-        this.pendings.delete(nodeId);
-        if (this.graph.isRunning) {
-            this.pushQueueIfReady();
-        }
-    }
-    pushQueueIfReady() {
-        if (this.pendings.size === 0 && !this.source) {
-            this.graph.pushQueue(this);
-        }
-    }
-    injectResult(result) {
-        if (this.source) {
-            const log = {
-                nodeId: this.nodeId,
-                retryCount: this.retryCount,
-                state: NodeState.Injected,
-                startTime: Date.now(),
-                endTime: Date.now(),
-                result,
-            };
-            this.graph.appendLog(log);
-            this.setResult(result, NodeState.Injected);
-        }
-        else {
-            console.error("- injectResult called on non-source node.", this.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);
-        });
-    }
-    async execute() {
-        const results = this.graph.resultsOf(this.inputs);
-        const transactionId = Date.now();
-        const log = {
-            nodeId: this.nodeId,
-            retryCount: this.retryCount,
-            state: NodeState.Executing,
-            startTime: transactionId,
-            agentId: this.agentId,
-            params: this.params,
-            inputs: results,
-        };
-        this.graph.appendLog(log);
-        this.state = NodeState.Executing;
-        this.transactionId = transactionId;
-        if (this.timeout && this.timeout > 0) {
-            setTimeout(() => {
-                if (this.state === NodeState.Executing && this.transactionId === transactionId) {
-                    console.log(`-- ${this.nodeId}: timeout ${this.timeout}`);
-                    log.errorMessage = "Timeout";
-                    log.state = NodeState.TimedOut;
-                    log.endTime = Date.now();
-                    this.retry(NodeState.TimedOut, Error("Timeout"));
-                }
-            }, this.timeout);
-        }
-        try {
-            const callback = this.graph.getCallback(this.agentId);
-            const result = await callback({
-                nodeId: this.nodeId,
-                retry: this.retryCount,
-                params: this.params,
-                inputs: results,
-                forkIndex: this.forkIndex,
-                verbose: this.graph.verbose,
-                agents: this.graph.callbackDictonary,
-            });
-            if (this.transactionId !== transactionId) {
-                console.log(`-- ${this.nodeId}: transactionId mismatch`);
-                return;
-            }
-            log.endTime = Date.now();
-            log.result = result;
-            const outputs = this.outputs;
-            if (outputs !== undefined) {
-                Object.keys(result).forEach((outputId) => {
-                    const nodeId = outputs[outputId];
-                    this.graph.injectResult(nodeId, result[outputId]);
-                });
-                log.state = NodeState.Dispatched;
-                this.state = NodeState.Dispatched;
-                this.graph.removeRunning(this);
-                return;
-            }
-            log.state = NodeState.Completed;
-            this.setResult(result, NodeState.Completed);
-            this.graph.removeRunning(this);
-        }
-        catch (error) {
-            if (this.transactionId !== transactionId) {
-                console.log(`-- ${this.nodeId}: transactionId mismatch(error)`);
-                return;
-            }
-            log.state = NodeState.Failed;
-            log.endTime = Date.now();
-            if (error instanceof Error) {
-                log.errorMessage = error.message;
-                this.retry(NodeState.Failed, error);
-            }
-            else {
-                console.error(`-- ${this.nodeId}: Unexpecrted error was caught`);
-                log.errorMessage = "Unknown";
-                this.retry(NodeState.Failed, Error("Unknown"));
-            }
-        }
-    }
-}
+exports.GraphAI = void 0;
+const node_1 = require("./node");
+const utils_1 = require("./utils/utils");
 const defaultConcurrency = 8;
 class GraphAI {
-    constructor(data, callbackDictonary) {
-        this.isRunning = false;
-        this.runningNodes = new Set();
-        this.nodeQueue = [];
-        this.logs = [];
-        this.callbackDictonary = typeof callbackDictonary === "function" ? { _default: callbackDictonary } : callbackDictonary;
-        this.concurrency = data.concurrency ?? defaultConcurrency;
-        this.verbose = data.verbose === true;
-        this.onComplete = () => {
-            console.error("-- SOMETHING IS WRONG: onComplete is called without run()");
-        };
+    createNodes(data) {
         const nodeId2forkedNodeIds = {};
         const forkedNodeId2Index = {};
-        // Create node instances from data.nodes
-        this.nodes = Object.keys(data.nodes).reduce((nodes, nodeId) => {
+        const forkedNodeId2NodeId = {}; // for sources
+        const nodes = Object.keys(data.nodes).reduce((_nodes, nodeId) => {
             const fork = data.nodes[nodeId].fork;
+            const isStaticNode = (data.nodes[nodeId].agentId ?? data.agentId) === undefined;
+            const node = isStaticNode ? node_1.StaticNode : node_1.ComputedNode;
             if (fork) {
                 // For fork, change the nodeId and increase the node
                 nodeId2forkedNodeIds[nodeId] = new Array(fork).fill(undefined).map((_, i) => {
                     const forkedNodeId = `${nodeId}_${i}`;
-                    nodes[forkedNodeId] = new Node(forkedNodeId, i, data.nodes[nodeId], this);
+                    _nodes[forkedNodeId] = new node(forkedNodeId, i, data.nodes[nodeId], this);
                     // Data for pending and waiting
                     forkedNodeId2Index[forkedNodeId] = i;
+                    forkedNodeId2NodeId[forkedNodeId] = nodeId;
                     return forkedNodeId;
                 });
             }
             else {
-                nodes[nodeId] = new Node(nodeId, undefined, data.nodes[nodeId], this);
+                _nodes[nodeId] = new node(nodeId, undefined, data.nodes[nodeId], this);
             }
-            return nodes;
+            return _nodes;
         }, {});
         // Generate the waitlist for each node, and update the pendings in case of forked node.
-        Object.keys(this.nodes).forEach((nodeId) => {
-            const node = this.nodes[nodeId];
+        Object.keys(nodes).forEach((nodeId) => {
+            const node = nodes[nodeId];
             node.pendings.forEach((pending) => {
                 // If the pending(previous) node is forking
                 if (nodeId2forkedNodeIds[pending]) {
@@ -203,36 +39,83 @@ class GraphAI {
                     if (node.fork) {
                         //  1:1 if current nodes are also forking.
                         const newPendingId = nodeId2forkedNodeIds[pending][forkedNodeId2Index[nodeId]];
-                        this.nodes[newPendingId].waitlist.add(nodeId); // previousNode
+                        nodes[newPendingId].waitlist.add(nodeId); // previousNode
                         node.pendings.add(newPendingId);
                     }
                     else {
                         //  1:n if current node is not forking.
                         nodeId2forkedNodeIds[pending].forEach((newPendingId) => {
-                            this.nodes[newPendingId].waitlist.add(nodeId); // previousNode
+                            nodes[newPendingId].waitlist.add(nodeId); // previousNode
                             node.pendings.add(newPendingId);
                         });
                     }
                     node.pendings.delete(pending);
                 }
                 else {
-                    this.nodes[pending].waitlist.add(nodeId); // previousNode
+                    if (nodes[pending]) {
+                        nodes[pending].waitlist.add(nodeId); // previousNode
+                    }
+                    else {
+                        console.error(`--- invalid input ${pending} for node, ${nodeId}`);
+                    }
                 }
             });
             node.inputs = Array.from(node.pendings); // for fork.
+            node.sources = node.inputs.reduce((sources, input) => {
+                const refNodeId = forkedNodeId2NodeId[input] ?? input;
+                sources[input] = { nodeId: input, propId: node.sources[refNodeId].propId };
+                return sources;
+            }, {});
         });
+        return nodes;
+    }
+    getValueFromResults(key, results) {
+        const source = (0, utils_1.parseNodeName)(key);
+        const result = results[source.nodeId];
+        return result ? (source.propId ? result[source.propId] : result) : undefined;
+    }
+    // for static
+    initializeNodes(previousResults) {
         // If the result property is specified, inject it.
-        // NOTE: This must be done at the end of this constructor
-        Object.keys(data.nodes).forEach((nodeId) => {
-            const result = data.nodes[nodeId].result;
-            if (result) {
-                this.injectResult(nodeId, result);
+        // If the previousResults exists (indicating we are in a loop),
+        // process the update property (nodeId or nodeId.propId).
+        Object.keys(this.data.nodes).forEach((nodeId) => {
+            const node = this.nodes[nodeId];
+            if (node?.isStaticNode) {
+                const value = node?.value;
+                const update = node?.update;
+                if (value) {
+                    this.injectValue(nodeId, value);
+                }
+                if (update && previousResults) {
+                    const result = this.getValueFromResults(update, previousResults);
+                    if (result) {
+                        this.injectValue(nodeId, result);
+                    }
+                }
             }
         });
     }
-    getCallback(_agentId) {
-        const agentId = _agentId ?? "_default";
-        if (this.callbackDictonary[agentId]) {
+    constructor(data, callbackDictonary) {
+        this.isRunning = false;
+        this.runningNodes = new Set();
+        this.nodeQueue = []; // for Computed Node
+        this.repeatCount = 0;
+        this.logs = [];
+        this.data = data;
+        this.callbackDictonary = callbackDictonary;
+        this.concurrency = data.concurrency ?? defaultConcurrency;
+        this.loop = data.loop;
+        this.agentId = data.agentId;
+        this.verbose = data.verbose === true;
+        this.onComplete = () => {
+            console.error("-- SOMETHING IS WRONG: onComplete is called without run()");
+        };
+        this.nodes = this.createNodes(data);
+        this.initializeNodes();
+    }
+    getCallback(agentId) {
+        if (agentId && this.callbackDictonary[agentId]) {
             return this.callbackDictonary[agentId];
         }
         throw new Error("No agent: " + agentId);
@@ -256,22 +139,29 @@ class GraphAI {
     errors() {
         return Object.keys(this.nodes).reduce((errors, nodeId) => {
             const node = this.nodes[nodeId];
-            if (node.error !== undefined) {
-                errors[nodeId] = node.error;
+            if (node.isComputedNode) {
+                if (node.error !== undefined) {
+                    errors[nodeId] = node.error;
+                }
             }
             return errors;
         }, {});
     }
+    pushReadyNodesIntoQueue() {
+        // Nodes without pending data should run immediately.
+        Object.keys(this.nodes).forEach((nodeId) => {
+            const node = this.nodes[nodeId];
+            if (node.isComputedNode) {
+                node.pushQueueIfReady();
+            }
+        });
+    }
     async run() {
         if (this.isRunning) {
             console.error("-- Already Running");
         }
         this.isRunning = true;
-        // Nodes without pending data should run immediately.
-        Object.keys(this.nodes).forEach((nodeId) => {
-            const node = this.nodes[nodeId];
-            node.pushQueueIfReady();
-        });
+        this.pushReadyNodesIntoQueue();
         return new Promise((resolve, reject) => {
             this.onComplete = () => {
                 this.isRunning = false;
@@ -286,10 +176,12 @@ class GraphAI {
             };
         });
     }
+    // for computed
     runNode(node) {
         this.runningNodes.add(node.nodeId);
         node.execute();
     }
+    // for computed
     pushQueue(node) {
         if (this.runningNodes.size < this.concurrency) {
             this.runNode(node);
@@ -298,6 +190,7 @@ class GraphAI {
             this.nodeQueue.push(node);
         }
     }
+    // for completed
     removeRunning(node) {
         this.runningNodes.delete(node.nodeId);
         if (this.nodeQueue.length > 0) {
@@ -307,6 +200,27 @@ class GraphAI {
             }
         }
         if (this.runningNodes.size === 0) {
+            this.repeatCount++;
+            const loop = this.loop;
+            if (loop && (loop.count === undefined || this.repeatCount < loop.count)) {
+                const results = this.results(); // results from previous loop
+                this.isRunning = false; // temporarily stop it
+                this.nodes = this.createNodes(this.data);
+                this.initializeNodes(results);
+                const checkWhileCondition = () => {
+                    if (loop.while) {
+                        const value = this.getValueFromResults(loop.while, this.results());
+                        // NOTE: We treat an empty array as false.
+                        return Array.isArray(value) ? value.length > 0 : !!value;
+                    }
+                    return true;
+                };
+                if (checkWhileCondition()) {
+                    this.isRunning = true; // restore it
+                    this.pushReadyNodesIntoQueue();
+                    return;
+                }
+            }
             this.onComplete();
         }
     }
@@ -316,18 +230,19 @@ class GraphAI {
     transactionLogs() {
         return this.logs;
     }
-    injectResult(nodeId, result) {
+    injectValue(nodeId, value) {
         const node = this.nodes[nodeId];
-        if (node) {
-            node.injectResult(result);
+        if (node && node.isStaticNode) {
+            node.injectValue(value);
         }
         else {
             console.error("-- Invalid nodeId", nodeId);
         }
     }
-    resultsOf(nodeIds) {
-        return nodeIds.map((nodeId) => {
-            return this.nodes[nodeId].result;
+    resultsOf(sources) {
+        return sources.map((source) => {
+            const result = this.nodes[source.nodeId].result;
+            return result && source.propId ? result[source.propId] : result;
         });
     }
 }

package/lib/graphai_cli.js

@@ -9,7 +9,7 @@ const experimental_agents_1 = require("./experimental_agents");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const yaml_1 = __importDefault(require("yaml"));
-const testAgent = async (context) => {
+const testAgent = async () => {
     return {};
 };
 const main = async () => {

package/lib/log.d.ts

@@ -0,0 +1,6 @@
+import { ResultData, TransactionLog, NodeDataParams } from "./type";
+export declare const injectValueLog: (nodeId: string, value: ResultData) => TransactionLog;
+export declare const executeLog: (nodeId: string, retryCount: number, transactionId: number, agentId: string | undefined, params: NodeDataParams, results: ResultData[]) => TransactionLog;
+export declare const timeoutLog: (log: TransactionLog) => void;
+export declare const callbackLog: (log: TransactionLog, result: ResultData, localLog: TransactionLog[]) => void;
+export declare const errorLog: (log: TransactionLog, errorMessage: string) => void;

package/lib/log.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.errorLog = exports.callbackLog = exports.timeoutLog = exports.executeLog = exports.injectValueLog = void 0;
+const type_1 = require("./type");
+const injectValueLog = (nodeId, value) => {
+    const log = {
+        nodeId,
+        state: type_1.NodeState.Injected,
+        startTime: Date.now(),
+        endTime: Date.now(),
+        result: value,
+    };
+    return log;
+};
+exports.injectValueLog = injectValueLog;
+const executeLog = (nodeId, retryCount, transactionId, agentId, params, results) => {
+    const log = {
+        nodeId,
+        retryCount: retryCount > 0 ? retryCount : undefined,
+        state: type_1.NodeState.Executing,
+        startTime: transactionId,
+        agentId,
+        params,
+        inputs: results.length > 0 ? results : undefined,
+    };
+    return log;
+};
+exports.executeLog = executeLog;
+const timeoutLog = (log) => {
+    log.errorMessage = "Timeout";
+    log.state = type_1.NodeState.TimedOut;
+    log.endTime = Date.now();
+};
+exports.timeoutLog = timeoutLog;
+const callbackLog = (log, result, localLog) => {
+    log.endTime = Date.now();
+    log.result = result;
+    if (localLog.length > 0) {
+        log.log = localLog;
+    }
+};
+exports.callbackLog = callbackLog;
+const errorLog = (log, errorMessage) => {
+    log.state = type_1.NodeState.Failed;
+    log.endTime = Date.now();
+    log.errorMessage = errorMessage;
+};
+exports.errorLog = errorLog;

package/lib/node.d.ts

@@ -0,0 +1,44 @@
+import type { NodeDataParams, ResultData, DataSource, NodeData } from "./type";
+import type { GraphAI } from "./graphai";
+import { NodeState } from "./type";
+export declare class Node {
+    nodeId: string;
+    sources: Record<string, DataSource>;
+    anyInput: boolean;
+    inputs: Array<string>;
+    pendings: Set<string>;
+    waitlist: Set<string>;
+    state: NodeState;
+    fork?: number;
+    forkIndex?: number;
+    result: ResultData;
+    transactionId: undefined | number;
+    protected graph: GraphAI;
+    constructor(nodeId: string, forkIndex: number | undefined, data: NodeData, graph: GraphAI);
+    asString(): string;
+    removePending(nodeId: string): void;
+    protected setResult(result: ResultData, state: NodeState): void;
+}
+export declare class ComputedNode extends Node {
+    params: NodeDataParams;
+    retryLimit: number;
+    retryCount: number;
+    agentId?: string;
+    timeout?: number;
+    error?: Error;
+    readonly isStaticNode = false;
+    readonly isComputedNode = true;
+    constructor(nodeId: string, forkIndex: number | undefined, data: NodeData, graph: GraphAI);
+    pushQueueIfReady(): void;
+    private retry;
+    removePending(nodeId: string): void;
+    execute(): Promise<void>;
+}
+export declare class StaticNode extends Node {
+    value?: ResultData;
+    update?: string;
+    readonly isStaticNode = true;
+    readonly isComputedNode = false;
+    constructor(nodeId: string, forkIndex: number | undefined, data: NodeData, graph: GraphAI);
+    injectValue(value: ResultData): void;
+}

package/lib/node.js

@@ -0,0 +1,179 @@
+"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 log_1 = require("./log");
+class Node {
+    constructor(nodeId, forkIndex, data, graph) {
+        this.sources = {}; // data sources.
+        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;
+    }
+    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();
+            }
+        }
+        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);
+        this.retryCount = 0;
+        this.isStaticNode = false;
+        this.isComputedNode = true;
+        this.params = data.params ?? {};
+        this.agentId = data.agentId ?? graph.agentId;
+        this.retryLimit = data.retry ?? 0;
+        this.timeout = data.timeout;
+    }
+    // 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;
+            }, 0);
+            if ((this.anyInput && count > 0) || count == this.inputs.length) {
+                this.graph.pushQueue(this);
+            }
+        }
+    }
+    // for computed
+    retry(state, error) {
+        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);
+        }
+    }
+    removePending(nodeId) {
+        super.removePending(nodeId);
+        if (this.graph.isRunning) {
+            this.pushQueueIfReady();
+        }
+    }
+    async execute() {
+        const results = this.graph
+            .resultsOf(this.inputs.map((input) => {
+            return this.sources[input];
+        }))
+            .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;
+        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.timeout);
+        }
+        try {
+            const callback = this.graph.getCallback(this.agentId);
+            const localLog = [];
+            const result = await callback({
+                nodeId: this.nodeId,
+                retry: this.retryCount,
+                params: this.params,
+                inputs: results,
+                forkIndex: this.forkIndex,
+                verbose: this.graph.verbose,
+                agents: this.graph.callbackDictonary,
+                log: localLog,
+            });
+            if (this.transactionId !== transactionId) {
+                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);
+        }
+        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"));
+            }
+        }
+    }
+}
+exports.ComputedNode = ComputedNode;
+class StaticNode extends Node {
+    constructor(nodeId, forkIndex, data, graph) {
+        super(nodeId, forkIndex, data, graph);
+        this.isStaticNode = true;
+        this.isComputedNode = false;
+        this.value = data.value;
+        this.update = data.update;
+    }
+    // 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);
+    }
+}
+exports.StaticNode = StaticNode;

package/lib/type.d.ts

@@ -0,0 +1,64 @@
+export declare enum NodeState {
+    Waiting = "waiting",
+    Executing = "executing",
+    Failed = "failed",
+    TimedOut = "timed-out",
+    Completed = "completed",
+    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 DataSource = {
+    nodeId: string;
+    propId?: string;
+};
+export type NodeData = {
+    inputs?: Array<string>;
+    anyInput?: boolean;
+    params?: NodeDataParams;
+    retry?: number;
+    timeout?: number;
+    agentId?: string;
+    fork?: number;
+    value?: ResultData;
+    update?: string;
+};
+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;
+    params: NodeDataParams<ParamsType>;
+    inputs: Array<PreviousResultType>;
+    verbose: boolean;
+    agents: CallbackDictonaryArgs;
+    log: TransactionLog[];
+};
+export type AgentFunction<ParamsType = Record<string, any>, ResultType = Record<string, any>, PreviousResultType = Record<string, any>> = (context: AgentFunctionContext<ParamsType, PreviousResultType>) => Promise<ResultData<ResultType>>;
+export type AgentFunctionDictonary = Record<string, AgentFunction<any, any, any>>;
+export type CallbackDictonaryArgs = AgentFunctionDictonary;

package/lib/type.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeState = void 0;
+var NodeState;
+(function (NodeState) {
+    NodeState["Waiting"] = "waiting";
+    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,3 @@
+import { DataSource } from "../type";
 export declare const sleep: (milliseconds: number) => Promise<unknown>;
+export declare const parseNodeName: (name: string) => DataSource;

package/lib/utils/utils.js

@@ -1,7 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sleep = void 0;
+exports.parseNodeName = exports.sleep = void 0;
 const sleep = async (milliseconds) => {
     return await new Promise((resolve) => setTimeout(resolve, milliseconds));
 };
 exports.sleep = sleep;
+const parseNodeName = (name) => {
+    const parts = name.split(".");
+    if (parts.length == 1) {
+        return { nodeId: parts[0] };
+    }
+    else {
+        return { nodeId: parts[0], propId: parts[1] };
+    }
+};
+exports.parseNodeName = parseNodeName;

package/lib/utils.d.ts

@@ -0,0 +1,7 @@
+export declare const parseNodeName: (name: string) => {
+    sourceNodeId: string;
+    propId?: undefined;
+} | {
+    sourceNodeId: string;
+    propId: string;
+};

package/lib/utils.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseNodeName = void 0;
+const parseNodeName = (name) => {
+    const parts = name.split(".");
+    if (parts.length == 1) {
+        return { sourceNodeId: parts[0] };
+    }
+    else {
+        return { sourceNodeId: parts[0], propId: parts[1] };
+    }
+};
+exports.parseNodeName = parseNodeName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphai",
-  "version": "0.0.11",
+  "version": "0.1.0",
   "description": "Asynchronous data flow execution engine to make it simple to build LLM apps.",
   "main": "lib/index.js",
   "bin": {
@@ -11,7 +11,7 @@
   ],
   "scripts": {
     "build": "tsc && tsc-alias",
-    "eslint": "eslint --fix --ext src/**/*.{ts} tests/**/*.ts",
+    "eslint": "eslint --fix --ext .ts ./src ./tests ./samples",
     "format": "prettier --write '{src,tests,samples}/**/*.ts' .eslintrc.js",
     "test": "node --test  -r tsconfig-paths/register --require ts-node/register ./tests/**/test_*.ts",
     "cli": "npx ts-node  -r tsconfig-paths/register ./src/graphai_cli.ts",