soe-ai 0.2.0b1__py3-none-any.whl

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 →

soe/docs/guide_05_agent.md

@@ -0,0 +1,159 @@
+
+# SOE Guide: Chapter 5 - Agent Nodes
+
+## Introduction to Agent Nodes
+
+The **Agent Node** is a convenience wrapper that encapsulates the **ReAct pattern** (Reasoning + Acting) into a single, configurable component.
+
+In the previous chapter, you learned how to build custom agent loops using Tool, LLM, and Router nodes. The Agent Node does the same thing—but packaged for common use cases where you want a "hands-off" tool-using agent.
+
+### Why Use Agent Nodes?
+
+| Building Custom (Ch. 4) | Using Agent Node |
+|------------------------|------------------|
+| Full control over each step | Quick to configure |
+| Custom reasoning patterns | Standard ReAct loop |
+| Explicit debugging points | Batteries included |
+| Any architecture you want | Opinionated but effective |
+
+**Use Agent Node when**: You need a straightforward tool-using agent and don't need custom reasoning patterns.
+
+**Use custom workflows when**: You need chain-of-thought, metacognition, voting, or other advanced patterns.
+
+**Note**: Agent nodes can also be used for other patterns (routing, summarization, etc.), but they involve more LLM calls than specialized nodes. Use the right node type for your use case.
+
+### The Agent Loop
+
+The Agent Node runs this loop internally:
+
+1.  **Router Stage**: The agent decides what to do (Call a Tool or Finish)
+2.  **Parameter Stage**: If calling a tool, it generates the arguments
+3.  **Execution Stage**: The tool is executed
+4.  **Loop**: The results are fed back into the history, and the agent decides again
+
+This is exactly what you built manually in Chapter 4's "Custom ReAct Loop" pattern—but as a single node.
+
+### Multiple Tool Calls
+
+The agent can call multiple tools in sequence during a single node execution:
+
+1. Agent decides to call Tool A → executes → sees result
+2. Agent decides to call Tool B → executes → sees result
+3. Agent decides to call Tool A again → executes → sees result
+4. Agent decides to Finish
+
+**Exhaustive tool calling**: The agent will keep calling tools until it decides to finish. There's no hard limit on tool calls—the agent uses its judgment. To prevent runaway loops, use operational limits (see [Operational Features](advanced_patterns/operational.md)).
+
+## Configuring Tools
+
+Agents have access to the tools you provide in their `tools` list.
+
+> [!IMPORTANT]
+> **Tool Restriction**: Agent nodes can ONLY call tools explicitly listed in their `tools` configuration, even if a tool is a SOE built-in. If you want an agent to be able to use a built-in tool like `soe_inject_node`, you must include it in the `tools` list for that node.
+
+### Example: Tool Restriction
+
+```yaml
+MyAgent:
+  node_type: agent
+  tools:
+    - calculate_total     # User tool
+    - soe_inject_node     # Built-in tool (MUST be listed here)
+```
+
+### The Workflow
+
+```yaml
+example_workflow:
+  CalculatorAgent:
+    node_type: agent
+    event_triggers: [START]
+    prompt: "You are a calculator. Solve the user's math problem: {{ context.problem }}"
+    tools: [calculator]
+    output_field: result
+    event_emissions:
+      - signal_name: CALCULATION_DONE
+```
+
+### How It Works
+
+1.  **`tools`**: We give the agent a list of tools (e.g., `[calculator]`).
+2.  **The Loop**:
+    *   The agent sees the prompt: "Solve... {{ context.problem }}"
+    *   It decides to call `calculator(5, 3, 'add')`.
+    *   The tool returns `8`.
+    *   The agent sees the result and decides to **Finish**.
+3.  **Output**: The final answer is stored in `context.result`.
+
+## Advanced Configuration: Multiple Tools
+
+Agents can handle complex tasks with multiple tools.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  ResearchAgent:
+    node_type: agent
+    event_triggers: [START]
+    prompt: "Research the topic: {{ context.topic }}"
+    tools: [search_web, summarize_text]
+    output_field: report
+    event_emissions:
+      - signal_name: REPORT_READY
+```
+
+### Robustness Features
+
+-   **Tool Selection**: The agent intelligently chooses between `search_web` and `summarize_text` based on the goal.
+-   **Error Recovery**: If a tool fails (throws an exception), the agent sees the error and can try again or try a different strategy.
+
+## Agent Signal Selection
+
+Like LLM nodes, Agent nodes can select which signal to emit based on their analysis:
+
+### The Workflow
+
+```yaml
+example_workflow:
+  AnalysisAgent:
+    node_type: agent
+    event_triggers: [START]
+    prompt: "Analyze the data and determine if it needs human review: {{ context.data }}"
+    tools: [analyze_data]
+    output_field: analysis
+    event_emissions:
+      - signal_name: AUTO_APPROVE
+        condition: "The analysis shows the data is clearly valid"
+      - signal_name: NEEDS_REVIEW
+        condition: "The analysis shows the data requires human review"
+      - signal_name: REJECT
+        condition: "The analysis shows the data is clearly invalid"
+```
+
+The agent completes its task, then the signal selection works the same as LLM nodes:
+- **Plain text conditions**: LLM chooses semantically
+- **Jinja conditions**: Evaluated programmatically
+
+## When to Choose Agent vs Custom Workflow
+
+### Use Agent Node For:
+
+- **Quick prototyping**: Get a tool-using agent running fast
+- **Standard tasks**: Research, calculation, data gathering
+- **Simple tool orchestration**: When tool selection is the main complexity
+
+### Build Custom Workflows For:
+
+- **Chain-of-thought reasoning**: Explicit step-by-step thinking
+- **Metacognition**: Self-review and refinement loops
+- **Parallel/voting patterns**: Multiple analyses combined
+- **Hybrid logic**: Mixing deterministic gates with AI
+- **Audit requirements**: When you need to log/inspect each decision
+- **Custom termination conditions**: Beyond simple "finish" detection
+
+Remember: The Agent Node is **syntactic sugar** for a common pattern. Everything it does, you can build yourself with the three core node types.
+
+## Next Steps
+
+Now that you understand both custom workflows and the Agent Node, let's explore [Schemas](guide_06_schema.md) for structured LLM output →