quantalogic 0.51.0__py3-none-any.whl → 0.52.1__py3-none-any.whl

quantalogic/flow/flow_yaml.md

@@ -1,20 +1,21 @@
-
 # Quantalogic Flow YAML DSL Specification 🚀
 
+
+
 ## 1. Introduction 🌟
 
-Welcome to the **Quantalogic Flow YAML DSL**—a powerful, human-readable way to craft workflows with the `quantalogic.flow` package! As of **March 1, 2025**, this DSL brings a suite of exciting features to automate complex tasks with ease:
+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:
 
-- **Function Execution** ⚙️: Run async Python functions—embedded or sourced from PyPI, local files, or URLs.
-- **Execution Flow** ➡️: Define sequential, conditional, and parallel transitions.
-- **Sub-Workflows** 🌳: Build hierarchical workflows for modularity.
-- **LLM Integration** 🤖: Leverage Large Language Models with plain text or structured outputs.
-- **Context Management** 📦: Share state across nodes via a dynamic context.
-- **Robustness** 🛡️: Add retries, delays, and timeouts for reliability.
-- **Observers** 👀: Monitor execution with custom event handlers.
-- **Programmatic Power** 🧑‍💻: Control everything via the `WorkflowManager`.
+- **Function Execution** ⚙️: Run async Python functions from embedded code, PyPI, local files, or URLs.
+- **Execution Flow** ➡️: Support sequential, conditional, and parallel transitions.
+- **Sub-Workflows** 🌳: Enable hierarchical, modular designs.
+- **LLM Integration** 🤖: Harness Large Language Models for text or structured outputs.
+- **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 seamlessly with `Workflow`, `WorkflowEngine`, and `Nodes` classes, powering everything from simple scripts to AI-driven workflows. Let’s dive in! 🎉
+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! 🎉
 
 ```mermaid
 graph TD
@@ -27,83 +28,236 @@ graph TD
     style D fill:#fff0e6,stroke:#cc3300
 ```
 
+---
+
 ## 2. Workflow Structure 🗺️
 
-A workflow YAML file is split into three core sections:
+A workflow YAML file is divided into three core sections:
 
-- **`functions`**: Your toolbox of Python functions.
-- **`nodes`**: The building blocks (tasks) of your workflow.
-- **`workflow`**: The roadmap tying it all together.
+- **`functions`**: Python code definitions.
+- **`nodes`**: Task specifications.
+- **`workflow`**: Flow orchestration.
 
 Here’s the skeleton:
 
 ```yaml
 functions:
-  # Your Python magic ✨
+  # Python magic ✨
 nodes:
-  # Tasks to execute 🎯
+  # Tasks 🎯
 workflow:
   # Flow control 🚦
+observers:
+  # Event watchers 👀 (optional)
 ```
 
-## 3. Functions ⚙️
+### 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.
 
-The `functions` section defines reusable Python code—either embedded in the YAML or pulled from external sources.
+---
 
-### Fields 📋
+## 3. Case Study: Story Generator Workflow 📖
 
-- `type` (string, required): `"embedded"` (inline code) or `"external"` (module-based).
-- `code` (string, optional): Multi-line Python code for `embedded`. Use `|` for readability!
-- `module` (string, optional): Source for `external`. Options:
-  - PyPI package (e.g., `"requests"`).
-  - Local path (e.g., `"/path/to/module.py"`).
-  - URL (e.g., `"https://example.com/script.py"`).
-- `function` (string, optional): Function name in the module (for `external`).
+### Python Version (`story_generator_agent.py`)
 
-### Rules ✅
+This script generates a story outline and chapters iteratively:
 
-- Embedded functions must be `async def` and match their dictionary key.
-- External functions need `module` and `function`; no `code` allowed.
-- PyPI modules must be installed (e.g., `pip install requests`).
+```python
+#!/usr/bin/env python
+from quantalogic.flow import Nodes, Workflow
+import anyio
 
-### Examples 🌈
+MODEL = "gemini/gemini-2.0-flash"
+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 {}
+
+@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 {}
+
+@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]
+    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):
+    return completed_chapters < num_chapters
+
+workflow = (
+    Workflow("generate_outline")
+    .then("generate_chapter")
+    .then("update_progress")
+    .then("check_if_complete")
+    .then("generate_chapter", condition=lambda ctx: ctx.get("continue_generating", False))
+    .then("update_progress")
+    .then("check_if_complete")
+)
+
+def story_observer(event_type, data=None):
+    print(f"Event: {event_type} - Data: {data}")
+workflow.add_observer(story_observer)
+
+if __name__ == "__main__":
+    async def main():
+        initial_context = {
+            "genre": "science fiction",
+            "num_chapters": 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)}")
+    anyio.run(main)
+```
+
+### YAML Version (`story_generator_workflow.yaml`)
+
+Here’s the equivalent YAML:
 
