graphai 0.1.0 → 0.1.2

package/README.md

@@ -2,45 +2,57 @@
 
 ## Overview
 
-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.
+GraphAI is an asynchronous data flow execution engine, which makes it easy to build *agentic* applications, which perform the orchestration of mutiple "AI agents". 
 
-You just need to describe dependencies among those API calls in a single data flow graph, create a GraphAI object with that graph, and run it.
+*Agentic* applications need to make asynchronous API calls (such as OpenAI's chat-completion API, database query, web search, and etc.) multiple times and manage data dependencies among them, such as giving the answer from one LLM call to another LLM call as a prompt -- which will become quite difficult to manage in a traditional programing style as the complexity of the application increases, because of the asynchronous nature of those APIs.
 
-Here is an example:
+GraphAI allows developers to describe dependencies among those API calls in a single data flow graph (either in YAML or JSON), create a GraphAI instance with that graph, and let it run. The GraphAI engine will take care of all the complexity of concurrent asynchronous calls, data dependency management, error handling, retries and logging. 
+
+Here is an example graph, which uses the Wikipedia as the data source and perform an in-memory RAG.
 
 ```YAML
-agentId: sample
 nodes:
-  taskA:
+  source: // Input data to this RAG application
+    value:
+      name: Sam Bankman-Fried
+      query: describe the final sentence by the court for Sam Bank-Fried
+  wikipedia: // Retrieve data from Wikipedia。
+    agentId: wikipediaAgent
+    inputs: [source.name]
+  chunks: // Break the text from Wikipedia into chunks(2048 character each with 512 overlap）
+    agentId: stringSplitterAgent
+    inputs: [wikipedia]
+  chunkEmbeddings: // Get embedding vector of each chunk
+    agentId: stringEmbeddingsAgent
+    inputs: [chunks]
+  topicEmbedding: // Get embedding vector of the question
+    agentId: stringEmbeddingsAgent
+    inputs: [source.query]
+  similarities: // Calculate the cosine similarity of each chunk
+    agentId: dotProductAgent
+    inputs: [chunkEmbeddings, topicEmbedding]
+  sortedChunks: // Sort chunks based on the similarity
+    agentId: sortByValuesAgent
+    inputs: [chunks, similarities]
+  referenceText: // Concatenate chunks up to the token limit (5000)
+    agentId: tokenBoundStringsAgent
+    inputs: [sortedChunks]
     params:
-      // agent-specific parameters for taskA
-  taskB:
+      limit: 5000
+  prompt: // Generate a prompt with that reference text
+    agentId: stringTemplateAgent
+    inputs: [source, referenceText]
     params:
-      // agent-specific parameters for taskB
-  taskC:
+      template: |-
+        Using the following document, ${0}
+        ${1}
+  query: // retrieves the answer from GPT3.5
+    agentId: slashGPTAgent
     params:
-      // agent-specific parameters for taskC
-    inputs: [taskA, taskB]
-```
-
-``` TypeScript
-const sampleAgentFunction = async (context: AgentFunctionContext) => {
-  const { 
-    nodeId, // taskA, taskB or taskC 
-    params, // agent-specific parameters specified in the graph definition file
-    inputs // inputs from previous nodes
-  } = context;
-  // Agent-specific code (such as calling OpenAI's chat.completions API)
-  ...
-  return result;
-}
-
-  ...
-  const file = fs.readFileSync(pathToYamlFile, "utf8");
-  const graphData = YAML.parse(file);
-  const graph = new GraphAI(graphData, { sample: sampleAgentFunction });
-  const results = await graph.run();
-  return results["taskC"];
+      manifest:
+        model: gpt-3.5-turbo
+    isResult: true // indicating this is the final result
+    inputs: [prompt]
 ```
 
 ## Background
@@ -115,7 +127,7 @@ 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 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.
+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, anyInput, 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").
 
@@ -123,7 +135,6 @@ Connections between nodes will be established by references from one not to anot
 
 - '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.
 
 ```
@@ -171,6 +182,7 @@ 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. 
+- 'anyInput': An optiona boolean flag, which indicates that the associated *agent function* will be called when at least one of input data became available. Otherwise, it will wait until all the data became available.
 - '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 property to the associated agent function, which are agent specific.
@@ -178,7 +190,7 @@ A *computed node* have following properties.
 
 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).
+- 'value': An **required** property, which specifies the initial 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
@@ -209,7 +221,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```
+### ```injectValue(nodeId: string, result: ResultData): void```
 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 static node into which the result is to be injected.

package/lib/experimental_agents/array_agents/index.d.ts

@@ -0,0 +1,3 @@
+export { pushAgent } from "../../experimental_agents/array_agents/push_agent";
+export { popAgent } from "../../experimental_agents/array_agents/pop_agent";
+export { shiftAgent } from "../../experimental_agents/array_agents/shift_agent";

package/lib/experimental_agents/array_agents/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shiftAgent = exports.popAgent = exports.pushAgent = void 0;
+var push_agent_1 = require("../../experimental_agents/array_agents/push_agent");
+Object.defineProperty(exports, "pushAgent", { enumerable: true, get: function () { return push_agent_1.pushAgent; } });
+var pop_agent_1 = require("../../experimental_agents/array_agents/pop_agent");
+Object.defineProperty(exports, "popAgent", { enumerable: true, get: function () { return pop_agent_1.popAgent; } });
+var shift_agent_1 = require("../../experimental_agents/array_agents/shift_agent");
+Object.defineProperty(exports, "shiftAgent", { enumerable: true, get: function () { return shift_agent_1.shiftAgent; } });

package/lib/experimental_agents/array_agents/pop_agent.d.ts

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

package/lib/experimental_agents/array_agents/pop_agent.js

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

package/lib/experimental_agents/array_agents/push_agent.d.ts

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

package/lib/experimental_agents/array_agents/push_agent.js

@@ -0,0 +1,14 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+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;

package/lib/experimental_agents/array_agents/shift_agent.d.ts

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

package/lib/experimental_agents/{array_agents.js → array_agents/shift_agent.js}

@@ -3,27 +3,12 @@ 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;
+exports.shiftAgent = 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
+    // TODO: Validation
     const item = array.shift();
     return { array, item };
 };

