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

soe/nodes/llm/factory.py

@@ -0,0 +1,103 @@
+"""
+LLM node factory
+
+Simple node that calls LLM directly without agent loop, tools, or routing.
+Supports conversation history via identity and schema validation via Pydantic.
+Prompts use Jinja templates - variables are auto-extracted from {{ context.field }}.
+"""
+
+from typing import Dict, Any, Callable
+from ..lib.llm_resolver import resolve_llm_call
+from ..lib.signal_emission import emit_completion_signals, handle_llm_failure
+from ..lib.response_builder import (
+    build_response_model,
+    extract_output_from_response,
+    extract_signal_from_response,
+)
+from ...types import CallLlm, BroadcastSignalsCaller, Backends, LlmNodeCaller, EventTypes
+from ...lib.register_event import register_event
+from ..lib.context import save_output_to_context
+from ..lib.conversation_history import save_conversation_turn
+from ...lib.jinja_render import render_prompt
+from ...validation.operational import validate_operational
+from .validation import validate_node_config
+from .state import get_operational_state
+from .types import LlmNodeInput
+
+
+def create_llm_node_caller(
+    backends: Backends,
+    call_llm: CallLlm,
+    broadcast_signals_caller: BroadcastSignalsCaller,
+) -> LlmNodeCaller:
+    """Create LLM node caller with pre-loaded dependencies."""
+
+    def execute_llm_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.LLM_CALL, {"identity": state.identity})
+
+        rendered_prompt, warnings = render_prompt(state.prompt, state.context)
+
+        if warnings:
+            register_event(backends, id, EventTypes.CONTEXT_WARNING, {"warnings": warnings})
+
+        input_data = LlmNodeInput(
+            prompt=rendered_prompt,
+            context=state.context_str,
+            conversation_history=state.history_str,
+        )
+
+        response_model = build_response_model(
+            output_field=state.output_field,
+            output_schema=state.output_model,
+            signal_options=state.signal_options,
+        )
+
+        try:
+            raw_response = resolve_llm_call(
+                call_llm=call_llm,
+                input_data=input_data,
+                config=node_config,
+                response_model=response_model,
+                max_retries=state.max_retries,
+            )
+
+            output_value = extract_output_from_response(raw_response, state.output_field)
+            save_output_to_context(id, state.output_field, output_value, backends)
+
+            if state.output_field:
+                if state.output_field in state.context:
+                    state.context[state.output_field].append(output_value)
+                else:
+                    state.context[state.output_field] = [output_value]
+
+            save_conversation_turn(
+                state.history_key, state.conversation_history,
+                rendered_prompt, str(output_value), backends
+            )
+
+            selected_signal = extract_signal_from_response(raw_response)
+
+            emit_completion_signals(
+                selected_signal=selected_signal,
+                node_config=node_config,
+                operational_state=state,
+                broadcast_signals_caller=broadcast_signals_caller,
+                execution_id=id,
+            )
+
+        except Exception as e:
+            handle_llm_failure(
+                failure_signal=state.llm_failure_signal,
+                error_message=str(e),
+                node_type="llm",
+                execution_id=id,
+                backends=backends,
+                broadcast_signals_caller=broadcast_signals_caller,
+            )
+
+    return execute_llm_node

soe/nodes/llm/state.py

