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

soe/nodes/agent/types.py

@@ -0,0 +1,66 @@
+"""
+Agent node models and data structures
+"""
+
+from typing import Any, Dict, List, Literal, Optional
+from pydantic import BaseModel, Field
+
+
+class AgentRequest(BaseModel):
+    """Request sent to agent - includes everything needed to build a complete prompt"""
+
+    agent_id: str
+    prompt: str
+    agent_config: Dict[str, Any]
+    tool_responses: Dict[str, Any] = {}
+
+
+class AgentResponse(BaseModel):
+    """Validated agent response with mutually exclusive types:
+    - Tool response: Only tool_calls + minimal context
+    - Signal response: Only emitted_signals + context (THE END)
+    - Clarification response: Only needs_clarification + message
+    """
+
+    output: Any = None
+
+    tool_calls: Dict[str, Any] = {}
+    emitted_signals: List[str] = []
+    needs_clarification: bool = False
+    clarification_message: str = ""
+
+
+class RouterInput(BaseModel):
+    """Input model for the Router stage prompt."""
+    instructions: str = Field(description="State-specific instructions for the router")
+    task_description: str
+    context: str
+    available_tools: str
+    conversation_history: str = ""
+
+
+class RouterResponse(BaseModel):
+    """Output model for the Router stage."""
+    action: Literal["call_tool", "finish"]
+    tool_name: Optional[str] = Field(None, description="Name of the tool to call. Required if action is 'call_tool'.")
+
+
+class ParameterInput(BaseModel):
+    """Input for Parameter stage prompt."""
+    task_description: str
+    context: str
+    tool_name: str
+    conversation_history: str = ""
+
+
+class ResponseStageInput(BaseModel):
+    """Input model for the Response stage prompt."""
+    task_description: str
+    context: str
+    conversation_history: str = ""
+
+
+class FinalResponse(BaseModel):
+    """Standardized output from the Response stage."""
+    output: Any
+    selected_signal: Optional[str] = None

soe/nodes/agent/validation/__init__.py

@@ -0,0 +1,11 @@
+"""
+Agent node validation.
+
+- config.py: Config validation at orchestration start
+- operational.py: Runtime validation before execution (fail-fast)
+"""
+
+from .config import validate_node_config
+from .operational import validate_agent_node_runtime
+
+__all__ = ["validate_node_config", "validate_agent_node_runtime"]

soe/nodes/agent/validation/config.py

@@ -0,0 +1,95 @@
+"""
+Agent node configuration validation.
+
+Called once at orchestration start, not during node execution.
+"""
+
+from typing import Dict, Any, List
+from ....types import WorkflowValidationError
+
+
+def validate_node_config(node_config: Dict[str, Any]) -> None:
+    """
+    Validate agent node configuration exhaustively.
+    Called once at orchestration start, not during node execution.
+
+    Raises:
+        WorkflowValidationError: If configuration is invalid
+    """
+    event_triggers = node_config.get("event_triggers")
+    if not event_triggers:
+        raise WorkflowValidationError(
+            "'event_triggers' is required - specify which signals activate this agent"
+        )
+    if not isinstance(event_triggers, list):
+        raise WorkflowValidationError(
+            "'event_triggers' must be a list, e.g., [\"START\", \"RETRY\"]"
+        )
+
+    if not node_config.get("prompt"):
+        raise WorkflowValidationError(
+            "'prompt' is required - provide the agent's task description or instructions"
+        )
+
+    if node_config.get("input_fields") is not None:
+        raise WorkflowValidationError(
+            "'input_fields' is no longer supported for Agent nodes. "
+            "Use Jinja syntax in prompts instead: {{ context.field_name }}"
+        )
+
+    output_field = node_config.get("output_field")
+    if output_field is not None:
+        if not isinstance(output_field, str):
+            raise WorkflowValidationError(
+                "'output_field' must be a string - the context field name to store the agent's output"
+            )
+        if output_field == "__operational__":
+            raise WorkflowValidationError(
+                "'output_field' cannot be '__operational__' - this is a reserved system field"
+            )
+
+    retries = node_config.get("retries")
+    if retries is not None:
+        if not isinstance(retries, int) or retries < 0:
+            raise WorkflowValidationError(
+                "'retries' must be a positive integer (default is 3)"
+            )
+
+    event_emissions = node_config.get("event_emissions")
+    if event_emissions is not None:
+        if not isinstance(event_emissions, list):
+            raise WorkflowValidationError(
+                "'event_emissions' must be a list of signal definitions"
+            )
+        for i, emission in enumerate(event_emissions):
+            if not isinstance(emission, dict):
+                raise WorkflowValidationError(
+                    f"Each event_emission must be an object with 'signal_name', got invalid item at position {i + 1}"
+                )
+            if not emission.get("signal_name"):
+                raise WorkflowValidationError(
+                    f"Event emission at position {i + 1} is missing 'signal_name'"
+                )
+            condition = emission.get("condition")
+            if condition is not None and not isinstance(condition, str):
+                raise WorkflowValidationError(
+                    f"Event emission at position {i + 1} has invalid 'condition' - must be a jinja string"
+                )
+
+    tools = node_config.get("tools")
+    if tools is not None and not isinstance(tools, list):
+        raise WorkflowValidationError(
+            "'tools' must be a list of tool names available to the agent"
+        )
+
+    identity = node_config.get("identity")
+    if identity is not None and not isinstance(identity, str):
+        raise WorkflowValidationError(
+            "'identity' must be a string - used to persist conversation history across executions"
+        )
+
+    llm_failure_signal = node_config.get("llm_failure_signal")
+    if llm_failure_signal is not None and not isinstance(llm_failure_signal, str):
+        raise WorkflowValidationError(
+            "'llm_failure_signal' must be a string - the signal to emit when LLM call fails"
+        )

