From 5b2d19645c1252d8a2d676cf9c0612b536aa71b0 Mon Sep 17 00:00:00 2001
From: InAnYan <ruslanpopov1512@gmail.com>
Date: Mon, 11 Nov 2024 16:59:59 +0200
Subject: [PATCH 1/8] Agents framework design draft

---
 module/move/assistant/design/agents_design.md | 96 +++++++++++++++++++
 .../design/agents_examples/qa_1.yaml          | 22 +++++
 2 files changed, 118 insertions(+)
 create mode 100644 module/move/assistant/design/agents_design.md
 create mode 100644 module/move/assistant/design/agents_examples/qa_1.yaml

diff --git a/module/move/assistant/design/agents_design.md b/module/move/assistant/design/agents_design.md
new file mode 100644
index 0000000000..69ac50cb6c
--- /dev/null
+++ b/module/move/assistant/design/agents_design.md
@@ -0,0 +1,96 @@
+# Agents
+
+## Descirption
+
+This file depicts a general framework for building **multi-agent AI systems**.
+
+Main description of such system is writen using **YAML**.
+
+The system consists of **nodes** and **edges**.
+
+Currently, we assume that the only information type passed between nodes is **single text** and nodes are connected in one way like a **pipeline**.
+
+In future, we can support other types like *list of strings*. *booleans*; we can deliver input to several nodes *in parallel*, etc.
+
+## Nodes
+
+Each node has an `id` property (its name).
+
+### Input nodes
+
+These nodes read an input from external environment and pass it to the graph.
+
+Current **types**:
+
+- Stding input node.
+- File input node.
+
+#### Stdin input node
+
+**Description**: retrieves input from user from the command line. A prompt can be supplied additionally.
+
+**Parameters**:
+
+- `prompt`: Text to show before the input, e.g.: `Query: `, `Your question: `, etc.
+
+#### File input node
+
+**Description**: reads file from the `path` parameters and passes to the next node.
+
+**Parameters**:
+
+- `path`: path to the file to read.
+
+### Processing nodes
+
+Those nodes perform intermediate processing of information. It can be either a mechanical one using an external program, or a real LLM agent.
+
+#### Script node
+
+**Description**: takes input from the node, runs the specified program, passes the input to the program's stdin, reads the programs output and passes it to the next node (this refs UNIX philosophy).
+
+**Paramters**:
+
+- `path`: path to the executable.
+
+#### Agent node
+
+**Description**: the core node type, represents an LLM agent that transforms text in one from to another.
+
+**Parameters**:
+
+- `provider`: LLM provider e.g.: `openai`, `anthropic`, etc.
+- `model`: LLM model name, e.g.: `gpt-4o-mini`, `claude`, etc.
+- `system_message`: system message template.
+- `user_message`: user message template.
+
+`system_message` and `user_message` are templates that have a variable called `{input}`.
+
+### Output nodes
+
+These nodes take an input from other node and present it to the external world.
+
+Current **types**:
+
+- Stdout output node.
+- File output node.
+
+#### Stdout output node
+
+**Description**: prints the input to the console.
+
+**Parameters**:
+
+- `prefix`: print text before the output, e.g.: `Answer: `, etc.
+
+#### File output node
+
+**Description**: saves input to a file.
+
+**Parameters**:
+
+- `path`: path to save the input.
+
+## YAML description structure
+
+Please refer to `examples/` directory.
diff --git a/module/move/assistant/design/agents_examples/qa_1.yaml b/module/move/assistant/design/agents_examples/qa_1.yaml
new file mode 100644
index 0000000000..5f58a74fc2
--- /dev/null
+++ b/module/move/assistant/design/agents_examples/qa_1.yaml
@@ -0,0 +1,22 @@
+title: Multi-agent Q&A example
+
+nodes:
+  - id: input
+    type: stdin
+    prompt: 'Your question: '
+
+  - id: cleaner
+    type: agent
+    system_message: 'Correct the orthography and other English mistakes. Make the input clean and easy to understand.'
+    user_message: '{input}'
+
+  - id: answerer
+    type: agent
+    system_message: 'You are a helpful Q&A assistant.'
+    user_message: 'Question: {input}'
+
+  - id: output
+    type: stdout
+    prefix: 'Answer: '
+
+connections: [input, clearer, answerer, output]

From 2a2455ba8beb3fc888fcbbff535aaae16cf348c9 Mon Sep 17 00:00:00 2001
From: InAnYan <ruslanpopov1512@gmail.com>
Date: Fri, 15 Nov 2024 10:07:09 +0200
Subject: [PATCH 2/8] Update from the review

---
 module/move/assistant/design/agents_design.md | 35 ++++++++++++----
 .../agents_examples/language_learner.yaml     | 42 +++++++++++++++++++
 .../design/agents_examples/qa_1.yaml          | 27 +++++++-----
 .../design/agents_examples/thinker.yaml       | 34 +++++++++++++++
 4 files changed, 119 insertions(+), 19 deletions(-)
 create mode 100644 module/move/assistant/design/agents_examples/language_learner.yaml
 create mode 100644 module/move/assistant/design/agents_examples/thinker.yaml

