quantalogic 0.53.0__py3-none-any.whl → 0.56.0__py3-none-any.whl

quantalogic/flow/flow_yaml.md

@@ -1,21 +1,21 @@
 # Quantalogic Flow YAML DSL Specification 🚀
 
-
-
 ## 1. Introduction 🌟
 
-The **Quantalogic Flow YAML DSL** is a human-readable, declarative language for defining workflows within the `quantalogic.flow` Python package. As of **March 2, 2025**, it empowers developers to automate tasks with a rich feature set:
+The **Quantalogic Flow YAML DSL** is a human-readable, declarative language for defining workflows within the `quantalogic.flow` Python package. As of **March 5, 2025**, it’s packed with features for task automation:
 
 - **Function Execution** ⚙️: Run async Python functions from embedded code, PyPI, local files, or URLs.
-- **Execution Flow** ➡️: Support sequential, conditional, and parallel transitions.
+- **Execution Flow** ➡️: Support sequential, conditional, parallel, branching, and converging transitions.
 - **Sub-Workflows** 🌳: Enable hierarchical, modular designs.
 - **LLM Integration** 🤖: Harness Large Language Models for text or structured outputs.
+- **Template Nodes** 📝: Render dynamic content with Jinja2 templates.
+- **Input Mapping** 🔗: Flexibly map node parameters to context or custom logic.
 - **Context Management** 📦: Share state dynamically across nodes.
 - **Robustness** 🛡️: Include retries, delays, and timeouts.
 - **Observers** 👀: Monitor execution with custom handlers.
 - **Programmatic Control** 🧑‍💻: Manage workflows via `WorkflowManager`.
 
-This DSL integrates with `Workflow`, `WorkflowEngine`, and `Nodes` classes, making it ideal for everything from simple scripts to AI-driven workflows. To illustrate, we’ll use a **Story Generator Workflow** as a running example, derived from `examples/qflow/story_generator_agent.py`. Let’s dive in! 🎉
+This DSL integrates with `Workflow`, `WorkflowEngine`, and `Nodes` classes, making it versatile for everything from simple scripts to complex AI-driven workflows. We’ll use an updated **Story Generator Workflow** as a running example, derived from `examples/flow/simple_story_generator/story_generator_agent.py`, now enhanced with branching, convergence, input mapping, and template nodes. Let’s dive in! 🎉
 
 ```mermaid
 graph TD
@@ -32,12 +32,13 @@ graph TD
 
 ## 2. Workflow Structure 🗺️
 
-A workflow YAML file is divided into four core sections:
+A workflow YAML file comprises five core sections:
 
 - **`functions`**: Python code definitions.
-- **`nodes`**: Task specifications.
-- **`workflow`**: Flow orchestration.
+- **`nodes`**: Task specifications with input mappings and template support.
+- **`workflow`**: Flow orchestration with branching and convergence.
 - **`dependencies`**: Python module dependencies.
+- **`observers`**: Event monitoring.
 
 Here’s the skeleton:
 
@@ -45,9 +46,9 @@ Here’s the skeleton:
 functions:
   # Python magic ✨
 nodes:
-  # Tasks 🎯
+  # Tasks with input mappings & templates 🎯
 workflow:
-  # Flow control 🚦
+  # Flow control with branches & convergence 🚦
 dependencies:
   # Python module dependencies (optional)
 observers:
@@ -55,7 +56,7 @@ observers:
 ```
 
 ### Story Generator Example
-Imagine a workflow that generates a multi-chapter story. We’ll build it step-by-step, starting with its Python form (`story_generator_agent.py`), then its YAML equivalent.
+We’ll evolve the Story Generator to include branching (e.g., based on story tone), convergence (e.g., finalizing the story), **input mapping** for flexible parameter passing, and a **template node** to format chapter summaries—showcasing these shiny new features step-by-step.
 
 ---
 
@@ -63,7 +64,7 @@ Imagine a workflow that generates a multi-chapter story. We’ll build it step-b
 
 ### Python Version (`story_generator_agent.py`)
 