soe/nodes/agent/validation/operational.py

@@ -0,0 +1,24 @@
+"""Agent node operational validation.
+
+Calls shared operational validation + Agent-specific backend validation.
+"""
+
+from typing import Dict, Any
+from ....types import Backends
+from ....validation.operational import validate_operational, OperationalValidationError
+
+
+def validate_agent_node_runtime(
+    execution_id: str,
+    backends: Backends,
+) -> Dict[str, Any]:
+    """Validate runtime state for Agent node."""
+    context = validate_operational(execution_id, backends)
+
+    try:
+        backends.workflow.get_current_workflow_name(execution_id)
+        backends.workflow.get_workflows_registry(execution_id)
+    except Exception as e:
+        raise OperationalValidationError(f"Cannot access workflow backend: {e}")
+
+    return context

soe/nodes/child/__init__.py

@@ -0,0 +1,3 @@
+"""
+Sub-orchestration node for executing child workflows with parent communication
+"""

soe/nodes/child/factory.py

@@ -0,0 +1,61 @@
+"""
+Child node factory
+"""
+
+import copy
+import time
+from typing import Dict, Any
+
+from ...validation.operational import validate_operational
+from .validation import validate_node_config
+from .state import get_operational_state
+from ...lib.register_event import register_event
+from ...types import ChildNodeCaller, OrchestrateCaller, EventTypes
+
+
+def create_child_node_caller(
+    backends,
+    orchestrate_caller: OrchestrateCaller,
+) -> ChildNodeCaller:
+    """Create child node caller with pre-loaded dependencies."""
+
+    def execute_child_node(id: str, node_config: Dict[str, Any]) -> None:
+        validate_operational(id, backends)
+        validate_node_config(node_config)
+
+        state = get_operational_state(id, node_config, backends)
+
+        register_event(
+            backends, id, EventTypes.NODE_EXECUTION,
+            {
+                "node_type": "child",
+                "child_workflow": state.child_workflow_name,
+                "parent_id": id,
+            }
+        )
+
+        if state.fan_out_items and state.child_input_field:
+            for i, item in enumerate(state.fan_out_items):
+                child_context = copy.deepcopy(state.child_initial_context)
+                child_context[state.child_input_field] = item
+
+                if i > 0 and state.spawn_interval > 0:
+                    time.sleep(state.spawn_interval)
+
+                orchestrate_caller(
+                    config=state.workflows_registry,
+                    initial_workflow_name=state.child_workflow_name,
+                    initial_signals=state.child_initial_signals,
+                    initial_context=child_context,
+                    backends=backends,
+                )
+        else:
+            orchestrate_caller(
+                config=state.workflows_registry,
+                initial_workflow_name=state.child_workflow_name,
+                initial_signals=state.child_initial_signals,
+                initial_context=state.child_initial_context,
+                backends=backends,
+            )
+
+    return execute_child_node

soe/nodes/child/state.py