-#### Embedded Function
 ```yaml
 functions:
-  greet:
+  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 greet(name: str) -> str:
-          return f"Hello, {name}!"
+      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}
+  check_if_complete:
+    type: embedded
+    code: |
+      async def check_if_complete(completed_chapters=0, num_chapters=0, **kwargs):
+          return completed_chapters < num_chapters
+  story_observer:
+    type: embedded
+    code: |
+      def story_observer(event_type, data=None):
+          print(f"Event: {event_type} - Data: {data}")
+
+nodes:
+  generate_outline:
+    llm_config:
+      model: "gemini/gemini-2.0-flash"
+      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."
+      temperature: 0.7
+      max_tokens: 1000
+    output: outline
+  generate_chapter:
+    llm_config:
+      model: "gemini/gemini-2.0-flash"
+      system_prompt: "You are a creative writer."
+      prompt_template: "Write chapter {chapter_num} for this story outline: {outline}. Style: {style}."
+      temperature: 0.7
+      max_tokens: 1000
+    output: chapter
+  update_progress:
+    function: update_progress
+    output: updated_context
+  check_if_complete:
+    function: check_if_complete
+    output: continue_generating
+
+workflow:
+  start: generate_outline
+  transitions:
+    - from_node: generate_outline
+      to_node: generate_chapter
+    - from_node: generate_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']"
+
+observers:
+  - story_observer
 ```
 
-#### External from PyPI
-```yaml
-functions:
-  fetch:
-    type: external
-    module: requests
-    function: get
+### Mermaid Diagram: 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]
+    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
 ```
-*Note*: Run `pip install requests` first!
 
-#### Local File
+#### 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.
+
+---
+
+## 4. Functions ⚙️
+
+The `functions` section defines Python code for reuse.
+
+### Fields 📋
+- `type` (string, required): `"embedded"` or `"external"`.
+- `code` (string, optional): Inline code for `embedded`.
+- `module` (string, optional): Source for `external` (PyPI, path, URL).
+- `function` (string, optional): Function name in `module`.
+
+### Rules ✅
+- Embedded: Use `async def`, name matches key.
+- External: Requires `module` and `function`, no `code`.
+
+### Examples 🌈
+From the story generator:
 ```yaml
 functions:
-  analyze:
-    type: external
-    module: ./utils/analyze.py
-    function: process_data
+  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}
 ```
-
-#### Remote URL
+External example:
 ```yaml
 functions:
-  compute:
+  fetch:
     type: external
-    module: https://example.com/compute.py
-    function: calculate
+    module: requests
+    function: get
 ```
 
 ```mermaid
@@ -119,83 +273,49 @@ graph TD
     style E fill:#cce6ff,stroke:#0066cc
 ```
 
-## 4. Nodes 🧩
+---
 
-Nodes are the heartbeat of your workflow—each one’s a task, powered by functions, sub-workflows, or LLMs.
+## 5. Nodes 🧩
 
-### Fields 📋
+Nodes are the tasks, powered by functions, sub-workflows, or LLMs.
 