-This script generates a story outline and chapters iteratively:
+This updated script generates a story with tone-based branching, convergence, input mapping, and a template node:
 
 ```python
 #!/usr/bin/env python
@@ -76,90 +77,114 @@ DEFAULT_LLM_PARAMS = {"model": MODEL, "temperature": 0.7, "max_tokens": 1000}
 @Nodes.llm_node(system_prompt="You are a creative writer skilled at generating stories.", 
                 prompt_template="Create a story outline for a {genre} story with {num_chapters} chapters.", 
                 output="outline", **DEFAULT_LLM_PARAMS)
-def generate_outline(genre, num_chapters):
-    return {}
+async def generate_outline(genre: str, num_chapters: int):
+    return ""
+
+@Nodes.llm_node(system_prompt="You are a creative writer.", 
+                prompt_template="Analyze the tone of this outline: {outline}.", 
+                output="tone", **DEFAULT_LLM_PARAMS)
+async def analyze_tone(outline: str):
+    return ""
 
 @Nodes.llm_node(system_prompt="You are a creative writer.", 
                 prompt_template="Write chapter {chapter_num} for this story outline: {outline}. Style: {style}.", 
                 output="chapter", **DEFAULT_LLM_PARAMS)
-def generate_chapter(outline, chapter_num, style):
-    return {}
+async def generate_chapter(outline: str, chapter_num: int, style: str):
+    return ""
+
+@Nodes.llm_node(system_prompt="You are a dramatic writer.", 
+                prompt_template="Write a dramatic chapter {chapter_num} for this outline: {outline}.", 
+                output="chapter", **DEFAULT_LLM_PARAMS)
+async def generate_dramatic_chapter(outline: str, chapter_num: int):
+    return ""
+
+@Nodes.template_node(output="chapter_summary", template="Chapter {chapter_num}: {chapter}")
+async def summarize_chapter(rendered_content: str, chapter: str, chapter_num: int):
+    return rendered_content
 
 @Nodes.define(output="updated_context")
 async def update_progress(**context):
     chapters = context.get('chapters', [])
     completed_chapters = context.get('completed_chapters', 0)
-    chapter = context.get('chapter', '')
-    updated_chapters = chapters + [chapter]
+    chapter_summary = context.get('chapter_summary', '')
+    updated_chapters = chapters + [chapter_summary]
     return {**context, "chapters": updated_chapters, "completed_chapters": completed_chapters + 1}
 
 @Nodes.define(output="continue_generating")
-async def check_if_complete(completed_chapters=0, num_chapters=0, **kwargs):
+async def check_if_complete(completed_chapters: int = 0, num_chapters: int = 0, **kwargs):
     return completed_chapters < num_chapters
 
+@Nodes.define(output="final_story")
+async def finalize_story(chapters: list):
+    return "\n".join(chapters)
+
 workflow = (
     Workflow("generate_outline")
-    .then("generate_chapter")
+    .node("generate_outline", inputs_mapping={"genre": "story_genre", "num_chapters": "chapter_count"})
+    .then("analyze_tone")
+    .branch([
+        ("generate_chapter", lambda ctx: ctx.get("tone") == "light"),
+        ("generate_dramatic_chapter", lambda ctx: ctx.get("tone") == "dark")
+    ])
+    .then("summarize_chapter")
     .then("update_progress")
     .then("check_if_complete")
     .then("generate_chapter", condition=lambda ctx: ctx.get("continue_generating", False))
+    .then("summarize_chapter")
     .then("update_progress")
     .then("check_if_complete")
+    .converge("finalize_story")
 )
 
-def story_observer(event_type, data=None):
-    print(f"Event: {event_type} - Data: {data}")
+def story_observer(event):
+    print(f"Event: {event.event_type.value} - Node: {event.node_name}")
 workflow.add_observer(story_observer)
 
 if __name__ == "__main__":
     async def main():
         initial_context = {
-            "genre": "science fiction",
-            "num_chapters": 3,
+            "story_genre": "science fiction",
+            "chapter_count": 3,
             "chapters": [],
             "completed_chapters": 0,
             "style": "descriptive"
         }
         engine = workflow.build()
         result = await engine.run(initial_context)
-        print(f"Completed chapters: {result.get('completed_chapters', 0)}")
+        print(f"Final Story:\n{result.get('final_story', '')}")
     anyio.run(main)
 ```
 
 ### YAML Version (`story_generator_workflow.yaml`)
 