diff --git a/module/move/assistant/design/agents_design.md b/module/move/assistant/design/agents_design.md
index 69ac50cb6c..223deaa6fb 100644
--- a/module/move/assistant/design/agents_design.md
+++ b/module/move/assistant/design/agents_design.md
@@ -8,13 +8,15 @@ Main description of such system is writen using **YAML**.
 
 The system consists of **nodes** and **edges**.
 
-Currently, we assume that the only information type passed between nodes is **single text** and nodes are connected in one way like a **pipeline**.
+Currently, we assume that the only information type passed between nodes is **single text** and nodes are connected as a direct acyclic graph (DAC). Node can take input from several nodes, but it can generate only 1 output.
 
 In future, we can support other types like *list of strings*. *booleans*; we can deliver input to several nodes *in parallel*, etc.
 
 ## Nodes
 
-Each node has an `id` property (its name).
+Each node has an `id` property (its name) and a `type` property.
+
+`type` specifies node type in a special format - `category.type`. Number of levels separated by dots may vary.
 
 ### Input nodes
 
@@ -22,8 +24,8 @@ These nodes read an input from external environment and pass it to the graph.
 
 Current **types**:
 
-- Stding input node.
-- File input node.
+- `trigger.stdin`: stdin input node.
+- `trigger.file`: file input node.
 
 #### Stdin input node
 
@@ -45,6 +47,9 @@ Current **types**:
 
 Those nodes perform intermediate processing of information. It can be either a mechanical one using an external program, or a real LLM agent.
 
+- `script`: script node.
+- `agent.completion`: agent completion node.
+
 #### Script node
 
 **Description**: takes input from the node, runs the specified program, passes the input to the program's stdin, reads the programs output and passes it to the next node (this refs UNIX philosophy).
@@ -53,7 +58,7 @@ Those nodes perform intermediate processing of information. It can be either a m
 
 - `path`: path to the executable.
 
-#### Agent node
+#### Agent completion node
 
 **Description**: the core node type, represents an LLM agent that transforms text in one from to another.
 
@@ -64,7 +69,7 @@ Those nodes perform intermediate processing of information. It can be either a m
 - `system_message`: system message template.
 - `user_message`: user message template.
 
-`system_message` and `user_message` are templates that have a variable called `{input}`.
+`system_message` and `user_message` are templates. Variables available to those templates are **node names**.
 
 ### Output nodes
 
@@ -72,8 +77,8 @@ These nodes take an input from other node and present it to the external world.
 
 Current **types**:
 
-- Stdout output node.
-- File output node.
+- `event.stdout`: stdout output node.
+- `event.file`: file output node.
 
 #### Stdout output node
 
@@ -91,6 +96,20 @@ Current **types**:
 
 - `path`: path to save the input.
 
+### Utility nodes
+
+These nodes are special nodes for various purposes.
+
+Current **types**:
+
+- `scenario.termination`: scenario termination node.
+
+#### Scenario termination node
+
+**Description**: when the process of execution is passed to this node, the whole program of the multi-agent system terminates.
+
+This node is **implicitly present in every graph**, and to call it you just need to fill `next:` with the `scenario.terminate`.
+
 ## YAML description structure
 
 Please refer to `examples/` directory.
diff --git a/module/move/assistant/design/agents_examples/language_learner.yaml b/module/move/assistant/design/agents_examples/language_learner.yaml
new file mode 100644
index 0000000000..06b141dee4
--- /dev/null
+++ b/module/move/assistant/design/agents_examples/language_learner.yaml
@@ -0,0 +1,42 @@
+title: Help in language learning
+description: >
+  This file demonstrates a simple system that will guide user in learning languages.
+  Its main purpose consists of answering user question using another language + providing translation to
+  user's mother tongue + set of used unique words with their translations.
+  For example: user may ask in their language - "why the sky is blue?", the model will then explain it in
+  the target language, then provide a translation of its output in original language, and additionaly
+  the system will provide a set of used frases with their translations.
+  Currently, system is set for English learning for Ukrainian speakers.
+
+nodes:
+  - id: question_input
+    type: trigger.stdin
+    prompt: 'Your question: '
+    next: answer
+
+  - id: answer
+    type: agent.completion
+    system_message: 'You are a helpful Q&A assistant. Answer in English'
+    user_message: 'Question: {{question_input}}'
+    next: 
+      - translator
+      - frases_extractor
+      - output # TODO: What will happen if output would be called first (or in paralel to other "next"s) but there is no output of `translator` or `frases_extractor`?
+
+  - id: translator
+    type: agent.completion
+    system_message: 'Translate the input in Ukrainian language'
+    user_message: '{{answer}}'
+    
+  - id: frases_extractor
+    type: agent.completion
+    system_message: >
+      You have a text in English. Extract unique and interesting frases or words from the text
+      that would be useful for English language learner. Present the output as a list of pairs:
+      the first element is English phrase and the second is Ukrainian translation.
+    user_message: '{{answer}}'
+
+  - id: output
+    type: event.stdout
+    output: 'Answer: {{answer}}'
+    next: scenario.termination
diff --git a/module/move/assistant/design/agents_examples/qa_1.yaml b/module/move/assistant/design/agents_examples/qa_1.yaml
index 5f58a74fc2..28724b93cb 100644
--- a/module/move/assistant/design/agents_examples/qa_1.yaml
+++ b/module/move/assistant/design/agents_examples/qa_1.yaml
@@ -1,22 +1,27 @@
 title: Multi-agent Q&A example
