graphai 0.0.4 → 0.0.6

package/.eslintrc.js

@@ -1,49 +1,30 @@
 module.exports = {
-    "env": {
-        "es2021": true,
-        "node": true
+  env: {
+    es2021: true,
+    node: true,
+  },
+  extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+  overrides: [
+    {
+      env: {
+        node: true,
+      },
+      files: [".eslintrc.{js,cjs}"],
+      parserOptions: {
+        sourceType: "script",
+      },
     },
-    "extends": [
-        "eslint:recommended",
-        "plugin:@typescript-eslint/recommended"
-    ],
-    "overrides": [
-        {
-            "env": {
-                "node": true
-            },
-            "files": [
-                ".eslintrc.{js,cjs}"
-            ],
-            "parserOptions": {
-                "sourceType": "script"
-            }
-        }
-    ],
-    "parser": "@typescript-eslint/parser",
-    "parserOptions": {
-        "ecmaVersion": "latest",
-        "sourceType": "module"
-    },
-    "plugins": [
-        "@typescript-eslint"
-    ],
-    "rules": {
-        "indent": [
-            "error",
-            2
-        ],
-        "linebreak-style": [
-            "error",
-            "unix"
-        ],
-        "quotes": [
-            "error",
-            "double"
-        ],
-        "semi": [
-            "error",
-            "always"
-        ]
-    }
+  ],
+  parser: "@typescript-eslint/parser",
+  parserOptions: {
+    ecmaVersion: "latest",
+    sourceType: "module",
+  },
+  plugins: ["@typescript-eslint"],
+  rules: {
+    indent: ["error", 2],
+    "linebreak-style": ["error", "unix"],
+    quotes: ["error", "double"],
+    semi: ["error", "always"],
+  },
 };

package/.github/workflows/node.js.yml

@@ -24,4 +24,5 @@ jobs:
         node-version: ${{ matrix.node-version }}
         cache: 'npm'
     - run: yarn install
+    - run: cd tests/http-server/docs/ && npx http-server &
     - run: yarn test

package/README.md

@@ -1,8 +1,10 @@
 # GraphAI
 
-GraphAI is a TypeScript library, which makes it easy to create AI applications that need to make asynchronous AI API calls multiple times with some dependencies among them, such as giving the answer from one LLM call to another LLM call as a prompt. 
+## Overview
 
-You just need to describe dependencies among those API calls in a single graph definition file (in JSON or YAML), create a GraphAI object with it, and run it.
+GraphAI is an asynchronous data flow execution engine, which makes it easy to create AI applications that need to make asynchronous AI API calls multiple times with some dependencies among them, such as giving the answer from one LLM call to another LLM call as a prompt.
+
+You just need to describe dependencies among those API calls in a single data flow graph (typically in YAML), create a GraphAI object with it, and run it.
 
 Here is an example:
 
@@ -10,24 +12,24 @@ Here is an example:
 nodes:
   taskA:
     params:
-      // app-specific parameters for taskA
+      // agent-specific parameters for taskA
   taskB:
     params:
-      // app-specific parameters for taskB
+      // agent-specific parameters for taskB
   taskC:
     params:
-      // app-specific parameters for taskC
+      // agent-specific parameters for taskC
     inputs: [taskA, taskB]
 ```
 
 ``` TypeScript
-const nodeExecute = async (context: NodeExecuteContext) => {
+const sampleAgentFunction = async (context: AgentFunctionContext) => {
   const { 
     nodeId, // taskA, taskB or taskC 
-    params, // app-specific/task-specific parameters specified in the graph definition file
+    params, // agent-specific parameters specified in the graph definition file
     payload // for taskC, { taskA: resultA, taskB: resultB }
   } = context;
-  // App-specific code (such as calling OpenAI's chat.completions API)
+  // Agent-specific code (such as calling OpenAI's chat.completions API)
   ...
   return result;
 }
@@ -35,10 +37,40 @@ const nodeExecute = async (context: NodeExecuteContext) => {
   ...
   const file = fs.readFileSync(pathToYamlFile, "utf8");
   const graphdata = YAML.parse(file);
-  const graph = new GraphAI(graph_data, nodeExecute);
+  const graph = new GraphAI(graph_data, sampleAgentFunction);
   const results = await graph.run();
   return results["taskC"];
-
 ```
 
+## Data Flow Graph
+
+A Data Flow Graph (DFG) is a JSON 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, retry, timeout, source, dispatch, agentId) that dictate the node's behavior and its relationship with other nodes.
+
+### DFG Structure
+
+- 'nodes': A list of node.
+- 'concurrency': An optional number, which specifies the maximum number of concurrent operations (agent functions to be executed at the same time). The default is 8.
+
+## Agent
+
+An agent is an abstract object, which takes some inputs and generates an output asynchronously. It could be an LLM (such as GPT-4), an image/video/music generation, a database, or a REST API over HTTP. Each node (except 'source node') is associated with an agent function, which takes data flow into the node as inputs, and generates an output.
+
+## Agent function
+
+An agent function is a TypeScript function, which implements an agent. A DFG is associated one or more agent functions. If the DFG is associated with multiple agent functions, each node needs to be associated only one of them (either explicitly with 'agentId' or implicitly to the default Agent function).
+
+An agent function receives two set of parameters via AgentFunctionContext, agent specific parameters specified in the DFG and input data came from other nodes (payload).
+
+A regular agent function returns the data (type: ```Record<string, any>```), but a dispatcher agent function returns the date with outputID(s) (type: ```Record<string: Record<string, any>>```). 
+
+## 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'.
+- 'dispatch': An optinal property (type: ```Record<string, string>```) which indicates that the current node is a 'dispatcher node'. A dispatcher node is associated is a dispaher-style agent function, which has multiple possible 'outputs'.
+- '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.
+- 'payloadMapping': An optional property (type: ```Record<string, string>```), which maps input nodeIds to agent specific inputIDs.  

package/lib/graphai.d.ts

@@ -3,66 +3,96 @@ export declare enum NodeState {
     Executing = 1,
     Failed = 2,
     TimedOut = 3,
-    Completed = 4
+    Completed = 4,
+    Injected = 5,
+    Dispatched = 6
 }
 type ResultData<ResultType = Record<string, any>> = ResultType | undefined;
 type ResultDataDictonary<ResultType = Record<string, any>> = Record<string, ResultData<ResultType>>;
-export type NodeDataParams = Record<string, any>;
+export type NodeDataParams<ParamsType = Record<string, any>> = ParamsType;
 type NodeData = {
-    inputs: undefined | Array<string>;
+    inputs?: Array<string>;
     params: NodeDataParams;
-    retry: undefined | number;
-    timeout: undefined | number;
-    functionName: undefined | string;
+    payloadMapping?: Record<string, string>;
+    retry?: number;
+    timeout?: number;
+    agentId?: string;
+    source?: boolean;
+    dispatch?: Record<string, string>;
 };
-type GraphData = {
+export type GraphData = {
     nodes: Record<string, NodeData>;
-    concurrency: number;
+    concurrency?: number;
 };
-export type NodeExecuteContext<ResultType> = {
+export type TransactionLog = {
+    nodeId: string;
+    state: NodeState;
+    startTime: number;
+    endTime?: number;
+    retryCount: number;
+    agentId?: string;
+    params?: NodeDataParams;
+    payload?: ResultDataDictonary<ResultData>;
+    errorMessage?: string;
+    result?: ResultData;
+};
+export type AgentFunctionContext<ParamsType, ResultType, PreviousResultType> = {
     nodeId: string;
     retry: number;
-    params: NodeDataParams;
-    payload: ResultDataDictonary<ResultType>;
+    params: NodeDataParams<ParamsType>;
+    payload: ResultDataDictonary<PreviousResultType>;
 };
-type NodeExecute<ResultType> = (context: NodeExecuteContext<ResultType>) => Promise<ResultData<ResultType>>;
-declare class Node<ResultType = Record<string, any>> {
+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>;
+    payloadMapping: Record<string, string>;
     pendings: Set<string>;
     waitlist: Set<string>;
     state: NodeState;
-    functionName: string;
-    result: ResultData<ResultType>;
+    agentId: string;
+    result: ResultData;
     retryLimit: number;
     retryCount: number;
     transactionId: undefined | number;
-    timeout: number;
+    timeout?: number;
+    error?: Error;
+    source: boolean;
+    dispatch?: Record<string, string>;
     private graph;
-    constructor(nodeId: string, data: NodeData, graph: GraphAI<ResultType>);
+    constructor(nodeId: string, data: NodeData, graph: GraphAI);
     asString(): string;
     private retry;
     removePending(nodeId: string): void;
-    payload(): ResultDataDictonary<ResultType>;
+    payload(): ResultDataDictonary<Record<string, any>>;
     pushQueueIfReady(): void;
+    injectResult(result: ResultData): void;
+    private setResult;
     execute(): Promise<void>;
 }
-type GraphNodes<ResultType> = Record<string, Node<ResultType>>;
-type NodeExecuteDictonary<ResultType> = Record<string, NodeExecute<ResultType>>;
-export declare class GraphAI<ResultType = Record<string, any>> {
-    nodes: GraphNodes<ResultType>;
-    callbackDictonary: NodeExecuteDictonary<ResultType>;
+type GraphNodes = Record<string, Node>;
+export declare class GraphAI {
+    nodes: GraphNodes;
+    callbackDictonary: AgentFunctionDictonary;
+    isRunning: boolean;
     private runningNodes;
     private nodeQueue;
     private onComplete;
     private concurrency;
-    constructor(data: GraphData, callbackDictonary: NodeExecuteDictonary<ResultType> | NodeExecute<ResultType>);
-    getCallback(functionName: string): NodeExecute<ResultType>;
+    private logs;
+    constructor(data: GraphData, callbackDictonary: AgentFunctionDictonary | AgentFunction<any, any, any>);
+    getCallback(agentId: string): AgentFunction<any, any, any>;
     asString(): string;
+    results(): ResultDataDictonary<Record<string, any>>;
+    errors(): Record<string, Error>;
     run(): Promise<unknown>;
     private runNode;
-    pushQueue(node: Node<ResultType>): void;
-    removeRunning(node: Node<ResultType>): void;
+    pushQueue(node: Node): void;
+    removeRunning(node: Node): void;
+    appendLog(log: TransactionLog): void;
+    transactionLogs(): TransactionLog[];
+    injectResult(nodeId: string, result: ResultData): void;
 }
 export {};

package/lib/graphai.js

@@ -8,102 +8,179 @@ var NodeState;
     NodeState[NodeState["Failed"] = 2] = "Failed";
     NodeState[NodeState["TimedOut"] = 3] = "TimedOut";
     NodeState[NodeState["Completed"] = 4] = "Completed";
+    NodeState[NodeState["Injected"] = 5] = "Injected";
+    NodeState[NodeState["Dispatched"] = 6] = "Dispatched";
 })(NodeState || (exports.NodeState = NodeState = {}));
 class Node {
     constructor(nodeId, 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.inputs = data.inputs ?? [];
+        this.payloadMapping = data.payloadMapping ?? {};
         this.pendings = new Set(this.inputs);
         this.params = data.params;
-        this.waitlist = new Set();
-        this.state = NodeState.Waiting;
-        this.functionName = data.functionName ?? "default";
-        this.result = undefined;
+        this.agentId = data.agentId ?? "default";
         this.retryLimit = data.retry ?? 0;
-        this.retryCount = 0;
-        this.timeout = data.timeout ?? 0;
+        this.timeout = data.timeout;
+        this.source = data.source === true;
+        this.dispatch = data.dispatch;
         this.graph = graph;
     }
     asString() {
         return `${this.nodeId}: ${this.state} ${[...this.waitlist]}`;
     }
-    retry(state, result) {
+    retry(state, error) {
         if (this.retryCount < this.retryLimit) {
             this.retryCount++;
             this.execute();
         }
         else {
             this.state = state;
-            this.result = result;
+            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);
-        this.pushQueueIfReady();
+        if (this.graph.isRunning) {
+            this.pushQueueIfReady();
+        }
     }
     payload() {
         return this.inputs.reduce((results, nodeId) => {
-            results[nodeId] = this.graph.nodes[nodeId].result;
+            if (this.payloadMapping && this.payloadMapping[nodeId]) {
+                results[this.payloadMapping[nodeId]] = this.graph.nodes[nodeId].result;
+            }
+            else {
+                results[nodeId] = this.graph.nodes[nodeId].result;
+            }
             return results;
         }, {});
     }
     pushQueueIfReady() {
-        if (this.pendings.size === 0) {
+        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(),
+            };
+            log.endTime = log.startTime;
+            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 payload = this.payload();
+        const log = {
+            nodeId: this.nodeId,
+            retryCount: this.retryCount,
+            state: NodeState.Executing,
+            startTime: Date.now(),
+            agentId: this.agentId,
+            params: this.params,
+            payload,
+        };
+        this.graph.appendLog(log);
         this.state = NodeState.Executing;
-        const transactionId = Date.now();
+        const transactionId = log.startTime;
         this.transactionId = transactionId;
-        if (this.timeout > 0) {
+        if (this.timeout && this.timeout > 0) {
             setTimeout(() => {
                 if (this.state === NodeState.Executing && this.transactionId === transactionId) {
-                    console.log("*** timeout", this.timeout);
-                    this.retry(NodeState.TimedOut, undefined);
+                    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.functionName);
+            const callback = this.graph.getCallback(this.agentId);
             const result = await callback({
                 nodeId: this.nodeId,
                 retry: this.retryCount,
                 params: this.params,
-                payload: this.payload(),
+                payload,
             });
             if (this.transactionId !== transactionId) {
-                console.log("****** transactionId mismatch (success)");
+                console.log(`-- ${this.nodeId}: transactionId mismatch`);
                 return;
             }
-            this.state = NodeState.Completed;
-            this.result = result;
-            this.waitlist.forEach((nodeId) => {
-                const node = this.graph.nodes[nodeId];
-                node.removePending(this.nodeId);
-            });
+            log.endTime = Date.now();
+            log.result = result;
+            const dispatch = this.dispatch;
+            if (dispatch !== undefined) {
+                Object.keys(result).forEach((outputId) => {
+                    const nodeId = dispatch[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 (e) {
+        catch (error) {
             if (this.transactionId !== transactionId) {
-                console.log("****** transactionId mismatch (failed)");
+                console.log(`-- ${this.nodeId}: transactionId mismatch(error)`);
                 return;
             }
-            this.retry(NodeState.Failed, undefined);
+            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"));
+            }
         }
     }
 }
+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;
         if (this.callbackDictonary["default"] === undefined) {
             throw new Error("No default function");
         }
-        this.concurrency = data.concurrency ?? 2;
-        this.runningNodes = new Set();
-        this.nodeQueue = [];
-        this.onComplete = () => { };
+        this.concurrency = data.concurrency ?? defaultConcurrency;
+        this.onComplete = () => {
+            console.error("-- SOMETHING IS WRONG: onComplete is called without run()");
+        };
         this.nodes = Object.keys(data.nodes).reduce((nodes, nodeId) => {
             nodes[nodeId] = new Node(nodeId, data.nodes[nodeId], this);
             return nodes;
@@ -117,9 +194,9 @@ class GraphAI {
             });
         });
     }
-    getCallback(functionName) {
-        if (functionName && this.callbackDictonary[functionName]) {
-            return this.callbackDictonary[functionName];
+    getCallback(agentId) {
+        if (agentId && this.callbackDictonary[agentId]) {
+            return this.callbackDictonary[agentId];
         }
         return this.callbackDictonary["default"];
     }
@@ -130,7 +207,29 @@ class GraphAI {
         })
             .join("\n");
     }
+    results() {
+        return Object.keys(this.nodes).reduce((results, nodeId) => {
+            const node = this.nodes[nodeId];
+            if (node.result !== undefined) {
+                results[nodeId] = node.result;
+            }
+            return results;
+        }, {});
+    }
+    errors() {
+        return Object.keys(this.nodes).reduce((errors, nodeId) => {
+            const node = this.nodes[nodeId];
+            if (node.error !== undefined) {
+                errors[nodeId] = node.error;
+            }
+            return errors;
+        }, {});
+    }
     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];
@@ -138,11 +237,15 @@ class GraphAI {
         });
         return new Promise((resolve, reject) => {
             this.onComplete = () => {
-                const results = Object.keys(this.nodes).reduce((results, nodeId) => {
-                    results[nodeId] = this.nodes[nodeId].result;
-                    return results;
-                }, {});
-                resolve(results);
+                this.isRunning = false;
+                const errors = this.errors();
+                const nodeIds = Object.keys(errors);
+                if (nodeIds.length > 0) {
+                    reject(errors[nodeIds[0]]);
+                }
+                else {
+                    resolve(this.results());
+                }
             };
         });
     }
@@ -170,5 +273,20 @@ class GraphAI {
             this.onComplete();
         }
     }
+    appendLog(log) {
+        this.logs.push(log);
+    }
+    transactionLogs() {
+        return this.logs;
+    }
+    injectResult(nodeId, result) {
+        const node = this.nodes[nodeId];
+        if (node) {
+            node.injectResult(result);
+        }
+        else {
+            console.error("-- Invalid nodeId", nodeId);
+        }
+    }
 }
 exports.GraphAI = GraphAI;

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "graphai",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Asynchronous data flow execution engine to make it simple to build LLM apps.",
   "main": "lib/index.js",
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc-alias",
     "eslint": "eslint --fix --ext src/**/*.{ts} tests/**/*.ts",
-    "format": "prettier --write '{src,tests}/**/*.ts'",
-    "test": "node --test --require ts-node/register ./tests/test_*.ts"
+    "format": "prettier --write '{src,tests,samples}/**/*.ts' .eslintrc.js",
+    "test": "node --test  -r tsconfig-paths/register --require ts-node/register ./tests/**/test_*.ts",
+    "gpt": "npx ts-node  -r tsconfig-paths/register ./samples/sample_gpt.ts"
   },
   "repository": {
     "type": "git",
@@ -20,15 +21,20 @@
   },
   "homepage": "https://github.com/snakajima/graphai#readme",
   "devDependencies": {
+    "@types/express": "^4.17.21",
     "@types/node": "^20.8.7",
     "@typescript-eslint/eslint-plugin": "^6.8.0",
     "@typescript-eslint/parser": "^6.8.0",
+    "arxiv-api-ts": "^1.0.3",
     "eslint": "^7.32.0 || ^8.2.0",
     "eslint-plugin-import": "^2.25.2",
+    "express": "^4.19.2",
     "openai": "^4.12.4",
     "prettier": "^3.0.3",
-    "slashgpt": "^0.0.6",
+    "slashgpt": "^0.0.8",
     "ts-node": "^10.9.1",
+    "tsc-alias": "^1.8.8",
+    "tsconfig-paths": "^4.2.0",
     "typescript": "^5.2.2"
   },
   "dependencies": {