package/lib/experimental_agents/data_agents/data_object_merge_template_agent.d.ts

@@ -0,0 +1,28 @@
+import { AgentFunction } from "../../graphai";
+export declare const dataObjectMergeTemplateAgent: AgentFunction;
+declare const dataObjectMergeTemplateAgentInfo: {
+    name: string;
+    agent: AgentFunction;
+    mock: AgentFunction;
+    samples: {
+        inputs: ({
+            a: number;
+            b: number;
+            c?: undefined;
+        } | {
+            a: number;
+            b: number;
+            c: number;
+        })[];
+        params: {};
+        result: {
+            a: number;
+            b: number;
+        };
+    }[];
+    description: string;
+    author: string;
+    repository: string;
+    license: string;
+};
+export default dataObjectMergeTemplateAgentInfo;

package/lib/experimental_agents/data_agents/data_object_merge_template_agent.js

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataObjectMergeTemplateAgent = void 0;
+const deepmerge_1 = __importDefault(require("deepmerge"));
+const dataObjectMergeTemplateAgent = async ({ inputs }) => {
+    return inputs.reduce((tmp, input) => {
+        return (0, deepmerge_1.default)(tmp, input);
+    }, {});
+};
+exports.dataObjectMergeTemplateAgent = dataObjectMergeTemplateAgent;
+// for test and document
+const sampleInputs = [
+    { a: 1, b: 1 },
+    { a: 2, b: 2 },
+    { a: 3, b: 0, c: 5 },
+];
+const sampleParams = {};
+const sampleResult = { a: 6, b: 3 };
+const dataObjectMergeTemplateAgentInfo = {
+    name: "dataObjectMergeTemplateAgent",
+    agent: exports.dataObjectMergeTemplateAgent,
+    mock: exports.dataObjectMergeTemplateAgent,
+    samples: [
+        {
+            inputs: sampleInputs,
+            params: sampleParams,
+            result: sampleResult,
+        },
+    ],
+    description: "Merge object",
+    author: "Satoshi Nakajima",
+    repository: "https://github.com/receptron/graphai",
+    license: "MIT",
+};
+exports.default = dataObjectMergeTemplateAgentInfo;

package/lib/experimental_agents/data_agents/data_sum_template_agent.d.ts

@@ -0,0 +1,17 @@
+import { AgentFunction } from "../../graphai";
+export declare const dataSumTemplateAgent: AgentFunction<Record<string, any>, number, number>;
+declare const dataSumTemplateAgentInfo: {
+    name: string;
+    agent: AgentFunction<Record<string, any>, number, number>;
+    mock: AgentFunction<Record<string, any>, number, number>;
+    samples: {
+        inputs: number[];
+        params: {};
+        result: number;
+    }[];
+    description: string;
+    author: string;
+    repository: string;
+    license: string;
+};
+export default dataSumTemplateAgentInfo;