+description: >
+  Demonstrates cleaning of user data, as the user may type fast or include only keywords. 
+  The first agent will turn user query into a valid question, and the second agent will answer it.
 
 nodes:
-  - id: input
-    type: stdin
+  - id: question_input
+    type: trigger.stdin
     prompt: 'Your question: '
+    next: cleaner
 
   - id: cleaner
-    type: agent
+    type: agent.completion
     system_message: 'Correct the orthography and other English mistakes. Make the input clean and easy to understand.'
-    user_message: '{input}'
+    user_message: '{{question_input}}'
+    next: answer
 
-  - id: answerer
-    type: agent
+  - id: answer
+    type: agent.completion
     system_message: 'You are a helpful Q&A assistant.'
-    user_message: 'Question: {input}'
+    user_message: 'Question: {{cleaner}}'
+    next: output
 
   - id: output
-    type: stdout
-    prefix: 'Answer: '
-
-connections: [input, clearer, answerer, output]
+    type: event.stdout
+    output: 'Answer: {{answer}}'
+    next: scenario.termination
diff --git a/module/move/assistant/design/agents_examples/thinker.yaml b/module/move/assistant/design/agents_examples/thinker.yaml
new file mode 100644
index 0000000000..ecff5edf55
--- /dev/null
+++ b/module/move/assistant/design/agents_examples/thinker.yaml
@@ -0,0 +1,34 @@
+title: Thinker
+description: >
+  This example demonstrates use of 2 agents: the first agent will think thoroughly on the user input.
+  It will utilize prompts like Chain-of-Thought: "Think step by step". This prompt increases the performance
+  of the model tens of times, however it introduces too much output. For that we utilize the second agent.
+
+nodes:
+  - id: question_input
+    type: trigger.stdin
+    prompt: 'Your question: '
+    next: cleaner
+
+  - id: thinker
+    type: agent.completion
+    system_message: > # This system prompt could be improved more, but for the sake of the example, we will leave it simple.
+      You are a methodical and knowledgeable assistant tasked with answering user questions thoroughly using a
+      chain-of-thought approach. Break down complex queries into components, outline a logical plan, and explain
+      each step in detail with examples or analogies as needed.
+    user_message: '{{question_input}}'
+    next: answer
+
+  - id: summarizer
+    type: agent.completion
+    system_message: >
+      You are a summarizer tasked with distilling detailed responses into clear, concise summaries.
+      Capture key points and main conclusions, removing unnecessary details while preserving essential meaning and logical flow.
+      But don't forget about code, it should be preserved.
+    user_message: 'Question: {{thinker}}'
+    next: output
+
+  - id: output
+    type: event.stdout
+    output: 'Answer: {{summarizer}}'
+    next: scenario.termination

From b7f95d2a23b1028a8b281fb0c9bcce287429c036 Mon Sep 17 00:00:00 2001
From: InAnYan <ruslanpopov1512@gmail.com>
Date: Fri, 15 Nov 2024 10:38:51 +0200
Subject: [PATCH 3/8] Add SQL example

---
 module/move/assistant/design/agents_design.md |  2 +-
 .../assistant/design/agents_examples/sql.yaml | 32 +++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)
 create mode 100644 module/move/assistant/design/agents_examples/sql.yaml

diff --git a/module/move/assistant/design/agents_design.md b/module/move/assistant/design/agents_design.md
index 223deaa6fb..0e7f1cf93a 100644
--- a/module/move/assistant/design/agents_design.md
+++ b/module/move/assistant/design/agents_design.md
@@ -56,7 +56,7 @@ Those nodes perform intermediate processing of information. It can be either a m
 
 **Paramters**:
 
-- `path`: path to the executable.
+- `cmd`: command to execute with path to the executable and arguments.
 
 #### Agent completion node
 
diff --git a/module/move/assistant/design/agents_examples/sql.yaml b/module/move/assistant/design/agents_examples/sql.yaml
new file mode 100644
index 0000000000..ca58fdd323
--- /dev/null
+++ b/module/move/assistant/design/agents_examples/sql.yaml
@@ -0,0 +1,32 @@
+title: DB information extractor
+description: >
+  This system accepts user query for the DB in natural language and converts it into SQL code, which is then passed to a script that will
+  execute this SQL and present the output.
+  This example requires that the script is correctly configured to the real DB.
+
+nodes:
+  - id: question_input
+    type: trigger.stdin
+    prompt: 'Your query: '
+    next: translator
+
+  - id: translator
+    type: agent.completion
+    # In real life scenario you should specify here:
+    # - Which DB is used?
+    # - What are the tables and columns?
+    # - Schema of the DB.
+    system_message: 'Your task is to translate user query into SQL code for the database.'
+    user_message: '{{question_input}}'
+    next: query
+
+  - id: query
+    type: script
+    # In real life scenario you should add parameters for contacting the DB.
+    cmd: 'query_db {{translator}}'
+    next: output
+
+  - id: output
+    type: event.stdout
+    output: 'Output: {{query}}'
+    next: scenario.termination

From f941f0128efd0e481b9f75bd04c0ee620a7126a1 Mon Sep 17 00:00:00 2001
From: InAnYan <ruslanpopov1512@gmail.com>
Date: Fri, 15 Nov 2024 11:19:29 +0200
Subject: [PATCH 4/8] Redesign sql.yaml

