soe-ai 0.2.0b1__py3-none-any.whl

soe/docs/guide_01_tool.md

@@ -0,0 +1,206 @@
+
+# SOE Guide: Chapter 1 - Tool Nodes
+
+## Introduction to Tool Nodes
+
+The **Tool Node** executes a Python function directly. It's the most concrete node type in SOE—it does real work: calling APIs, processing data, interacting with databases.
+
+We start with Tool nodes because they represent **actual execution**. While other nodes route signals or generate text, Tool nodes are where your workflow touches the real world.
+
+### When to Use Tool Nodes
+
+- **External Operations**: Sending emails, processing payments, database queries
+- **API Calls**: HTTP requests, third-party service integrations
+- **Data Transformations**: Calculations, file processing, format conversions
+- **Deterministic Logic**: When you need code, not AI
+
+## Your First Tool Node
+
+Let's send an email using a tool node.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  SendEmail:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: send_email
+    context_parameter_field: email_data
+    output_field: email_result
+    event_emissions:
+      - signal_name: EMAIL_SENT
+```
+
+### How It Works
+
+1.  **`tool_name`**: The key in your `tools_registry` dict.
+2.  **`context_parameter_field`**: The context field containing the tool's kwargs (a dict).
+3.  **`output_field`**: Where to store the result in context.
+4.  **`event_emissions`**: Signals to emit after execution (conditions evaluate `result`).
+
+### Understanding context_parameter_field
+
+The `context_parameter_field` specifies which context field contains the parameters to pass to your tool. This field must contain a dictionary that will be unpacked as keyword arguments.
+
+**Where does this data come from?**
+
+1. **Initial context**: You can pass it when starting the workflow:
+   ```python
+   orchestrate(
+       config=workflow,
+       initial_context={"email_data": {"to": "user@example.com", "subject": "Hello"}}
+   )
+   ```
+
+2. **LLM output**: An LLM node can generate structured parameters:
+   ```yaml
+   ExtractEmailParams:
+     node_type: llm
+     prompt: "Extract email parameters from: {{ context.user_request }}"
+     output_field: email_data  # LLM returns {"to": "...", "subject": "...", "body": "..."}
+
+   SendEmail:
+     node_type: tool
+     tool_name: send_email
+     context_parameter_field: email_data  # Uses LLM output as tool input
+   ```
+
+3. **Another tool's output**: Chain tools together:
+   ```yaml
+   PrepareData:
+     node_type: tool
+     tool_name: prepare_email_data
+     output_field: email_data
+
+   SendEmail:
+     node_type: tool
+     tool_name: send_email
+     context_parameter_field: email_data  # Uses previous tool's output
+   ```
+
+**Tip**: Use [Context Schema](guide_06_schema.md) to validate that LLM output has the correct structure before passing to tools.
+
+### The Tools Registry
+
+Tools are registered as plain Python functions:
+
+```python
+def send_email(to: str, subject: str, body: str) -> dict:
+    # Your email sending logic
+    return {"status": "sent", "to": to}
+
+tools_registry = {
+    "send_email": send_email,
+}
+```
+
+## Event Emissions with Conditions
+
+Tool nodes use `event_emissions` with optional Jinja conditions. Signals without conditions are always emitted on success. Signals with conditions can reference:
+
+- **`result`**: The tool's return value
+- **`context`**: The full workflow context
+
+### Conditional Signal Example
+
+```yaml
+example_workflow:
+  ProcessPayment:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: process_payment
+    context_parameter_field: payment_data
+    output_field: payment_result
+    event_emissions:
+      - signal_name: PAYMENT_SUCCESS
+        condition: "{{ result.status == 'approved' }}"
+      - signal_name: PAYMENT_DECLINED
+        condition: "{{ result.status == 'declined' }}"
+      - signal_name: PAYMENT_PENDING
+        condition: "{{ result.status == 'pending' }}"
+```
+
+### How It Works
+
+1.  Tool executes and stores result in `output_field`.
+2.  Each `event_emissions` condition is evaluated against both `result` and `context`.
+3.  Signals with matching conditions (or no condition) are emitted.
+
+**Note:** `event_emissions` are only evaluated on successful execution. For failure handling, use `failure_signal` in the registry.
+
+### Combining Result and Context
+
+Conditions can use both the tool's output and existing context values:
+
+```yaml
+example_workflow:
+  ProcessPayment:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: process_payment
+    context_parameter_field: payment_data
+    output_field: payment_result
+    event_emissions:
+      - signal_name: PAYMENT_SUCCESS
+        condition: "{{ result.status == 'approved' }}"
+      - signal_name: VIP_PAYMENT_SUCCESS
+        condition: "{{ result.status == 'approved' and context.customer.is_vip }}"
+      - signal_name: LARGE_PAYMENT_SUCCESS
+        condition: "{{ result.status == 'approved' and context.payment_data.amount > 1000 }}"
+```
+
+This is useful when you need to:
+- Combine tool output with customer data (VIP handling)
+- Check result against thresholds from context
+- Route based on both tool success and workflow state
+
+## Extended Tool Registry
+
+For more control over tool behavior, use the extended format:
+
+```python
+tools_registry = {
+    # Simple format (default: max_retries=1)
+    "send_email": send_email,
+
+    # Extended format with configuration
+    "process_payment": {
+        "function": process_payment,
+        "max_retries": 3,  # Retry up to 3 times on failure
+        "failure_signal": "PAYMENT_FAILED",  # Emit when all retries exhausted
+    },
+}
+```
+
+**Extended registry fields:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `function` | Callable | (required) | The Python function to execute |
+| `max_retries` | int | 1 | Number of retries after initial failure |
+| `failure_signal` | str | None | Signal to emit when all retries exhausted |
+| `process_accumulated` | bool | False | Pass full history list (advanced) |
+
+> **Note:** The `process_accumulated` option is an advanced feature for aggregation patterns. It allows a tool to receive the entire history of a context field instead of just the last value. See [Fan-Out, Fan-In & Aggregations](advanced_patterns/guide_fanout_and_aggregations.md) for details.
+
+### Success vs Failure Flow
+
+```
+Tool executes
+    │
+    ├── Success → evaluate event_emissions → emit matching signals
+    │
+    └── Exception → retry up to max_retries
+                        │
+                        └── All retries failed → emit failure_signal (if defined)
+```
+
+**When to use extended format:**
+
+- **Flaky operations**: Set `max_retries` higher for network calls or external APIs
+- **Critical failures**: Use `failure_signal` to handle unrecoverable errors
+
+## Next Steps
+
+Now that you can execute real operations, let's add intelligence with [LLM Nodes](guide_02_llm.md) →

soe/docs/guide_02_llm.md

@@ -0,0 +1,143 @@
+
+# SOE Guide: Chapter 2 - LLM Nodes
+
+## Introduction to LLM Nodes
+
+The **LLM Node** is a simple way to call a language model directly. Unlike Agent nodes (which we'll cover later), LLM nodes make a single call to the model and store the response.
+
+Think of an LLM node as a specialist: it receives context, generates a response, and passes it along.
+
+## Your First LLM Node: Text Summarization
+
+Let's start with a common pattern: summarizing text.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  SimpleLLM:
+    node_type: llm
+    event_triggers: [START]
+    prompt: "Summarize the following text in one sentence: {{ context.text }}"
+    output_field: summary
+    event_emissions:
+      - signal_name: SUMMARY_COMPLETE
+```
+
+### How It Works
+
+1. **Event Trigger**: The `START` signal triggers the `SimpleLLM` node.
+2. **Prompt Rendering**: The Jinja2 template `{{ context.text }}` is replaced with the actual text.
+3. **LLM Call**: The rendered prompt is sent to your LLM provider.
+4. **Output Storage**: The response is stored in `context.summary` (the `output_field`).
+5. **Signal Emission**: `SUMMARY_COMPLETE` is emitted to continue the workflow.
+
+### Key Concepts
+
+- **`prompt`**: A Jinja2 template. Use `{{ context.field }}` to inject context values.
+- **`output_field`**: Where the LLM response is stored in context.
+- **`event_emissions`**: Signals to emit after the LLM call completes.
+
+## Chaining LLM Nodes
+
+LLM nodes become powerful when chained together. Each node can use the output of the previous one.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  Translator:
+    node_type: llm
+    event_triggers: [START]
+    prompt: "Translate the following to Spanish: {{ context.text }}"
+    output_field: spanish_text
+    event_emissions:
+      - signal_name: TRANSLATED
+
+  Summarizer:
+    node_type: llm
+    event_triggers: [TRANSLATED]
+    prompt: "Summarize this Spanish text: {{ context.spanish_text }}"
+    output_field: summary
+    event_emissions:
+      - signal_name: CHAIN_COMPLETE
+```
+
+### How It Works
+
+1. `START` triggers `Translator`
+2. Translator stores Spanish text in `context.spanish_text`
+3. Translator emits `TRANSLATED`
+4. `TRANSLATED` triggers `Summarizer`
+5. Summarizer reads `context.spanish_text` and stores summary
+6. Summarizer emits `CHAIN_COMPLETE`
+
+This pattern is incredibly useful for:
+- Multi-step processing pipelines
+- Translation → Analysis workflows
+- Extract → Transform → Load patterns
+
+## LLM Signal Selection (Resolution Step)
+
+When an LLM node has multiple signals with **conditions** (plain text, not Jinja), the LLM itself decides which signal to emit.
+
+### The Workflow
+
+```yaml
+example_workflow:
+  SentimentAnalyzer:
+    node_type: llm
+    event_triggers: [START]
+    prompt: "Analyze the sentiment of: {{ context.user_message }}"
+    output_field: analysis
+    event_emissions:
+      - signal_name: POSITIVE
+        condition: "The message expresses positive sentiment"
+      - signal_name: NEGATIVE
+        condition: "The message expresses negative sentiment"
+      - signal_name: NEUTRAL
+        condition: "The message is neutral or factual"
+```
+
+### How It Works
+
+1. The LLM analyzes the sentiment
+2. SOE sees multiple signals with plain-text conditions (no `{{ }}`)
+3. SOE asks the LLM: "Based on your analysis, which signal should be emitted?" using the conditions as descriptions
+4. The LLM returns the appropriate signal (POSITIVE, NEGATIVE, or NEUTRAL)
+
+This is called the **resolution step** - it lets the LLM make routing decisions based on its understanding.
+
+### Signal Emission Rules
+
+The `condition` field controls how signals are emitted:
+
+| Condition | Behavior |
+|-----------|----------|
+| **No condition** | Signal is always emitted |
+| **Plain text** | Semantic—LLM selects which signal to emit based on the description |
+| **Jinja template (`{{ }}`)** | Programmatic—evaluated against `context`, emits if truthy |
+
+**How SOE decides:**
+
+1. **No conditions**: All signals emit unconditionally after node execution
+2. **Has conditions**: SOE checks if they contain `{{ }}`:
+   - **Yes (Jinja)**: Evaluate expression against `context`—emit if result is truthy
+   - **No (plain text)**: Ask LLM to choose which signal best matches its output
+
+## Testing LLM Nodes
+
+In tests, we inject a stub function instead of calling a real LLM:
+
+```python
+def stub_llm(prompt: str, config: dict) -> str:
+    return "This is a predictable response."
+
+nodes["llm"] = create_llm_node_caller(backends, stub_llm, broadcast_signals_caller)
+```
+
+The stub knows the *contract* (prompt → response), not the implementation. This keeps tests fast and deterministic.
+
+## Next Steps
+
+Now that you understand LLM nodes, let's see how [Router Nodes](guide_03_router.md) connect your workflows together →

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) →