graphai 0.5.7 → 0.5.9

package/README.md

@@ -22,41 +22,53 @@ nodes:
       query: describe the final sentence by the court for Sam Bank-Fried
   wikipedia: // Retrieve data from Wikipedia
     agent: wikipediaAgent
-    inputs: [:source.name]
+    inputs:
+      query: :source.name
   chunks: // Break the text from Wikipedia into chunks (2048 character each with 512 overlap）
     agent: stringSplitterAgent
-    inputs: [:wikipedia]
+    inputs:
+      text: :wikipedia
   chunkEmbeddings: // Get embedding vector of each chunk
     agent: stringEmbeddingsAgent
-    inputs: [:chunks]
+    inputs:
+      array: :chunks
   topicEmbedding: // Get embedding vector of the question
     agent: stringEmbeddingsAgent
-    inputs: [:source.query]
+    inputs:
+      item: :source.query
   similarities: // Calculate the cosine similarity of each chunk
     agent: dotProductAgent
-    inputs: [:chunkEmbeddings, :topicEmbedding]
+    inputs:
+      matrix: :chunkEmbeddings
+      vector: :topicEmbedding
   sortedChunks: // Sort chunks based on their similarities
     agent: sortByValuesAgent
-    inputs: [:chunks, :similarities]
+    inputs:
+      array: :chunks
+      values: :similarities
   referenceText: // Concatenate chunks up to the token limit (5000)
     agent: tokenBoundStringsAgent
-    inputs: [:sortedChunks]
+    inputs:
+      array: :sortedChunks
     params:
       limit: 5000
   prompt: // Generate a prompt with that reference text
     agent: stringTemplateAgent
-    inputs: [:source, :referenceText]
+    inputs:
+      prompt: :source
+      text: :referenceText
     params:
       template: |-
-        Using the following document, ${0}
-        ${1}
+        Using the following document, ${prompt}
+        ${text}
   query: // retrieves the answer from GPT3.5
     agent: slashGPTAgent
     params:
       manifest:
         model: gpt-3.5-turbo
     isResult: true // indicating this is the final result
-    inputs: [:prompt]
+    inputs:
+      prompt: :prompt
 ```
 
 ```mermaid