@@ -0,0 +1,59 @@
+"""Child node state retrieval."""
+
+import copy
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, ConfigDict, Field
+
+from ...types import Backends
+from ...lib.context_fields import get_accumulated
+from ...lib.child_context import prepare_child_context
+
+
+class ChildOperationalState(BaseModel):
+    """All data needed for child node execution."""
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    context: Dict[str, Any]
+    main_execution_id: str
+    child_workflow_name: str
+    child_initial_signals: List[str]
+    child_initial_context: Dict[str, Any]
+    workflows_registry: Dict[str, Any]
+    fan_out_items: List[Any] = Field(default_factory=list)
+    child_input_field: Optional[str] = None
+    spawn_interval: float = 0.0
+
+
+def get_operational_state(
+    execution_id: str,
+    node_config: Dict[str, Any],
+    backends: Backends,
+) -> ChildOperationalState:
+    """Retrieve all state needed for child node execution."""
+    context = backends.context.get_context(execution_id)
+    operational = context["__operational__"]
+    main_execution_id = operational["main_execution_id"]
+
+    child_initial_context = prepare_child_context(
+        parent_context=context,
+        node_config=node_config,
+        parent_execution_id=execution_id,
+        main_execution_id=main_execution_id,
+    )
+
+    workflows_registry = copy.deepcopy(backends.workflow.get_workflows_registry(execution_id))
+
+    fan_out_field = node_config.get("fan_out_field")
+    fan_out_items = get_accumulated(context, fan_out_field) if fan_out_field else []
+
+    return ChildOperationalState(
+        context=context,
+        main_execution_id=main_execution_id,
+        child_workflow_name=node_config["child_workflow_name"],
+        child_initial_signals=node_config["child_initial_signals"],
+        child_initial_context=child_initial_context,
+        workflows_registry=workflows_registry,
+        fan_out_items=fan_out_items,
+        child_input_field=node_config.get("child_input_field"),
+        spawn_interval=node_config.get("spawn_interval", 0.0),
+    )

soe/nodes/child/validation/__init__.py

@@ -0,0 +1,11 @@
+"""
+Child node validation.
+
+- config.py: Config validation at orchestration start
+- operational.py: Runtime validation before execution (fail-fast)
+"""
+
+from .config import validate_node_config
+from .operational import validate_child_node_runtime
+
+__all__ = ["validate_node_config", "validate_child_node_runtime"]

soe/nodes/child/validation/config.py

@@ -0,0 +1,126 @@
+"""
+Child node configuration validation.
+
+Called once at orchestration start, not during node execution.
+"""
+
+from typing import Dict, Any
+from ....types import WorkflowValidationError
+
+
+def validate_node_config(node_config: Dict[str, Any]) -> None:
+    """
+    Validate sub-orchestration node configuration exhaustively.
+    Called once at orchestration start, not during node execution.
+
+    Raises:
+        WorkflowValidationError: If configuration is invalid
+    """
+    child_workflow_name = node_config.get("child_workflow_name")
+    if not child_workflow_name:
+        raise WorkflowValidationError(
+            "'child_workflow_name' is required - specify which workflow to start as a child"
+        )
+    if not isinstance(child_workflow_name, str):
+        raise WorkflowValidationError(
+            "'child_workflow_name' must be a string"
+        )
+
+    child_initial_signals = node_config.get("child_initial_signals")
+    if not child_initial_signals:
+        raise WorkflowValidationError(
+            "'child_initial_signals' is required - specify which signals to start the child workflow with"
+        )
+    if not isinstance(child_initial_signals, list):
+        raise WorkflowValidationError(
+            "'child_initial_signals' must be a list of signal names"
+        )
+
+    event_triggers = node_config.get("event_triggers")
+    if not event_triggers:
+        raise WorkflowValidationError(
+            "'event_triggers' is required - specify which signals trigger the start of the child workflow"
+        )
+    if not isinstance(event_triggers, list):
+        raise WorkflowValidationError(
+            "'event_triggers' must be a list of signal names, e.g., [\"START_CHILD\"]"
+        )
+
+    signals_to_parent = node_config.get("signals_to_parent")
+    if signals_to_parent is not None:
+        if not isinstance(signals_to_parent, list):
+            raise WorkflowValidationError(
+                "'signals_to_parent' must be a list of signal names that should propagate from child to parent"
+            )
+        for signal in signals_to_parent:
+            if not isinstance(signal, str):
+                raise WorkflowValidationError(
+                    f"All items in 'signals_to_parent' must be strings. Found: {type(signal).__name__}"
+                )
+
+    context_updates_to_parent = node_config.get("context_updates_to_parent")
+    if context_updates_to_parent is not None:
+        if not isinstance(context_updates_to_parent, list):
+            raise WorkflowValidationError(
+                "'context_updates_to_parent' must be a list of context key names that should propagate from child to parent"
+            )
+        for key in context_updates_to_parent:
+            if not isinstance(key, str):
+                raise WorkflowValidationError(
+                    f"All items in 'context_updates_to_parent' must be strings. Found: {type(key).__name__}"
+                )
+
+    input_fields = node_config.get("input_fields")
+    if input_fields is not None and not isinstance(input_fields, list):
+        raise WorkflowValidationError(
+            "'input_fields' must be a list of context field names to pass to the child workflow"
+        )
+
+    fan_out_field = node_config.get("fan_out_field")
+    if fan_out_field is not None:
+        if not isinstance(fan_out_field, str):
+            raise WorkflowValidationError(
+                "'fan_out_field' must be a string (the context field to iterate over)"
+            )
+        child_input_field = node_config.get("child_input_field")
+        if not child_input_field:
+            raise WorkflowValidationError(
+                "'child_input_field' is required when 'fan_out_field' is set - "
+                "specify which field in child context receives each item"
+            )
+        if not isinstance(child_input_field, str):
+            raise WorkflowValidationError(
+                "'child_input_field' must be a string"
+            )
+
+    spawn_interval = node_config.get("spawn_interval")
+    if spawn_interval is not None:
+        if not isinstance(spawn_interval, (int, float)):
+            raise WorkflowValidationError(
+                "'spawn_interval' must be a number (seconds to sleep between spawns)"
+            )
+        if spawn_interval < 0:
+            raise WorkflowValidationError(
+                "'spawn_interval' must be non-negative"
+            )
+
+    event_emissions = node_config.get("event_emissions")
+    if event_emissions is not None:
+        if not isinstance(event_emissions, list):
+            raise WorkflowValidationError(
+                "'event_emissions' must be a list of signal definitions"
+            )
+        for i, emission in enumerate(event_emissions):
+            if not isinstance(emission, dict):
+                raise WorkflowValidationError(
+                    f"Each event_emission must be an object with 'signal_name', got invalid item at position {i + 1}"
+                )
+            if not emission.get("signal_name"):
+                raise WorkflowValidationError(
+                    f"Event emission at position {i + 1} is missing 'signal_name'"
+                )
+            condition = emission.get("condition")
+            if condition is not None and not isinstance(condition, str):
+                raise WorkflowValidationError(
+                    f"Event emission at position {i + 1} has invalid 'condition' - must be a jinja string"
+                )