-- `function` (string, optional): Links to a `functions` entry.
-- `sub_workflow` (object, optional): Nested workflow definition.
-  - `start` (string): Starting node.
-  - `transitions` (list): Flow rules (see Workflow section).
-- `llm_config` (object, optional): LLM setup.
-  - `model` (string, default: `"gpt-3.5-turbo"`): e.g., `"gemini/gemini-2.0-flash"`.
-  - `system_prompt` (string, optional): LLM’s role.
-  - `prompt_template` (string, default: `"{{ input }}"`): Jinja2 template (e.g., `"Summarize {{ text }}"`).
-  - `temperature` (float, default: `0.7`): Randomness (0.0–1.0).
-  - `max_tokens` (int, optional): Token limit (e.g., `2000`).
-  - `top_p` (float, default: `1.0`): Nucleus sampling (0.0–1.0).
-  - `presence_penalty` (float, default: `0.0`): Topic repetition (-2.0–2.0).
-  - `frequency_penalty` (float, default: `0.0`): Word repetition (-2.0–2.0).
-  - `response_model` (string, optional): Structured output model (e.g., `"my_module:OrderDetails"`).
-- `output` (string, optional): Context key for results (defaults to `<node_name>_result` for function/LLM nodes).
-- `retries` (int, default: `3`): Retry attempts (≥ 0).
-- `delay` (float, default: `1.0`): Seconds between retries (≥ 0).
-- `timeout` (float/null, default: `null`): Max runtime in seconds.
-- `parallel` (bool, default: `false`): Run concurrently?
+### Fields 📋
+- `function` (string, optional): Links to `functions`.
+- `sub_workflow` (object, optional):
+  - `start` (string)
+  - `transitions` (list)
+- `llm_config` (object, optional):
+  - `model` (string, default: `"gpt-3.5-turbo"`)
+  - `system_prompt` (string, optional)
+  - `prompt_template` (string, default: `"{{ input }}"`)
+  - `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.
+- `retries` (int, default: `3`)
+- `delay` (float, default: `1.0`)
+- `timeout` (float/null, default: `null`)
+- `parallel` (bool, default: `false`)
 
 ### Rules ✅
-
-- Exactly one of `function`, `sub_workflow`, or `llm_config` per node.
-- LLM inputs come from `prompt_template` placeholders (e.g., `{{ text }}` → `text`).
+- One of `function`, `sub_workflow`, or `llm_config` per node.
+- LLM inputs come from `prompt_template`.
 
 ### Examples 🌈
-
-#### Function Node
-```yaml
-nodes:
-  validate:
-    function: validate_order
-    output: is_valid
-    retries: 2
-    timeout: 5.0
-```
-
-#### Sub-Workflow Node
-```yaml
-nodes:
-  payment_flow:
-    sub_workflow:
-      start: pay
-      transitions:
-        - from: pay
-          to: ship
-    output: shipping_status
-```
-
-#### Plain LLM Node
+From the story generator:
 ```yaml
 nodes:
-  summarize:
-    llm_config:
-      model: "gro k/xai"
-      system_prompt: "You’re a concise summarizer."
-      prompt_template: "Summarize: {{ text }}"
-      temperature: 0.5
-    output: summary
-```
-
-#### Structured LLM Node
-```yaml
-nodes:
-  inventory_check:
+  generate_outline:
     llm_config:
       model: "gemini/gemini-2.0-flash"
-      system_prompt: "Check stock."
-      prompt_template: "Items: {{ items }}"
-      response_model: "inventory:StockStatus"
-    output: stock
+      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."
+      temperature: 0.7
+      max_tokens: 1000
+    output: outline
 ```
 
 ```mermaid
@@ -217,54 +337,42 @@ graph TD
     style H fill:#b3ffb3,stroke:#009933
 ```
 
-## 5. Workflow 🌐
-
-The `workflow` section maps out how nodes connect and flow.
-
-### Fields 📋
-
-- `start` (string, optional): First node to run.
-- `transitions` (list): Flow rules.
-  - `from` (string): Source node.
-  - `to` (string/list): Target(s)—string for sequential, list for parallel.
-  - `condition` (string, optional): Python expression (e.g., `"ctx['stock'].available"`).
+---
 
-### Examples 🌈
-
-#### Sequential Flow
-```yaml
-workflow:
-  start: validate
-  transitions:
-    - from: validate
-      to: process
-```
+## 6. Workflow 🌐
 
-#### Conditional Flow
-```yaml
-workflow:
-  start: inventory_check
-  transitions:
-    - from: inventory_check
-      to: payment_flow
-      condition: "ctx['stock'].available"
-```
+The `workflow` section defines execution order.
 
-#### Parallel Flow
+### Fields 📋
+- `start` (string, optional): First node.
+- `transitions` (list):
+  - `from_node` (string)
+  - `to_node` (string/list)
+  - `condition` (string, optional)
+
+### Example 🌈
+From the story generator:
 ```yaml
 workflow:
-  start: payment_flow
+  start: generate_outline
   transitions:
-    - from: payment_flow
-      to: [update_db, send_email]
+    - from_node: generate_outline
+      to_node: generate_chapter
+    - from_node: generate_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']"
 ```
 
 ```mermaid
 graph TD
     A[Workflow] --> B[Start Node]
     A --> C[Transitions]
-    C --> D[From]
-    D --> E{To}
+    C --> D[From Node]
+    D --> E{To Node}
     E -->|Sequential| F[Single Node]
     E -->|Parallel| G[List of Nodes]
     C --> H[Condition?]