package/lib/experimental_agents/data_agents/data_sum_template_agent.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataSumTemplateAgent = void 0;
+const dataSumTemplateAgent = async ({ inputs }) => {
+    return inputs.reduce((tmp, input) => {
+        return tmp + input;
+    }, 0);
+};
+exports.dataSumTemplateAgent = dataSumTemplateAgent;
+// for test and document
+const sampleInputs = [1, 2, 3];
+const sampleParams = {};
+const sampleResult = 6;
+const dataSumTemplateAgentInfo = {
+    name: "dataSumTemplateAgent",
+    agent: exports.dataSumTemplateAgent,
+    mock: exports.dataSumTemplateAgent,
+    samples: [
+        {
+            inputs: sampleInputs,
+            params: sampleParams,
+            result: sampleResult,
+        },
+    ],
+    description: "Returns the sum of input values",
+    author: "Satoshi Nakajima",
+    repository: "https://github.com/receptron/graphai",
+    license: "MIT",
+};
+exports.default = dataSumTemplateAgentInfo;

package/lib/experimental_agents/data_agents/index.d.ts

@@ -0,0 +1,3 @@
+export { totalAgent } from "../../experimental_agents/data_agents/total_agent";
+export { dataObjectMergeTemplateAgent } from "../../experimental_agents/data_agents/data_object_merge_template_agent";
+export { dataSumTemplateAgent } from "../../experimental_agents/data_agents/data_sum_template_agent";

package/lib/experimental_agents/data_agents/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataSumTemplateAgent = exports.dataObjectMergeTemplateAgent = exports.totalAgent = void 0;
+var total_agent_1 = require("../../experimental_agents/data_agents/total_agent");
+Object.defineProperty(exports, "totalAgent", { enumerable: true, get: function () { return total_agent_1.totalAgent; } });
+var data_object_merge_template_agent_1 = require("../../experimental_agents/data_agents/data_object_merge_template_agent");
+Object.defineProperty(exports, "dataObjectMergeTemplateAgent", { enumerable: true, get: function () { return data_object_merge_template_agent_1.dataObjectMergeTemplateAgent; } });
+var data_sum_template_agent_1 = require("../../experimental_agents/data_agents/data_sum_template_agent");
+Object.defineProperty(exports, "dataSumTemplateAgent", { enumerable: true, get: function () { return data_sum_template_agent_1.dataSumTemplateAgent; } });

package/lib/experimental_agents/data_agents/total_agent.d.ts

@@ -0,0 +1,46 @@
+import { AgentFunction } from "../../graphai";
+export declare const totalAgent: AgentFunction<Record<never, never>, Record<string, number>>;
+declare const totalAgentInfo: {
+    name: string;
+    agent: AgentFunction<Record<never, never>, Record<string, number>>;
+    mock: AgentFunction<Record<never, never>, Record<string, number>>;
+    samples: ({
+        inputs: {
+            a: number;
+        }[];
+        params: {};
+        result: {
+            a: number;
+        };
+    } | {
+        inputs: (({
+            a: number;
+            b: number;
+            c?: undefined;
+        } | {
+            c: number;
+            a?: undefined;
+            b?: undefined;
+        })[] | ({
+            a: number;
+            b: number;
+            d?: undefined;
+        } | {
+            d: number;
+            a?: undefined;
+            b?: undefined;
+        })[])[];
+        params: {};
+        result: {
+            a: number;
+            b: number;
+            c: number;
+            d: number;
+        };
+    })[];
+    description: string;
+    author: string;
+    repository: string;
+    license: string;
+};
+export default totalAgentInfo;