---
 .../assistant/design/agents_examples/sql.yaml   | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/module/move/assistant/design/agents_examples/sql.yaml b/module/move/assistant/design/agents_examples/sql.yaml
index ca58fdd323..0fcec23fa1 100644
--- a/module/move/assistant/design/agents_examples/sql.yaml
+++ b/module/move/assistant/design/agents_examples/sql.yaml
@@ -1,8 +1,4 @@
 title: DB information extractor
-description: >
-  This system accepts user query for the DB in natural language and converts it into SQL code, which is then passed to a script that will
-  execute this SQL and present the output.
-  This example requires that the script is correctly configured to the real DB.
 
 nodes:
   - id: question_input
@@ -10,23 +6,22 @@ nodes:
     prompt: 'Your query: '
     next: translator
 
-  - id: translator
+  - id: thinker
     type: agent.completion
     # In real life scenario you should specify here:
     # - Which DB is used?
     # - What are the tables and columns?
     # - Schema of the DB.
-    system_message: 'Your task is to translate user query into SQL code for the database.'
+    system_message: 'Your task is to think about how to translate the user query in natural langauge in SQL langauge. Think step by steps.'
     user_message: '{{question_input}}'
     next: query
 
   - id: query
-    type: script
-    # In real life scenario you should add parameters for contacting the DB.
-    cmd: 'query_db {{translator}}'
-    next: output
+    type: agent.completion
+    system_message: 'Your task to make an SQL code based on user query in natural language and the results of thinking on that query'.
+    user_message: 'Query: {{question_input}}. Thoughts: {{thinker}}'
 
   - id: output
     type: event.stdout
-    output: 'Output: {{query}}'
+    output: '{{query}}'
     next: scenario.termination

From 4e3e9017b8c512f469a19a12fed77e7f0e6fa631 Mon Sep 17 00:00:00 2001
From: InAnYan <ruslanpopov1512@gmail.com>
Date: Fri, 15 Nov 2024 18:06:52 +0200
Subject: [PATCH 5/8] Fix from the call

---
 module/move/assistant/design/agents_design.md | 42 ++++++++++++++++---
 .../agents_examples/language_learner.yaml     | 21 +++++-----
 .../design/agents_examples/qa_1.yaml          |  8 ++--
 .../assistant/design/agents_examples/sql.yaml | 36 +++++++---------
 .../design/agents_examples/thinker.yaml       | 10 ++---
 5 files changed, 71 insertions(+), 46 deletions(-)

diff --git a/module/move/assistant/design/agents_design.md b/module/move/assistant/design/agents_design.md
index 0e7f1cf93a..1e16a537aa 100644
--- a/module/move/assistant/design/agents_design.md
+++ b/module/move/assistant/design/agents_design.md
@@ -8,11 +8,45 @@ Main description of such system is writen using **YAML**.
 
 The system consists of **nodes** and **edges**.
 
-Currently, we assume that the only information type passed between nodes is **single text** and nodes are connected as a direct acyclic graph (DAC). Node can take input from several nodes, but it can generate only 1 output.
+Currently, we assume that the only information type passed between nodes is **single text** and nodes are connected as a direct acyclic graph (DAC). Node can take input from other nodes, but it can generate only 1 output.
 
 In future, we can support other types like *list of strings*. *booleans*; we can deliver input to several nodes *in parallel*, etc.
 
-## Nodes
+## YAML description structure
+
+Please refer to `examples/` directory.
+
+## Paths
+
+In several places in YAML file there are values of **paths**. Paths resemble paths in a real file system, parts are delimited with `::`. Absolute path starts from `::`.\
+
+Examples of paths:
+
+- `output`: relative path to single element `output`.
+- `event::stdout`: relative path to `stdout` through `event`.
+- `::trigger::stdin`: absolute path to `stdin` through `trigger`.
+
+Places where paths are used:
+
+- In nodes - `type`: type of the node. Different types of nodes live in different dirs.
+- In nodes - `next`: to which node pass the execution. Nodes live in `::nodes` dir.
+- In nodes - `agent_reuse`: reuse conversation history of previous agent.
+- In templates - `{{...}}`: take output from the node. Output of nodes live in `::output` dir.
+
+All paths (expect absolute) **are subject to absolutization**. This means that every relative path will be implicitly turned out to absolute path. In case of any ambiguities an error will be thrown. Absolutization also depends on the context: in `next` fields paths are absolutized to `::nodes` dir, in templates - to `::output` and so on.
+
+## Execution
+
+YAML file contains section about `nodes:`. You can think of them as statements in a programming language. Next statement is encoded in `next:` field. Output of the nodes are stored in `::output` dir.
+
+## Scenarios referencing
+
+There are two builtin scenarios:
+
+- `::scenario::entry`
+- `::scenario::termination`
+
+## Detailed description of nodes
 
 Each node has an `id` property (its name) and a `type` property.
 
@@ -109,7 +143,3 @@ Current **types**:
 **Description**: when the process of execution is passed to this node, the whole program of the multi-agent system terminates.
 
 This node is **implicitly present in every graph**, and to call it you just need to fill `next:` with the `scenario.terminate`.
