Add documentation for tutorials

.github/PULL_REQUEST_TEMPLATE/feature_template.md

@@ -2,11 +2,11 @@
 A brief overview of what this PR does. Explain the purpose and context.
 
 ## Explain the features implemented:
-	- Feature 1
-	- Feature 2
+- Feature 1
+- Feature 2
 
 ## Performance impact (if any):
-	- Mention about the performance impact if there are any or N/A
+- Mention about the performance impact if there are any or N/A
 
 ## How to Test the feature
 Steps for reviewers to verify functionality:

.github/PULL_REQUEST_TEMPLATE/issue_template.md

@@ -6,8 +6,8 @@ A brief overview of what this PR does. Explain the purpose and context.
 - Relates to #<issue-number>
 
 ## Impacted Features:
-	- Feature 1
-	- Feature 2
+- Feature 1
+- Feature 2
 
 ## How to Test
 Steps for reviewers to verify functionality:

README.md

@@ -57,6 +57,8 @@ For a **complete reference** of all YAML configuration options, node/edge types,
 
 👉 **[Concepts](https://github.com/ServiceNow/GraSP/tree/main/docs/concepts)**
 
+👉 **[Tutorials](https://github.com/ServiceNow/GraSP/tree/main/docs/tutorials)**
+
 👉 **[GraSP Library](https://github.com/ServiceNow/GraSP/blob/main/docs/grasp_library.md)**
 
 ---

docs/concepts/nodes/subgraph_node.md

@@ -9,7 +9,7 @@ You can include a subgraph in your main graph and customize the configuration of
 #### Subgraph Definition (`generate_question` subgraph)
 
 ```yaml
-# Example: tasks/subgraph_examples/subgraphs/generate_question.yaml
+# Example: tasks/examples/custom_subgraphs/generate_question_subgraph/graph_config.yaml
 graph_config:
   nodes:
     persona_sampler:
@@ -51,7 +51,7 @@ graph_config:
 nodes:
   generate_question:
     node_type: subgraph
-    subgraph: tasks.subgraph_examples.subgraphs.generate_question
+    subgraph: tasks.examples.custom_subgraphs.generate_question_subgraph
     node_config_map:
       paraphrase_question:
         output_keys: rephrased_text

docs/tutorials/agent_simulation_tutorial.md

@@ -0,0 +1,162 @@
+# Agent Simulation
+
+This tutorial walks you through creating structured AI agent dialogues with opposing viewpoints using the GraSP framework. By the end, you’ll have built a system that orchestrates realistic, multi-turn conversations between dynamically generated personas on specific topics.
+
+> **Key Features You’ll Learn**  
+> `agent nodes`, `chat history`, `system message intervention`, `multi-turn dialogue`, `multi-agent`
+
+---
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- GraSP framework installed and configured (see [Installation Guide](../installation.md))  
+- A basic understanding of YAML configuration files  
+- Access to an LLM API or local model for generating agent responses  
+
+---
+
+## What You’ll Build
+
+In this tutorial, you’ll create a system that:
+
+- **Generates realistic debates**: Builds authentic dialogues with contrasting perspectives  
+- **Guides conversation arcs**: Manages full conversations from greeting to conclusion  
+- **Uses system interventions**: Injects strategic system messages to guide the flow  
+
+---
+
+## Step 1: Project Structure
+
+Your project directory in this tutorial looks like this:
+
+```
+agent_simulation/
+├── task_executor.py     # Core functionality 
+├── graph_config.yaml    # Workflow graph configuration
+└── categories.json      # Topics for agent conversations
+```
+
+## Step 2: Defining Conversation Topics
+
+The `categories.json` file lists potential conversation topics. Start with a simple example:
+
+```json
+[
+  {
+    "category": "Health",
+    "subcategory": "Yoga"
+  }
+]
+```
+
+You can expand this list with more categories and subcategories as needed.
+
+
+## Step 3: Understanding the Conversation Flow
+
+The simulation follows this workflow:
+
+1. **Topic selection** – The system loads a category/subcategory (e.g., Health/Yoga)  
+2. **Persona generation** – Two distinct personas with opposing viewpoints are created  
+3. **Conversation initialization** – A random agent begins with a greeting  
+4. **Turn-based discussion** – Agents respond to one another, guided by system interventions  
+5. **Conversation conclusion** – Ends when an agent outputs `"FINAL ANSWER"`  
+
+
+## Step 4: Pipeline Implementation
+
+### Graph Configuration (`graph_config.yaml`)
+
+Defines the conversation structure and flow, including:
+
+- **Persona generation**: A node that creates two distinct personas with different viewpoints  
+- **Agent nodes**: Separate nodes for each conversational agent  
+- **System interventions**: Strategic system messages injected at specific turns (e.g., turns 3 and 5)  
+- **Edge conditions**: Rules that control conversation flow and termination  
+
+### Task Executor (`task_executor.py`)
+
+Implements the processing logic for your nodes:
+
+- **Post-processors** – Extract and format agent personas  
+- **Pre-processors** – Prepare agents before each turn  
+- **Edge conditions** – Manage turn switching and when to end the conversation  
+- **Output formatting** – Structure the final conversation output  
+
+### Reference Implementation
+
+See the GraSP repository for complete examples:
+
+- Graph configuration: [`graph_config.yaml`](https://github.com/ServiceNow/GraSP/blob/main/tasks/examples/agent_simulation/graph_config.yaml)  
+- Task executor: [`task_executor.py`](https://github.com/ServiceNow/GraSP/blob/main/tasks/examples/agent_simulation/task_executor.py)  
+
+
+## Step 5: Creating Your Own Implementation
+
+To build your own simulation:
+
+1. **Define agent personas** – Generate distinct personas with opposing viewpoints  
+2. **Set up turn taking** – Implement sequential agent responses  
+3. **Add system interventions** – Configure strategic message injections (e.g., to deepen debate or wrap up)  
+4. **Define conversation flow** – Create edge conditions to control agent switching and termination  
+5. **Format output** – Generate structured conversation history and taxonomy  
+
+
+## Step 6: Running the Simulation
+
+From your GraSP project root, run:
+
+```bash
+python main.py --task path/to/your/agent_simulation
+```
+
+---
+
+## Try It Yourself
+
+Extend this tutorial by:
+
+1. **Adding more topics** – Expand `categories.json` with new categories and subcategories  
+2. **Creating personality modifiers** – Add debate styles to your persona generator  
+3. **Adding emotional trajectories** – Guide the emotional tone of the conversation  
+
+---
+
+## Example Output
+
+Here’s a sample output (your results will vary based on LLM responses):
+
+```json
+[
+  {
+    "id": "<conversation_id>",
+    "conversation": [
+      {
+        "user": "Open the dialogue with respectful greetings. Remain in character and begin discussing the assigned topic."
+      },
+      {
+        "agent_2": "Hello. Let's dive into the subject of yoga. I'm interested in its physical benefits, but I’m skeptical about the spiritual claims. What evidence supports these?"
+      },
+      {
+        "agent_1": "Greetings. Yoga’s physical benefits are well-documented, but its mental and spiritual aspects are harder to quantify. Still, studies link yoga to reduced anxiety and improved mindfulness, which many practitioners interpret as spiritual growth. How does that align with your perspective?"
+      }
+      // Additional turns omitted for brevity
+    ],
+    "taxonomy": [
+      {
+        "category": "Health",
+        "subcategory": "Yoga"
+      }
+    ]
+  }
+]
+```
+
+---
+
+## Next Steps
+
+- Learn how to [use tool interventions](agent_tool_simulation_tutorial.md) for more grounded conversations  
+- Explore [structured output](structured_output_tutorial.md) to format results  

docs/tutorials/agent_tool_simulation_tutorial.md

@@ -0,0 +1,142 @@
+# Agent Simulation with Tools
+
+This tutorial guides you through integrating external tools with AI agents using the GraSP framework. By the end, you’ll have a system where agents can call mathematical functions implemented as Python modules, classes, or standalone functions.
+
+> **Key Features You’ll Learn**  
+> `function calling`, `tool integration`, `mathematical operations`, `class-based tools`, `module-based tools`
+
+---
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- GraSP framework installed and configured (see [Installation Guide](../installation.md))
+- Basic understanding of Python modules and function/class definitions
+- Access to an LLM API or local model for agent reasoning
+
+---
+
+## What You’ll Build
+
+You’ll create an agent that:
+
+- **Receives math queries** (e.g., "Multiply 2 and 3, then subtract 1")
+- **Selects and calls appropriate tools** (addition, subtraction, multiplication, division)
+- **Combines tool outputs** to produce a final answer
+
+---
+
+## Step 1: Project Structure
+
+Directory structure in this tutorial:
+
+```
+agent_tool_simulation/
+├── task_executor.py         # Post-processing logic for tool-using agent
+├── graph_config.yaml        # Workflow graph and tool imports
+├── tools.py                 # Standalone function tools
+├── tools_from_class.py      # Tools as class methods
+├── tools_from_module.py     # Tools as module-level functions
+├── user_queries.json        # Sample math queries
+```
+
+## Step 2: Defining Tools and Queries
+
+- `tools.py`: Functions like `add(a, b)`
+- `tools_from_class.py`: Class with methods for subtraction/division
+- `tools_from_module.py`: Module with multiplication, etc.
+- `user_queries.json`: Sample queries, e.g.:
+
+```json
+[
+  { "user_query": "What is 3/2?" },
+  { "user_query": "What is (2+3)*5?" }
+]
+```
+
+## Step 3: Workflow Overview
+
+1. **Query Loading**: System loads questions from `user_queries.json`
+2. **Tool Configuration**: Agent is given access to all relevant tools
+3. **Agent Processing**:
+   - Receives a query
+   - Decides which tools to call and in what order
+   - Calls tools via function calling
+   - Combines results
+4. **Result Capture**: Post-processor extracts the answer for output
+
+## Step 4: Pipeline Implementation
+
+### Graph Configuration (`graph_config.yaml`)
+
+The `graph_config.yaml` file defines the workflow for the agent tool simulation task. Here’s what it does:
+
+- **Data Source**: Specifies that user queries are loaded from `user_queries.json`.
+- **Nodes**: Defines a single `math_agent` node of type `agent`. This node is configured with:
+  - **Tools**: Lists all available mathematical tools, including standalone functions, class-based methods, and module-level tools. These are imported and made available for function calling by the agent.
+  - **Prompt**: Provides the system and user prompts, instructing the agent on how to use the tools for arithmetic operations.
+  - **Model**: Sets the LLM to use (e.g., gpt-4o) and its parameters.
+- **Edges**: Establishes the flow from `START` to `math_agent` and then to `END`, representing a single-step reasoning process.
+- **Output Config**: Maps the output fields (`id`, `user_query`, `math_result`) from the agent’s state to the final output structure.
+
+### Task Executor (`task_executor.py`)
+
+The `task_executor.py` file implements the post-processing logic for the agent node:
+
+- **MathAgentPostProcessor**: This class extracts the agent’s answer from the LLM response and stores it in the state under the key `math_result`. This enables the output mapping defined in the graph config.
+- The post-processor ensures that the final output always contains the computed answer in a structured format.
+
+### Reference Implementation
+
+See the GraSP repository for complete examples:
+
+- Graph configuration: [agent_tool_simulation/graph_config.yaml](https://github.com/ServiceNow/GraSP/blob/main/tasks/examples/agent_tool_simulation/graph_config.yaml)
+- Task Executor: [agent_tool_simulation/task_executor.py](https://github.com/ServiceNow/GraSP/blob/main/tasks/examples/agent_tool_simulation/task_executor.py)
+
+## Step 5: Running the Simulation
+
+From your GraSP project root, run:
+
+```bash
+python main.py --task path/to/your/agent_tool_simulation
+```
+
+---
+
+## Example Output
+
+```json
+[
+    {
+        "id": "6b9e75c4fe9b803f0c6f1dd59081750fa100db56874a12b0b83683b7ea9a0c8b",
+        "user_query": "Can you give me answer for 3/2?",
+        "math_result": "The result of ( 3/2 ) is 1.5."
+    },
+    {
+        "id": "e79908ac2f64bbdf7611c307ba3b73f647a2bbcf06d42e9c16c6321aa9ac3e1d",
+        "user_query": "Can you give me answer for (2+3)*5?",
+        "math_result": "The answer to ((2+3) × 5) is (25)."
+    },
+    {
+        "id": "6af6cadbfaa3eda3b9eb678dece24dac211c8bd3cd62e8742d8364422cfeecb2",
+        "user_query": "Can you give me answer for multiplying 2 and 3 and then subtract 1 from answer?",
+        "math_result": "The result of multiplying 2 and 3 and then subtracting 1 is 5."
+    }
+]
+```
+
+---
+
+## Try It Yourself
+
+- Add more mathematical tools (e.g., exponentiation)
+- Modify `user_queries.json` with new queries
+- Implement more complex reasoning chains
+
+---
+
+## Next Steps
+
+- Explore [agent simulation](agent_simulation_tutorial.md) for multi-agent conversations
+- Learn about [structured output](structured_output_tutorial.md) for standardized results