graphai 0.0.10 → 0.0.12

package/README.md

@@ -52,16 +52,103 @@ GraphAI is designed to simplify this process by decoupling the complexity of mul
 
 Furthermore, GraphAI's robust mechanisms for error handling, retry strategies, timeouts, and logging empower developers to concentrate on refining the application logic.
 
+## Quick Install
+
+```
+npm install graphai
+```
+
+or
+
+```
+yarn add graphai
+```
+
+## Collaboration
+
+Step 1. Install git, node and yarn
+
+Step 2. Clone the project and install necessary node modules
+
+```
+git clone git@github.com:snakajima/graphai.git
+cd graphai
+yarn install
+```
+
+Step 3. Set the environment variable OPENAI_API_KEY to your own key (=sk-...)
+
+You need to set ANTHROPIC_API_KEY as well, if you want to use Claude.
+
+Step 4. Run the test script
+
+Start web server for http agent
+
+```
+cd tests/http-server/docs/
+npx http-server
+```
+
+then run the test
+
+```
+npm run test
+```
+
+Step 5. Run one of sample scripts
+
+```
+npm run sample ./samples/home.ts
+```
+
+Step 6. Write some code and send pull requests
+
+Key principles:
+
+1. Keep the core (Node and GraphAI classes) small and simple.
+2. Enhance the platform by adding 'agents' (plug ins).
+3. Simple but effective test scripts make it easy to maintain.
+4. Run "npm run format" before submitting pull requests. 
+
 ## Data Flow Graph
 
 A Data Flow Graph (DFG) is a JavaScript object, which defines the flow of data. It is typically described in YAML file and loaded at runtime.
 
-A DFG consists of a collection of 'nodes', which contains a series of nested keys representing individual nodes in the data flow. Each node is identified by a unique key (e.g., node1, node2) and can contain several predefined keys (params, inputs, outputs, retry, timeout, source, agentId, result, fork) that dictate the node's behavior and its relationship with other nodes.
+A DFG consists of a collection of 'nodes', which contains a series of nested keys representing individual nodes in the data flow. Each node is identified by a unique key (e.g., node1, node2) and can contain several predefined keys (params, inputs, outputs, retry, timeout, source, agentId, fork, value) that dictate the node's behavior and its relationship with other nodes.
 
 ### DFG Structure
 
 - 'nodes': A list of node. Required.
 - 'concurrency': An optional property, which specifies the maximum number of concurrent operations (agent functions to be executed at the same time). The default is 8.
+- 'agentId': An optional property, which specifies the default agent for all the nodes.
+- 'loop': An optional property, which specifies if the graph needs to be executed multiple times. The loop is an JavaScript object, which has two optinoal properties. The *count* property specifies the number of times the graph needs to be executed and the *while* property specifies the condition required to contineu the loop in the form of node name (nodeId) or its property (nodeId.propId). Unlike JavaScript, an empty array will be treated as false.
+
+```
+loop:
+  while: people
+nodes:
+  people:
+    value:
+      - Steve Jobs
+      - Elon Musk
+      - Nikola Tesla
+    next: retriever.array
+  result:
+    value: []
+    next: reducer
+  retriever:
+    agentId: shift
+    inputs: [people]
+  query:
+    agentId: slashgpt
+    params:
+      manifest:
+        prompt: 指定した人について日本語で４００字以内で答えて
+    inputs: [retriever.item]
+  reducer:
+    agentId: push
+    inputs: [result, query.content]
+```
 
 ## Agent
 
@@ -75,19 +162,26 @@ An agent function receives two set of parameters via AgentFunctionContext, agent
 
 ## Node Structure
 
