graphai 0.5.14 → 0.5.15

package/README.md

@@ -2,91 +2,125 @@
 
 ## Overview
 
-GraphAI is an asynchronous data flow execution engine, which allows developers to build *agentic applications* by describing *agent workflows* as declarative data flow graphs in YAML or JSON. 
+GraphAI is an asynchronous dataflow execution engine, which allows developers to build *agentic applications* by describing *agent workflows* as declarative dataflow graphs in YAML or JSON. 
 
 As Andrew Ng has described in his article, "[The batch: Issue 242](https://www.deeplearning.ai/the-batch/issue-242/)", better results can often be achieved by making multiple calls to a Large Language Model (LLM) and allowing it to incrementally build towards a higher-quality output. Dr. Ng refers to this approach as 'agentic workflows.' 
 
 Such *agentic applications* require making multiple asynchronous API calls (e.g., OpenAI's chat-completion API, database queries, web searches) and managing data dependencies among them. As the complexity of the application increases, managing these dependencies in a traditional programming style becomes challenging due to the asynchronous nature of the APIs.
 
-GraphAI allows developers to describe dependencies among those agents (asynchronous API calls) in a data flow graph in YAML or JSON, which is called *declarative data flow programming* . The GraphAI engine will take care of all the complexity of concurrent asynchronous calls, data dependency management, task priority management, map-reduce processing, error handling, retries and logging. 
+GraphAI allows developers to describe dependencies among those agents (asynchronous API calls) in a dataflow graph in YAML or JSON, which is called *declarative dataflow programming* . The GraphAI engine will take care of all the complexity of concurrent asynchronous calls, data dependency management, task priority management, map-reduce processing, error handling, retries and logging. 
 
-## Declarative Data Flow Programming
+## Declarative Dataflow Programming
 
 Here is a simple example, which uses the Wikipedia as the data source and perform an in-memory RAG (Retrieval-Augmented Generation).
 
 ```YAML
+version: 0.5
 nodes:
-  source: // Input data to this RAG application
+  source:
     value:
       name: Sam Bankman-Fried
+      topic: sentence by the court
       query: describe the final sentence by the court for Sam Bank-Fried
-  wikipedia: // Retrieve data from Wikipedia
+  wikipedia:
+    console:
+      before: ...fetching data from wikkpedia
     agent: wikipediaAgent
     inputs:
       query: :source.name
-  chunks: // Break the text from Wikipedia into chunks (2048 character each with 512 overlap）
+    params:
+      lang: en
+  chunks:
+    console:
+      before: ...splitting the article into chunks
     agent: stringSplitterAgent
     inputs:
-      text: :wikipedia
-  chunkEmbeddings: // Get embedding vector of each chunk
+      text: :wikipedia.content
+  chunkEmbeddings:
+    console:
+      before: ...fetching embeddings for chunks
     agent: stringEmbeddingsAgent
     inputs:
-      array: :chunks
-  topicEmbedding: // Get embedding vector of the question
+      array: :chunks.contents
+  topicEmbedding:
+    console:
+      before: ...fetching embedding for the topic
     agent: stringEmbeddingsAgent
     inputs:
-      item: :source.query
-  similarities: // Calculate the cosine similarity of each chunk
+      item: :source.topic
+  similarities:
     agent: dotProductAgent
     inputs:
       matrix: :chunkEmbeddings
-      vector: :topicEmbedding
-  sortedChunks: // Sort chunks based on their similarities
+      vector: :topicEmbedding.$0
+  sortedChunks:
     agent: sortByValuesAgent
     inputs:
-      array: :chunks
+      array: :chunks.contents
       values: :similarities
-  referenceText: // Concatenate chunks up to the token limit (5000)
+  referenceText:
     agent: tokenBoundStringsAgent
     inputs:
-      array: :sortedChunks
+      chunks: :sortedChunks
     params:
       limit: 5000
-  prompt: // Generate a prompt with that reference text
+  prompt:
     agent: stringTemplateAgent
     inputs:
-      prompt: :source
-      text: :referenceText
+      prompt: :source.query
+      text: :referenceText.content
     params:
       template: |-
-        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
+        Using the following document, ${text}
+
+        ${prompt}
+  RagQuery:
+    console:
+      before: ...performing the RAG query
+    agent: openAIAgent
     inputs:
       prompt: :prompt
+    params:
+      model: gpt-4o
+  OneShotQuery:
+    agent: openAIAgent
+    inputs:
+      prompt: :source.query
+    params:
+      model: gpt-4o
+  RagResult:
+    agent: copyAgent
+    inputs:
+      result: :RagQuery.text
+    isResult: true
+  OneShotResult:
+    agent: copyAgent
+    inputs:
+      result: :OneShotQuery.text
+    isResult: true
+
 ```
 
 ```mermaid
 flowchart TD
  source -- name --> wikipedia(wikipedia)
- source -- query --> topicEmbedding(topicEmbedding)
- wikipedia --> chunks(chunks)
- chunks --> chunkEmbeddings(chunkEmbeddings)
+ wikipedia -- content --> chunks(chunks)
+ chunks -- contents --> chunkEmbeddings(chunkEmbeddings)
+ source -- topic --> topicEmbedding(topicEmbedding)
  chunkEmbeddings --> similarities(similarities)
- topicEmbedding --> similarities
+ topicEmbedding -- $0 --> similarities
  similarities --> sortedChunks(sortedChunks)
+ chunks -- contents --> sortedChunks
  sortedChunks --> referenceText(resourceText)
+ referenceText -- content --> prompt
  source -- query --> prompt(prompt)
- referenceText --> prompt
- prompt --> query(query)
+ prompt --> RagQuery(RagQuery)
+ source -- query --> OneShotQuery(OneShotQuery)
+ RagQuery -- text --> RagResult(RagResult)
+ OneShotQuery -- text --> OneShotResult(OneShotResult)
 ```
 
-Notice that the conversion of the query text into an embedding vector and text chunks into an array of embedding vectors can be done concurrently because there is no dependency between them. GraphAI will automatically recognize it and execute them concurrently. This kind of *concurrent programing* is very difficult in traditional programming style, and GraphAI's *data flow programming* style is much better alternative.
+Notice that the conversion of the query text into an embedding vector and text chunks into an array of embedding vectors can be done concurrently because there is no dependency between them. GraphAI will automatically recognize it and execute them concurrently. This kind of *concurrent programming* is very difficult in traditional programming style, and GraphAI's *dataflow programming* style is much better alternative.
 
 ## Quick Install
 
@@ -100,28 +134,28 @@ or
 yarn add graphai
 ```
 
-## Data Flow Graph
+## Dataflow 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 Dataflow Graph (DFG) is a JavaScript object, which defines the flow of data. It is described in YAML or JSON and loaded at runtime.
 
-A DFG consists of a collection of [nodes](#node), 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 (such as params, inputs, and value) that dictate the node's behavior and its relationship with other nodes. There are two types of nodes, [computed nodes](#computed-node) and [static nodes](#static-node), which are described below.
+A DFG consists of a collection of [nodes](#node), which contains a series of nested properties representing individual nodes in the dataflow. Each node is identified by a unique key, *nodeId* (e.g., node1, node2) and can contain several predefined properties (such as params, inputs, and value) that dictate the node's behavior and its relationship with other nodes. There are two types of nodes, [computed nodes](#computed-node) and [static nodes](#static-node), which are described below.
 
 ### Data Source
 
-Connections between nodes will be established by references from one node to another, using either its "inputs", "update", "if" or "while" property. The values of those properties are *data sources*. A *data souce* is specified by either the ":" + nodeId (e.g., ":node1"), or ":" + nodeId + propertyId (e.g., ":node1.item"), index (e.g., ":node1.$0", ":node2.$last") or combinations (e.g., ":node1.messages.$0.content").
+Connections between nodes will be established by references from one node to another, using either its "inputs", "update", "if", "unless" or "while" property. The values of those properties are *data sources*. A *data souce* is specified by either the ":" + nodeId (e.g., ":node1"), or ":" + nodeId + propertyId (e.g., ":node1.item"), index (e.g., ":node1.$0", ":node2.$last") or combinations (e.g., ```:node1.messages.$0.content```).
 
 ### DFG Structure
 
-- *version*: GraphAI version, *required*. The latest version is 0.3.
+- *version*: GraphAI version, required. The latest version is 0.5.
 - *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.
 - *loop*: An optional property, which specifies if the graph needs to be executed multiple times (iterations). See the [Loop section below](#loop) for details.
 
 ## Agent
 
-An *agent* is an abstract object which takes some inputs and generates an output asynchronously. It could be an LLM call (such as GPT-4), a media generator, a database access, or a REST API over HTTP. A node associated with an agent (specified by the *agent*'* property) is called [computed node](#computed-node), which takes a set of *inputs* from *data sources*, asks the *agent function* to process it, and makes the returned value available to other nodes.
+An *agent* is an abstract object which takes some inputs and generates an output asynchronously. It could be an LLM call (such as GPT-4), a media generator, a database access, or a REST API over HTTP. A node associated with an agent (specified by the *agent*'* property) is called [computed node](#computed-node), which takes a set of *inputs* from *data sources*, asks the *agent function* to process it, and makes the returned value available to other nodes as its output.
 
-### Agent function
+### Agent Function
 
 An *agent function* is a TypeScript function, which implements a particular *agent*, performing some computations for the associated *computed node*. An *agent function* receives a *context* (type AgentFunctionContext), which has following properties:
 
@@ -139,18 +173,20 @@ There are additional optional parameters for developers of nested agents and age
 
 ### Inline Agent Function
 
-An *inline agent function* is a simplified version of *agent function*, which is embedded in the graph (available only when the graph was described in TypeScript). An *inline agent function* receives only the *inputs* paramter as a variable length arguments.
+An *inline agent function* is a simplified version of *agent function*, which is embedded in the graph (available only when the graph was described in TypeScript). An *inline agent function* receives the *inputs* paramter as its only argument.
 
-Here is an examnple (from [weather chat](https://github.com/receptron/graphai/blob/main/samples/sample_weather.ts)):
+Here is an example:
 
 ```typescript
     messagesWithUserInput: {
       // Appends the user's input to the messages.
-      agent: ({ messages: Array<any>, content: string }) => [...messages, { role: "user", content }],
-      inputs:
-        messages: ":messages"
-        content: ":userInput"
-      if: "checkInput",
+      agent: ({ messages: Array<any>, content: string }) => { 
+        return { array:[...messages, { role: "user", content }] };
+      },
+      inputs: {
+        messages: ":messages.array"
+        content: ":userInput.text"
+      }
     },
 ```
 
@@ -168,14 +204,14 @@ A *computed node* has following properties.
 
 - *agent*: An **required** property, which specifies the id of the *agent function*, or an *inline agent function* (NOTE: this is not possible in JSON or YAML).
 - *params*: An optional agent-specific property to control the behavior of the associated agent function. The top level property may reference a *data source*.
-- *inputs*: An optional list of *data sources* that the current node receives the data from. This establishes a data 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.
+- *inputs*: An optional list of *data sources* that the current node receives the data from. This establishes a dataflow 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 immediately executed. 
+- *anyInput*: An optional boolean flag (default is false), which indicates that the associated *agent function* will be called when at least one of input data became available. Otherwise (default), 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, the error 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. The returned value received after the time out will be discarded.
 - *isResult*: An optional boolean value, which indicates that the return value of this node, should be included as a property of the return value from the run() method of the GraphUI instance.
 - *priority*: An optional number, which specifies the priority of the execution of the associated agent (the task). Default is 0, which means "neutral". Negative numbers are allowed as well.
 - *if*: An optional data source property. The node will be activated only if the value from the data source is truthy. 
-- *unless*: An optional data source property. The node will be activated only if the value from the data source is falty (including empty array). 
+- *unless*: An optional data source property. The node will be activated only if the value from the data source is falsy (including empty array). 
 - *graph*: An optional property for nested agents, which specifies the inner graph. This value can be a graph itself or the data souce, whose value is a graph.
 
 ### Static Node
@@ -187,7 +223,7 @@ A *static* node has following properties.
 
 ## Flow Control
 
-Since the data-flow graph must be asyclic by design, we added a few mechanisms to control data flows, [nesting](#nesting), [loop](#loop), [mapping](#mapping) and [conditional flow](#conditional-flow).
+Since the dataflow graph must be acyclic by design, we added a few mechanisms to control dataflows, [nesting](#nesting), [loop](#loop), [mapping](#mapping) and [conditional flow](#conditional-flow).
 
 ### Nested Graph
 
@@ -202,7 +238,7 @@ nodes:
   projectId: // identifies the projectId from the question
     agent: identifierAgent
     inputs: 
-      id: :source
+      id: :question
   database:
     agent: "nestedAgent"
     inputs:
@@ -210,9 +246,10 @@ nodes:
       projectId: ":projectId"
     graph:
       nodes:
-        schema: // retrieves the database schema for the apecified projectId
+        schema: // retrieves the database schema for the specified projectId
           agent: "schemaAgent"
-          inputs: [":projectId"]
+          inputs:
+            projectId: :projectId
         ... // issue query to the database and build an appropriate prompt with it.
         query: // send the generated prompt to the LLM
           agent: "llama3Agent"
@@ -222,10 +259,10 @@ nodes:
   response: // Deliver the answer
     agent: "deliveryAgent"      
     inputs:
-      text: :database.query.$last.content
+      text: :database.query.text
 ```
 
-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.
+The databaseQuery node (which is associated "nestedAgent") takes the data from "question" node and "projectId" node, and make them available to inner nodes (nodes of the child graph) via phantom node, ":question" and ":projectId". 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.
 
 Here is the diagram of the parent graph.
 
@@ -234,20 +271,20 @@ flowchart LR
  question --> projectId(projectId)
  question --> database
  projectId --> database
- database[[database]] -- query --> response(response)
+ database[[database]] -- query.text --> response(response)
 ```
 
 Here is the diagram of the child graph. Notice that two phantom nodes are automatically created to allow inner nodes to access input data from the parent graph.
 
 ```mermaid
 flowchart LR
- $0 --> ...
- $1 --> schema(schema)
+ :question --> ...
+ :projectId --> schema(schema)
  schema --> ...(...)
  ... --> query(query)
 ```
 
-This mechanism does not only allows devleoper to reuse code, but also makes it possible to execute the child graph on another machine using a "remote" agent (which will be released later), enabling the *distributed execution* of nested graphs. 
+This mechanism does not only allow developer to reuse code, but also make it possible to execute the child graph on another machine using a "remote" agent, enabling the *distributed execution* of nested graphs. 
 
 ### Loop
 
@@ -258,34 +295,40 @@ The loop is an optional property of a graph, which has two optional properties.
 
 Here is an example, which performs an LLM query for each person in the list and create the list of answers. The "people" node (static), is initialized with an array of names, and the "retriever" node (computed) retrieves one name at a time, and sends it to the "query" node (computed) to perform an LLM query. The "reducer" append it the array retrieved form the "result" node (static node, which is initialized as an empty array). 
 
-The "update" property of two static nodes ("people" and "result"), updates those properties based on the results from the previous itelation. This loop continues until the value of "people" node become an empty array.
+The "update" property of two static nodes ("people" and "result"), updates those properties based on the results from the previous iteration. This loop continues until the value of "people" node become an empty array.
 
-```
+```YAML
+version: 0.5
 loop:
   while: :people
 nodes:
   people:
-    value: [Steve Jobs, Elon Musk, Nikola Tesla]
+    value:
+      - Steve Jobs
+      - Elon Musk
+      - Nikola Tesla
     update: :retriever.array
   result:
     value: []
-    update: :reducer
+    update: :reducer.array
     isResult: true
   retriever:
-    agent: shift
+    agent: shiftAgent
     inputs:
       array: :people
   query:
-    agent: slashgpt
+    agent: openAIAgent
     params:
-      manifest:
-        prompt: Describe about the person in less than 100 words
-    inputs: [:retriever.item]
+      system: Describe about the person in less than 100 words
+      model: gpt-4o
+    inputs:
+      prompt: :retriever.item
   reducer:
-    agent: push
+    agent: pushAgent
     inputs:
       array: :result
-      item: :query.content
+      item: :query.text
+
 ```
 
 ```mermaid
@@ -293,14 +336,14 @@ flowchart LR
  result --> reducer(reducer)
  people --> retriever(retriever)
  retriever -- item --> query(query)
- query -- content --> reducer
+ query -- text --> reducer
  retriever -. array .-> people
  reducer -.-> result
 ```
 
 The *loop* mechanism is often used with a nested graph, which receives an array of data from a node of the parent graph and performs the "reduction" process of a *map-reduce* operation, just like the *reduce* method of JavaScript.
 
-Please notice that each iteration will be done sequencially unlike the *mapping* described below.
+Please notice that each iteration will be done sequentially unlike the *mapping* described below.
 
 ### Mapping
 
@@ -310,23 +353,27 @@ If the size of array is N, the mapAgent creates N instances of GraphAI object, a
 
 After the completion of all of instances, the mapAgent returns an array of results, just like the map function of JavaScript. 
 
-The following graph will generate the same result (an array of answers) as the sample graph for the *loop*, but three queries will be issued concurretly. 
+The following graph will generate the same result (an array of answers) as the sample graph for the *loop*, but three queries will be issued concurrently. 
 
-```
+```YAML
+version: 0.5
 nodes:
   people:
     value: [Steve Jobs, Elon Musk, Nikola Tesla]
   retriever:
     agent: "mapAgent"
     inputs: { rows: ":people" }
+    isResult: true
     graph:
       nodes:
         query:
-          agent: slashgpt
+          agent: openAIAgent
           params:
-            manifest:
-              prompt: Describe about the person in less than 100 words
-          inputs: [":row"]
+            system: Describe about the person in less than 100 words
+          inputs:
+            prompt: ":row"
+          isResult: true
+
 ```
 
 Here is the conceptual representation of this operation.
@@ -342,7 +389,7 @@ flowchart LR
 ```
 ### Conditional Flow
 
-GraphAI provides mechanisms to control the flow of data based on certain conditions. This is achieved through the *if* and *anyInput* properties.
+GraphAI provides mechanisms to control the flow of data based on certain conditions. This is achieved through the *if*, *unless* and *anyInput* properties.
 
 #### If/Unless Property
 
@@ -354,8 +401,10 @@ For example, the following node will be executed only if the *tool_calls* proper
     tool_calls: {
       // This node is activated if the LLM requests a tool call.
       agent: "nestedAgent",
-      inputs: [":groq.choices.$0.message.tool_calls", ":messagesWithFirstRes"],
-      if: ":groq.choices.$0.message.tool_calls",
+      inputs: {
+        array: [":groq.tool", ":messagesWithFirstRes"]
+      },
+      if: ":groq.tool",
       graph: {
         // This graph is nested only for the readability.
 ```
@@ -364,7 +413,7 @@ It is recommended to use the *if* property in conjunction with nested graphs for
 
 #### AnyInput Property
 
-The *anyInput* property (boolean) allows you to merge multiple data flow paths into a single node. When set to *true*, the agent function associated with the node will be executed as soon as data becomes available from any of the specified input data sources.
+The *anyInput* property (boolean) allows you to merge multiple dataflow paths into a single node. When set to *true*, the agent function associated with the node will be executed as soon as data becomes available from any of the specified input data sources.
 
 This property is particularly useful when you want to continue the flow regardless of which path the data comes from. In the weather chat sample application, it is used to continue the chat iteration whether a tool was requested by the LLM or not:
 

package/README.template.md

@@ -0,0 +1,324 @@
+# GraphAI
+
+## Overview
+
+GraphAI is an asynchronous dataflow execution engine, which allows developers to build *agentic applications* by describing *agent workflows* as declarative dataflow graphs in YAML or JSON. 
+
+As Andrew Ng has described in his article, "[The batch: Issue 242](https://www.deeplearning.ai/the-batch/issue-242/)", better results can often be achieved by making multiple calls to a Large Language Model (LLM) and allowing it to incrementally build towards a higher-quality output. Dr. Ng refers to this approach as 'agentic workflows.' 
+
+Such *agentic applications* require making multiple asynchronous API calls (e.g., OpenAI's chat-completion API, database queries, web searches) and managing data dependencies among them. As the complexity of the application increases, managing these dependencies in a traditional programming style becomes challenging due to the asynchronous nature of the APIs.
+
+GraphAI allows developers to describe dependencies among those agents (asynchronous API calls) in a dataflow graph in YAML or JSON, which is called *declarative dataflow programming* . The GraphAI engine will take care of all the complexity of concurrent asynchronous calls, data dependency management, task priority management, map-reduce processing, error handling, retries and logging. 
+
+## Declarative Dataflow Programming
+
+Here is a simple example, which uses the Wikipedia as the data source and perform an in-memory RAG (Retrieval-Augmented Generation).
+
+```YAML
+${packages/samples/graph_data/openai/wikipedia_rag.yaml}
+```
+
+```mermaid
+flowchart TD
+ source -- name --> wikipedia(wikipedia)
+ wikipedia -- content --> chunks(chunks)
+ chunks -- contents --> chunkEmbeddings(chunkEmbeddings)
+ source -- topic --> topicEmbedding(topicEmbedding)
+ chunkEmbeddings --> similarities(similarities)
+ topicEmbedding -- $0 --> similarities
+ similarities --> sortedChunks(sortedChunks)
+ chunks -- contents --> sortedChunks
+ sortedChunks --> referenceText(resourceText)
+ referenceText -- content --> prompt
+ source -- query --> prompt(prompt)
+ prompt --> RagQuery(RagQuery)
+ source -- query --> OneShotQuery(OneShotQuery)
+ RagQuery -- text --> RagResult(RagResult)
+ OneShotQuery -- text --> OneShotResult(OneShotResult)
+```
+
+Notice that the conversion of the query text into an embedding vector and text chunks into an array of embedding vectors can be done concurrently because there is no dependency between them. GraphAI will automatically recognize it and execute them concurrently. This kind of *concurrent programming* is very difficult in traditional programming style, and GraphAI's *dataflow programming* style is much better alternative.
+
+## Quick Install
+
+```
+npm install graphai
+```
+
+or
+
+```
+yarn add graphai
+```
+
+## Dataflow Graph
+
+A Dataflow Graph (DFG) is a JavaScript object, which defines the flow of data. It is described in YAML or JSON and loaded at runtime.
+
+A DFG consists of a collection of [nodes](#node), which contains a series of nested properties representing individual nodes in the dataflow. Each node is identified by a unique key, *nodeId* (e.g., node1, node2) and can contain several predefined properties (such as params, inputs, and value) that dictate the node's behavior and its relationship with other nodes. There are two types of nodes, [computed nodes](#computed-node) and [static nodes](#static-node), which are described below.
+
+### Data Source
+
+Connections between nodes will be established by references from one node to another, using either its "inputs", "update", "if", "unless" or "while" property. The values of those properties are *data sources*. A *data souce* is specified by either the ":" + nodeId (e.g., ":node1"), or ":" + nodeId + propertyId (e.g., ":node1.item"), index (e.g., ":node1.$0", ":node2.$last") or combinations (e.g., ```:node1.messages.$0.content```).
+
+### DFG Structure
+
+- *version*: GraphAI version, required. The latest version is 0.5.
+- *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.
+- *loop*: An optional property, which specifies if the graph needs to be executed multiple times (iterations). See the [Loop section below](#loop) for details.
+
+## Agent
+
+An *agent* is an abstract object which takes some inputs and generates an output asynchronously. It could be an LLM call (such as GPT-4), a media generator, a database access, or a REST API over HTTP. A node associated with an agent (specified by the *agent*'* property) is called [computed node](#computed-node), which takes a set of *inputs* from *data sources*, asks the *agent function* to process it, and makes the returned value available to other nodes as its output.
+
+### Agent Function
+
+An *agent function* is a TypeScript function, which implements a particular *agent*, performing some computations for the associated *computed node*. An *agent function* receives a *context* (type AgentFunctionContext), which has following properties:
+
+- *params*: agent specific parameters specified in the DFG (specified by the "params" property of the node)
+- *inputs*: a set of inputs came from other nodes (specified by "inputs" property of the node).
+- *debugInfo*: a set of information for debugging purposes.
+
+There are additional optional parameters for developers of nested agents and agent filters.
+
+- *graphData*: an optional GraphData (for nested agents)
+- *agents*: AgentFunctionInfoDictionary (for nested agents)
+- *taskManager*: TaskManager (for nested agents)
+- *log*: TransactionLog[] (for nested agents)
+- *filterParams*: agent filter parameters (for agent filters)
+
+### Inline Agent Function
+
+An *inline agent function* is a simplified version of *agent function*, which is embedded in the graph (available only when the graph was described in TypeScript). An *inline agent function* receives the *inputs* paramter as its only argument.
+
+Here is an example:
+
+```typescript
+    messagesWithUserInput: {
+      // Appends the user's input to the messages.
+      agent: ({ messages: Array<any>, content: string }) => { 
+        return { array:[...messages, { role: "user", content }] };
+      },
+      inputs: {
+        messages: ":messages.array"
+        content: ":userInput.text"
+      }
+    },
+```
+
+## Node
+
+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, and returns the result (output). 
+
+A *static node* is a placeholder of a value (just like a variable in programming languages), which is initially specified by its *value* property, and can be updated by an external program (before the execution of the graph), or updated using the *update* property at the end of each iteration of a [loop](#loop) operation. 
+
+### Computed Node
+
+A *computed node* has following properties.
+
+- *agent*: An **required** property, which specifies the id of the *agent function*, or an *inline agent function* (NOTE: this is not possible in JSON or YAML).
+- *params*: An optional agent-specific property to control the behavior of the associated agent function. The top level property may reference a *data source*.
+- *inputs*: An optional list of *data sources* that the current node receives the data from. This establishes a dataflow 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 immediately executed. 
+- *anyInput*: An optional boolean flag (default is false), which indicates that the associated *agent function* will be called when at least one of input data became available. Otherwise (default), 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, the error 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. The returned value received after the time out will be discarded.
+- *isResult*: An optional boolean value, which indicates that the return value of this node, should be included as a property of the return value from the run() method of the GraphUI instance.
+- *priority*: An optional number, which specifies the priority of the execution of the associated agent (the task). Default is 0, which means "neutral". Negative numbers are allowed as well.
+- *if*: An optional data source property. The node will be activated only if the value from the data source is truthy. 
+- *unless*: An optional data source property. The node will be activated only if the value from the data source is falsy (including empty array). 
+- *graph*: An optional property for nested agents, which specifies the inner graph. This value can be a graph itself or the data souce, whose value is a graph.
+
+### Static Node
+
+A *static* node has following properties.
+
+- *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* for a [loop](#loop) operation. After each iteration, the value of this node will be updated with the data from the specified *data source*.
+
+## Flow Control
+
+Since the dataflow graph must be acyclic by design, we added a few mechanisms to control dataflows, [nesting](#nesting), [loop](#loop), [mapping](#mapping) and [conditional flow](#conditional-flow).
+
+### Nested Graph
+
+In order to make it easy to reuse some code, GraphAI supports nesting. It requires a special agent function, which creates an instance (or instances) of GraphAI object within the agent function and execute it. The system supports two types of nesting agent functions (nestAgent and mapAgent), but developers can create their own using the standard agent extension mechanism.
+
+A typical nesting graph looks like this:
+
+```YAML
+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: 
+      id: :question
+  database:
+    agent: "nestedAgent"
+    inputs:
+      prompt: ":question"
+      projectId: ":projectId"
+    graph:
+      nodes:
+        schema: // retrieves the database schema for the specified projectId
+          agent: "schemaAgent"
+          inputs:
+            projectId: :projectId
+        ... // issue query to the database and build an appropriate prompt with it.
+        query: // send the generated prompt to the LLM
+          agent: "llama3Agent"
+          inputs:
+            promot: ":prompt"
+          isResult: true
+  response: // Deliver the answer
+    agent: "deliveryAgent"      
+    inputs:
+      text: :database.query.text
+```
+
+The databaseQuery node (which is associated "nestedAgent") takes the data from "question" node and "projectId" node, and make them available to inner nodes (nodes of the child graph) via phantom node, ":question" and ":projectId". 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.
+
+Here is the diagram of the parent graph.
+
+```mermaid
+flowchart LR
+ question --> projectId(projectId)
+ question --> database
+ projectId --> database
+ database[[database]] -- query.text --> response(response)
+```
+
+Here is the diagram of the child graph. Notice that two phantom nodes are automatically created to allow inner nodes to access input data from the parent graph.
+
+```mermaid
+flowchart LR
+ :question --> ...
+ :projectId --> schema(schema)
+ schema --> ...(...)
+ ... --> query(query)
+```
+
+This mechanism does not only allow developer to reuse code, but also make it possible to execute the child graph on another machine using a "remote" agent, enabling the *distributed execution* of nested graphs. 
+
+### Loop
+
+The loop is an optional property of a graph, which has two optional properties. 
+
+- *count*: Specifies the number of times the graph needs to be executed.
+- *while*: Specifies the *data source* to check after the each iteration. It continues if the data from that *data source* is *true*. Unlike JavaScript, an empty array will be treated as *false*.
+
+Here is an example, which performs an LLM query for each person in the list and create the list of answers. The "people" node (static), is initialized with an array of names, and the "retriever" node (computed) retrieves one name at a time, and sends it to the "query" node (computed) to perform an LLM query. The "reducer" append it the array retrieved form the "result" node (static node, which is initialized as an empty array). 
+
+The "update" property of two static nodes ("people" and "result"), updates those properties based on the results from the previous iteration. This loop continues until the value of "people" node become an empty array.
+
+```YAML
+${packages/samples/graph_data/test/loop.yaml}
+```
+
+```mermaid
+flowchart LR
+ result --> reducer(reducer)
+ people --> retriever(retriever)
+ retriever -- item --> query(query)
+ query -- text --> reducer
+ retriever -. array .-> people
+ reducer -.-> result
+```
+
+The *loop* mechanism is often used with a nested graph, which receives an array of data from a node of the parent graph and performs the "reduction" process of a *map-reduce* operation, just like the *reduce* method of JavaScript.
+
+Please notice that each iteration will be done sequentially unlike the *mapping* described below.
+
+### Mapping
+
+The mapAgent is one of nested agents, which receives an array of data as an input (inputs[0]) and performs the same operation (specified by its graph property) on each item concurrently.
+
+If the size of array is N, the mapAgent creates N instances of GraphAI object, and run them concurrently.
+
+After the completion of all of instances, the mapAgent returns an array of results, just like the map function of JavaScript. 
+
+The following graph will generate the same result (an array of answers) as the sample graph for the *loop*, but three queries will be issued concurrently. 
+
+```YAML
+${packages/samples/src/simple/map_people.yaml}
+```
+
+Here is the conceptual representation of this operation.
+
+```mermaid
+flowchart LR
+ people -- "[0]" --> query_0(query_0)
+ people -- "[1]" --> query_1(query_1)
+ people -- "[2]" --> query_2(query_2)
+ query_0 --> retriever[[retriever]]
+ query_1 --> retriever
+ query_2 --> retriever
+```
+### Conditional Flow
+
+GraphAI provides mechanisms to control the flow of data based on certain conditions. This is achieved through the *if*, *unless* and *anyInput* properties.
+
+#### If/Unless Property
+
+The *if* property allows you to specify a condition that must be met for the data to flow into a particular node. The condition is defined by a data source. If the value obtained from the specified *data source* is truthy (i.e., not null, undefined, 0, false, NaN, or an empty array/string), the node will be executed; otherwise, it will be skipped.The *unless* property is just the opporsite of the *if* property. 
+
+For example, the following node will be executed only if the *tool_calls* property of the message from the LLM contains a non-zero/non-empty value:
+
+```typescript
+    tool_calls: {
+      // This node is activated if the LLM requests a tool call.
+      agent: "nestedAgent",
+      inputs: {
+        array: [":groq.tool", ":messagesWithFirstRes"]
+      },
+      if: ":groq.tool",
+      graph: {
+        // This graph is nested only for the readability.
+```
+
+It is recommended to use the *if* property in conjunction with nested graphs for better code readability and organization.
+
+#### AnyInput Property
+
+The *anyInput* property (boolean) allows you to merge multiple dataflow paths into a single node. When set to *true*, the agent function associated with the node will be executed as soon as data becomes available from any of the specified input data sources.
+
+This property is particularly useful when you want to continue the flow regardless of which path the data comes from. In the weather chat sample application, it is used to continue the chat iteration whether a tool was requested by the LLM or not:
+
+```typescript
+    reducer: {
+      // Receives messages from either case.
+      agent: "copyAgent",
+      anyInput: true,
+      inputs: 
+        array: [":no_tool_calls", ":tool_calls.messagesWithSecondRes"],
+    },
+```
+
+In this example, the "reducer" node will execute as soon as data is available from either the "no_tool_calls" or "tool_calls.messagesWithSecondRes" data source.
+
+By combining the *if* and *anyInput* properties, you can create complex conditional flows that control the execution of nodes based on the availability and values of data from various sources. This flexibility allows you to build sophisticated data-driven applications with GraphAI.
+
+## Concurrency
+
+GraphAI supports concurrent execution of tasks, allowing you to leverage parallelism and improve performance. The level of concurrency can be controlled through the *concurrency* property at the top level of the graph definition.
+
+```typescript
+  concurrency: 16 # Maximum number of concurrent tasks
+```
+
+If the *concurrency* property is not specified, the default value of 8 is used.
+
+### Concurrency and Nested Graphs
+
+Since the task queue is shared between the parent graph and the children graph (uness the graph is running remotely), tasks created by the child graph will be bound by the same concurrency specified by the parent graph. 
+
+Since the task executing the nested graph will be in "running" state while tasks within the child graph are runnig, the concurrency limit will be incremented by one when we start running the child graph and restored when it is completed.
+
+### Task Prioritization
+
+By default, tasks are executed in a first-in, first-out (FIFO) order with a neutral priority (0). However, you can assign custom priorities to nodes using the *priority* property. Tasks associated with nodes that have a higher priority value will be executed before those with lower priorities.
+
+Negative priority values are allowed, enabling you to fine-tune the execution order based on your application's requirements.

package/lib/graphai.d.ts

@@ -1,4 +1,4 @@
-import { AgentFunctionInfoDictionary, AgentFilterInfo, GraphData, DataSource, ResultDataDictionary, ResultData, DefaultResultData, GraphOptions } from "./type";
+import { AgentFunctionInfoDictionary, AgentFilterInfo, GraphData, DataSource, ResultDataDictionary, ResultData, DefaultResultData, GraphOptions, GraphDataLoader } from "./type";
 import { TransactionLog } from "./transaction_log";
 import { ComputedNode, GraphNodes } from "./node";
 import { TaskManager } from "./task_manager";
@@ -17,6 +17,7 @@ export declare class GraphAI {
     readonly agentFilters: AgentFilterInfo[];
     readonly retryLimit?: number;
     private readonly propFunctions;
+    readonly graphLoader?: GraphDataLoader;
     nodes: GraphNodes;
     onLogCallback: (__log: TransactionLog, __isUpdate: boolean) => void;
     verbose: boolean;

package/lib/graphai.js

@@ -87,6 +87,7 @@ class GraphAI {
         agentFilters: [],
         bypassAgentIds: [],
         config: {},
+        graphLoader: undefined,
     }) {
         this.logs = [];
         this.config = {};
@@ -108,6 +109,7 @@ class GraphAI {
         this.agentFilters = options.agentFilters ?? [];
         this.bypassAgentIds = options.bypassAgentIds ?? [];
         this.config = options.config;
+        this.graphLoader = options.graphLoader;
         this.loop = data.loop;
         this.verbose = data.verbose === true;
         this.onComplete = () => {

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, DefaultParamsType, } from "./type";
+export { AgentFunction, AgentFunctionInfo, AgentFunctionInfoDictionary, AgentFunctionInfoSample, AgentFunctionContext, GraphData, ResultDataDictionary, ResultData, NodeState, AgentFilterFunction, AgentFilterInfo, NodeData, StaticNodeData, ComputedNodeData, DefaultResultData, DefaultInputData, DefaultParamsType, GraphDataLoaderOption, GraphDataLoader, } from "./type";
 export type { TransactionLog } from "./transaction_log";
-export { defaultAgentInfo, agentInfoWrapper, defaultTestContext, strIntentionalError, assert, sleep, isObject } from "./utils/utils";
+export { defaultAgentInfo, agentInfoWrapper, defaultTestContext, strIntentionalError, assert, sleep, isObject, parseNodeName } 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.isObject = 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.parseNodeName = 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; } });
@@ -15,5 +15,6 @@ Object.defineProperty(exports, "strIntentionalError", { enumerable: true, get: f
 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; } });
+Object.defineProperty(exports, "parseNodeName", { enumerable: true, get: function () { return utils_1.parseNodeName; } });
 var common_1 = require("./validators/common");
 Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return common_1.ValidationError; } });

package/lib/node.js

@@ -76,6 +76,9 @@ class ComputedNode extends Node {
         if (data.graph) {
             this.nestedGraph = typeof data.graph === "string" ? this.addPendingNode(data.graph) : data.graph;
         }
+        if (data.graphLoader && graph.graphLoader) {
+            this.nestedGraph = graph.graphLoader(data.graphLoader);
+        }
         if (data.if) {
             this.ifSource = this.addPendingNode(data.if);
         }

package/lib/type.d.ts

@@ -31,6 +31,10 @@ export type StaticNodeData = {
 };
 export type AgentAnonymousFunction = (...params: any[]) => unknown;
 export type AgentFilterParams = Record<string, any>;
+export type GraphDataLoaderOption = {
+    fileName: string;
+    option?: any;
+};
 export type ComputedNodeData = {
     agent: string | AgentAnonymousFunction;
     inputs?: Array<any> | Record<string, any>;
@@ -42,6 +46,7 @@ export type ComputedNodeData = {
     if?: string;
     unless?: string;
     graph?: GraphData | string;
+    graphLoader?: GraphDataLoaderOption;
     isResult?: boolean;
     priority?: number;
     passThrough?: PassThrough;
@@ -61,11 +66,13 @@ export type GraphData = {
     retry?: number;
     metadata?: any;
 };
+export type GraphDataLoader = (loaderOption: GraphDataLoaderOption) => GraphData;
 export type GraphOptions = {
     agentFilters?: AgentFilterInfo[] | undefined;
     taskManager?: TaskManager | undefined;
     bypassAgentIds?: string[] | undefined;
     config?: Record<string, unknown>;
+    graphLoader?: GraphDataLoader;
 };
 export type AgentFunctionContext<ParamsType = DefaultParamsType, InputDataType = DefaultInputData, NamedInputDataType = DefaultInputData> = {
     params: NodeDataParams<ParamsType>;

package/lib/utils/data_source.d.ts

@@ -1,2 +1,2 @@
 import { ResultData, DataSource, PropFunction } from "../type";
-export declare const getDataFromSource: (result: ResultData | undefined, source: DataSource, propFunctions: PropFunction[]) => ResultData | undefined;
+export declare const getDataFromSource: (result: ResultData | undefined, source: DataSource, propFunctions?: PropFunction[]) => ResultData | undefined;

package/lib/utils/data_source.js

@@ -47,7 +47,7 @@ const innerGetDataFromSource = (result, propIds, propFunctions) => {
     }
     return result;
 };
-const getDataFromSource = (result, source, propFunctions) => {
+const getDataFromSource = (result, source, propFunctions = []) => {
     if (!source.nodeId) {
         return source.value;
     }

package/lib/utils/prop_function.d.ts

@@ -1,4 +1,3 @@
 import { PropFunction } from "../type";
 export declare const propFunctionRegex: RegExp;
 export declare const propFunctions: PropFunction[];
-export declare const propFunction: PropFunction;

package/lib/utils/prop_function.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.propFunction = exports.propFunctions = exports.propFunctionRegex = void 0;
+exports.propFunctions = exports.propFunctionRegex = void 0;
 const utils_1 = require("./utils");
 exports.propFunctionRegex = /^[a-zA-Z]+\([^)]*\)$/;
 const propArrayFunction = (result, propId) => {
@@ -81,23 +81,3 @@ const propBooleanFunction = (result, propId) => {
     return undefined;
 };
 exports.propFunctions = [propArrayFunction, propObjectFunction, propStringFunction, propNumberFunction, propBooleanFunction];
-const propFunction = (result, propId) => {
-    if (Array.isArray(result)) {
-        // flat, join
-        return propArrayFunction(result, propId);
-    }
-    else if ((0, utils_1.isObject)(result)) {
-        return propObjectFunction(result, propId);
-    }
-    else if (typeof result === "string") {
-        return propStringFunction(result, propId);
-    }
-    else if (result !== undefined && Number.isFinite(result)) {
-        return propNumberFunction(result, propId);
-    }
-    else if (typeof result === "boolean") {
-        return propBooleanFunction(result, propId);
-    }
-    return undefined;
-};
-exports.propFunction = propFunction;

package/lib/validators/common.js

@@ -10,6 +10,7 @@ exports.computedNodeAttributeKeys = [
     "timeout",
     "agent",
     "graph",
+    "graphLoader",
     "isResult",
     "priority",
     "if",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphai",
-  "version": "0.5.14",
+  "version": "0.5.15",
   "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.10"
+    "typedoc": "^0.26.11"
   },
   "types": "./lib/index.d.ts",
   "directories": {