@@ -280,138 +388,74 @@ graph TD
     style I fill:#ffd9b3,stroke:#cc3300
 ```
 
-## 6. Observers 👀
+---
+
+## 7. Workflow Validation 🕵️‍♀️
 
-Add observers to watch workflow events (e.g., node start, completion, failures). Define them in `functions` and list them under `observers`.
+`validate_workflow_definition()` ensures integrity:
+- Checks node connectivity, circular references, undefined nodes, and missing start.
+- Returns `WorkflowIssue` objects (`node_name`, `description`).
 
 ### Example
-```yaml
-functions:
-  log_event:
-    type: embedded
-    code: |
-      async def log_event(event):
-          print(f"{event.event_type}: {event.node_name}")
-nodes:
-  task:
-    function: greet
-workflow:
-  start: task
-  transitions: []
-observers:
-  - log_event
+```python
+issues = validate_workflow_definition(workflow)
+if issues:
+    for issue in issues:
+        print(f"Node '{issue.node_name}': {issue.description}")
 ```
 
-## 7. Context 📦
+---
 
-The `ctx` dictionary carries data across nodes:
-- `greet` → `ctx["greeting"] = "Hello, Alice!"`
-- `inventory_check` → `ctx["stock"] = StockStatus(...)`
+## 8. Observers 👀
 
-## 8. Execution Flow 🏃‍♂️
+Monitor events like node starts or failures.
 
-The `WorkflowEngine` runs it all:
-1. Starts at `workflow.start`.
-2. Executes nodes, updating `ctx`.
-3. Follows transitions based on conditions or parallel rules.
-4. Notifies observers of events.
-5. Stops when no transitions remain.
+### Example
+From the story generator:
+```yaml
+observers:
+  - story_observer
+```
 
-## 9. Converting Between Python and YAML 🔄
+---
 
-The `quantalogic.flow` package provides tools to bridge Python-defined workflows and YAML definitions, making your workflows portable and standalone.
+## 9. Context 📦
 
-### From Python to YAML with `flow_extractor.py` 📜
-Want to turn a Python workflow (using `Nodes` and `Workflow`) into a YAML file? Use `quantalogic/flow/flow_extractor.py`! The `extract_workflow_from_file` function parses a Python file, extracting nodes, transitions, functions, and globals into a `WorkflowDefinition`. Then, `WorkflowManager` saves it as YAML. This is perfect for sharing or archiving workflows defined programmatically.
+The `ctx` dictionary shares data:
+- `generate_outline` → `ctx["outline"]`
+- `update_progress` → `ctx["chapters"]`, `ctx["completed_chapters"]`
 
-#### How It Works
-1. **Parse**: `WorkflowExtractor` uses Python’s `ast` module to analyze the file, identifying `@Nodes` decorators (e.g., `define`, `llm_node`) and `Workflow` chaining.
-2. **Extract**: It builds a `WorkflowDefinition` with nodes, transitions, embedded functions, and observers.
-3. **Save**: `WorkflowManager.save_to_yaml` writes it to a YAML file.
+---
 
-#### Example
-```python
-# story_generator.py
-from quantalogic.flow import Nodes, Workflow
+## 10. Execution Flow 🏃‍♂️
 
-@Nodes.define(output="greeting")
-async def say_hello(name: str) -> str:
-    return f"Hello, {name}!"
+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.
 
-workflow = Workflow("say_hello")
+---
 
-# Convert to YAML
+## 11. Converting Between Python and YAML 🔄
+
+### Python to YAML (`flow_extractor.py`)
+```python
 from quantalogic.flow.flow_extractor import extract_workflow_from_file
 from quantalogic.flow.flow_manager import WorkflowManager
 
-wf_def, globals = extract_workflow_from_file("story_generator.py")
-manager = WorkflowManager(wf_def)
-manager.save_to_yaml("story_workflow.yaml")
-```
-**Output (`story_workflow.yaml`)**:
-```yaml
-functions:
-  say_hello:
-    type: embedded
-    code: |
-      @Nodes.define(output="greeting")
-      async def say_hello(name: str) -> str:
-          return f"Hello, {name}!"
-nodes:
-  say_hello:
-    function: say_hello
-    output: greeting
-    retries: 3
-    delay: 1.0
-workflow:
-  start: say_hello
-  transitions: []
+wf_def, globals = extract_workflow_from_file("story_generator_agent.py")
+WorkflowManager(wf_def).save_to_yaml("story_generator_workflow.yaml")
 ```
 
-### From YAML to Standalone Python with `flow_generator.py` 🐍
-Need a self-contained Python script from a `WorkflowDefinition`? `quantalogic/flow/flow_generator.py` has you covered with `generate_executable_script`. It creates an executable file with embedded functions, dependencies, and a `main` function—ready to run anywhere with `uv run`.
-
-#### How It Works
-1. **Generate**: Takes a `WorkflowDefinition` and global variables.
-2. **Structure**: Adds a shebang (`#!/usr/bin/env -S uv run`), dependencies, globals, functions, and workflow chaining.
-3. **Execute**: Sets permissions to make it runnable.
-
-#### Example
+### YAML to Python (`flow_generator.py`)
 ```python
-from quantalogic.flow.flow_manager import WorkflowManager
 from quantalogic.flow.flow_generator import generate_executable_script
 
-manager = WorkflowManager()
-manager.load_from_yaml("story_workflow.yaml")
+manager = WorkflowManager().load_from_yaml("story_generator_workflow.yaml")
 generate_executable_script(manager.workflow, {}, "standalone_story.py")
 ```