-- 'inputs': An optional list of node identifiers that the current node depends on. This establishes a flow where the current node can only be executed after the completion of the nodes listed under 'inputs'. If this list is empty and the 'source' property is not set, the associated Agent Function will be immediatley executed. 
-- 'source': An optional flag, which specifies if the node is a 'source node' or not. A souce node is a special node, which receives data from either an external code (via GraphAI's injectResult method) or from a 'dispatcher node'.
-- 'result': An optional object, which injects the result into the source node (equivalent to calling the injectResult method).
+There are two types of Node, *computed nodes* and *static nodes*. A *computed node* is associated with an *agent function*, which receives some inputs, performs some computations asynchronously then returns the result (output). A *static node* is a placeholder of a value (just like a variable in programming language), which is injected by an external program, or is retrived from a *data source* (in case of interations). 
+
+A *computed node* have following properties.
+
+- 'agentId': An **required** property, which specifies the id of the *agent function*.
+- 'inputs': An optional list of *data sources* that the current node depends on. This establishes a flow where the current node can only be executed after the completion of the nodes listed under 'inputs'. If this list is empty, the associated *agent function* will be immediatley executed. 
 - 'retry': An optional number, which specifies the maximum number of retries to be made. If the last attempt fails, that return value will be recorded.
 - 'timeout': An optional number, which specifies the maximum waittime in msec. If the associated agent function does not return the value in time, the "Timeout" error will be recorded and the returned value will be discarded. 
-- 'params': An optional parameters to the associated agent function, which are agent specific.
-- 'agentId': An optional parameter, which specifies the id of the agent, when the graph is associated with multiple agents.
+- 'params': An optional property to the associated agent function, which are agent specific.
 - 'fork': An optional paramter, which specifies the number of concurrent transactions to be created for the current node.
-- 'outputs': An optinal property, which specifies the mapping from outputId to nodeId. If this property is set, the node become a special node called "dispatcher". A dispatcher node injects result(s) into specified nodes, enabling the dynamic flow of data.
+- 'outputs' (MAY BECOME OBSOLETE): An optinal property, which specifies the mapping from outputId to nodeId. If this property is set, the node become a special node called *dispatcher*. A *dispatcher* node injects result(s) into specified static nodes, enabling the dynamic flow of data.
+
+A *static* node have following properties.
+
+- 'value': An optional property, which specifies the value of this static node (equivalent to calling the injectValue method from outside).
+- 'next': An optional property, which specifies the *data source* after each iteration.
 
 ## GraphAI class
 
-### ```constructor(data: GraphData, callbackDictonary: AgentFunctionDictonary | AgentFunction<any, any, any>)```
+### ```constructor(data: GraphData, callbackDictonary: AgentFunctionDictonary)```
 Initializes a new instance of the GraphAI class with the specified graph data and a dictionary of callback functions.
 
 - ```data: GraphData```: The graph data including nodes and optional concurrency limit.
@@ -114,7 +208,7 @@ Retrieves all transaction logs recorded during the execution of the graph.
 Returns: An array of transaction logs detailing the execution states and outcomes of the nodes within the graph.
 
 ### ```injectResult(nodeId: string, result: ResultData): void```
-Injects a result into a specified node. This is used to manually set the result of a source node, allowing dependent nodes to proceed with execution.
+Injects a result into a specified node. This is used to manually set the result of a static node, allowing dependent nodes to proceed with execution.
 
-- ```nodeId: string```: The ID of the source node into which the result is to be injected.
+- ```nodeId: string```: The ID of the static node into which the result is to be injected.
 - ```result: ResultData```: The result to be injected into the specified node.

package/lib/experimental_agents/array_agents.d.ts

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

package/lib/experimental_agents/array_agents.js

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

package/lib/experimental_agents/data_agent.d.ts

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

package/lib/experimental_agents/data_agent.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataSumTemplateAgent = exports.dataObjectMergeTemplateAgent = void 0;
+const deepmerge_1 = __importDefault(require("deepmerge"));
+const dataObjectMergeTemplateAgent = async ({ nodeId, params, inputs, verbose }) => {
+    if (verbose) {
+        console.log("executing", nodeId, params);
+    }
+    return inputs.reduce((tmp, input) => {
+        return (0, deepmerge_1.default)(tmp, input);
+    }, {});
+};
+exports.dataObjectMergeTemplateAgent = dataObjectMergeTemplateAgent;
+const dataSumTemplateAgent = async ({ nodeId, params, inputs, verbose }) => {
+    if (verbose) {
+        console.log("executing", nodeId, params);
+    }
+    return inputs.reduce((tmp, input) => {
+        return tmp + input;
+    }, 0);
+};
+exports.dataSumTemplateAgent = dataSumTemplateAgent;

package/lib/experimental_agents/index.d.ts

@@ -1,2 +1,6 @@
 export * from "./string_agent";
 export * from "./slashgpt_agent";
+export * from "./sleeper_agent";
+export * from "./data_agent";
+export * from "./nested_agent";
+export * from "./array_agents";

package/lib/experimental_agents/index.js

@@ -16,3 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./string_agent"), exports);
 __exportStar(require("./slashgpt_agent"), exports);
+__exportStar(require("./sleeper_agent"), exports);
+__exportStar(require("./data_agent"), exports);
+__exportStar(require("./nested_agent"), exports);
+__exportStar(require("./array_agents"), exports);

package/lib/experimental_agents/nested_agent.d.ts

@@ -0,0 +1,6 @@
+import { GraphData, AgentFunction } from "../graphai";
+export declare const nestedAgent: AgentFunction<{
+    graph: GraphData;
+    nodeId: string;
+    inputNodes?: Array<string>;
+}>;

package/lib/experimental_agents/nested_agent.js

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

package/lib/experimental_agents/slashgpt_agent.js

@@ -7,17 +7,22 @@ exports.slashGPTAgent = void 0;
 const path_1 = __importDefault(require("path"));
 const slashgpt_1 = require("slashgpt");
 const config = new slashgpt_1.ChatConfig(path_1.default.resolve(__dirname));
-const slashGPTAgent = async (context) => {
-    console.log("executing", context.nodeId, context.params);
-    const session = new slashgpt_1.ChatSession(config, context.params.manifest ?? {});
-    const query = context.params?.query ? [context.params.query] : [];
-    const contents = query.concat(context.inputs.map((input) => {
+const slashGPTAgent = async ({ nodeId, params, inputs, verbose }) => {
+    if (verbose) {
+        console.log("executing", nodeId, params);
+    }
+    const session = new slashgpt_1.ChatSession(config, params.manifest ?? {});
+    const query = params?.query ? [params.query] : [];
+    const contents = query.concat(inputs.map((input) => {
+        if (typeof input === "string") {
+            return input;
+        }
         return input.content;
     }));
     session.append_user_question(contents.join("\n"));
     await session.call_loop(() => { });
     const message = (() => {
-        if (context.params?.function_result) {
+        if (params?.function_result) {
             return session.history.messages().find((m) => m.role === "function_result");
         }
         return session.history.last_message();

package/lib/experimental_agents/sleeper_agent.d.ts

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

package/lib/experimental_agents/sleeper_agent.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sleeperAgentDebug = exports.sleeperAgent = void 0;
+const utils_1 = require("../utils/utils");
+const deepmerge_1 = __importDefault(require("deepmerge"));
+const sleeperAgent = async (context) => {
+    const { params, inputs } = context;
+    await (0, utils_1.sleep)(params.duration);
+    return inputs.reduce((result, input) => {
+        return (0, deepmerge_1.default)(result, input);
+    }, params.value ?? {});
+};
+exports.sleeperAgent = sleeperAgent;
+const sleeperAgentDebug = async (context) => {
+    const { nodeId, params, inputs, retry } = context;
+    await (0, utils_1.sleep)(params.duration / (retry + 1));
+    if (params.fail && retry < 2) {
+        console.log("failed (intentional)", nodeId, retry);
+        throw new Error("Intentional Failure");
+    }
+    return inputs.reduce((result, input) => {
+        return (0, deepmerge_1.default)(result, input);
+    }, params.value ?? {});
+};
+exports.sleeperAgentDebug = sleeperAgentDebug;

package/lib/experimental_agents/string_agent.js

@@ -1,11 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stringTemplateAgent = void 0;
-const stringTemplateAgent = async (context) => {
-    console.log("executing", context.nodeId, context.params);
-    const content = context.inputs.reduce((template, input, index) => {
-        return template.replace("${" + index + "}", input[context.params.inputKey ?? "content"]);
-    }, context.params.template);
+// see example
+//  tests/agents/test_string_agent.ts
+const stringTemplateAgent = async ({ nodeId, params, inputs, verbose }) => {
+    if (verbose) {
+        console.log("executing", nodeId, params);
+    }
+    const content = inputs.reduce((template, input, index) => {
+        return template.replace("${" + index + "}", input[params.inputKey ?? "content"]);
+    }, params.template);
     return { content };
 };
 exports.stringTemplateAgent = stringTemplateAgent;

package/lib/graphai.d.ts

@@ -18,38 +18,51 @@ type NodeData = {
     agentId?: string;
     fork?: number;
     source?: boolean;
-    result?: ResultData;
+    value?: ResultData;
+    next?: string;
     outputs?: Record<string, string>;
 };
+type LoopData = {
+    count?: number;
+    while?: string;
+};
 export type GraphData = {
+    agentId?: string;
     nodes: Record<string, NodeData>;
     concurrency?: number;
+    loop?: LoopData;
+    verbose?: boolean;
 };
 export type TransactionLog = {
     nodeId: string;
     state: NodeState;
     startTime: number;
     endTime?: number;
-    retryCount: number;
+    retryCount?: number;
     agentId?: string;
     params?: NodeDataParams;
     inputs?: Array<ResultData>;
     errorMessage?: string;
     result?: ResultData;
+    log?: TransactionLog[];
 };
-export type AgentFunctionContext<ParamsType, ResultType, PreviousResultType> = {
+export type AgentFunctionContext<ParamsType, PreviousResultType> = {
     nodeId: string;
     forkIndex?: number;
     retry: number;
     params: NodeDataParams<ParamsType>;
     inputs: Array<PreviousResultType>;
+    verbose: boolean;
+    agents: CallbackDictonaryArgs;
+    log: TransactionLog[];
 };
-export type AgentFunction<ParamsType = Record<string, any>, ResultType = Record<string, any>, PreviousResultType = Record<string, any>> = (context: AgentFunctionContext<ParamsType, ResultType, PreviousResultType>) => Promise<ResultData<ResultType>>;
+export type AgentFunction<ParamsType = Record<string, any>, ResultType = Record<string, any>, PreviousResultType = Record<string, any>> = (context: AgentFunctionContext<ParamsType, PreviousResultType>) => Promise<ResultData<ResultType>>;
 export type AgentFunctionDictonary = Record<string, AgentFunction<any, any, any>>;
 declare class Node {
     nodeId: string;
     params: NodeDataParams;
     inputs: Array<string>;
+    inputProps: Record<string, string>;
     pendings: Set<string>;
     waitlist: Set<string>;
     state: NodeState;
@@ -70,32 +83,42 @@ declare class Node {
     private retry;
     removePending(nodeId: string): void;
     pushQueueIfReady(): void;
-    injectResult(result: ResultData): void;
+    injectValue(value: ResultData): void;
     private setResult;
     execute(): Promise<void>;
 }
 type GraphNodes = Record<string, Node>;
+export type CallbackDictonaryArgs = AgentFunctionDictonary;
 export declare class GraphAI {
+    private data;
     nodes: GraphNodes;
+    agentId?: string;
     callbackDictonary: AgentFunctionDictonary;
     isRunning: boolean;
     private runningNodes;
     private nodeQueue;
     private onComplete;
     private concurrency;
+    private loop?;
+    private repeatCount;
+    verbose: boolean;
     private logs;
-    constructor(data: GraphData, callbackDictonary: AgentFunctionDictonary | AgentFunction<any, any, any>);
-    getCallback(_agentId?: string): AgentFunction<any, any, any>;
+    private createNodes;
+    private getValueFromResults;
+    private initializeNodes;
+    constructor(data: GraphData, callbackDictonary: CallbackDictonaryArgs);
+    getCallback(agentId?: string): AgentFunction<any, any, any>;
     asString(): string;
     results(): ResultDataDictonary<Record<string, any>>;
     errors(): Record<string, Error>;
+    private pushReadyNodesIntoQueue;
     run(): Promise<ResultDataDictonary>;
     private runNode;
     pushQueue(node: Node): void;
     removeRunning(node: Node): void;
     appendLog(log: TransactionLog): void;
     transactionLogs(): TransactionLog[];
-    injectResult(nodeId: string, result: ResultData): void;
+    injectValue(nodeId: string, value: ResultData): void;
     resultsOf(nodeIds: Array<string>): ResultData<Record<string, any>>[];
 }
 export {};