@@ -134,8 +146,10 @@ Here is an examnple (from [weather chat](https://github.com/receptron/graphai/bl
 ```typescript
     messagesWithUserInput: {
       // Appends the user's input to the messages.
-      agent: (messages: Array<any>, content: string) => [...messages, { role: "user", content }],
-      inputs: [":messages", ":userInput"],
+      agent: ({ messages: Array<any>, content: string }) => [...messages, { role: "user", content }],
+      inputs:
+        messages: ":messages"
+        content: ":userInput"
       if: "checkInput",
     },
 ```
@@ -186,8 +200,9 @@ nodes:
   question:
     value: "Find out which materials we need to purchase this week for Joe Smith's residential house project."
   projectId: // identifies the projectId from the question
-    agent: "identifierAgent"
-    inputs: [":source"] // == "sourceNode.query"
+    agent: identifierAgent
+    inputs: 
+      id: :source
   database:
     agent: "nestedAgent"
     inputs:
@@ -201,11 +216,13 @@ nodes:
         ... // issue query to the database and build an appropriate prompt with it.
         query: // send the generated prompt to the LLM
           agent: "llama3Agent"
-          inputs: [":prompt"]
+          inputs:
+            promot: ":prompt"
           isResult: true
   response: // Deliver the answer
     agent: "deliveryAgent"      
-    inputs: [:database.query.$last.content]
+    inputs:
+      text: :database.query.$last.content
 ```
 
 The databaseQuery node (which is associated "nestedAgent") takes the data from "question" node abd "projectId" node, and make them available to inner nodes (nodes of the child graph) via phantom node, "$0" and "$1". After the completion of the child graph, the data from "query" node (which has "isResult" property) becomes available as a property of the output of "database" node.
@@ -256,7 +273,8 @@ nodes:
     isResult: true
   retriever:
     agent: shift
-    inputs: [people]
+    inputs:
+      array: :people
   query:
     agent: slashgpt
     params:
@@ -265,7 +283,9 @@ nodes:
     inputs: [:retriever.item]
   reducer:
     agent: push
-    inputs: [:result, :query.content]
+    inputs:
+      array: :result
+      item: :query.content
 ```
 
 ```mermaid
@@ -353,7 +373,8 @@ This property is particularly useful when you want to continue the flow regardle
       // Receives messages from either case.
       agent: "copyAgent",
       anyInput: true,
-      inputs: [":no_tool_calls", ":tool_calls.messagesWithSecondRes"],
+      inputs: 
+        array: [":no_tool_calls", ":tool_calls.messagesWithSecondRes"],
     },
 ```
 

package/lib/graphai.d.ts

@@ -1,8 +1,7 @@
-import { AgentFunctionInfoDictionary, AgentFilterInfo, GraphData, DataSource, ResultDataDictionary, ResultData, DefaultResultData, GraphOptions, NestedDataSource } from "./type";
+import { AgentFunctionInfoDictionary, AgentFilterInfo, GraphData, DataSource, ResultDataDictionary, ResultData, DefaultResultData, GraphOptions } from "./type";
 import { TransactionLog } from "./transaction_log";
-import { ComputedNode, StaticNode } from "./node";
+import { ComputedNode, GraphNodes } from "./node";
 import { TaskManager } from "./task_manager";
-type GraphNodes = Record<string, ComputedNode | StaticNode>;
 export declare const defaultConcurrency = 8;
 export declare const graphDataLatestVersion = 0.5;
 export declare class GraphAI {
@@ -24,7 +23,8 @@ export declare class GraphAI {
     private repeatCount;
     private createNodes;
     private getValueFromResults;
-    private initializeNodes;
+    private initializeStaticNodes;
+    private updateStaticNodes;
     constructor(data: GraphData, agentFunctionInfoDictionary: AgentFunctionInfoDictionary, options?: GraphOptions);
     getAgentFunctionInfo(agentId?: string): import("./type").AgentFunctionInfo | {
         agent: () => Promise<null>;
@@ -46,8 +46,6 @@ export declare class GraphAI {
     updateLog(log: TransactionLog): void;
     transactionLogs(): TransactionLog[];
     injectValue(nodeId: string, value: ResultData, injectFrom?: string): void;
-    private nestedResultOf;
-    resultsOf(sources: NestedDataSource): Record<string, ResultData>;
+    resultsOf(inputs?: Array<any> | Record<string, any>, anyInput?: boolean): Record<string, ResultData>;
     resultOf(source: DataSource): ResultData;
 }
-export {};

package/lib/graphai.js

@@ -5,6 +5,7 @@ const node_1 = require("./node");
 const utils_1 = require("./utils/utils");
 const validator_1 = require("./validator");
 const task_manager_1 = require("./task_manager");
+const result_1 = require("./result");
 exports.defaultConcurrency = 8;
 exports.graphDataLatestVersion = 0.5;
 class GraphAI {
@@ -44,7 +45,7 @@ class GraphAI {
         return (0, utils_1.getDataFromSource)(source.nodeId ? results[source.nodeId] : undefined, source);
     }
     // for static
-    initializeNodes(previousResults) {
+    initializeStaticNodes() {
         // If the result property is specified, inject it.
         // If the previousResults exists (indicating we are in a loop),
         // process the update property (nodeId or nodeId.propId).
@@ -52,9 +53,19 @@ class GraphAI {
             const node = this.nodes[nodeId];
             if (node?.isStaticNode) {
                 const value = node?.value;
-                if (value) {
+                if (value !== undefined) {
                     this.injectValue(nodeId, value, nodeId);
                 }
+            }
+        });
+    }
+    updateStaticNodes(previousResults) {
+        // If the result property is specified, inject it.
+        // 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 update = node?.update;
                 if (update && previousResults) {
                     const result = this.getValueFromResults(update, previousResults);
@@ -95,7 +106,7 @@ class GraphAI {
         };
         (0, validator_1.validateGraphData)(data, [...Object.keys(agentFunctionInfoDictionary), ...this.bypassAgentIds]);
         this.nodes = this.createNodes(data);
-        this.initializeNodes();
+        this.initializeStaticNodes();
     }
     getAgentFunctionInfo(agentId) {
         if (agentId && this.agentFunctionInfoDictionary[agentId]) {
@@ -209,11 +220,13 @@ class GraphAI {
     processLoopIfNecessary() {
         this.repeatCount++;
         const loop = this.loop;
-        if (loop && (loop.count === undefined || this.repeatCount < loop.count)) {
-            const results = this.results(true); // results from previous loop
-            this.nodes = this.createNodes(this.data);
-            this.initializeNodes(results);
-            // Notice that we need to check the while condition *after* calling initializeNodes.
+        if (!loop) {
+            return false;
+        }
+        // We need to update static nodes, before checking the condition
+        const previousResults = this.results(true); // results from previous loop
+        this.updateStaticNodes(previousResults);
+        if (loop.count === undefined || this.repeatCount < loop.count) {
             if (loop.while) {
                 const source = (0, utils_1.parseNodeName)(loop.while, this.version);
                 const value = this.getValueFromResults(source, this.results(true));
@@ -222,6 +235,9 @@ class GraphAI {
                     return false; // while condition is not met
                 }
             }
+            this.nodes = this.createNodes(this.data);
+            this.initializeStaticNodes();
+            this.updateStaticNodes(previousResults);
             this.pushReadyNodesIntoQueue();
             return true; // Indicating that we are going to continue.
         }
@@ -252,24 +268,15 @@ class GraphAI {
             throw new Error(`injectValue with Invalid nodeId, ${nodeId}`);
         }
     }
-    nestedResultOf(source) {
-        if (Array.isArray(source)) {
-            return source.map((a) => {
-                return this.nestedResultOf(a);
-            });
+    resultsOf(inputs, anyInput = false) {
+        const results = (0, result_1.resultsOf)(inputs ?? [], this.nodes, this.version);
+        if (anyInput) {
+            return (0, result_1.cleanResult)(results);
         }
-        return this.resultOf(source);
-    }
-    resultsOf(sources) {
-        const ret = {};
-        Object.keys(sources).forEach((key) => {
-            ret[key] = this.nestedResultOf(sources[key]);
-        });
-        return ret;
+        return results;
     }
     resultOf(source) {
-        const { result } = source.nodeId ? this.nodes[source.nodeId] : { result: undefined };
-        return (0, utils_1.getDataFromSource)(result, source);
+        return (0, result_1.resultOf)(source, this.nodes);
     }
 }
 exports.GraphAI = GraphAI;

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export { GraphAI, defaultConcurrency, graphDataLatestVersion } from "./graphai";
-export { AgentFunction, AgentFunctionInfo, AgentFunctionInfoDictionary, AgentFunctionInfoSample, AgentFunctionContext, GraphData, ResultDataDictionary, ResultData, NodeState, AgentFilterFunction, AgentFilterInfo, NodeData, StaticNodeData, ComputedNodeData, DefaultResultData, DefaultInputData, } from "./type";
+export { AgentFunction, AgentFunctionInfo, AgentFunctionInfoDictionary, AgentFunctionInfoSample, AgentFunctionContext, GraphData, ResultDataDictionary, ResultData, NodeState, AgentFilterFunction, AgentFilterInfo, NodeData, StaticNodeData, ComputedNodeData, DefaultResultData, DefaultInputData, DefaultParamsType, } from "./type";
 export type { TransactionLog } from "./transaction_log";
-export { defaultAgentInfo, agentInfoWrapper, defaultTestContext, strIntentionalError, assert, sleep } from "./utils/utils";
+export { defaultAgentInfo, agentInfoWrapper, defaultTestContext, strIntentionalError, assert, sleep, isObject } from "./utils/utils";
 export { ValidationError } from "./validators/common";

package/lib/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ValidationError = exports.sleep = exports.assert = exports.strIntentionalError = exports.defaultTestContext = exports.agentInfoWrapper = exports.defaultAgentInfo = exports.NodeState = exports.graphDataLatestVersion = exports.defaultConcurrency = exports.GraphAI = void 0;
+exports.ValidationError = exports.isObject = exports.sleep = exports.assert = exports.strIntentionalError = exports.defaultTestContext = exports.agentInfoWrapper = exports.defaultAgentInfo = exports.NodeState = exports.graphDataLatestVersion = exports.defaultConcurrency = exports.GraphAI = void 0;
 var graphai_1 = require("./graphai");
 Object.defineProperty(exports, "GraphAI", { enumerable: true, get: function () { return graphai_1.GraphAI; } });
 Object.defineProperty(exports, "defaultConcurrency", { enumerable: true, get: function () { return graphai_1.defaultConcurrency; } });
@@ -14,5 +14,6 @@ Object.defineProperty(exports, "defaultTestContext", { enumerable: true, get: fu
 Object.defineProperty(exports, "strIntentionalError", { enumerable: true, get: function () { return utils_1.strIntentionalError; } });
 Object.defineProperty(exports, "assert", { enumerable: true, get: function () { return utils_1.assert; } });
 Object.defineProperty(exports, "sleep", { enumerable: true, get: function () { return utils_1.sleep; } });
+Object.defineProperty(exports, "isObject", { enumerable: true, get: function () { return utils_1.isObject; } });
 var common_1 = require("./validators/common");
 Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return common_1.ValidationError; } });

package/lib/node.d.ts

@@ -1,5 +1,5 @@
 import type { GraphAI, GraphData } from "./index";
-import { NodeDataParams, ResultData, DataSource, ComputedNodeData, StaticNodeData, NodeState, NestedDataSource } from "./type";
+import { NodeDataParams, ResultData, DataSource, ComputedNodeData, StaticNodeData, NodeState } from "./type";
 import { TransactionLog } from "./transaction_log";
 export declare class Node {
     readonly nodeId: string;
@@ -29,9 +29,9 @@ export declare class ComputedNode extends Node {
     transactionId: undefined | number;
     private readonly passThrough?;
     readonly anyInput: boolean;
-    dataSources: NestedDataSource;
+    dataSources: DataSource[];
     private inputs?;
-    inputNames?: Array<string>;
+    isNamedInputs: boolean;
     pendings: Set<string>;
     private ifSource?;
     private unlessSource?;
@@ -40,7 +40,7 @@ export declare class ComputedNode extends Node {
     readonly isComputedNode = true;
     constructor(graphId: string, nodeId: string, data: ComputedNodeData, graph: GraphAI);
     getAgentId(): string;
-    private addPengindNode;
+    private addPendingNode;
     isReadyNode(): boolean;
     private retry;
     private checkDataAvailability;
@@ -53,8 +53,10 @@ export declare class ComputedNode extends Node {
     execute(): Promise<void>;
     private prepareExecute;
     private errorProcess;
-    private getNamedInput;
+    private getParams;
     private getInputs;
+    private getContext;
+    private getResult;
     private getDebugInfo;
     private beforeConsoleLog;
     private afterConsoleLog;
@@ -68,3 +70,4 @@ export declare class StaticNode extends Node {
     constructor(nodeId: string, data: StaticNodeData, graph: GraphAI);
     injectValue(value: ResultData, injectFrom?: string): void;
 }
+export type GraphNodes = Record<string, ComputedNode | StaticNode>;

package/lib/node.js

@@ -35,7 +35,8 @@ class ComputedNode extends Node {
     constructor(graphId, nodeId, data, graph) {
         super(nodeId, graph);
         this.retryCount = 0;
-        this.dataSources = {}; // data sources.
+        this.dataSources = []; // no longer needed. This is for transaction log.
+        this.isNamedInputs = false;
         this.isStaticNode = false;
         this.isComputedNode = true;
         this.graphId = graphId;
@@ -48,33 +49,29 @@ class ComputedNode extends Node {
         this.isResult = data.isResult ?? false;
         this.priority = data.priority ?? 0;
         this.anyInput = data.anyInput ?? false;
-        if (data.inputs) {
-            if (Array.isArray(data.inputs)) {
-                this.inputs = data.inputs;
-                this.dataSources = (0, nodeUtils_1.inputs2dataSources)(data.inputs, graph.version);
-            }
-            else {
-                this.inputNames = Object.keys(data.inputs);
-                this.dataSources = (0, nodeUtils_1.namedInputs2dataSources)(data.inputs, graph.version);
-            }
+        this.inputs = data.inputs;
+        this.isNamedInputs = (0, utils_2.isObject)(data.inputs) && !Array.isArray(data.inputs);
+        this.dataSources = data.inputs ? (0, nodeUtils_1.inputs2dataSources)(data.inputs, graph.version).flat(10) : [];
+        if (data.inputs && !this.isNamedInputs) {
+            console.warn(`array inputs have been deprecated. nodeId: ${nodeId}: see https://github.com/receptron/graphai/blob/main/docs/NamedInputs.md`);
         }
-        this.pendings = new Set((0, nodeUtils_1.flatDataSourceNodeIds)(Object.values(this.dataSources)));
+        this.pendings = new Set((0, nodeUtils_1.dataSourceNodeIds)(this.dataSources));
         (0, utils_2.assert)(["function", "string"].includes(typeof data.agent), "agent must be either string or function");
         if (typeof data.agent === "string") {
             this.agentId = data.agent;
         }
         else {
             const agent = data.agent;
-            this.agentFunction = this.inputNames ? async ({ namedInputs }) => agent(namedInputs) : async ({ inputs }) => agent(...inputs);
+            this.agentFunction = this.isNamedInputs ? async ({ namedInputs }) => agent(namedInputs) : async ({ inputs }) => agent(...inputs);
         }
         if (data.graph) {
-            this.nestedGraph = typeof data.graph === "string" ? this.addPengindNode(data.graph) : data.graph;
+            this.nestedGraph = typeof data.graph === "string" ? this.addPendingNode(data.graph) : data.graph;
         }
         if (data.if) {
-            this.ifSource = this.addPengindNode(data.if);
+            this.ifSource = this.addPendingNode(data.if);
         }
         if (data.unless) {
-            this.unlessSource = this.addPengindNode(data.unless);
+            this.unlessSource = this.addPendingNode(data.unless);
         }
         this.dynamicParams = Object.keys(this.params).reduce((tmp, key) => {
             const dataSource = (0, utils_2.parseNodeName)(this.params[key], graph.version < 0.3 ? 0.3 : graph.version);
@@ -90,7 +87,7 @@ class ComputedNode extends Node {
     getAgentId() {
         return this.agentId ?? "__custom__function"; // only for display purpose in the log.
     }
-    addPengindNode(nodeId) {
+    addPendingNode(nodeId) {
         const source = (0, utils_2.parseNodeName)(nodeId, this.graph.version);
         (0, utils_2.assert)(!!source.nodeId, `Invalid data source ${nodeId}`);
         this.pendings.add(source.nodeId);
@@ -126,7 +123,7 @@ class ComputedNode extends Node {
         }
     }
     checkDataAvailability() {
-        return Object.values(this.graph.resultsOf(this.dataSources))
+        return Object.values(this.graph.resultsOf(this.inputs))
             .flat()
             .some((result) => result !== undefined);
     }
@@ -195,7 +192,7 @@ class ComputedNode extends Node {
     // 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.dataSources);
+        const previousResults = this.graph.resultsOf(this.inputs, this.anyInput);
         const transactionId = Date.now();
         this.prepareExecute(transactionId, Object.values(previousResults));
         if (this.timeout && this.timeout > 0) {
@@ -206,22 +203,7 @@ class ComputedNode extends Node {
         try {
             const agentFunction = this.agentFunction ?? this.graph.getAgentFunctionInfo(this.agentId).agent;
             const localLog = [];
-            const params = Object.keys(this.dynamicParams).reduce((tmp, key) => {
-                const result = this.graph.resultOf(this.dynamicParams[key]);
-                tmp[key] = result;
-                return tmp;
-            }, { ...this.params });
-            const context = {
-                params: params,
-                inputs: this.getInputs(previousResults),
-                namedInputs: this.getNamedInput(previousResults),
-                inputSchema: this.agentFunction ? undefined : this.graph.getAgentFunctionInfo(this.agentId)?.inputs,
-                debugInfo: this.getDebugInfo(),
-                filterParams: this.filterParams,
-                agentFilters: this.graph.agentFilters,
-                config: this.graph.config,
-                log: localLog,
-            };
+            const context = this.getContext(previousResults, 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) {
@@ -248,23 +230,13 @@ class ComputedNode extends Node {
                 return;
             }
             this.state = type_1.NodeState.Completed;
-            this.result = (() => {
-                if (result && this.passThrough) {
-                    if ((0, utils_2.isObject)(result) && !Array.isArray(result)) {
-                        return { ...result, ...this.passThrough };
-                    }
-                    else if (Array.isArray(result)) {
-                        return result.map((r) => ((0, utils_2.isObject)(r) && !Array.isArray(r) ? { ...r, ...this.passThrough } : r));
-                    }
-                }
-                return result;
-            })();
+            this.result = this.getResult(result);
             this.log.onComplete(this, this.graph, localLog);
             this.onSetResult();
             this.graph.onExecutionComplete(this);
         }
         catch (error) {
-            this.errorProcess(error, transactionId);
+            this.errorProcess(error, transactionId, previousResults);
         }
     }
     // This private method (called only by execute()) prepares the ComputedNode object
@@ -277,9 +249,10 @@ class ComputedNode extends Node {
     // 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) {
+    errorProcess(error, transactionId, namedInputs) {
         if (error instanceof Error && error.message !== utils_1.strIntentionalError) {
             console.error(`<-- NodeId: ${this.nodeId}, Agent: ${this.agentId}`);
+            console.error({ namedInputs });
             console.error(error);
             console.error("-->");
         }
@@ -295,22 +268,43 @@ class ComputedNode extends Node {
             this.retry(type_1.NodeState.Failed, Error("Unknown"));
         }
     }
-    getNamedInput(previousResults) {
-        if (this.inputNames) {
-            return this.inputNames.reduce((tmp, name) => {
-                if (!this.anyInput || previousResults[name]) {
-                    tmp[name] = previousResults[name];
-                }
-                return tmp;
-            }, {});
-        }
-        return {};
+    getParams() {
+        return Object.keys(this.dynamicParams).reduce((tmp, key) => {
+            const result = this.graph.resultOf(this.dynamicParams[key]);
+            tmp[key] = result;
+            return tmp;
+        }, { ...this.params });
     }
     getInputs(previousResults) {
-        if (this.inputNames) {
-            return [];
+        if (Array.isArray(this.inputs)) {
+            return (this.inputs ?? []).map((key) => previousResults[String(key)]).filter((a) => !this.anyInput || a);
+        }
+        return [];
+    }
+    getContext(previousResults, localLog) {
+        const context = {
+            params: this.getParams(),
+            inputs: this.getInputs(previousResults),
+            namedInputs: this.isNamedInputs ? previousResults : {},
+            inputSchema: this.agentFunction ? undefined : this.graph.getAgentFunctionInfo(this.agentId)?.inputs,
+            debugInfo: this.getDebugInfo(),
+            filterParams: this.filterParams,
+            agentFilters: this.graph.agentFilters,
+            config: this.graph.config,
+            log: localLog,
+        };
+        return context;
+    }
+    getResult(result) {
+        if (result && this.passThrough) {
+            if ((0, utils_2.isObject)(result) && !Array.isArray(result)) {
+                return { ...result, ...this.passThrough };
+            }
+            else if (Array.isArray(result)) {
+                return result.map((r) => ((0, utils_2.isObject)(r) && !Array.isArray(r) ? { ...r, ...this.passThrough } : r));
+            }
         }
-        return (this.inputs ?? []).map((key) => previousResults[String(key)]).filter((a) => !this.anyInput || a);
+        return result;
     }
     getDebugInfo() {
         return {
@@ -324,7 +318,7 @@ class ComputedNode extends Node {
     }
     beforeConsoleLog(context) {
         if (this.console.before === true) {
-            console.log(JSON.stringify(this.inputNames ? context.namedInputs : context.inputs, null, 2));
+            console.log(JSON.stringify(this.isNamedInputs ? context.namedInputs : context.inputs, null, 2));
         }
         else if (this.console.before) {
             console.log(this.console.before);

package/lib/result.d.ts

@@ -0,0 +1,6 @@
+import { DataSource, ResultData } from "./type";
+import { GraphNodes } from "./node";
+export declare const resultsOf: (inputs: Record<string, any> | Array<string>, nodes: GraphNodes, graphVersion: number) => Record<string, ResultData>;
+export declare const resultOf: (source: DataSource, nodes: GraphNodes) => ResultData;
+export declare const cleanResultInner: (results: ResultData) => ResultData | null;
+export declare const cleanResult: (results: Record<string, ResultData | undefined>) => Record<string, ResultData>;

package/lib/result.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanResult = exports.cleanResultInner = exports.resultOf = exports.resultsOf = void 0;
+const utils_1 = require("./utils/utils");
+const resultsOfInner = (input, nodes, graphVersion) => {
+    if (Array.isArray(input)) {
+        return input.map((inp) => resultsOfInner(inp, nodes, graphVersion));
+    }
+    if ((0, utils_1.isNamedInputs)(input)) {
+        return (0, exports.resultsOf)(input, nodes, graphVersion);
+    }
+    if (typeof input === "string") {
+        const templateMatch = [...input.matchAll(/\${(:[^}]+)}/g)].map((m) => m[1]);
+        if (templateMatch.length > 0) {
+            const results = resultsOfInner(templateMatch, nodes, graphVersion);
+            return Array.from(templateMatch.keys()).reduce((tmp, key) => {
+                return tmp.replaceAll("${" + templateMatch[key] + "}", results[key]);
+            }, input);
+        }
+    }
+    return (0, exports.resultOf)((0, utils_1.parseNodeName)(input, graphVersion), nodes);
+};
+const resultsOf = (inputs, nodes, graphVersion) => {
+    // for inputs. TODO remove if array input is not supported
+    if (Array.isArray(inputs)) {
+        return inputs.reduce((tmp, key) => {
+            tmp[key] = resultsOfInner(key, nodes, graphVersion);
+            return tmp;
+        }, {});
+    }
+    return Object.keys(inputs).reduce((tmp, key) => {
+        const input = inputs[key];
+        tmp[key] = (0, utils_1.isNamedInputs)(input) ? (0, exports.resultsOf)(input, nodes, graphVersion) : resultsOfInner(input, nodes, graphVersion);
+        return tmp;
+    }, {});
+};
+exports.resultsOf = resultsOf;
+const resultOf = (source, nodes) => {
+    const { result } = source.nodeId ? nodes[source.nodeId] : { result: undefined };
+    return (0, utils_1.getDataFromSource)(result, source);
+};
+exports.resultOf = resultOf;
+// clean up object for anyInput
+const cleanResultInner = (results) => {
+    if (Array.isArray(results)) {
+        return results.map((result) => (0, exports.cleanResultInner)(result)).filter((result) => !(0, utils_1.isNull)(result));
+    }
+    if ((0, utils_1.isObject)(results)) {
+        return Object.keys(results).reduce((tmp, key) => {
+            const value = (0, exports.cleanResultInner)(results[key]);
+            if (!(0, utils_1.isNull)(value)) {
+                tmp[key] = value;
+            }
+            return tmp;
+        }, {});
+    }
+    return results;
+};
+exports.cleanResultInner = cleanResultInner;
+const cleanResult = (results) => {
+    return Object.keys(results).reduce((tmp, key) => {
+        const value = (0, exports.cleanResultInner)(results[key]);
+        if (!(0, utils_1.isNull)(value)) {
+            tmp[key] = value;
+        }
+        return tmp;
+    }, {});
+};
+exports.cleanResult = cleanResult;

package/lib/transaction_log.js

@@ -44,7 +44,7 @@ class TransactionLog {
         this.state = node.state;
         this.retryCount = node.retryCount > 0 ? node.retryCount : undefined;
         this.startTime = transactionId;
-        this.inputs = (0, nodeUtils_1.flatDataSourceNodeIds)(Object.values(node.dataSources));
+        this.inputs = (0, nodeUtils_1.dataSourceNodeIds)(node.dataSources);
         this.inputsData = inputs.length > 0 ? inputs : undefined;
         graph.setLoopLog(this);
         graph.appendLog(this);

package/lib/type.d.ts

@@ -23,9 +23,6 @@ export type DataSource = {
     value?: any;
     propIds?: string[];
 };
-export type DataSources = DataSource | DataSource[] | DataSources[];
-export type NestedDataSource = Record<string, DataSources>;
-export type ResultDataSet = ResultData | ResultData[] | ResultDataSet[];
 export type StaticNodeData = {
     value: ResultData;
     update?: string;
@@ -61,6 +58,7 @@ export type GraphData = {
     loop?: LoopData;
     verbose?: boolean;
     retry?: number;
+    metadata?: any;
 };
 export type GraphOptions = {
     agentFilters?: AgentFilterInfo[] | undefined;
@@ -118,6 +116,7 @@ export type AgentFunctionInfo = {
     author: string;
     repository: string;
     license: string;
+    environmentVariables?: string[];
     stream?: boolean;
     apiKeys?: string[];
     npms?: string[];

package/lib/utils/nodeUtils.d.ts

@@ -1,5 +1,3 @@
-import { DataSource, DataSources, NestedDataSource } from "../type";
-export declare const inputs2dataSources: (inputs: string[], graphVersion: number) => Record<string, DataSource>;
-export declare const namedInputs2dataSources: (inputs: Record<string, any>, graphVersion: number) => NestedDataSource;
-export declare const flatDataSourceNodeIds: (sources: DataSource[] | DataSources[]) => string[];
-export declare const flatDataSource: (sources: DataSource[] | DataSources[]) => DataSource[];
+import { DataSource } from "../type";
+export declare const inputs2dataSources: (inputs: any, graphVersion: number) => DataSource[];
+export declare const dataSourceNodeIds: (sources: DataSource[]) => string[];

package/lib/utils/nodeUtils.js

@@ -1,49 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.flatDataSource = exports.flatDataSourceNodeIds = exports.namedInputs2dataSources = exports.inputs2dataSources = void 0;
+exports.dataSourceNodeIds = exports.inputs2dataSources = void 0;
 const utils_1 = require("./utils");
+// for dataSource
 const inputs2dataSources = (inputs, graphVersion) => {
-    return inputs.reduce((tmp, input) => {
-        tmp[input] = (0, utils_1.parseNodeName)(input, graphVersion);
-        return tmp;
-    }, {});
-};
-exports.inputs2dataSources = inputs2dataSources;
-const nestedParseNodeName = (input, graphVersion) => {
-    if (Array.isArray(input)) {
-        return input.map((inp) => nestedParseNodeName(inp, graphVersion));
+    if (Array.isArray(inputs)) {
+        return inputs.map((inp) => (0, exports.inputs2dataSources)(inp, graphVersion)).flat();
     }
-    return (0, utils_1.parseNodeName)(input, graphVersion);
-};
-const namedInputs2dataSources = (inputs, graphVersion) => {
-    return Object.keys(inputs).reduce((tmp, key) => {
-        const input = inputs[key];
-        tmp[key] = nestedParseNodeName(input, graphVersion);
-        return tmp;
-    }, {});
-};
-exports.namedInputs2dataSources = namedInputs2dataSources;
-const flatDataSourceNodeIds = (sources) => {
-    return (0, exports.flatDataSource)(sources)
-        .filter((source) => source.nodeId)
-        .map((source) => source.nodeId);
-};
-exports.flatDataSourceNodeIds = flatDataSourceNodeIds;
-const flatDataSource = (sources) => {
-    return sources
-        .map((source) => {
-        if (Array.isArray(source)) {
-            return source
-                .map((s) => {
-                if (Array.isArray(s)) {
-                    return (0, exports.flatDataSource)(s);
-                }
-                return s;
-            })
-                .flat();
+    if ((0, utils_1.isObject)(inputs)) {
+        return Object.values(inputs)
+            .map((input) => (0, exports.inputs2dataSources)(input, graphVersion))
+            .flat();
+    }
+    if (typeof inputs === "string") {
+        const templateMatch = [...inputs.matchAll(/\${(:[^}]+)}/g)].map((m) => m[1]);
+        if (templateMatch.length > 0) {
+            return (0, exports.inputs2dataSources)(templateMatch, graphVersion);
         }
-        return source;
-    })
-        .flat();
+    }
+    return (0, utils_1.parseNodeName)(inputs, graphVersion);
+};
+exports.inputs2dataSources = inputs2dataSources;
+const dataSourceNodeIds = (sources) => {
+    return sources.filter((source) => source.nodeId).map((source) => source.nodeId);
 };
-exports.flatDataSource = flatDataSource;
+exports.dataSourceNodeIds = dataSourceNodeIds;

package/lib/utils/utils.d.ts

@@ -1,8 +1,9 @@
-import { DataSource, ResultData, AgentFunction } from "../type";
+import { DataSource, ResultData, AgentFunction, DefaultInputData } from "../type";
 export declare const sleep: (milliseconds: number) => Promise<unknown>;
 export declare const parseNodeName: (inputNodeId: any, version: number) => DataSource;
 export declare function assert(condition: boolean, message: string, isWarn?: boolean): asserts condition;
 export declare const isObject: (x: unknown) => x is object;
+export declare const isNull: (data: unknown) => data is null | undefined;
 export declare const getDataFromSource: (result: ResultData | undefined, source: DataSource) => ResultData | undefined;
 export declare const strIntentionalError = "Intentional Error for Debugging";
 export declare const defaultAgentInfo: {
@@ -46,3 +47,4 @@ export declare const defaultTestContext: {
     agents: {};
     log: never[];
 };
+export declare const isNamedInputs: <NamedInput = DefaultInputData>(namedInputs: NamedInput) => boolean;

package/lib/utils/utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.defaultTestContext = exports.isLogicallyTrue = exports.debugResultKey = exports.agentInfoWrapper = exports.defaultAgentInfo = exports.strIntentionalError = exports.getDataFromSource = exports.isObject = exports.parseNodeName = exports.sleep = void 0;
+exports.isNamedInputs = exports.defaultTestContext = exports.isLogicallyTrue = exports.debugResultKey = exports.agentInfoWrapper = exports.defaultAgentInfo = exports.strIntentionalError = exports.getDataFromSource = exports.isNull = exports.isObject = exports.parseNodeName = exports.sleep = void 0;
 exports.assert = assert;
 const sleep = async (milliseconds) => {
     return await new Promise((resolve) => setTimeout(resolve, milliseconds));
@@ -52,6 +52,10 @@ const isObject = (x) => {
     return x !== null && typeof x === "object";
 };
 exports.isObject = isObject;
+const isNull = (data) => {
+    return data === null || data === undefined;
+};
+exports.isNull = isNull;
 const getNestedData = (result, propId) => {
     if (Array.isArray(result)) {
         const regex = /^\$(\d+)$/;
@@ -63,10 +67,32 @@ const getNestedData = (result, propId) => {
         if (propId === "$last") {
             return result[result.length - 1];
         }
+        if (propId === "length()") {
+            return result.length;
+        }
+        if (propId === "flat()") {
+            return result.flat();
+        }
+        const matchJoin = propId.match(/^join\(([,-])\)$/);
+        if (matchJoin && Array.isArray(matchJoin)) {
+            return result.join(matchJoin[1]);
+        }
+        // flat, join
     }
     else if ((0, exports.isObject)(result)) {
+        if (propId === "keys()") {
+            return Object.keys(result);
+        }
+        if (propId === "values()") {
+            return Object.values(result);
+        }
         return result[propId];
     }
+    else if (typeof result === "string") {
+        if (propId === "jsonParse()") {
+            return JSON.parse(result);
+        }
+    }
     return undefined;
 };
 const innerGetDataFromSource = (result, propIds) => {
@@ -166,3 +192,7 @@ exports.defaultTestContext = {
     agents: {},
     log: [],
 };
+const isNamedInputs = (namedInputs) => {
+    return (0, exports.isObject)(namedInputs) && !Array.isArray(namedInputs) && Object.keys(namedInputs || {}).length > 0;
+};
+exports.isNamedInputs = isNamedInputs;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphai",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Asynchronous data flow execution engine for agentic AI apps.",
   "main": "lib/index.js",
   "files": [
@@ -26,7 +26,7 @@
   },
   "homepage": "https://github.com/receptron/graphai#readme",
   "devDependencies": {
-    "typedoc": "^0.26.5"
+    "typedoc": "^0.26.7"
   },
   "types": "./lib/index.d.ts",
   "directories": {