-
-## YAML description structure
-
-Please refer to `examples/` directory.
diff --git a/module/move/assistant/design/agents_examples/language_learner.yaml b/module/move/assistant/design/agents_examples/language_learner.yaml
index 06b141dee4..e9199f7844 100644
--- a/module/move/assistant/design/agents_examples/language_learner.yaml
+++ b/module/move/assistant/design/agents_examples/language_learner.yaml
@@ -10,33 +10,32 @@ description: >
 
 nodes:
   - id: question_input
-    type: trigger.stdin
+    type: trigger::stdin
     prompt: 'Your question: '
     next: answer
 
   - id: answer
-    type: agent.completion
+    type: agent::completion
     system_message: 'You are a helpful Q&A assistant. Answer in English'
     user_message: 'Question: {{question_input}}'
-    next: 
-      - translator
-      - frases_extractor
-      - output # TODO: What will happen if output would be called first (or in paralel to other "next"s) but there is no output of `translator` or `frases_extractor`?
+    next: translator
 
   - id: translator
-    type: agent.completion
+    type: agent::completion
     system_message: 'Translate the input in Ukrainian language'
     user_message: '{{answer}}'
+    next: frases_extractor
     
   - id: frases_extractor
-    type: agent.completion
+    type: agent::completion
     system_message: >
       You have a text in English. Extract unique and interesting frases or words from the text
       that would be useful for English language learner. Present the output as a list of pairs:
       the first element is English phrase and the second is Ukrainian translation.
-    user_message: '{{answer}}'
+    user_message: '{{translator}}'
+    next: output
 
   - id: output
-    type: event.stdout
-    output: 'Answer: {{answer}}'
+    type: event::stdout
+    output: 'Answer: {{answer}}. In Ukrainian: {{translator}}. Words: {{frases_extractor}}'
     next: scenario.termination
diff --git a/module/move/assistant/design/agents_examples/qa_1.yaml b/module/move/assistant/design/agents_examples/qa_1.yaml
index 28724b93cb..9570478369 100644
--- a/module/move/assistant/design/agents_examples/qa_1.yaml
+++ b/module/move/assistant/design/agents_examples/qa_1.yaml
@@ -5,18 +5,18 @@ description: >
 
 nodes:
   - id: question_input
-    type: trigger.stdin
+    type: trigger::stdin
     prompt: 'Your question: '
     next: cleaner
 
   - id: cleaner
-    type: agent.completion
+    type: agent::completion
     system_message: 'Correct the orthography and other English mistakes. Make the input clean and easy to understand.'
     user_message: '{{question_input}}'
     next: answer
 
   - id: answer
-    type: agent.completion
+    type: agent::completion
     system_message: 'You are a helpful Q&A assistant.'
     user_message: 'Question: {{cleaner}}'
     next: output
@@ -24,4 +24,4 @@ nodes:
   - id: output
     type: event.stdout
     output: 'Answer: {{answer}}'
-    next: scenario.termination
+    next: scenario::termination
diff --git a/module/move/assistant/design/agents_examples/sql.yaml b/module/move/assistant/design/agents_examples/sql.yaml
index 0fcec23fa1..a465756357 100644
--- a/module/move/assistant/design/agents_examples/sql.yaml
+++ b/module/move/assistant/design/agents_examples/sql.yaml
@@ -1,27 +1,23 @@
-title: DB information extractor
-
-nodes:
-  - id: question_input
-    type: trigger.stdin
+ nodes:
+  - id: input
+    type: trigger::stdin
     prompt: 'Your query: '
-    next: translator
+    next: node::translator
 
-  - id: thinker
-    type: agent.completion
-    # In real life scenario you should specify here:
-    # - Which DB is used?
-    # - What are the tables and columns?
-    # - Schema of the DB.
+  - id: sql_generator_stage1
+    type: agent::completion
     system_message: 'Your task is to think about how to translate the user query in natural langauge in SQL langauge. Think step by steps.'
-    user_message: '{{question_input}}'
-    next: query
+    user_message: '{{input}}'
+    next: node::sql_generator_stage2
 
-  - id: query
-    type: agent.completion
+  - id: sql_generator_stage2
+    type: agent::completion
     system_message: 'Your task to make an SQL code based on user query in natural language and the results of thinking on that query'.
-    user_message: 'Query: {{question_input}}. Thoughts: {{thinker}}'
+    user_message: '{{sql_generator_stage1}}'
+    agent_reuse: node::sql_generator_stage2
+    next: node::output
 
   - id: output
-    type: event.stdout
-    output: '{{query}}'
-    next: scenario.termination
+    type: event::stdout
+    output: '{{sql_generator_stage2}}'
+    next: scenario::termination
\ No newline at end of file
diff --git a/module/move/assistant/design/agents_examples/thinker.yaml b/module/move/assistant/design/agents_examples/thinker.yaml
index ecff5edf55..7df897fc8f 100644
--- a/module/move/assistant/design/agents_examples/thinker.yaml
+++ b/module/move/assistant/design/agents_examples/thinker.yaml
@@ -6,21 +6,21 @@ description: >
 
 nodes:
   - id: question_input
-    type: trigger.stdin
+    type: trigger::stdin
     prompt: 'Your question: '
     next: cleaner
 
   - id: thinker