soe/nodes/child/validation/operational.py

@@ -0,0 +1,28 @@
+"""Child node operational validation.
+
+Calls shared operational validation + Child-specific backend validation.
+"""
+
+from typing import Dict, Any
+from ....types import Backends
+from ....validation.operational import validate_operational, OperationalValidationError
+
+
+def validate_child_node_runtime(
+    execution_id: str,
+    backends: Backends,
+) -> Dict[str, Any]:
+    """Validate runtime state for Child node."""
+    context = validate_operational(execution_id, backends)
+
+    try:
+        workflows_registry = backends.workflow.get_workflows_registry(execution_id)
+    except Exception as e:
+        raise OperationalValidationError(f"Cannot access workflow backend: {e}")
+
+    if not workflows_registry:
+        raise OperationalValidationError(
+            f"No workflows_registry found for execution_id '{execution_id}'"
+        )
+
+    return context

soe/nodes/lib/conditions.py

@@ -0,0 +1,71 @@
+"""
+Shared condition evaluation for nodes that emit signals.
+Used by Router, LLM, Agent, and Tool nodes.
+"""
+
+import re
+from typing import Dict, List, Any
+from jinja2 import Environment
+
+
+def _create_accumulated_filter(full_context: Dict[str, Any]):
+    """Create an accumulated filter that returns full history for a field."""
+    def accumulated_filter(value):
+        """
+        Return the full accumulated history list for a context field.
+
+        If history has exactly one entry and it's a list, returns that list
+        (common case: initial context passed a list as value).
+        Otherwise returns the history entries.
+        """
+        for key, hist_list in full_context.items():
+            if key.startswith("__"):
+                continue
+            if isinstance(hist_list, list) and hist_list and hist_list[-1] == value:
+                if len(hist_list) == 1 and isinstance(hist_list[0], list):
+                    return hist_list[0]
+                return hist_list
+        return [value] if value is not None else []
+
+    return accumulated_filter
+
+
+def evaluate_conditions(
+    event_emissions: List[Dict[str, Any]],
+    render_context: Dict[str, Any],
+    full_context: Dict[str, Any] = None,
+) -> List[str]:
+    """
+    Evaluate jinja conditions and return signals that pass.
+
+    Args:
+        event_emissions: List of emission configs with signal_name and optional condition
+        render_context: Variables for jinja (e.g., {"context": ctx} or {"result": res, "context": ctx})
+        full_context: The raw context with history lists (for accumulated filter)
+
+    Returns:
+        List of signal names that passed their conditions (or had no condition)
+    """
+    jinja_env = Environment()
+
+    if full_context:
+        jinja_env.filters["accumulated"] = _create_accumulated_filter(full_context)
+
+    filtered_signals = []
+
+    for emission in event_emissions:
+        signal_name = emission.get("signal_name")
+        condition = emission.get("condition", "")
+
+        if not condition or not re.search(r"\{\{.*\}\}", condition):
+            filtered_signals.append(signal_name)
+            continue
+
+        try:
+            result = jinja_env.from_string(condition).render(**render_context)
+            if result and result.strip().lower() not in ["false", "0", "none", ""]:
+                filtered_signals.append(signal_name)
+        except Exception:
+            pass
+
+    return filtered_signals

