soe-ai 0.2.0b1__py3-none-any.whl → 0.2.0b3__py3-none-any.whl

soe/broker.py

@@ -4,15 +4,18 @@ from .types import Backends, BroadcastSignalsCaller, NodeCaller, EventTypes, Wor
 from .lib.register_event import register_event
 from .lib.yaml_parser import parse_yaml
 from .lib.operational import add_operational_state
-from .lib.context_fields import set_field
 from .lib.parent_sync import get_signals_for_parent
 from .lib.inheritance import (
     inherit_config,
-    inherit_context,
     extract_and_save_config_sections,
+    prepare_initial_context,
+)
+from .validation import (
+    validate_config,
+    validate_operational,
+    validate_orchestrate_params,
+    validate_initial_workflow,
 )
-from .validation import validate_config, validate_operational, validate_orchestrate_params
-from .types import WorkflowValidationError
 
 
 def orchestrate(
@@ -70,17 +73,15 @@ def orchestrate(
 
     id = str(uuid4())
 
+    parsed_registry = {}
     if inherit_config_from_id:
         register_event(
             backends, id, EventTypes.CONFIG_INHERITANCE_START,
             {"source_execution_id": inherit_config_from_id}
         )
         parsed_registry = inherit_config(inherit_config_from_id, id, backends)
-        if config:
-            validate_config(config)
-            parsed_config = parse_yaml(config)
-            parsed_registry = extract_and_save_config_sections(parsed_config, id, backends)
-    else:
+
+    if config:
         validate_config(config)
         parsed_config = parse_yaml(config)
         parsed_registry = extract_and_save_config_sections(parsed_config, id, backends)
@@ -92,32 +93,13 @@ def orchestrate(
 
     backends.workflow.save_workflows_registry(id, parsed_registry)
 
-    if initial_workflow_name not in parsed_registry:
-        available = list(parsed_registry.keys())
-        raise WorkflowValidationError(
-            f"Workflow '{initial_workflow_name}' not found in config. "
-            f"Available workflows: {available}"
-        )
+    validate_initial_workflow(initial_workflow_name, parsed_registry)
 
     backends.workflow.save_current_workflow_name(id, initial_workflow_name)
 
-    if inherit_context_from_id:
-        register_event(
-            backends, id, EventTypes.CONTEXT_INHERITANCE_START,
-        )
-        context = inherit_context(inherit_context_from_id, backends)
-        if initial_context:
-            register_event(
-                backends, id, EventTypes.CONTEXT_MERGE,
-                {"fields": list(initial_context.keys())}
-            )
-            for field, value in initial_context.items():
-                set_field(context, field, value)
-    else:
-        context = {
-            k: [v] if not k.startswith("__") else v
-            for k, v in initial_context.items()
-        }
+    context = prepare_initial_context(
+        id, initial_context, backends, inherit_context_from_id
+    )
 
     context = add_operational_state(id, context)
     backends.context.save_context(id, context)

soe/builtin_tools/soe_update_context.py

@@ -5,6 +5,8 @@ Allows agents to write context fields dynamically.
 
 from typing import Any, Dict
 
+from ..lib.context_fields import set_field
+
 
 def create_soe_update_context_tool(backends, execution_id: str, tools_registry=None):
     """
@@ -41,9 +43,10 @@ def create_soe_update_context_tool(backends, execution_id: str, tools_registry=N
         if not filtered_updates:
             return {"status": "no valid updates (operational fields cannot be updated)"}
 
-        # Get current context and update
+        # Get current context and update using set_field for proper list wrapping
         context = backends.context.get_context(execution_id)
-        context.update(filtered_updates)
+        for field, value in filtered_updates.items():
+            set_field(context, field, value)
         backends.context.save_context(execution_id, context)
 
         return {

soe/docs/guide_01_tool.md

@@ -39,6 +39,58 @@ example_workflow:
 3.  **`output_field`**: Where to store the result in context.
 4.  **`event_emissions`**: Signals to emit after execution (conditions evaluate `result`).
 
+## Passing Parameters to Tools
+
+There are two ways to pass parameters to a tool: **inline parameters** (hardcoded in YAML) or **context parameters** (dynamic from context).
+
+### Option 1: Inline Parameters (Static)
+
+Use `parameters` to specify tool arguments directly in the workflow YAML:
+
+```yaml
+example_workflow:
+  ReadToolDocs:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: soe_explore_docs
+    parameters:
+      path: "soe/docs/guide_01_tool.md"
+      action: "read"
+    output_field: tool_documentation
+    event_emissions:
+      - signal_name: DOCS_READY
+```
+
+**Jinja templates work in parameters:**
+
+```yaml
+example_workflow:
+  FetchUserData:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: fetch_data
+    parameters:
+      user_id: "{{ context.current_user_id }}"
+      include_history: true
+    output_field: user_data
+    event_emissions:
+      - signal_name: DATA_FETCHED
+```
+
+### Option 2: Context Parameters (Dynamic)
+
+Use `context_parameter_field` when the parameters come from another node's output or initial context:
+
+```yaml
+example_workflow:
+  SendEmail:
+    node_type: tool
+    event_triggers: [START]
+    tool_name: send_email
+    context_parameter_field: email_data
+    output_field: email_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.

soe/docs/guide_02_llm.md

@@ -79,7 +79,7 @@ This pattern is incredibly useful for:
 
 ## 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.
+When an LLM node has multiple signals with **conditions** (plain text, not Jinja), the LLM itself decides which signals to emit.
 
 ### The Workflow
 
@@ -103,8 +103,8 @@ example_workflow:
 
 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)
+3. SOE asks the LLM: "Select ALL signals that apply" using the conditions as descriptions
+4. The LLM returns a list of matching signals (can be none, one, or multiple)
 
 This is called the **resolution step** - it lets the LLM make routing decisions based on its understanding.
 
@@ -115,7 +115,7 @@ 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 |
+| **Plain text** | Semantic—LLM selects any/all signals that apply based on the descriptions |
 | **Jinja template (`{{ }}`)** | Programmatic—evaluated against `context`, emits if truthy |
 
 **How SOE decides:**
@@ -123,7 +123,7 @@ The `condition` field controls how signals are emitted:
 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
+   - **No (plain text)**: Ask LLM to select which signals apply (multi-select)
 
 ## Testing LLM Nodes
 

soe/docs/index.md

@@ -81,10 +81,12 @@ Built-in tools enable granular runtime modifications:
 
 | Built-in | Description |
 |----------|-------------|
-| [explore_docs](builtins/explore_docs.md) | Make SOE self-aware by exploring its documentation |
+| [soe_explore_docs](builtins/soe_explore_docs.md) | Make SOE self-aware by exploring its documentation |
 | [workflows](builtins/workflows.md) | Query, inject, and modify workflows at runtime |
 | [context](builtins/context.md) | Read, update, and copy execution context |
 | [tools](builtins/tools.md) | Discover and dynamically call registered tools |
+| [identity](builtins/identity.md) | Query, inject, and remove identity definitions |
+| [context_schema](builtins/context_schema.md) | Query, inject, and remove context schema fields |
 
 ---
 

soe/docs/primitives/node_reference.md

@@ -44,6 +44,7 @@ Complete reference for all node configuration parameters across all node types.
 |-----------|------|--------|-----|-------|------|-------|-------------|
 | `tool_name` | `str` | ✗ | ✗ | ✗ | **R** | ✗ | Tool to execute from registry |
 | `tools` | `List[str]` | ✗ | ✗ | **O** | ✗ | ✗ | Tool names available to agent |
+| `parameters` | `Dict` | ✗ | ✗ | ✗ | **O** | ✗ | Inline tool kwargs (supports Jinja) |
 | `context_parameter_field` | `str` | ✗ | ✗ | ✗ | **O** | ✗ | Context field containing tool kwargs |
 
 ### Child Workflow Parameters

soe/docs/primitives/signals.md

@@ -122,7 +122,7 @@ example_workflow:
 
 Both `PROCESSING_DONE` and `LOG_EVENT` emit every time the node runs.
 
-> **Note**: For Router nodes, multiple unconditional signals all emit simultaneously (fan-out pattern). For LLM/Agent nodes with multiple signals, the LLM must select one - use Jinja conditions like `{{ true }}` if you want all signals to emit.
+> **Note**: For Router nodes, multiple unconditional signals all emit simultaneously (fan-out pattern). For LLM/Agent nodes with multiple signals, the LLM can select any/all that apply—including none.
 
 ### Mode 2: Jinja Template (Programmatic)
 
@@ -207,8 +207,9 @@ The behavior depends on the node type:
 │     └─ Zero signals? → Nothing emitted                       │
 │     └─ Single signal? → Emit unconditionally                 │
 │     └─ Multiple signals?                                     │
-│         └─ LLM selects ONE signal                            │
+│         └─ LLM selects ANY/ALL that apply                    │
 │            (uses conditions as semantic descriptions)        │
+│            (can select none, one, or multiple)               │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘
 
@@ -300,7 +301,7 @@ example_workflow:
         condition: "The message is factual, neutral, or emotionally ambiguous"
 ```
 
-**LLM Selection Mechanism**: SOE adds a `selected_signal` field to the response model, forcing the LLM to choose from the options. The condition text serves as the description.
+**LLM Selection Mechanism**: SOE adds a `selected_signals` field to the response model, allowing the LLM to select any/all signals that apply. The condition text serves as the description.
 
 ---
 
@@ -627,26 +628,26 @@ When the child updates these keys, they're automatically copied to the parent's
 
 ## LLM Signal Selection: Under the Hood
 
-When the LLM selects a signal, SOE:
+When the LLM selects signals, SOE:
 
-1. **Builds a response model** with a `selected_signal` field:
+1. **Builds a response model** with a `selected_signals` field (list):
    ```python
    class Response(BaseModel):
        response: str
-       selected_signal: Literal["POSITIVE", "NEGATIVE", "NEUTRAL"]
+       selected_signals: List[Literal["POSITIVE", "NEGATIVE", "NEUTRAL"]] = []
    ```
 
 2. **Provides descriptions** from the `condition` field:
    ```
-   Select one of these signals based on your response:
+   Select ALL signals that apply (can be none, one, or multiple):
    - POSITIVE: The message expresses positive sentiment
    - NEGATIVE: The message expresses negative sentiment
    - NEUTRAL: The message is neutral
    ```
 
-3. **Extracts the selection** and emits that signal.
+3. **Extracts the selection** and emits all selected signals (can be empty).
 
-This is why plain-text conditions are called "semantic"—the LLM understands the description and makes a judgment call.
+This is why plain-text conditions are called "semantic"—the LLM understands the descriptions and selects all that apply.
 
 ---