@@ -0,0 +1,76 @@
+"""LLM node state retrieval."""
+
+import json
+from typing import Dict, Any, List, Optional
+from pydantic import BaseModel, ConfigDict
+from ...types import Backends
+from ..lib.conversation_history import get_conversation_history, format_conversation_history
+from ...lib.jinja_render import get_context_for_prompt
+from ..lib.output import get_output_model, get_signal_options
+
+
+class LlmOperationalState(BaseModel):
+    """All data needed for LLM node execution."""
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    context: Dict[str, Any]
+    main_execution_id: str
+    prompt: str
+    identity: Optional[str]
+    output_field: Optional[str]
+    event_emissions: List[Dict[str, Any]]
+    max_retries: int
+    llm_failure_signal: Optional[str]
+    current_workflow_name: str
+    history_key: Optional[str]
+    conversation_history: List[Dict[str, Any]]
+    context_data: Dict[str, Any]
+    context_str: str
+    history_str: str
+    output_model: Optional[Any]
+    signal_options: Optional[List[Dict[str, str]]]
+
+
+def get_operational_state(
+    execution_id: str,
+    node_config: Dict[str, Any],
+    backends: Backends,
+) -> LlmOperationalState:
+    """Retrieve all state needed for LLM node execution."""
+    context = backends.context.get_context(execution_id)
+    operational = context["__operational__"]
+    identity = node_config.get("identity")
+    prompt = node_config["prompt"]
+    output_field = node_config.get("output_field")
+    event_emissions = node_config.get("event_emissions", [])
+    current_workflow_name = backends.workflow.get_current_workflow_name(execution_id)
+
+    history_key, conversation_history = get_conversation_history(
+        execution_id, identity, backends
+    )
+
+    context_data, _ = get_context_for_prompt(context, prompt)
+    context_str = json.dumps(context_data, indent=2) if context_data else ""
+    history_str = format_conversation_history(conversation_history)
+    main_execution_id = operational["main_execution_id"]
+    output_model = get_output_model(backends, main_execution_id, output_field)
+    signal_options = get_signal_options(event_emissions)
+
+    return LlmOperationalState(
+        context=context,
+        main_execution_id=main_execution_id,
+        prompt=prompt,
+        identity=identity,
+        output_field=output_field,
+        event_emissions=event_emissions,
+        max_retries=node_config.get("retries", 3),
+        llm_failure_signal=node_config.get("llm_failure_signal"),
+        current_workflow_name=current_workflow_name,
+        history_key=history_key,
+        conversation_history=conversation_history,
+        context_data=context_data,
+        context_str=context_str,
+        history_str=history_str,
+        output_model=output_model,
+        signal_options=signal_options,
+    )

soe/nodes/llm/types.py

@@ -0,0 +1,12 @@
+"""
+LLM node models and data structures
+"""
+
+from pydantic import BaseModel
+
+
+class LlmNodeInput(BaseModel):
+    """Input model for LLM execution."""
+    prompt: str
+    context: str = ""
+    conversation_history: str = ""

soe/nodes/llm/validation/__init__.py

@@ -0,0 +1,11 @@
+"""
+LLM 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_llm_node_runtime
+
+__all__ = ["validate_node_config", "validate_llm_node_runtime"]

soe/nodes/llm/validation/config.py

@@ -0,0 +1,89 @@
+"""
+LLM 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 LLM 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 LLM node"
+        )
+    if not isinstance(event_triggers, list):
+        raise WorkflowValidationError(
+            "'event_triggers' must be a list, e.g., [\"START\", \"PROCESS\"]"
+        )
+
+    if not node_config.get("prompt"):
+        raise WorkflowValidationError(
+            "'prompt' is required - provide the prompt template for the LLM"
+        )
+
+    if node_config.get("input_fields") is not None:
+        raise WorkflowValidationError(
+            "'input_fields' is no longer supported for LLM 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 LLM response"
+            )
+        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"
+                )
+
+    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/llm/validation/operational.py

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

soe/nodes/router/__init__.py

@@ -0,0 +1,3 @@
+"""
+Router node - conditional routing based on jinja templates
+"""

soe/nodes/router/factory.py

@@ -0,0 +1,37 @@
+"""
+Router node factory
+"""
+
+from typing import Dict, Any
+
+from ..lib.conditions import evaluate_conditions
+from ...lib.context_fields import get_field
+from ...validation.operational import validate_operational
+from ...lib.register_event import register_event
+from ...types import BroadcastSignalsCaller, RouterNodeCaller, EventTypes
+from .validation import validate_node_config
+from .state import get_operational_state
+
+
+def create_router_node_caller(
+    backends, broadcast_signals_caller: BroadcastSignalsCaller
+) -> RouterNodeCaller:
+    """Create router node caller with pre-loaded dependencies."""
+
+    def execute_router_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": "router"})
+
+        unwrapped = {k: get_field(state.context, k) for k in state.context if not k.startswith("__")}
+        for k, v in state.context.items():
+            if k.startswith("__"):
+                unwrapped[k] = v
+        signals = evaluate_conditions(state.event_emissions, {"context": unwrapped}, state.context)
+        if signals:
+            broadcast_signals_caller(id, signals)
+
+    return execute_router_node