-**Output (`standalone_story.py`)**:
-```python
-#!/usr/bin/env -S uv run
-# /// script
-# requires-python = ">=3.12"
-# dependencies = ["loguru", "litellm", "pydantic>=2.0", "anyio", "quantalogic>=0.35", "jinja2", "instructor[litellm]"]
-# ///
-import anyio
-from loguru import logger
-from quantalogic.flow import Nodes, Workflow
-
-@Nodes.define(output="greeting")
-async def say_hello(name: str) -> str:
-    return f"Hello, {name}!"
-
-workflow = Workflow("say_hello")
-
-async def main():
-    initial_context = {"name": "World"}
-    engine = workflow.build()
-    result = await engine.run(initial_context)
-    logger.info(f"Workflow result: {result}")
-
-if __name__ == "__main__":
-    anyio.run(main)
-```
-Run it with `./standalone_story.py`—no extra setup needed (assuming `uv` is installed)!
 
 ```mermaid
 graph TD
@@ -426,81 +470,21 @@ graph TD
     style E fill:#fff0e6,stroke:#cc3300,stroke-width:2px
 ```
 
-## 10. WorkflowManager 🧑‍💻
+---
 
-The `WorkflowManager` lets you build workflows programmatically:
-- Add nodes, transitions, functions, and observers.
-- Load/save YAML.
-- Instantiate a `Workflow` object.
+## 12. WorkflowManager 🧑‍💻
 
-### Example
+Programmatic workflow creation:
 ```python
 manager = WorkflowManager()
-manager.add_function("say_hi", "embedded", code="async def say_hi(name): return f'Hi, {name}!'")
-manager.add_node("start", function="say_hi")
+manager.add_node("start", llm_config={"model": "grok/xai", "prompt_template": "Say hi"})
 manager.set_start_node("start")
 manager.save_to_yaml("hi.yaml")
 ```
 
-## 11. Full Example: Order Processing 📦🤖
-
-```yaml
-functions:
-  validate:
-    type: embedded
-    code: |
-      async def validate(order: dict) -> str:
-          return "valid" if order["items"] else "invalid"
-  track_usage:
-    type: embedded
-    code: |
-      def track_usage(event):
-          if event.usage:
-              print(f"{event.node_name}: {event.usage['total_tokens']} tokens")
-nodes:
-  validate_order:
-    function: validate
-    output: validity
-  check_stock:
-    llm_config:
-      model: "gemini/gemini-2.0-flash"
-      system_prompt: "Check inventory."
-      prompt_template: "Items: {{ items }}"
-      response_model: "shop:Stock"
-    output: stock
-  notify:
-    llm_config:
-      prompt_template: "Order {{ order_id }} status: {{ validity }}"
-    output: message
-workflow:
-  start: validate_order
-  transitions:
-    - from: validate_order
-      to: check_stock
-      condition: "ctx['validity'] == 'valid'"
-    - from: check_stock
-      to: notify
-observers:
-  - track_usage
-```
-
-### Execution
-With `ctx = {"order": {"items": ["book"], "order_id": "123"}}`:
-1. `validate_order` → `ctx["validity"] = "valid"`
-2. `check_stock` → `ctx["stock"] = Stock(...)`
-3. `notify` → `ctx["message"] = "Order 123 status: valid"`
-4. `track_usage` prints token usage for LLM nodes.
-
-```mermaid
-graph TD
-    A["validate_order"] -->|"ctx['validity'] == 'valid'"| B["check_stock"]
-    B --> C["notify"]
-    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
-```
+---
 
-## 12. Conclusion 🎉
+## 13. Conclusion 🎉
 
-The Quantalogic Flow YAML DSL (March 1, 2025) is your go-to for crafting workflows—simple or sophisticated. With tools like `flow_extractor.py` and `flow_generator.py`, you can switch between Python and YAML effortlessly, making workflows portable and standalone. Add PyPI support, sub-workflows, LLM nodes, and observers, and you’ve got a versatile framework for automation and AI tasks. Pair it with `WorkflowManager` for maximum flexibility! 🚀
+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. 🚀