soe-ai 0.1.4__tar.gz → 0.2.0b2__tar.gz

{soe_ai-0.1.4 → soe_ai-0.2.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soe-ai
-Version: 0.1.4
+Version: 0.2.0b2
 Summary: Signal-driven Orchestration Engine - Agent orchestration with event-driven workflow engine
 Author-email: Pedro Garcia <pgarcia14180@gmail.com>
 License-Expression: MIT

{soe_ai-0.1.4 → soe_ai-0.2.0b2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "soe-ai"
-version = "0.1.4"
+version = "0.2.0b2"
 description = "Signal-driven Orchestration Engine - Agent orchestration with event-driven workflow engine"
 readme = "README.md"
 requires-python = ">=3.8"

{soe_ai-0.1.4 → soe_ai-0.2.0b2}/soe/broker.py

@@ -4,18 +4,15 @@ 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(
@@ -73,15 +70,17 @@ 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:
+        if config:
+            validate_config(config)
+            parsed_config = parse_yaml(config)
+            parsed_registry = extract_and_save_config_sections(parsed_config, id, backends)
+    else:
         validate_config(config)
         parsed_config = parse_yaml(config)
         parsed_registry = extract_and_save_config_sections(parsed_config, id, backends)
@@ -93,13 +92,32 @@ def orchestrate(
 
     backends.workflow.save_workflows_registry(id, parsed_registry)
 
-    validate_initial_workflow(initial_workflow_name, 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}"
+        )
 
     backends.workflow.save_current_workflow_name(id, initial_workflow_name)
 
-    context = prepare_initial_context(
-        id, initial_context, backends, inherit_context_from_id
-    )
+    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 = add_operational_state(id, context)
     backends.context.save_context(id, context)

{soe_ai-0.1.4 → soe_ai-0.2.0b2}/soe/docs/guide_01_tool.md

@@ -39,58 +39,6 @@ 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_ai-0.1.4 → soe_ai-0.2.0b2}/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 signals to emit.
+When an LLM node has multiple signals with **conditions** (plain text, not Jinja), the LLM itself decides which signal 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: "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)
+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.
 
@@ -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 any/all signals that apply based on the descriptions |
+| **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:**
@@ -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 select which signals apply (multi-select)
+   - **No (plain text)**: Ask LLM to choose which signal best matches its output
 
 ## Testing LLM Nodes
 

{soe_ai-0.1.4 → soe_ai-0.2.0b2}/soe/docs/primitives/node_reference.md

@@ -44,7 +44,6 @@ 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_ai-0.1.4 → soe_ai-0.2.0b2}/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 can select any/all that apply—including none.
+> **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.
 
 ### Mode 2: Jinja Template (Programmatic)
 
@@ -207,9 +207,8 @@ The behavior depends on the node type:
 │     └─ Zero signals? → Nothing emitted                       │
 │     └─ Single signal? → Emit unconditionally                 │
 │     └─ Multiple signals?                                     │
-│         └─ LLM selects ANY/ALL that apply                    │
+│         └─ LLM selects ONE signal                            │
 │            (uses conditions as semantic descriptions)        │
-│            (can select none, one, or multiple)               │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘
 
@@ -301,7 +300,7 @@ example_workflow:
         condition: "The message is factual, neutral, or emotionally ambiguous"
 ```
 
-**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.
+**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.
 
 ---
 
@@ -628,26 +627,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 signals, SOE:
+When the LLM selects a signal, SOE:
 
-1. **Builds a response model** with a `selected_signals` field (list):
+1. **Builds a response model** with a `selected_signal` field:
    ```python
    class Response(BaseModel):
        response: str
-       selected_signals: List[Literal["POSITIVE", "NEGATIVE", "NEUTRAL"]] = []
+       selected_signal: Literal["POSITIVE", "NEGATIVE", "NEUTRAL"]
    ```
 
 2. **Provides descriptions** from the `condition` field:
    ```
-   Select ALL signals that apply (can be none, one, or multiple):
+   Select one of these signals based on your response:
    - POSITIVE: The message expresses positive sentiment
    - NEGATIVE: The message expresses negative sentiment
    - NEUTRAL: The message is neutral
    ```
 
-3. **Extracts the selection** and emits all selected signals (can be empty).
+3. **Extracts the selection** and emits that signal.
 
-This is why plain-text conditions are called "semantic"—the LLM understands the descriptions and selects all that apply.
+This is why plain-text conditions are called "semantic"—the LLM understands the description and makes a judgment call.
 
 ---