-Here’s the equivalent YAML:
+Here’s the updated YAML with branching, convergence, input mapping, and a template node:
 
 ```yaml
 functions:
-  generate_outline:
-    type: embedded
-    code: |
-      async def generate_outline(genre: str, num_chapters: int) -> str:
-          return ""
-  generate_chapter:
-    type: embedded
-    code: |
-      async def generate_chapter(outline: str, chapter_num: int, style: str) -> str:
-          return ""
   update_progress:
     type: embedded
     code: |
       async def update_progress(**context):
           chapters = context.get('chapters', [])
           completed_chapters = context.get('completed_chapters', 0)
-          chapter = context.get('chapter', '')
-          return {**context, "chapters": chapters + [chapter], "completed_chapters": completed_chapters + 1}
+          chapter_summary = context.get('chapter_summary', '')
+          updated_chapters = chapters + [chapter_summary]
+          return {**context, "chapters": updated_chapters, "completed_chapters": completed_chapters + 1}
   check_if_complete:
     type: embedded
     code: |
       async def check_if_complete(completed_chapters=0, num_chapters=0, **kwargs):
           return completed_chapters < num_chapters
+  finalize_story:
+    type: embedded
+    code: |
+      async def finalize_story(chapters):
+          return "\n".join(chapters)
   story_observer:
     type: embedded
     code: |
-      def story_observer(event_type, data=None):
-          print(f"Event: {event_type} - Data: {data}")
+      def story_observer(event):
+          print(f"Event: {event.event_type.value} - Node: {event.node_name}")
 
 nodes:
   generate_outline:
@@ -169,7 +194,18 @@ nodes:
       prompt_template: "Create a story outline for a {genre} story with {num_chapters} chapters."
       temperature: 0.7
       max_tokens: 1000
+    inputs_mapping:
+      genre: "story_genre"
+      num_chapters: "chapter_count"
     output: outline
+  analyze_tone:
+    llm_config:
+      model: "gemini/gemini-2.0-flash"
+      system_prompt: "You are a creative writer."
+      prompt_template: "Analyze the tone of this outline: {outline}."
+      temperature: 0.7
+      max_tokens: 1000
+    output: tone
   generate_chapter:
     llm_config:
       model: "gemini/gemini-2.0-flash"
@@ -177,59 +213,104 @@ nodes:
       prompt_template: "Write chapter {chapter_num} for this story outline: {outline}. Style: {style}."
       temperature: 0.7
       max_tokens: 1000
+    inputs_mapping:
+      chapter_num: "completed_chapters"
+      style: "style"
     output: chapter
+  generate_dramatic_chapter:
+    llm_config:
+      model: "gemini/gemini-2.0-flash"
+      system_prompt: "You are a dramatic writer."
+      prompt_template: "Write a dramatic chapter {chapter_num} for this outline: {outline}."
+      temperature: 0.7
+      max_tokens: 1000
+    inputs_mapping:
+      chapter_num: "completed_chapters"
+    output: chapter
+  summarize_chapter:
+    template_config:
+      template: "Chapter {chapter_num}: {chapter}"
+    inputs_mapping:
+      chapter_num: "completed_chapters"
+    output: chapter_summary
   update_progress:
     function: update_progress
     output: updated_context
   check_if_complete:
     function: check_if_complete
     output: continue_generating
+  finalize_story:
+    function: finalize_story
+    output: final_story
 
 workflow:
   start: generate_outline
   transitions:
     - from_node: generate_outline
-      to_node: generate_chapter
+      to_node: analyze_tone
+    - from_node: analyze_tone
+      to_node:
+        - to_node: generate_chapter
+          condition: "ctx['tone'] == 'light'"
+        - to_node: generate_dramatic_chapter
+          condition: "ctx['tone'] == 'dark'"
     - from_node: generate_chapter
+      to_node: summarize_chapter
+    - from_node: generate_dramatic_chapter
+      to_node: summarize_chapter
+    - from_node: summarize_chapter
       to_node: update_progress
     - from_node: update_progress
       to_node: check_if_complete
     - from_node: check_if_complete
       to_node: generate_chapter
       condition: "ctx['continue_generating']"
+  convergence_nodes:
+    - finalize_story
 
 observers:
   - story_observer
 ```
 
