soe-ai 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

soe/docs/guide_03_router.md

@@ -0,0 +1,146 @@
+
+# SOE Guide: Chapter 3 - Router Nodes
+
+## Introduction to Router Nodes
+
+The **Router** is a pure routing node—it doesn't execute code or call LLMs. It simply reads the context, evaluates conditions, and emits signals to direct the workflow.
+
+Think of a Router as a **traffic controller**: based on the current state (context), it decides which signal to emit, directing the workflow to the next step. Routers are the glue that connects your Tool and LLM nodes together.
+
+### When to Use Router Nodes
+
+- **Entry Points**: Start a workflow and fan out to multiple paths
+- **Conditional Branching**: Route based on context values
+- **Signal Transformation**: Convert one signal to another
+- **Checkpoints**: Create explicit decision points in your workflow
+
+### Why Router Comes Third
+
+We covered Tool and LLM nodes first because they **do work**. Routers don't—they route. Now that you understand the nodes that execute, you can see how Routers connect them into powerful workflows.
+
+## Your First Router: Input Validation
+
+Let's validate that user input exists before processing it.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  InputValidator:
+    node_type: router
+    event_triggers: [START]
+    event_emissions:
+      - signal_name: VALID_INPUT
+        condition: "{{ context.user_input is defined and context.user_input != '' }}"
+      - signal_name: INVALID_INPUT
+        condition: "{{ context.user_input is not defined or context.user_input == '' }}"
+```
+
+### How It Works
+
+1. **Event Trigger**: The `START` signal triggers the `InputValidator` node.
+2. **Condition Evaluation**: The router checks two conditions using Jinja2 templates:
+   - If `context.user_input` is defined and not empty → emit `VALID_INPUT`
+   - If `context.user_input` is missing or empty → emit `INVALID_INPUT`
+3. **Signal Emission**: One or more signals are emitted based on which conditions are true.
+
+### Key Concepts
+
+- **Routers** evaluate Jinja2 conditions and emit signals
+- **Conditions** can check if variables exist, compare values, etc.
+- **Signals** are the "nervous system" of SOE—they trigger the next steps
+
+## Unconditional Signals
+
+Not every router needs a condition. Sometimes you just want to forward a signal unconditionally.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  Forwarder:
+    node_type: router
+    event_triggers: [START]
+    event_emissions:
+      - signal_name: CONTINUE
+```
+
+This router simply receives `START` and immediately emits `CONTINUE`. It's useful when you want to:
+- **Rename signals**: Transform external signals to internal naming
+- **Create checkpoints**: Make workflow structure explicit
+- **Fan-out**: Emit multiple signals to trigger parallel processing
+
+## Decision Trees: Routers Calling Routers
+
+The real power of routers emerges when you chain them together. Since each router emits signals that trigger other nodes, you can build **decision trees** (or more generally, **directed graphs**) where the workflow branches based on context.
+
+### The Pattern
+
+Think of it as a flowchart:
+- **Level 1 Router**: Classifies the initial request
+- **Level 2+ Routers**: Handle sub-cases, triggered by signals from Level 1
+- **Terminal Nodes**: Complete specific branches of the tree
+
+### The Workflow
+
+```yaml
+example_workflow:
+  # Level 1: Is the user premium or free?
+  UserTierCheck:
+    node_type: router
+    event_triggers: [START]
+    event_emissions:
+      - signal_name: PREMIUM_PATH
+        condition: "{{ context.user_tier == 'premium' }}"
+      - signal_name: FREE_PATH
+        condition: "{{ context.user_tier == 'free' }}"
+
+  # Level 2a: Premium users get feature checks
+  PremiumFeatureRouter:
+    node_type: router
+    event_triggers: [PREMIUM_PATH]
+    event_emissions:
+      - signal_name: ENABLE_ADVANCED
+        condition: "{{ context.feature_level == 'advanced' }}"
+      - signal_name: ENABLE_BASIC
+        condition: "{{ context.feature_level != 'advanced' }}"
+
+  # Level 2b: Free users get upgrade prompts
+  FreeUserRouter:
+    node_type: router
+    event_triggers: [FREE_PATH]
+    event_emissions:
+      - signal_name: SHOW_UPGRADE
+        condition: "{{ context.show_upsell }}"
+      - signal_name: CONTINUE_FREE
+        condition: "{{ not context.show_upsell }}"
+```
+
+### How It Works
+
+1. `UserTierCheck` receives `START` and evaluates `context.user_tier`
+2. Depending on the tier, it emits either `PREMIUM_PATH` or `FREE_PATH`
+3. The corresponding router (`PremiumFeatureRouter` or `FreeUserRouter`) activates
+4. That router evaluates its own conditions and emits the final signal
+
+### Why This Matters
+
+- **Modularity**: Each router handles one decision. Easy to test, easy to modify.
+- **Composition**: Add new branches by adding new routers—no need to modify existing ones.
+- **Visibility**: The workflow YAML *is* the flowchart. No hidden logic in code.
+
+## The Three Core Node Types
+
+You now know the three core node types in SOE:
+
+| Node | Purpose | Does Work? |
+|------|---------|-----------|
+| **Tool** | Execute Python functions | ✅ Yes |
+| **LLM** | Call language models | ✅ Yes |
+| **Router** | Route signals based on context | ❌ No (pure routing) |
+
+With just these three nodes, you can build remarkably sophisticated workflows—including custom agent patterns, chain-of-thought reasoning, and more. The next chapter shows you how.
+
+## Next Steps
+
+Now that you understand the three core node types, let's combine them into powerful patterns with [Building Custom Workflows](guide_04_patterns.md) →