-    type: agent.completion
+    type: agent::completion
     system_message: > # This system prompt could be improved more, but for the sake of the example, we will leave it simple.
       You are a methodical and knowledgeable assistant tasked with answering user questions thoroughly using a
       chain-of-thought approach. Break down complex queries into components, outline a logical plan, and explain
       each step in detail with examples or analogies as needed.
     user_message: '{{question_input}}'
-    next: answer
+    next: summarizer
 
   - id: summarizer
-    type: agent.completion
+    type: agent::completion
     system_message: >
       You are a summarizer tasked with distilling detailed responses into clear, concise summaries.
       Capture key points and main conclusions, removing unnecessary details while preserving essential meaning and logical flow.
@@ -31,4 +31,4 @@ nodes:
   - id: output
     type: event.stdout
     output: 'Answer: {{summarizer}}'
-    next: scenario.termination
+    next: scenario::termination

From 30a9432525f1bcd243e00724e2b108111268fb8f Mon Sep 17 00:00:00 2001
From: InAnYan <ruslanpopov1512@gmail.com>
Date: Mon, 18 Nov 2024 09:24:50 +0200
Subject: [PATCH 6/8] Remove other examples

---
 module/move/assistant/design/agents_design.md |  1 +
 .../agents_examples/language_learner.yaml     | 41 -------------------
 .../design/agents_examples/qa_1.yaml          | 27 ------------
 .../design/agents_examples/thinker.yaml       | 34 ---------------
 4 files changed, 1 insertion(+), 102 deletions(-)
 delete mode 100644 module/move/assistant/design/agents_examples/language_learner.yaml
 delete mode 100644 module/move/assistant/design/agents_examples/qa_1.yaml
 delete mode 100644 module/move/assistant/design/agents_examples/thinker.yaml

diff --git a/module/move/assistant/design/agents_design.md b/module/move/assistant/design/agents_design.md
index 1e16a537aa..bc95217970 100644
--- a/module/move/assistant/design/agents_design.md
+++ b/module/move/assistant/design/agents_design.md
@@ -102,6 +102,7 @@ Those nodes perform intermediate processing of information. It can be either a m
 - `model`: LLM model name, e.g.: `gpt-4o-mini`, `claude`, etc.
 - `system_message`: system message template.
 - `user_message`: user message template.
+- `agent_reuse`: reuse conversation history from other agent.
 
 `system_message` and `user_message` are templates. Variables available to those templates are **node names**.
 
diff --git a/module/move/assistant/design/agents_examples/language_learner.yaml b/module/move/assistant/design/agents_examples/language_learner.yaml
deleted file mode 100644
index e9199f7844..0000000000
--- a/module/move/assistant/design/agents_examples/language_learner.yaml
+++ /dev/null
@@ -1,41 +0,0 @@
-title: Help in language learning
-description: >
-  This file demonstrates a simple system that will guide user in learning languages.
-  Its main purpose consists of answering user question using another language + providing translation to
-  user's mother tongue + set of used unique words with their translations.
-  For example: user may ask in their language - "why the sky is blue?", the model will then explain it in
-  the target language, then provide a translation of its output in original language, and additionaly
-  the system will provide a set of used frases with their translations.
-  Currently, system is set for English learning for Ukrainian speakers.
-
-nodes:
-  - id: question_input
-    type: trigger::stdin
-    prompt: 'Your question: '
-    next: answer
-
-  - id: answer
-    type: agent::completion
-    system_message: 'You are a helpful Q&A assistant. Answer in English'
-    user_message: 'Question: {{question_input}}'
-    next: translator
-
-  - id: translator
-    type: agent::completion
-    system_message: 'Translate the input in Ukrainian language'
-    user_message: '{{answer}}'
-    next: frases_extractor
-    
-  - id: frases_extractor
-    type: agent::completion
-    system_message: >
-      You have a text in English. Extract unique and interesting frases or words from the text
-      that would be useful for English language learner. Present the output as a list of pairs:
-      the first element is English phrase and the second is Ukrainian translation.
-    user_message: '{{translator}}'
-    next: output
-
-  - id: output
-    type: event::stdout
-    output: 'Answer: {{answer}}. In Ukrainian: {{translator}}. Words: {{frases_extractor}}'
-    next: scenario.termination
diff --git a/module/move/assistant/design/agents_examples/qa_1.yaml b/module/move/assistant/design/agents_examples/qa_1.yaml
deleted file mode 100644
index 9570478369..0000000000
--- a/module/move/assistant/design/agents_examples/qa_1.yaml
+++ /dev/null
@@ -1,27 +0,0 @@
-title: Multi-agent Q&A example
-description: >
-  Demonstrates cleaning of user data, as the user may type fast or include only keywords. 
-  The first agent will turn user query into a valid question, and the second agent will answer it.
-
-nodes:
-  - id: question_input
-    type: trigger::stdin
-    prompt: 'Your question: '
-    next: cleaner
-
-  - id: cleaner
-    type: agent::completion
-    system_message: 'Correct the orthography and other English mistakes. Make the input clean and easy to understand.'
-    user_message: '{{question_input}}'
-    next: answer
-
-  - id: answer
-    type: agent::completion
-    system_message: 'You are a helpful Q&A assistant.'
-    user_message: 'Question: {{cleaner}}'
-    next: output
-
-  - id: output
-    type: event.stdout
-    output: 'Answer: {{answer}}'
-    next: scenario::termination
diff --git a/module/move/assistant/design/agents_examples/thinker.yaml b/module/move/assistant/design/agents_examples/thinker.yaml
deleted file mode 100644
index 7df897fc8f..0000000000
--- a/module/move/assistant/design/agents_examples/thinker.yaml
+++ /dev/null
@@ -1,34 +0,0 @@
-title: Thinker
-description: >
-  This example demonstrates use of 2 agents: the first agent will think thoroughly on the user input.
-  It will utilize prompts like Chain-of-Thought: "Think step by step". This prompt increases the performance
-  of the model tens of times, however it introduces too much output. For that we utilize the second agent.
-
-nodes:
-  - id: question_input
-    type: trigger::stdin
-    prompt: 'Your question: '
-    next: cleaner
-
-  - id: thinker
-    type: agent::completion
-    system_message: > # This system prompt could be improved more, but for the sake of the example, we will leave it simple.
-      You are a methodical and knowledgeable assistant tasked with answering user questions thoroughly using a
-      chain-of-thought approach. Break down complex queries into components, outline a logical plan, and explain
-      each step in detail with examples or analogies as needed.
-    user_message: '{{question_input}}'
-    next: summarizer
-
-  - id: summarizer
-    type: agent::completion
-    system_message: >
-      You are a summarizer tasked with distilling detailed responses into clear, concise summaries.
-      Capture key points and main conclusions, removing unnecessary details while preserving essential meaning and logical flow.
-      But don't forget about code, it should be preserved.
-    user_message: 'Question: {{thinker}}'
-    next: output
-
-  - id: output
-    type: event.stdout
-    output: 'Answer: {{summarizer}}'
-    next: scenario::termination