-### Mermaid Diagram: Story Generator Flow
+### Mermaid Diagram: Updated Story Generator Flow
 
 ```mermaid
 graph TD
-    A[generate_outline] --> B[generate_chapter]
-    B --> C[update_progress]
-    C --> D[check_if_complete]
-    D -->|"ctx['continue_generating']"| B
-    D -->|else| E[End]
+    A[generate_outline] --> B[analyze_tone]
+    B -->|"'light'"| C[generate_chapter]
+    B -->|"'dark'"| D[generate_dramatic_chapter]
+    C --> E[summarize_chapter]
+    D --> E
+    E --> F[update_progress]
+    F --> G[check_if_complete]
+    G -->|"ctx['continue_generating']"| C
+    G --> H[finalize_story]
+    F --> H
     style A fill:#e6ffe6,stroke:#009933,stroke-width:2px
     style B fill:#e6ffe6,stroke:#009933,stroke-width:2px
     style C fill:#e6ffe6,stroke:#009933,stroke-width:2px
     style D fill:#e6ffe6,stroke:#009933,stroke-width:2px
-    style E fill:#fff0e6,stroke:#cc3300,stroke-width:2px
+    style E fill:#e6ffe6,stroke:#009933,stroke-width:2px
+    style F fill:#e6ffe6,stroke:#009933,stroke-width:2px
+    style G fill:#e6ffe6,stroke:#009933,stroke-width:2px
+    style H fill:#fff0e6,stroke:#cc3300,stroke-width:2px,stroke-dasharray:5
 ```
 
 #### Execution
-With `initial_context = {"genre": "science fiction", "num_chapters": 3, "chapters": [], "completed_chapters": 0, "style": "descriptive"}`:
-1. `generate_outline` creates an outline.
-2. `generate_chapter` writes a chapter.
-3. `update_progress` updates the chapter list and count.
-4. `check_if_complete` loops back if more chapters are needed.
+With `initial_context = {"story_genre": "science fiction", "chapter_count": 3, "chapters": [], "completed_chapters": 0, "style": "descriptive"}`:
+1. `generate_outline` uses input mapping (`story_genre`, `chapter_count`) to create an outline.
+2. `analyze_tone` determines the story’s tone.
+3. Branches to `generate_chapter` (light tone) or `generate_dramatic_chapter` (dark tone), mapping `chapter_num` to `completed_chapters`.
+4. `summarize_chapter` formats the chapter using a template, mapping `chapter_num`.
+5. `update_progress` updates chapters and count with the summary.
+6. `check_if_complete` loops back if more chapters are needed.
+7. Converges at `finalize_story` to compile the final story.
 
 ---
 
 ## 4. Functions ⚙️
 
-The `functions` section defines Python code for reuse.
+The `functions` section defines reusable Python code.
 
 ### Fields 📋
 - `type` (string, required): `"embedded"` or `"external"`.
@@ -238,21 +319,18 @@ The `functions` section defines Python code for reuse.
 - `function` (string, optional): Function name in `module`.
 
 ### Rules ✅
-- Embedded: Use `async def`, name matches key.
+- Embedded: Use `async def` (if async), name matches key.
 - External: Requires `module` and `function`, no `code`.
 
 ### Examples 🌈
 From the story generator:
 ```yaml
 functions:
-  update_progress:
+  finalize_story:
     type: embedded
     code: |
-      async def update_progress(**context):
-          chapters = context.get('chapters', [])
-          completed_chapters = context.get('completed_chapters', 0)
-          chapter = context.get('chapter', '')
-          return {**context, "chapters": chapters + [chapter], "completed_chapters": completed_chapters + 1}
+      async def finalize_story(chapters):
+          return "\n".join(chapters)
 ```
 External example:
 ```yaml
@@ -278,23 +356,14 @@ graph TD
 
 ---
 
----
-
 ## 5. Dependencies 🐍
 
-The `dependencies` section lists Python modules required by the workflow.
+The `dependencies` section lists required Python modules.
 
 ### Fields 📋
-
-- `dependencies` (list, optional): A list of Python module dependencies. Each dependency can be a:
-    - PyPI package name (e.g., `requests>=2.28.0`).
-    - Local file path (e.g., `/path/to/module.py`).
-    - Remote URL (e.g., `https://example.com/module.py`).
-
-These dependencies are processed during workflow instantiation, ensuring that all required modules are available before the workflow starts.
+- `dependencies` (list, optional): PyPI packages (e.g., `requests>=2.28.0`), local paths (e.g., `/path/to/module.py`), or URLs (e.g., `https://example.com/module.py`).
 
 ### Example 🌈