soe/nodes/router/state.py

@@ -0,0 +1,32 @@
+"""
+Router node state retrieval.
+"""
+
+from typing import Dict, Any, List
+from pydantic import BaseModel, ConfigDict
+from ...types import Backends
+
+
+class RouterOperationalState(BaseModel):
+    """All data needed for router node execution."""
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    context: Dict[str, Any]
+    main_execution_id: str
+    event_emissions: List[Dict[str, Any]]
+
+
+def get_operational_state(
+    execution_id: str,
+    node_config: Dict[str, Any],
+    backends: Backends,
+) -> RouterOperationalState:
+    """Retrieve all state needed for router node execution."""
+    context = backends.context.get_context(execution_id)
+    operational = context["__operational__"]
+
+    return RouterOperationalState(
+        context=context,
+        main_execution_id=operational["main_execution_id"],
+        event_emissions=node_config["event_emissions"],
+    )

soe/nodes/router/validation/__init__.py

@@ -0,0 +1,11 @@
+"""
+Router 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_router_node_runtime
+
+__all__ = ["validate_node_config", "validate_router_node_runtime"]

soe/nodes/router/validation/config.py

@@ -0,0 +1,58 @@
+"""
+Router node configuration validation.
+
+Called once at orchestration start, not during node execution.
+"""
+
+from typing import Dict, Any
+from ....types import WorkflowValidationError
+from ....validation.jinja import validate_jinja_syntax
+
+
+def validate_node_config(node_config: Dict[str, Any]) -> None:
+    """
+    Validate router 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 router"
+        )
+    if not isinstance(event_triggers, list):
+        raise WorkflowValidationError(
+            "'event_triggers' must be a list, e.g., [\"START\", \"RETRY\"]"
+        )
+
+    event_emissions = node_config.get("event_emissions")
+    if not event_emissions:
+        raise WorkflowValidationError(
+            "'event_emissions' is required - specify which signals to emit based on conditions"
+        )
+    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"
+            )
+        if condition:
+            validate_jinja_syntax(
+                condition,
+                f"Event emission '{emission.get('signal_name')}' condition"
+            )

soe/nodes/router/validation/operational.py

@@ -0,0 +1,16 @@
+"""Router node operational validation.
+
+Calls shared operational validation. Router has no additional backend requirements.
+"""
+
+from typing import Dict, Any
+from ....types import Backends
+from ....validation.operational import validate_operational, OperationalValidationError
+
+
+def validate_router_node_runtime(
+    execution_id: str,
+    backends: Backends,
+) -> Dict[str, Any]:
+    """Validate runtime state for Router node. Delegates to shared validation."""
+    return validate_operational(execution_id, backends)

soe/nodes/tool/factory.py