From 4c171ad946e1307f8d21c2c5a5041868b052d833 Mon Sep 17 00:00:00 2001
From: InAnYan <ruslanpopov1512@gmail.com>
Date: Mon, 18 Nov 2024 09:29:27 +0200
Subject: [PATCH 7/8] Update agents_design.md

---
 module/move/assistant/design/agents_design.md | 81 ++++---------------
 1 file changed, 14 insertions(+), 67 deletions(-)

diff --git a/module/move/assistant/design/agents_design.md b/module/move/assistant/design/agents_design.md
index bc95217970..cc6afe23d0 100644
--- a/module/move/assistant/design/agents_design.md
+++ b/module/move/assistant/design/agents_design.md
@@ -50,7 +50,7 @@ There are two builtin scenarios:
 
 Each node has an `id` property (its name) and a `type` property.
 
-`type` specifies node type in a special format - `category.type`. Number of levels separated by dots may vary.
+`type` specifies node type in a special format - `category::type`. Number of levels separated by dots may vary.
 
 ### Input nodes
 
@@ -58,53 +58,20 @@ These nodes read an input from external environment and pass it to the graph.
 
 Current **types**:
 
-- `trigger.stdin`: stdin input node.
-- `trigger.file`: file input node.
-
-#### Stdin input node
-
-**Description**: retrieves input from user from the command line. A prompt can be supplied additionally.
-
-**Parameters**:
-
-- `prompt`: Text to show before the input, e.g.: `Query: `, `Your question: `, etc.
-
-#### File input node
-
-**Description**: reads file from the `path` parameters and passes to the next node.
-
-**Parameters**:
-
-- `path`: path to the file to read.
+- `trigger::stdin`: stdin input node.
+  Parameters: `prompt`.
+- `trigger::file`: file input node. 
+  Parameters `path`.
 
 ### Processing nodes
 
 Those nodes perform intermediate processing of information. It can be either a mechanical one using an external program, or a real LLM agent.
 
 - `script`: script node.
-- `agent.completion`: agent completion node.
-
-#### Script node
-
-**Description**: takes input from the node, runs the specified program, passes the input to the program's stdin, reads the programs output and passes it to the next node (this refs UNIX philosophy).
-
-**Paramters**:
-
-- `cmd`: command to execute with path to the executable and arguments.
-
-#### Agent completion node
-
-**Description**: the core node type, represents an LLM agent that transforms text in one from to another.
-
-**Parameters**:
-
-- `provider`: LLM provider e.g.: `openai`, `anthropic`, etc.
-- `model`: LLM model name, e.g.: `gpt-4o-mini`, `claude`, etc.
-- `system_message`: system message template.
-- `user_message`: user message template.
-- `agent_reuse`: reuse conversation history from other agent.
-
-`system_message` and `user_message` are templates. Variables available to those templates are **node names**.
+  Parameters: `cmd`.
+- `agent::completion`: agent completion node.
+  Parameters: `provider`, `model`, `system_message`, `user_message`, `agent_reuse`.
+  `system_message` and `user_message` are templates. Variables available to those templates are **node names**.
 
 ### Output nodes
 
@@ -112,24 +79,10 @@ These nodes take an input from other node and present it to the external world.
 
 Current **types**:
 
-- `event.stdout`: stdout output node.
-- `event.file`: file output node.
-
-#### Stdout output node
-
-**Description**: prints the input to the console.
-
-**Parameters**:
-
-- `prefix`: print text before the output, e.g.: `Answer: `, etc.
-
-#### File output node
-
-**Description**: saves input to a file.
-
-**Parameters**:
-
-- `path`: path to save the input.
+- `event::stdout`: stdout output node.
+  Parameters: `output`.
+- `event::file`: file output node.
+  Parameters: `path`.
 
 ### Utility nodes
 