-
 ```yaml
 dependencies:
   - requests>=2.28.0
@@ -306,80 +375,55 @@ dependencies:
 
 ## 6. Nodes 🧩
 
-Nodes are the tasks, powered by functions, sub-workflows, or LLMs.
+Nodes define tasks, now enhanced with **input mappings** and **template nodes**, alongside functions, sub-workflows, and LLMs.
 
 ### Fields 📋
 - `function` (string, optional): Links to `functions`.
 - `sub_workflow` (object, optional):
   - `start` (string)
   - `transitions` (list)
+  - `convergence_nodes` (list, optional)
 - `llm_config` (object, optional):
   - `model` (string, default: `"gpt-3.5-turbo"`)
   - `system_prompt` (string, optional)
   - `prompt_template` (string, default: `"{{ input }}"`)
-  - `prompt_file` (string, optional): Path to an external Jinja2 template file. If provided, the template file will be loaded and rendered with the available context.
-
-To leverage the power of Jinja2 templating directly within your Quantalogic Flow YAML DSL, you can embed Jinja2 syntax within the `prompt_template` field of your `llm_config`. This allows you to dynamically generate prompts based on variables passed from previous nodes or defined within the flow itself. Simply enclose your Jinja2 expressions within `{{ ... }}`. Ensure that the variables you reference are accessible within the scope of the node execution.
-
-Here's an example:
-
-```yaml
-nodes:
-  - id: generate_email
-    type: llm
-    config:
-      llm_config:
-        model: "gpt-4"
-        prompt_template: "Write an email to {{ recipient }} about the upcoming {{ event }}."
-        temperature: 0.7
-    inputs:
-      recipient: ${get_user_details.outputs.email}
-      event: "Company Picnic"
-```
-
-In this example, the `prompt_template` will dynamically generate an email prompt using the `recipient` variable (fetched from the output of the `get_user_details` node) and the `event` variable, which is a hardcoded string in this case.  The LLM will then use the generated prompt to compose the email.
-
+  - `prompt_file` (string, optional): Path to a Jinja2 template file.
   - `temperature` (float, default: `0.7`)
   - `max_tokens` (int, optional)
   - `top_p` (float, default: `1.0`)
   - `presence_penalty` (float, default: `0.0`)
   - `frequency_penalty` (float, default: `0.0`)
   - `response_model` (string, optional)
-- `output` (string, optional): Context key.
+- `template_config` (object, optional):
+  - `template` (string, default: `""`): Jinja2 template string.
+  - `template_file` (string, optional): Path to a Jinja2 template file (overrides `template`).
+- `inputs_mapping` (dict, optional): Maps node parameters to context keys or lambda expressions (e.g., `"lambda ctx: ctx['x'] + 1"`).
+- `output` (string, optional): Context key for the result.
 - `retries` (int, default: `3`)
 - `delay` (float, default: `1.0`)
 - `timeout` (float/null, default: `null`)
 - `parallel` (bool, default: `false`)
 
 ### Rules ✅
-- One of `function`, `sub_workflow`, or `llm_config` per node.
-- LLM inputs come from `prompt_template`.
+- Exactly one of `function`, `sub_workflow`, `llm_config`, or `template_config`.
+- LLM and template inputs derived from `prompt_template`/`template` or `prompt_file`/`template_file`, overridden by `inputs_mapping`.
+- `inputs_mapping` values can be strings (context keys) or serialized lambdas.
 
 ### Examples 🌈
-To use an external Jinja2 template file for your `prompt_template` within a Quantalogic Flow YAML DSL node's `llm_config`, specify the path to your template file using the `prompt_file` field.  The Flow will then load and render this template using Jinja2 with the available context variables during execution. This promotes cleaner YAML and allows for easier template reuse and maintenance.
-
-Here's an example `llm_config` in your YAML:
-
+Using a template node with an external Jinja2 file:
 ```yaml