package/lib/experimental_agents/data_agents/total_agent.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.totalAgent = void 0;
+const totalAgent = async ({ inputs }) => {
+    return inputs.reduce((result, input) => {
+        const inputArray = Array.isArray(input) ? input : [input];
+        inputArray.forEach((innerInput) => {
+            Object.keys(innerInput).forEach((key) => {
+                const value = innerInput[key];
+                if (result[key]) {
+                    result[key] += value;
+                }
+                else {
+                    result[key] = value;
+                }
+            });
+        });
+        return result;
+    }, {});
+};
+exports.totalAgent = totalAgent;
+// for test and document
+const sampleInputs = [{ a: 1 }, { a: 2 }, { a: 3 }];
+const sampleParams = {};
+const sampleResult = { a: 6 };
+const sample2Inputs = [[{ a: 1, b: -1 }, { c: 10 }], [{ a: 2, b: -1 }], [{ a: 3, b: -2 }, { d: -10 }]];
+const sample2Params = {};
+const sample2Result = { a: 6, b: -4, c: 10, d: -10 };
+//
+const totalAgentInfo = {
+    name: "totalAgent",
+    agent: exports.totalAgent,
+    mock: exports.totalAgent,
+    samples: [
+        {
+            inputs: sampleInputs,
+            params: sampleParams,
+            result: sampleResult,
+        },
+        {
+            inputs: sample2Inputs,
+            params: sample2Params,
+            result: sample2Result,
+        },
+    ],
+    description: "Returns the sum of input values",
+    author: "Satoshi Nakajima",
+    repository: "https://github.com/snakajima/graphai",
+    license: "MIT",
+};
+exports.default = totalAgentInfo;

package/lib/experimental_agents/embedding_agent.d.ts

@@ -0,0 +1,6 @@
+import { AgentFunction } from "../graphai";
+export declare const stringEmbeddingsAgent: AgentFunction<{
+    model?: string;
+}, {
+    contents: any;
+}, Array<string> | string>;

package/lib/experimental_agents/embedding_agent.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringEmbeddingsAgent = void 0;
+const defaultEmbeddingModel = "text-embedding-3-small";
+const OpenAI_embedding_API = "https://api.openai.com/v1/embeddings";
+// This agent retrieves embedding vectors for an array of strings using OpenAI's API
+//
+// Parameters:
+//   model: Specifies the model (default is "text-embedding-3-small")
+// Inputs:
+//   inputs[0]: Array<string>
+// Result:
+//   contents: Array<Array<number>>
+//
+const stringEmbeddingsAgent = async ({ params, inputs }) => {
+    const input = inputs[0];
+    const sources = Array.isArray(input) ? input : [input];
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        throw new Error("OPENAI_API_KEY key is not set in environment variables.");
+    }
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+    };
+    const response = await fetch(OpenAI_embedding_API, {
+        method: "POST",
+        headers: headers,
+        body: JSON.stringify({
+            input: sources,
+            model: params?.model ?? defaultEmbeddingModel,
+        }),
+    });
+    const jsonResponse = await response.json();
+    if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    const embeddings = jsonResponse.data.map((object) => {
+        return object.embedding;
+    });
+    return { contents: embeddings };
+};
+exports.stringEmbeddingsAgent = stringEmbeddingsAgent;

package/lib/experimental_agents/index.d.ts

@@ -1,6 +1,11 @@
-export * from "./string_agent";
+export * from "./string_agents";
 export * from "./slashgpt_agent";
-export * from "./sleeper_agent";
-export * from "./data_agent";
+export * from "./sleeper_agents";
+export * from "./data_agents";
 export * from "./nested_agent";
 export * from "./array_agents";
+export * from "./embedding_agent";
+export * from "./matrix_agents";
+export * from "./token_agent";
+export * from "./test_agents";
+export * from "./map_agent";

package/lib/experimental_agents/index.js

@@ -14,9 +14,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./string_agent"), exports);
+__exportStar(require("./string_agents"), exports);
 __exportStar(require("./slashgpt_agent"), exports);
-__exportStar(require("./sleeper_agent"), exports);
-__exportStar(require("./data_agent"), exports);
+__exportStar(require("./sleeper_agents"), exports);
+__exportStar(require("./data_agents"), exports);
 __exportStar(require("./nested_agent"), exports);
 __exportStar(require("./array_agents"), exports);
+__exportStar(require("./embedding_agent"), exports);
+__exportStar(require("./matrix_agents"), exports);
+__exportStar(require("./token_agent"), exports);
+__exportStar(require("./test_agents"), exports);
+__exportStar(require("./map_agent"), exports);

package/lib/experimental_agents/map_agent.d.ts

@@ -0,0 +1,4 @@
+import { AgentFunction } from "../graphai";
+export declare const mapAgent: AgentFunction<{
+    injectionTo?: string;
+}, Record<string, Array<any>>, any>;