@@ -0,0 +1,66 @@
+"""
+Tool node factory
+"""
+
+from typing import Dict, Any
+
+from .validation import validate_tool_node_config
+from .validation.operational import validate_tool_node_runtime
+from .state import get_operational_state
+from .lib.failure import handle_tool_failure
+from .lib.conditions import evaluate_tool_conditions
+from .types import ToolsRegistry
+from ...lib.register_event import register_event
+from ..lib.context import save_output_to_context
+from ...types import Backends, BroadcastSignalsCaller, ToolNodeCaller, EventTypes
+
+
+def create_tool_node_caller(
+    backends: Backends,
+    tools_registry: ToolsRegistry,
+    broadcast_signals_caller: BroadcastSignalsCaller,
+) -> ToolNodeCaller:
+    """Create tool node caller with pre-loaded dependencies."""
+
+    def execute_tool_node(id: str, node_config: Dict[str, Any]) -> None:
+        validate_tool_node_config(node_config, tools_registry)
+        validate_tool_node_runtime(id, backends)
+
+        state = get_operational_state(id, node_config, backends, tools_registry)
+
+        register_event(
+            backends, id, EventTypes.TOOL_CALL,
+            {"tool_name": state.tool_name, "max_retries": state.max_retries}
+        )
+
+        last_error = None
+        for attempt in range(state.max_retries + 1):
+            try:
+                if state.process_accumulated and isinstance(state.parameters, list):
+                    result = state.tool_function(state.parameters)
+                else:
+                    result = state.tool_function(**state.parameters)
+                save_output_to_context(id, state.output_field, result, backends)
+
+                signals = evaluate_tool_conditions(
+                    state.event_emissions, result, state.context, id, backends
+                )
+                if signals:
+                    broadcast_signals_caller(id, signals)
+                return
+
+            except Exception as tool_error:
+                last_error = tool_error
+                if attempt < state.max_retries:
+                    register_event(
+                        backends, id, EventTypes.NODE_ERROR,
+                        {"tool_name": state.tool_name, "retry_attempt": attempt + 1, "error": str(tool_error)}
+                    )
+                    continue
+
+        handle_tool_failure(
+            state.tool_name, state.failure_signal, state.output_field,
+            str(last_error), backends, broadcast_signals_caller, id
+        )
+
+    return execute_tool_node

soe/nodes/tool/lib/__init__.py

@@ -0,0 +1,11 @@
+"""
+Tool node library utilities
+"""
+
+from .conditions import evaluate_tool_conditions
+from .failure import handle_tool_failure
+
+__all__ = [
+    "evaluate_tool_conditions",
+    "handle_tool_failure",
+]

soe/nodes/tool/lib/conditions.py

@@ -0,0 +1,35 @@
+"""
+Tool-specific condition evaluation with error logging.
+"""
+
+from typing import Dict, List, Any
+
+from ...lib.conditions import evaluate_conditions
+from ....lib.context_fields import get_field
+from ....lib.register_event import register_event
+from ....types import Backends, EventTypes
+
+
+def evaluate_tool_conditions(
+    event_emissions: List[Dict[str, Any]],
+    result: Any,
+    context: Dict[str, Any],
+    execution_id: str,
+    backends: Backends,
+) -> List[str]:
+    """Evaluate jinja conditions against tool result and context with error logging."""
+    if not event_emissions:
+        return []
+
+    try:
+        unwrapped = {k: get_field(context, k) for k in context if not k.startswith("__")}
+        for k, v in context.items():
+            if k.startswith("__"):
+                unwrapped[k] = v
+        return evaluate_conditions(event_emissions, {"result": result, "context": unwrapped}, context)
+    except Exception as e:
+        register_event(
+            backends, execution_id, EventTypes.NODE_ERROR,
+            {"error": f"Condition evaluation failed: {e}"}
+        )
+        return []

soe/nodes/tool/lib/failure.py

@@ -0,0 +1,28 @@
+"""Tool failure handling utilities."""
+
+from typing import Optional
+
+from ...lib.context import save_output_to_context
+from ....lib.register_event import register_event
+from ....types import Backends, BroadcastSignalsCaller, EventTypes
+
+
+def handle_tool_failure(
+    tool_name: str,
+    failure_signal: Optional[str],
+    output_field: Optional[str],
+    error_message: str,
+    backends: Backends,
+    broadcast_signals_caller: BroadcastSignalsCaller,
+    execution_id: str,
+) -> None:
+    """Handle tool execution failure by saving error and optionally emitting failure signal."""
+    save_output_to_context(execution_id, output_field, error_message, backends)
+
+    register_event(
+        backends, execution_id, EventTypes.NODE_ERROR,
+        {"tool_name": tool_name, "error": error_message}
+    )
+
+    if failure_signal:
+        broadcast_signals_caller(execution_id, [failure_signal])