-llm_config:
-  model: "gpt-3.5-turbo"
-  prompt_file: "templates/my_prompt.j2"
-  temperature: 0.7
-```
-
-And here's a corresponding example of the external Jinja2 template file (`templates/my_prompt.j2`):
-
-```jinja2
-You are a helpful assistant. The user has asked the following:
-
-{{ user_query }}
-
-Please provide a concise and accurate answer.
+nodes:
+  format_report:
+    template_config:
+      template_file: "templates/report.j2"
+    inputs_mapping:
+      title: "report_title"
+      data: "report_data"
+    output: formatted_report
 ```
+(`templates/report.j2`: `Report: {{ title }}\nData: {{ data }}`)
 
-In this example, `{{ user_query }}` will be replaced by the value of the `user_query` variable available in the Flow's context when the template is rendered. Remember to ensure the path specified in `prompt_file` is relative to the Flow's execution directory or an absolute path.
-
-From the story generator:
+With input mapping and an LLM:
 ```yaml
 nodes:
   generate_outline:
@@ -389,40 +433,149 @@ nodes:
       prompt_template: "Create a story outline for a {genre} story with {num_chapters} chapters."
       temperature: 0.7
       max_tokens: 1000
+    inputs_mapping:
+      genre: "story_genre"
+      num_chapters: "lambda ctx: ctx['chapter_count'] + 1"
     output: outline
 ```
 
+From the story generator (template node):
+```yaml
+nodes:
+  summarize_chapter:
+    template_config:
+      template: "Chapter {chapter_num}: {chapter}"
+    inputs_mapping:
+      chapter_num: "completed_chapters"
+    output: chapter_summary
+```
+
 ```mermaid
 graph TD
     A[Node] --> B{Type?}
     B -->|function| C[Function Ref]
-    B -->|sub_workflow| D[Start + Transitions]
+    B -->|sub_workflow| D[Start + Transitions + Convergence]
     B -->|llm_config| E[LLM Setup]
-    E --> F{Structured?}
-    F -->|Yes| G[response_model]
-    F -->|No| H[Plain Text]
+    B -->|template_config| F[Template Setup]
+    A --> G[Inputs Mapping?]
+    G -->|Yes| H[Context Keys or Lambdas]
+    E --> I{Structured?}
+    I -->|Yes| J[response_model]
+    I -->|No| K[Plain Text]
+    F --> L[Jinja2 Template]
     style A fill:#e6ffe6,stroke:#009933,stroke-width:2px
     style B fill:#fff,stroke:#333
     style C fill:#ccffcc,stroke:#009933
     style D fill:#ccffcc,stroke:#009933
     style E fill:#ccffcc,stroke:#009933
-    style F fill:#fff,stroke:#333
-    style G fill:#b3ffb3,stroke:#009933
+    style F fill:#ccffcc,stroke:#009933
+    style G fill:#fff,stroke:#333
     style H fill:#b3ffb3,stroke:#009933