soe/nodes/lib/context.py

@@ -0,0 +1,24 @@
+"""Context output utilities shared across nodes."""
+
+from typing import Any, Optional
+from ...lib.parent_sync import sync_context_to_parent
+from ...lib.context_fields import set_field, get_field
+from ...types import Backends
+
+__all__ = ["set_field", "get_field", "save_output_to_context"]
+
+
+def save_output_to_context(
+    execution_id: str,
+    output_field: Optional[str],
+    output_value: Any,
+    backends: Backends,
+) -> None:
+    """Save output value to context and sync to parent if configured."""
+    if not output_field or output_value is None:
+        return
+
+    context = backends.context.get_context(execution_id)
+    set_field(context, output_field, output_value)
+    backends.context.save_context(execution_id, context)
+    sync_context_to_parent(context, [output_field], backends)

soe/nodes/lib/conversation_history.py

@@ -0,0 +1,77 @@
+"""
+Shared conversation history utilities for LLM and Agent nodes.
+
+This module handles conversation history retrieval, formatting, and saving
+for nodes that support identity-based conversation persistence.
+"""
+
+from typing import Dict, Any, List, Optional, Tuple
+from ...types import Backends
+
+
+def get_conversation_history(
+    execution_id: str,
+    identity: Optional[str],
+    backends: Backends,
+) -> Tuple[Optional[str], List[Dict[str, Any]]]:
+    """
+    Get conversation history and history key for a node with identity.
+
+    Identity enables conversation history. The key is main_execution_id,
+    ensuring history persists across sub-orchestration boundaries.
+
+    When the history is empty and an identity backend is configured,
+    the identity's system prompt is injected as the first message.
+    Both identity and context_schema are keyed by main_execution_id.
+
+    Args:
+        execution_id: Current execution ID
+        identity: Identity key for conversation history
+        backends: Backend services
+
+    Returns:
+        Tuple of (history_key, conversation_history list)
+        history_key is None if no identity or no conversation backend
+    """
+    if not identity or not backends.conversation_history:
+        return (None, [])
+
+    context = backends.context.get_context(execution_id)
+    main_id = context.get("__operational__", {}).get("main_execution_id", execution_id)
+    history = backends.conversation_history.get_conversation_history(main_id)
+
+    if not history and backends.identity:
+        identities = backends.identity.get_identities(main_id)
+        if identities and identity in identities:
+            system_prompt = identities[identity]
+            if system_prompt:
+                history = [{"role": "system", "content": system_prompt}]
+                backends.conversation_history.save_conversation_history(main_id, history)
+
+    return (main_id, history)
+
+
+def format_conversation_history(conversation_history: List[Dict[str, Any]]) -> str:
+    """Format conversation history as a string for prompts."""
+    if not conversation_history:
+        return ""
+    return "\n".join(
+        f"[{msg.get('role', 'unknown')}]: {msg.get('content', '')}"
+        for msg in conversation_history
+    )
+
+
+def save_conversation_turn(
+    history_key: Optional[str],
+    conversation_history: List[Dict[str, Any]],
+    user_content: str,
+    assistant_content: str,
+    backends: Backends,
+) -> None:
+    """Save a conversation turn (user + assistant) to history."""
+    if not history_key or not backends.conversation_history:
+        return
+
+    conversation_history.append({"role": "user", "content": user_content})
+    conversation_history.append({"role": "assistant", "content": str(assistant_content)})
+    backends.conversation_history.save_conversation_history(history_key, conversation_history)