@@ -137,10 +90,4 @@ These nodes are special nodes for various purposes.
 
 Current **types**:
 
-- `scenario.termination`: scenario termination node.
-
-#### Scenario termination node
-
-**Description**: when the process of execution is passed to this node, the whole program of the multi-agent system terminates.
-
-This node is **implicitly present in every graph**, and to call it you just need to fill `next:` with the `scenario.terminate`.
+- `scenario::termination`: scenario termination node.

From ef4fdb612e361cb4c24b164823b1fb4d5f447109 Mon Sep 17 00:00:00 2001
From: InAnYan <ruslanpopov1512@gmail.com>
Date: Mon, 18 Nov 2024 15:58:41 +0200
Subject: [PATCH 8/8] Update agents_design.md

---
 module/move/assistant/design/agents_design.md | 94 ++++---------------
 1 file changed, 19 insertions(+), 75 deletions(-)

diff --git a/module/move/assistant/design/agents_design.md b/module/move/assistant/design/agents_design.md
index cc6afe23d0..a4f9901294 100644
--- a/module/move/assistant/design/agents_design.md
+++ b/module/move/assistant/design/agents_design.md
@@ -1,93 +1,37 @@
 # Agents
 
-## Descirption
-
-This file depicts a general framework for building **multi-agent AI systems**.
-
-Main description of such system is writen using **YAML**.
-
-The system consists of **nodes** and **edges**.
-
-Currently, we assume that the only information type passed between nodes is **single text** and nodes are connected as a direct acyclic graph (DAC). Node can take input from other nodes, but it can generate only 1 output.
-
-In future, we can support other types like *list of strings*. *booleans*; we can deliver input to several nodes *in parallel*, etc.
-
 ## YAML description structure
 
 Please refer to `examples/` directory.
 
 ## Paths
 
-In several places in YAML file there are values of **paths**. Paths resemble paths in a real file system, parts are delimited with `::`. Absolute path starts from `::`.\
-
-Examples of paths:
-
-- `output`: relative path to single element `output`.
-- `event::stdout`: relative path to `stdout` through `event`.
-- `::trigger::stdin`: absolute path to `stdin` through `trigger`.
-
-Places where paths are used:
-
-- In nodes - `type`: type of the node. Different types of nodes live in different dirs.
-- In nodes - `next`: to which node pass the execution. Nodes live in `::nodes` dir.
-- In nodes - `agent_reuse`: reuse conversation history of previous agent.
-- In templates - `{{...}}`: take output from the node. Output of nodes live in `::output` dir.
-
-All paths (expect absolute) **are subject to absolutization**. This means that every relative path will be implicitly turned out to absolute path. In case of any ambiguities an error will be thrown. Absolutization also depends on the context: in `next` fields paths are absolutized to `::nodes` dir, in templates - to `::output` and so on.
+- Used in node types, templates.
+- Parts are delimited with `::`.
+- Absolute path has a leading `::`.
+- All paths (expect absolute) **are subject to absolutization**. Absolutization also depends on the context: in `next` fields paths are absolutized to `::nodes` dir, in templates - to `::output` and so on.
 
 ## Execution
 
-YAML file contains section about `nodes:`. You can think of them as statements in a programming language. Next statement is encoded in `next:` field. Output of the nodes are stored in `::output` dir.
+- YAML file contains section about `nodes:`.
+- Next node is encoded in `next:` field. 
+- Output of the nodes are stored in `::output` dir.
 
-## Scenarios referencing
-
-There are two builtin scenarios:
+## Builtin scenarios
 
 - `::scenario::entry`
 - `::scenario::termination`
 
-## Detailed description of nodes
-
-Each node has an `id` property (its name) and a `type` property.
-
-`type` specifies node type in a special format - `category::type`. Number of levels separated by dots may vary.
-
-### Input nodes
-
-These nodes read an input from external environment and pass it to the graph.
-
-Current **types**:
-
-- `trigger::stdin`: stdin input node.
-  Parameters: `prompt`.
-- `trigger::file`: file input node. 
-  Parameters `path`.
-
-### Processing nodes
-
-Those nodes perform intermediate processing of information. It can be either a mechanical one using an external program, or a real LLM agent.
-
-- `script`: script node.
-  Parameters: `cmd`.
-- `agent::completion`: agent completion node.
-  Parameters: `provider`, `model`, `system_message`, `user_message`, `agent_reuse`.
-  `system_message` and `user_message` are templates. Variables available to those templates are **node names**.
-
-### Output nodes
-
-These nodes take an input from other node and present it to the external world.
-
-Current **types**:
-
-- `event::stdout`: stdout output node.
-  Parameters: `output`.
-- `event::file`: file output node.
-  Parameters: `path`.
-
-### Utility nodes
-
-These nodes are special nodes for various purposes.
+## Node types
 
-Current **types**:
+- Input nodes:
+  - `trigger::stdin`
+  - `trigger::file`
+- Processing nodes:
+  - `script`
+  - `agent::completion`
+- Output nodes:
+  - `event::stdout`
+  - `event::file`
 
-- `scenario::termination`: scenario termination node.
+Refer to examples in `examples/` to see fields of nodes.
\ No newline at end of file