+    style I fill:#fff,stroke:#333
+    style J fill:#b3ffb3,stroke:#009933
+    style K fill:#b3ffb3,stroke:#009933
+    style L fill:#b3ffb3,stroke:#009933
 ```
 
 ---
 
-## 6. Workflow 🌐
+## 6. Input Mapping with LLM Nodes and Template Nodes 🔗
+
+Input mapping allows flexible parameter passing to nodes, enabling dynamic behavior based on workflow context. This is particularly powerful when combined with LLM nodes and template nodes.
+
+### Implementation Details
+
+- **Input Mapping Types**:
+  - Direct context references (e.g., "story_genre")
+  - Lambda expressions (e.g., "lambda ctx: ctx['chapter_count'] + 1")
+  - Static values
+
+- **Supported Node Types**:
+  - LLM nodes
+  - Template nodes
+  - Function nodes
+  - Sub-workflow nodes
+
+### LLM Node Input Mapping
+
+LLM nodes support input mapping for both system prompts and user prompts:
+
+```yaml
+nodes:
+  generate_outline:
+    llm_config:
+      model: "gemini/gemini-2.0-flash"
+      system_prompt: "You are a creative writer skilled in {genre} stories."
+      prompt_template: "Create a story outline for a {genre} story with {num_chapters} chapters."
+    inputs_mapping:
+      genre: "story_genre"  # Map from context
+      num_chapters: "lambda ctx: ctx['chapter_count'] + 1"  # Dynamic value
+    output: outline
+```
 
-The `workflow` section defines execution order.
+### Template Node Input Mapping
+
+Template nodes use mapped inputs in Jinja2 templates:
+
+```yaml
+nodes:
+  summarize_chapter:
+    template_config:
+      template: "Chapter {chapter_num}: {chapter}\n\nSummary: {summary}"
+    inputs_mapping:
+      chapter_num: "current_chapter"
+      chapter: "lambda ctx: ctx['chapters'][ctx['current_chapter']]"
+      summary: "lambda ctx: ctx['summaries'][ctx['current_chapter']]"
+    output: chapter_summary
+```
+
+### Combined Example
+
+Here's an example combining both LLM and template nodes with input mapping:
+
+```yaml
+nodes:
+  generate_character:
+    llm_config:
+      model: "gemini/gemini-2.0-flash"
+      system_prompt: "You are a character designer."
+      prompt_template: "Create a character for a {genre} story."
+    inputs_mapping:
+      genre: "story_genre"
+    output: character_description
+
+  format_character:
+    template_config:
+      template: "Character Profile:\n\n{description}\n\nTraits: {traits}"
+    inputs_mapping:
+      description: "character_description"
+      traits: "lambda ctx: ', '.join(ctx['character_traits'])"
+    output: formatted_character
+```
+
+### Key Points
+
+- Use `inputs_mapping` to map context values to node parameters
+- Support both direct context references and lambda expressions
+- Works seamlessly with LLM, template, and other node types
+- Enables dynamic, context-aware workflows
+- Input mapping is validated against node parameters
+
+---
+
+## 7. Workflow 🌐
+
+The `workflow` section orchestrates execution, leveraging branching and convergence.
 
 ### Fields 📋
 - `start` (string, optional): First node.
 - `transitions` (list):
   - `from_node` (string)
-  - `to_node` (string/list)
-  - `condition` (string, optional)
+  - `to_node` (string or list):
+    - String: Sequential or parallel transition.
+    - List of objects: Branching with `to_node` and `condition`.
+  - `condition` (string, optional): For sequential transitions.
+- `convergence_nodes` (list, optional): Nodes where branches merge.
 
 ### Example 🌈
 From the story generator:
@@ -431,14 +584,26 @@ workflow:
   start: generate_outline
   transitions:
     - from_node: generate_outline
-      to_node: generate_chapter
+      to_node: analyze_tone
+    - from_node: analyze_tone
+      to_node:
+        - to_node: generate_chapter
+          condition: "ctx['tone'] == 'light'"
+        - to_node: generate_dramatic_chapter
+          condition: "ctx['tone'] == 'dark'"
     - from_node: generate_chapter
+      to_node: summarize_chapter
+    - from_node: generate_dramatic_chapter
+      to_node: summarize_chapter
+    - from_node: summarize_chapter
       to_node: update_progress
     - from_node: update_progress
       to_node: check_if_complete
     - from_node: check_if_complete
       to_node: generate_chapter
       condition: "ctx['continue_generating']"
+  convergence_nodes:
+    - finalize_story
 ```
 
 ```mermaid
@@ -449,8 +614,11 @@ graph TD
     D --> E{To Node}
     E -->|Sequential| F[Single Node]
     E -->|Parallel| G[List of Nodes]
-    C --> H[Condition?]
-    H -->|Yes| I[ctx-based Logic]
+    E -->|Branching| H[List with Conditions]
+    C --> I[Condition?]
+    I -->|Yes| J[ctx-based Logic]
+    A --> K[Convergence Nodes]
+    K --> L[Merge Points]
     style A fill:#fff0e6,stroke:#cc3300,stroke-width:2px
     style B fill:#ffe6cc,stroke:#cc3300
     style C fill:#ffe6cc,stroke:#cc3300
@@ -458,17 +626,21 @@ graph TD
     style E fill:#fff,stroke:#333
     style F fill:#ffd9b3,stroke:#cc3300
     style G fill:#ffd9b3,stroke:#cc3300
-    style H fill:#fff,stroke:#333
-    style I fill:#ffd9b3,stroke:#cc3300
+    style H fill:#ffd9b3,stroke:#cc3300
+    style I fill:#fff,stroke:#333
+    style J fill:#ffd9b3,stroke:#cc3300
+    style K fill:#ffe6cc,stroke:#cc3300
+    style L fill:#ffd9b3,stroke:#cc3300
 ```
 
 ---
 
-## 7. Workflow Validation 🕵️‍♀️
+## 8. Workflow Validation 🕵️‍♀️
 
 `validate_workflow_definition()` ensures integrity:
-- Checks node connectivity, circular references, undefined nodes, and missing start.
-- Returns `WorkflowIssue` objects (`node_name`, `description`).
+- Checks node connectivity, circular references, undefined nodes, missing start.
+- Validates branch conditions, convergence points (at least two incoming transitions), and input mappings.
+- Returns `NodeError` objects (`node_name`, `description`).
 
 ### Example
 ```python
@@ -480,9 +652,9 @@ if issues:
 
 ---
 
-## 8. Observers 👀
+## 9. Observers 👀
 
-Monitor events like node starts or failures.
+Monitor events like node starts, completions, or failures.
 
 ### Example
 From the story generator:
@@ -493,26 +665,28 @@ observers:
 
 ---
 
-## 9. Context 📦
+## 10. Context 📦
 
-The `ctx` dictionary shares data:
-- `generate_outline` → `ctx["outline"]`
-- `update_progress` → `ctx["chapters"]`, `ctx["completed_chapters"]`
+The `ctx` dictionary shares data, enhanced by input mappings:
+- `generate_outline` → `ctx["outline"]` (mapped from `story_genre`, `chapter_count`)
+- `summarize_chapter` → `ctx["chapter_summary"]` (mapped from `completed_chapters`)
+- `finalize_story` → `ctx["final_story"]`
 
 ---
 
-## 10. Execution Flow 🏃‍♂️
+## 11. Execution Flow 🏃‍♂️
 
 The `WorkflowEngine`:
 1. Starts at `workflow.start`.
-2. Executes nodes, updates `ctx`.
-3. Follows transitions based on conditions.
-4. Notifies observers.
-5. Ends when transitions are exhausted.
+2. Executes nodes, applying input mappings and updating `ctx`.
+3. Follows transitions (sequential, parallel, or branching) based on conditions.
+4. Converges at specified nodes.
+5. Notifies observers.
+6. Ends when transitions are exhausted.
 
 ---
 
-## 11. Converting Between Python and YAML 🔄
+## 12. Converting Between Python and YAML 🔄
 
 ### Python to YAML (`flow_extractor.py`)
 ```python
@@ -527,7 +701,8 @@ WorkflowManager(wf_def).save_to_yaml("story_generator_workflow.yaml")
 ```python
 from quantalogic.flow.flow_generator import generate_executable_script
 
-manager = WorkflowManager().load_from_yaml("story_generator_workflow.yaml")
+manager = WorkflowManager()
+manager.load_from_yaml("story_generator_workflow.yaml")
 generate_executable_script(manager.workflow, {}, "standalone_story.py")
 ```
 
@@ -546,19 +721,29 @@ graph TD
 
 ---
 
-## 12. WorkflowManager 🧑‍💻
+## 13. WorkflowManager 🧑‍💻
 
-Programmatic workflow creation:
+Programmatic workflow creation with new features:
 ```python
 manager = WorkflowManager()
-manager.add_node("start", llm_config={"model": "grok/xai", "prompt_template": "Say hi"})
+manager.add_node(
+    "start",
+    llm_config={"model": "grok/xai", "prompt_template": "Say hi to {name}"},
+    inputs_mapping={"name": "user_name"}
+)
+manager.add_node(
+    "format",
+    template_config={"template": "Message: {text}"},
+    inputs_mapping={"text": "start_result"}
+)
 manager.set_start_node("start")
+manager.add_transition("start", "format")
+manager.add_convergence_node("format")
 manager.save_to_yaml("hi.yaml")
 ```
 
 ---
 
-## 13. Conclusion 🎉
-
-The Quantalogic Flow YAML DSL (March 2, 2025) is a powerful tool for workflow automation, exemplified by the Story Generator case study. With support for LLMs, flexible flows, and conversion tools, it bridges Python and YAML seamlessly. Whether you’re crafting stories or processing orders, this DSL, paired with `WorkflowManager`, is your key to efficient, scalable workflows. 🚀
+## 14. Conclusion 🎉
 
+The Quantalogic Flow YAML DSL (March 5, 2025) is a powerful, flexible tool for workflow automation, exemplified by the updated Story Generator case study. With new **input mapping** and **template nodes**, alongside LLMs, sub-workflows, branching, convergence, and conversion tools, it seamlessly bridges Python and YAML. Whether crafting dynamic stories with formatted chapters or managing complex processes, this DSL, paired with `WorkflowManager`, unlocks efficient, scalable workflows. 🚀