soe/docs/guide_04_patterns.md

@@ -0,0 +1,475 @@
+
+# SOE Guide: Chapter 4 - Building Custom Workflows
+
+## The Three Core Node Types
+
+You now know SOE's three core node types:
+
+| Node | What It Does | Key Capability |
+|------|--------------|----------------|
+| **Tool** | Executes Python functions | Real-world actions |
+| **LLM** | Calls language models | Intelligence & generation |
+| **Router** | Routes based on context | Control flow & branching |
+
+These three nodes are **all you need** to build sophisticated AI workflows. This chapter shows you how to combine them into powerful patterns—including building your own agent loops from scratch.
+
+## Why Build Custom Workflows?
+
+The built-in **Agent Node** (covered in the next chapter) provides a convenient ReAct loop. But sometimes you need:
+
+- **Custom reasoning patterns** (chain-of-thought, tree-of-thought, metacognition)
+- **Fine-grained control** over each step
+- **Hybrid logic** mixing deterministic and AI-driven decisions
+- **Domain-specific agent architectures**
+
+With these three core nodes, you can build any pattern—the Agent Node is just one opinionated implementation.
+
+---
+
+## Pattern 1: Chain of Thought
+
+**The Pattern**: Break complex reasoning into explicit steps, where each LLM call builds on the previous one.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  Understand:
+    node_type: llm
+    event_triggers: [START]
+    prompt: "Analyze this problem and restate it in your own words: {{ context.problem }}"
+    output_field: understanding
+    event_emissions:
+      - signal_name: UNDERSTOOD
+
+  Plan:
+    node_type: llm
+    event_triggers: [UNDERSTOOD]
+    prompt: |
+      Based on your understanding: {{ context.understanding }}
+
+      Create a step-by-step plan to solve this problem.
+    output_field: plan
+    event_emissions:
+      - signal_name: PLANNED
+
+  Execute:
+    node_type: llm
+    event_triggers: [PLANNED]
+    prompt: |
+      Understanding: {{ context.understanding }}
+      Plan: {{ context.plan }}
+
+      Now execute the plan and provide the final answer.
+    output_field: answer
+    event_emissions:
+      - signal_name: COMPLETE
+```
+
+### How It Works
+
+1. **Understand**: LLM analyzes and restates the problem
+2. **Plan**: LLM creates a step-by-step plan based on its understanding
+3. **Execute**: LLM generates the final answer using the plan
+
+Each step stores its output in context, and the next step reads it.
+
+### Why This Pattern?
+
+- **Transparency**: Each reasoning step is visible and inspectable
+- **Debuggability**: If the answer is wrong, you can see exactly where reasoning failed
+- **Control**: You can add validation routers between steps
+
+---
+
+## Pattern 2: Custom ReAct Loop
+
+**The Pattern**: Build your own Reasoning + Acting loop using the three core node types.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  Reason:
+    node_type: llm
+    event_triggers: [START, TOOL_RESULT]
+    prompt: |
+      Task: {{ context.task }}
+      {% if context.tool_results %}
+      Previous tool results: {{ context.tool_results }}
+      {% endif %}
+
+      Decide what to do next. If you need to use a tool, output:
+      {"action": "use_tool", "tool": "tool_name", "args": {...}}
+
+      If you have the final answer, output:
+      {"action": "finish", "answer": "your answer"}
+    output_field: decision
+    event_emissions:
+      - signal_name: DECIDED
+
+  Route:
+    node_type: router
+    event_triggers: [DECIDED]
+    event_emissions:
+      - signal_name: USE_TOOL
+        condition: "{{ context.decision.action == 'use_tool' }}"
+      - signal_name: FINISH
+        condition: "{{ context.decision.action == 'finish' }}"
+
+  Act:
+    node_type: tool
+    event_triggers: [USE_TOOL]
+    tool_name: dynamic_tool
+    context_parameter_field: decision
+    output_field: tool_results
+    event_emissions:
+      - signal_name: TOOL_RESULT
+
+  Complete:
+    node_type: router
+    event_triggers: [FINISH]
+    event_emissions:
+      - signal_name: TASK_COMPLETE
+```
+
+### How It Works
+
+1. **Reason**: LLM analyzes the situation and decides what to do
+2. **Route**: Router checks if LLM wants to use a tool or finish
+3. **Act**: If tool needed, execute it and loop back to Reason
+4. **Complete**: When done, emit final signal
+
+### The Loop Structure
+
+```
+┌──────────────────────────────────────────────────────┐
+│                                                      │
+│  ┌─────────┐    ┌─────────┐    ┌─────────┐          │
+│  │ Reason  │───▶│  Route  │───▶│   Act   │──────────┘
+│  │  (LLM)  │    │(Router) │    │ (Tool)  │
+│  └─────────┘    └────┬────┘    └─────────┘
+│                      │
+│                      ▼
+│                 ┌─────────┐
+│                 │Complete │
+│                 │(Router) │
+│                 └─────────┘
+```
+
+This is exactly what the Agent Node does internally—but now you control every piece.
+
+---
+
+## Pattern 3: Metacognition (Self-Reflection)
+
+**The Pattern**: Have the LLM review and critique its own output before finalizing.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  Generate:
+    node_type: llm
+    event_triggers: [START]
+    prompt: "Write a response to: {{ context.request }}"
+    output_field: draft
+    event_emissions:
+      - signal_name: DRAFT_READY
+
+  Critique:
+    node_type: llm
+    event_triggers: [DRAFT_READY]
+    prompt: |
+      Review this response for errors, unclear language, or improvements:
+      {{ context.draft }}
+
+      Output JSON with needs_revision (true or false) and critique fields.
+    output_field: review
+    event_emissions:
+      - signal_name: REVIEWED
+
+  CheckRevision:
+    node_type: router
+    event_triggers: [REVIEWED]
+    event_emissions:
+      - signal_name: REVISE
+        condition: "{{ context.review.needs_revision == true }}"
+      - signal_name: FINALIZE
+        condition: "{{ context.review.needs_revision == false }}"
+
+  Refine:
+    node_type: llm
+    event_triggers: [REVISE]
+    prompt: |
+      Original: {{ context.draft }}
+      Critique: {{ context.review.critique }}
+
+      Write an improved version addressing the feedback.
+    output_field: final_response
+    event_emissions:
+      - signal_name: COMPLETE
+
+  AcceptDraft:
+    node_type: router
+    event_triggers: [FINALIZE]
+    event_emissions:
+      - signal_name: COMPLETE
+```
+
+### How It Works
+
+1. **Generate**: LLM produces an initial response
+2. **Critique**: A second LLM call reviews the response for errors or improvements
+3. **Route**: Check if revision is needed
+4. **Refine** (if needed): Generate improved response based on critique
+5. **Finalize**: Output the best version
+
+### Why This Pattern?
+
+- **Quality improvement**: Catches errors the first pass missed
+- **Self-correction**: The model identifies its own weaknesses
+- **Controllable iteration**: You decide when to stop refining
+
+---
+
+## Pattern 4: Parallel Analysis with Voting
+
+**The Pattern**: Run multiple LLM analyses in parallel, then aggregate results.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  FanOut:
+    node_type: router
+    event_triggers: [START]
+    event_emissions:
+      - signal_name: ANALYZE_SAFETY
+      - signal_name: ANALYZE_QUALITY
+      - signal_name: ANALYZE_RELEVANCE
+
+  SafetyCheck:
+    node_type: llm
+    event_triggers: [ANALYZE_SAFETY]
+    prompt: |
+      Check if this content is safe: {{ context.content }}
+      Return JSON with safe (boolean) and reason (string) fields.
+    output_field: safety_result
+    event_emissions:
+      - signal_name: SAFETY_DONE
+
+  QualityCheck:
+    node_type: llm
+    event_triggers: [ANALYZE_QUALITY]
+    prompt: |
+      Rate the quality of this content: {{ context.content }}
+      Return JSON with score (1-10) and feedback (string) fields.
+    output_field: quality_result
+    event_emissions:
+      - signal_name: QUALITY_DONE
+
+  RelevanceCheck:
+    node_type: llm
+    event_triggers: [ANALYZE_RELEVANCE]
+    prompt: |
+      Check relevance to topic '{{ context.topic }}': {{ context.content }}
+      Return JSON with relevant (boolean) field.
+    output_field: relevance_result
+    event_emissions:
+      - signal_name: RELEVANCE_DONE
+
+  Aggregate:
+    node_type: tool
+    event_triggers: [SAFETY_DONE, QUALITY_DONE, RELEVANCE_DONE]
+    tool_name: aggregate_votes
+    context_parameter_field: vote_params
+    output_field: final_decision
+    event_emissions:
+      - signal_name: APPROVED
+        condition: "{{ result.approved == true }}"
+      - signal_name: REJECTED
+        condition: "{{ result.approved == false }}"
+```
+
+### How It Works
+
+1. **Fan-Out**: Router emits multiple signals simultaneously
+2. **Parallel Analysis**: Multiple LLM nodes run independently
+3. **Aggregate**: Tool collects all analyses and determines consensus
+4. **Route Result**: Based on the aggregated vote
+
+### Why This Pattern?
+
+- **Diversity of perspective**: Different prompts catch different issues
+- **Robustness**: Single LLM errors are outvoted
+- **Speed**: Parallel execution (if your infrastructure supports it)
+
+---
+
+## Pattern 5: Iterative Refinement with Tools
+
+**The Pattern**: LLM generates, tool validates, loop until valid.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  Generate:
+    node_type: llm
+    event_triggers: [START, RETRY]
+    prompt: |
+      Generate Python code for: {{ context.task }}
+      {% if context.errors %}
+      Previous attempt had these errors: {{ context.errors }}
+      Fix them in this attempt.
+      {% endif %}
+    output_field: code
+    event_emissions:
+      - signal_name: CODE_GENERATED
+
+  Validate:
+    node_type: tool
+    event_triggers: [CODE_GENERATED]
+    tool_name: lint_code
+    context_parameter_field: code
+    output_field: validation
+    event_emissions:
+      - signal_name: VALID
+        condition: "{{ result.errors|length == 0 }}"
+      - signal_name: INVALID
+        condition: "{{ result.errors|length > 0 }}"
+
+  PrepareRetry:
+    node_type: router
+    event_triggers: [INVALID]
+    event_emissions:
+      - signal_name: RETRY
+
+  Complete:
+    node_type: router
+    event_triggers: [VALID]
+    event_emissions:
+      - signal_name: CODE_COMPLETE
+```
+
+### How It Works
+
+1. **Generate**: LLM creates code/content
+2. **Validate**: Tool runs linter, tests, or other validation
+3. **Route**: Check validation result
+4. **Loop or Complete**: If invalid, inject errors and regenerate
+
+### The Loop Structure
+
+```
+┌────────────────────────────────────────────────┐
+│                                                │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐ │
+│  │ Generate │───▶│ Validate │───▶│  Route   │─┘
+│  │  (LLM)   │    │  (Tool)  │    │ (Router) │
+│  └──────────┘    └──────────┘    └────┬─────┘
+│                                       │
+│                                       ▼
+│                                 ┌──────────┐
+│                                 │ Complete │
+│                                 └──────────┘
+```
+
+---
+
+## Pattern 6: Hierarchical Task Decomposition
+
+**The Pattern**: Break complex tasks into subtasks, solve each, then synthesize.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  Decompose:
+    node_type: llm
+    event_triggers: [START]
+    prompt: |
+      Break this task into subtasks: {{ context.task }}
+      Output JSON with subtasks array and types array (research, code, writing).
+    output_field: breakdown
+    event_emissions:
+      - signal_name: DECOMPOSED
+
+  RouteSubtasks:
+    node_type: router
+    event_triggers: [DECOMPOSED]
+    event_emissions:
+      - signal_name: DO_RESEARCH
+        condition: "{{ 'research' in context.breakdown.types }}"
+      - signal_name: DO_CODING
+        condition: "{{ 'code' in context.breakdown.types }}"
+      - signal_name: DO_WRITING
+        condition: "{{ 'writing' in context.breakdown.types }}"
+
+  ResearchSubtask:
+    node_type: llm
+    event_triggers: [DO_RESEARCH]
+    prompt: "Research: {{ context.breakdown.subtasks | selectattr('type', 'equalto', 'research') | list }}"
+    output_field: research_result
+    event_emissions:
+      - signal_name: SUBTASK_DONE
+
+  CodingSubtask:
+    node_type: llm
+    event_triggers: [DO_CODING]
+    prompt: "Code: {{ context.breakdown.subtasks | selectattr('type', 'equalto', 'code') | list }}"
+    output_field: code_result
+    event_emissions:
+      - signal_name: SUBTASK_DONE
+
+  Synthesize:
+    node_type: llm
+    event_triggers: [SUBTASK_DONE]
+    prompt: |
+      Combine these results into a final answer:
+      Research: {{ context.research_result }}
+      Code: {{ context.code_result }}
+    output_field: final_answer
+    event_emissions:
+      - signal_name: COMPLETE
+```
+
+### How It Works
+
+1. **Decompose**: LLM breaks the task into subtasks
+2. **Fan-Out**: Router emits signals for each subtask type
+3. **Solve**: Specialized nodes handle each subtask
+4. **Synthesize**: Combine subtask results into final answer
+
+---
+
+## Combining Patterns
+
+The real power comes from combining patterns. For example:
+
+- **Chain-of-Thought + Metacognition**: Reason step-by-step, then self-review
+- **Custom ReAct + Iterative Refinement**: Agent loop with validation gates
+- **Parallel Voting + Hierarchical Decomposition**: Ensemble of specialized agents
+
+Since everything is YAML, you can compose patterns freely.
+
+---
+
+## When to Use Custom Workflows vs Agent Node
+
+| Use Custom Workflows When... | Use Agent Node When... |
+|------------------------------|------------------------|
+| You need non-standard reasoning patterns | Standard ReAct loop is sufficient |
+| You want explicit control over each step | You want hands-off tool-using agent |
+| You're debugging or iterating on agent logic | You need quick prototyping |
+| You need deterministic checkpoints | Tool selection is the main complexity |
+| You're building production systems with audit requirements | Development speed matters most |
+
+The Agent Node is a **convenience**—it encapsulates a common pattern. These custom workflows show you can build anything.
+
+---
+
+## Next Steps
+
+Now that you can build custom agent patterns, see how the built-in [Agent Node](guide_05_agent.md) encapsulates the ReAct pattern for convenience →