package/lib/experimental_agents/map_agent.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapAgent = void 0;
+const graphai_1 = require("../graphai");
+const utils_1 = require("../utils/utils");
+const mapAgent = async ({ params, inputs, agents, log, taskManager, graphData }) => {
+    if (taskManager) {
+        const status = taskManager.getStatus();
+        (0, utils_1.assert)(status.concurrency > status.running, `mapAgent: Concurrency is too low: ${status.concurrency}`);
+    }
+    (0, utils_1.assert)(graphData !== undefined, "mapAgent: graphData is required");
+    const input = Array.isArray(inputs[0]) ? inputs[0] : inputs;
+    const injectionTo = params.injectionTo ?? "$0";
+    if (graphData.nodes[injectionTo] === undefined) {
+        // If the input node does not exist, automatically create a static node
+        graphData.nodes[injectionTo] = { value: {} };
+    }
+    const graphs = input.map((data) => {
+        const graphAI = new graphai_1.GraphAI(graphData, agents || {}, taskManager);
+        graphAI.injectValue(injectionTo, data, "__mapAgent_inputs__");
+        return graphAI;
+    });
+    const runs = graphs.map((graph) => {
+        return graph.run(false);
+    });
+    const results = await Promise.all(runs);
+    const nodeIds = Object.keys(results[0]);
+    (0, utils_1.assert)(nodeIds.length > 0, "mapAgent: no return values (missing isResult)");
+    const compositeResult = nodeIds.reduce((tmp, nodeId) => {
+        tmp[nodeId] = results.map((result) => {
+            return result[nodeId];
+        });
+        return tmp;
+    }, {});
+    if (log) {
+        const logs = graphs.map((graph, index) => {
+            return graph.transactionLogs().map((log) => {
+                log.mapIndex = index;
+                return log;
+            });
+        });
+        log.push(...logs.flat());
+    }
+    return compositeResult;
+};
+exports.mapAgent = mapAgent;

package/lib/experimental_agents/matrix_agents/dot_product_agent.d.ts

@@ -0,0 +1,4 @@
+import { AgentFunction } from "../../graphai";
+export declare const dotProductAgent: AgentFunction<Record<string, any>, {
+    contents: Array<number>;
+}, Array<Array<number>>>;

package/lib/experimental_agents/matrix_agents/dot_product_agent.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dotProductAgent = void 0;
+// This agent calculates the dot product of an array of vectors (A[]) and a vector (B),
+// typically used to calculate cosine similarity of embedding vectors.
+// Inputs:
+//  inputs[0]: Two dimentional array of numbers.
+//  inputs[1]: Two dimentional array of numbers (but the array size is 1 for the first dimention)
+// Outputs:
+//  { contents: Array<number> } // array of docProduct of each vector (A[]) and vector B
+const dotProductAgent = async ({ inputs }) => {
+    const embeddings = inputs[0];
+    const reference = inputs[1][0];
+    if (embeddings[0].length != reference.length) {
+        throw new Error("dotProduct: Length of vectors do not match.");
+    }
+    const contents = embeddings.map((embedding) => {
+        return embedding.reduce((dotProduct, value, index) => {
+            return dotProduct + value * reference[index];
+        }, 0);
+    });
+    return { contents };
+};
+exports.dotProductAgent = dotProductAgent;

package/lib/experimental_agents/matrix_agents/index.d.ts

@@ -0,0 +1,2 @@
+export { dotProductAgent } from "../../experimental_agents/matrix_agents/dot_product_agent";
+export { sortByValuesAgent } from "../../experimental_agents/matrix_agents/sort_by_values_agent";

package/lib/experimental_agents/matrix_agents/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sortByValuesAgent = exports.dotProductAgent = void 0;
+var dot_product_agent_1 = require("../../experimental_agents/matrix_agents/dot_product_agent");
+Object.defineProperty(exports, "dotProductAgent", { enumerable: true, get: function () { return dot_product_agent_1.dotProductAgent; } });
+var sort_by_values_agent_1 = require("../../experimental_agents/matrix_agents/sort_by_values_agent");
+Object.defineProperty(exports, "sortByValuesAgent", { enumerable: true, get: function () { return sort_by_values_agent_1.sortByValuesAgent; } });

package/lib/experimental_agents/matrix_agents/sort_by_values_agent.d.ts

@@ -0,0 +1,6 @@
+import { AgentFunction } from "../../graphai";
+export declare const sortByValuesAgent: AgentFunction<{
+    assendant?: boolean;
+}, {
+    contents: Array<any>;
+}, Array<any>>;