soe-ai 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

soe/nodes/tool/lib/parameters.py

@@ -0,0 +1,67 @@
+"""Tool parameter extraction and validation utilities."""
+
+import inspect
+from typing import Dict, Any, Callable, Optional
+
+from ....lib.context_fields import get_field
+from ..types import ToolParameterError
+
+
+def extract_tool_parameters(
+    context: Dict[str, Any],
+    context_parameter_field: Optional[str],
+) -> Dict[str, Any]:
+    """Extract tool parameters from context.
+
+    Args:
+        context: The workflow context
+        context_parameter_field: Name of the context field containing tool kwargs
+
+    Returns:
+        Dict of parameters to pass to the tool function
+
+    Raises:
+        ToolParameterError: If field is missing or not a dict
+    """
+    if not context_parameter_field:
+        return {}
+
+    if context_parameter_field not in context:
+        raise ToolParameterError(f"Context missing required field: {context_parameter_field}")
+
+    parameters = get_field(context, context_parameter_field)
+
+    if not isinstance(parameters, dict):
+        raise ToolParameterError(
+            f"Context field '{context_parameter_field}' must be a dict of parameters, got {type(parameters)}"
+        )
+
+    return parameters
+
+
+def validate_tool_parameters(
+    tool_function: Callable, parameters: Dict[str, Any], tool_name: str
+) -> None:
+    """Validate parameters match tool function signature."""
+    signature = inspect.signature(tool_function)
+
+    has_var_keyword = any(
+        param.kind == inspect.Parameter.VAR_KEYWORD
+        for param in signature.parameters.values()
+    )
+
+    for param_name, param in signature.parameters.items():
+        if param.kind in (inspect.Parameter.VAR_KEYWORD, inspect.Parameter.VAR_POSITIONAL):
+            continue
+        if param.default == inspect.Parameter.empty:
+            if param_name not in parameters:
+                raise ToolParameterError(
+                    f"Tool '{tool_name}' missing required parameter: {param_name}"
+                )
+
+    if not has_var_keyword:
+        for param_name in parameters.keys():
+            if param_name not in signature.parameters:
+                raise ToolParameterError(
+                    f"Tool '{tool_name}' unexpected parameter: {param_name}"
+                )

soe/nodes/tool/state.py

@@ -0,0 +1,66 @@
+"""
+Tool node state retrieval.
+"""
+
+from typing import Callable, Dict, Any, List, Optional
+from pydantic import BaseModel, ConfigDict
+
+from ...types import Backends
+from ...lib.yaml_parser import parse_yaml
+from ...lib.context_fields import get_field
+from ..lib.tools import get_tool_from_registry
+from .types import ToolsRegistry
+
+
+class ToolOperationalState(BaseModel):
+    """All data needed for tool node execution."""
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    context: Dict[str, Any]
+    main_execution_id: str
+    tool_name: str
+    tool_function: Callable
+    max_retries: int
+    failure_signal: Optional[str]
+    output_field: Optional[str]
+    event_emissions: List[Dict[str, Any]]
+    parameters: Any  # Can be Dict or List when process_accumulated=True
+    process_accumulated: bool = False
+
+
+def get_operational_state(
+    execution_id: str,
+    node_config: Dict[str, Any],
+    backends: Backends,
+    tools_registry: ToolsRegistry,
+) -> ToolOperationalState:
+    """Retrieve all state needed for tool node execution."""
+    context = backends.context.get_context(execution_id)
+    operational = context["__operational__"]
+    tool_name = node_config["tool_name"]
+    tool_function, max_retries, failure_signal, process_accumulated = get_tool_from_registry(
+        tool_name, tools_registry, execution_id, backends
+    )
+
+    context_parameter_field = node_config.get("context_parameter_field")
+    if context_parameter_field and context_parameter_field in context:
+        if process_accumulated:
+            raw_params = context[context_parameter_field]
+        else:
+            raw_params = get_field(context, context_parameter_field)
+        parameters = parse_yaml(raw_params) if isinstance(raw_params, str) else raw_params
+    else:
+        parameters = {}
+
+    return ToolOperationalState(
+        context=context,
+        main_execution_id=operational["main_execution_id"],
+        tool_name=tool_name,
+        tool_function=tool_function,
+        max_retries=max_retries,
+        failure_signal=failure_signal,
+        output_field=node_config.get("output_field"),
+        event_emissions=node_config.get("event_emissions", []),
+        parameters=parameters,
+        process_accumulated=process_accumulated,
+    )

soe/nodes/tool/types.py

@@ -0,0 +1,27 @@
+"""
+Tool node models and exceptions
+"""
+
+from typing import Callable, TypedDict, Union, Dict
+
+
+class ToolRegistryEntry(TypedDict, total=False):
+    """Extended tool registry entry with optional configuration"""
+    function: Callable
+    max_retries: int
+    failure_signal: str
+
+
+ToolsRegistry = Dict[str, Union[Callable, ToolRegistryEntry]]
+
+
+class ToolNodeConfigurationError(Exception):
+    """Raised when tool node configuration is invalid"""
+
+    pass
+
+
+class ToolParameterError(Exception):
+    """Raised when tool parameters don't match signature"""
+
+    pass

soe/nodes/tool/validation/__init__.py

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

soe/nodes/tool/validation/config.py

@@ -0,0 +1,132 @@
+"""
+Tool node configuration validation.
+
+Called once at orchestration start, not during node execution.
+"""
+
+from typing import Dict, Any, Callable, Union
+
+from ....types import WorkflowValidationError
+from ....builtin_tools import get_builtin_tool_factory
+from ..types import ToolRegistryEntry, ToolsRegistry
+
+
+def _get_function_from_entry(entry: Union[Callable, ToolRegistryEntry]) -> Callable:
+    """Extract the callable from a registry entry"""
+    if callable(entry):
+        return entry
+    return entry.get("function")
+
+
+def _validate_registry_entry(tool_name: str, entry: Union[Callable, ToolRegistryEntry]) -> None:
+    """
+    Validate a tool registry entry format.
+
+    Raises:
+        WorkflowValidationError: If entry format is invalid
+    """
+    if callable(entry):
+        return
+
+    if not isinstance(entry, dict):
+        raise WorkflowValidationError(
+            f"Tool '{tool_name}' registry entry must be a callable or dict with 'function' key"
+        )
+
+    if "function" not in entry:
+        raise WorkflowValidationError(
+            f"Tool '{tool_name}' registry entry dict must have 'function' key"
+        )
+
+    if not callable(entry["function"]):
+        raise WorkflowValidationError(
+            f"Tool '{tool_name}' 'function' must be callable"
+        )
+
+    max_retries = entry.get("max_retries")
+    if max_retries is not None:
+        if not isinstance(max_retries, int) or max_retries < 0:
+            raise WorkflowValidationError(
+                f"Tool '{tool_name}' 'max_retries' must be a non-negative integer"
+            )
+
+    failure_signal = entry.get("failure_signal")
+    if failure_signal is not None:
+        if not isinstance(failure_signal, str):
+            raise WorkflowValidationError(
+                f"Tool '{tool_name}' 'failure_signal' must be a string"
+            )
+
+
+def validate_node_config(node_config: Dict[str, Any]) -> None:
+    """
+    Validate tool node configuration (structure only, no runtime checks).
+    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 tool node"
+        )
+    if not isinstance(event_triggers, list):
+        raise WorkflowValidationError(
+            "'event_triggers' must be a list, e.g., [\"EXECUTE_TOOL\"]"
+        )
+
+    if "tool_name" not in node_config:
+        raise WorkflowValidationError(
+            "'tool_name' is required - specify which tool to execute"
+        )
+
+    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"'event_emissions[{i}]' must be a dict with 'signal_name'"
+                )
+            if "signal_name" not in emission:
+                raise WorkflowValidationError(
+                    f"'event_emissions[{i}]' must have 'signal_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 tool output"
+            )
+        if output_field == "__operational__":
+            raise WorkflowValidationError(
+                "'output_field' cannot be '__operational__' - this is a reserved system field"
+            )
+
+
+def validate_tool_node_config(
+    node_config: Dict[str, Any], tools_registry: ToolsRegistry
+) -> None:
+    """Validate tool node configuration with runtime checks (tool registry)"""
+
+    validate_node_config(node_config)
+
+    tool_name = node_config["tool_name"]
+    if tool_name not in tools_registry:
+        if not get_builtin_tool_factory(tool_name):
+            raise WorkflowValidationError(
+                f"Tool '{tool_name}' not found in tools_registry or builtin tools"
+            )
+        return
+
+    entry = tools_registry[tool_name]
+    _validate_registry_entry(tool_name, entry)
+
+    tool_function = _get_function_from_entry(entry)
+    if not callable(tool_function):
+        raise WorkflowValidationError(f"Tool '{tool_name}' is not callable")

soe/nodes/tool/validation/operational.py

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

soe/validation/__init__.py

@@ -0,0 +1,18 @@
+"""
+Validation module for SOE.
+
+Two types of validation:
+1. config.py - Validates config structure at orchestration start
+2. operational.py - Validates runtime state before node execution (fail-fast)
+"""
+
+from .config import validate_config, validate_workflow, validate_orchestrate_params
+from .operational import validate_operational, OperationalValidationError
+
+__all__ = [
+    "validate_config",
+    "validate_workflow",
+    "validate_orchestrate_params",
+    "validate_operational",
+    "OperationalValidationError",
+]

soe/validation/config.py

@@ -0,0 +1,195 @@
+"""
+Config validation - validates config structure before orchestration starts.
+
+Supports two config formats:
+1. Single Workflow format: Dict of workflow definitions directly
+2. Combined config format: Dict with 'workflows', 'context_schema', 'identities' keys
+
+Runs once at orchestration start, before any execution.
+"""
+
+from typing import Dict, Any
+
+from ..types import WorkflowValidationError
+from ..nodes.router.validation import validate_node_config as validate_router
+from ..nodes.agent.validation import validate_node_config as validate_agent
+from ..nodes.llm.validation import validate_node_config as validate_llm
+from ..nodes.child.validation import validate_node_config as validate_child
+from ..nodes.tool.validation import validate_node_config as validate_tool
+from ..lib.yaml_parser import parse_yaml
+
+
+NODE_VALIDATORS = {
+    "router": validate_router,
+    "agent": validate_agent,
+    "llm": validate_llm,
+    "child": validate_child,
+    "tool": validate_tool,
+}
+
+
+def _validate_workflow_section(workflow_name: str, workflow: Dict[str, Any]) -> None:
+    """
+    Validate all nodes in a workflow section.
+
+    Args:
+        workflow_name: Name of the workflow (for error messages)
+        workflow: Workflow definition dict
+
+    Raises:
+        WorkflowValidationError: If any node configuration is invalid
+    """
+    if not workflow:
+        raise WorkflowValidationError(
+            f"Workflow '{workflow_name}' is empty - at least one node is required"
+        )
+
+    for node_name, node_config in workflow.items():
+        if node_name.startswith("__"):
+            raise WorkflowValidationError(
+                f"Workflow '{workflow_name}': node name '{node_name}' is reserved - "
+                f"names starting with '__' are reserved for internal use"
+            )
+        node_type = node_config.get("node_type")
+
+        if not node_type:
+            raise WorkflowValidationError(
+                f"Workflow '{workflow_name}', node '{node_name}': "
+                f"'node_type' is required - specify the type (router, agent, llm, tool, child)"
+            )
+
+        if node_type.startswith("_"):
+            continue
+
+        validator = NODE_VALIDATORS.get(node_type)
+        if not validator:
+            valid_types = ", ".join(NODE_VALIDATORS.keys())
+            raise WorkflowValidationError(
+                f"Workflow '{workflow_name}', node '{node_name}': "
+                f"unknown node_type '{node_type}'. Valid types are: {valid_types}"
+            )
+
+        try:
+            validator(node_config)
+        except WorkflowValidationError as e:
+            raise WorkflowValidationError(
+                f"Workflow '{workflow_name}', node '{node_name}': {e}"
+            ) from e
+
+
+def _validate_context_schema_section(context_schema: Dict[str, Any]) -> None:
+    """
+    Validate context_schema section of config.
+
+    Args:
+        context_schema: Context schema definitions
+
+    Raises:
+        WorkflowValidationError: If schema format is invalid
+    """
+    if not isinstance(context_schema, dict):
+        raise WorkflowValidationError(
+            "'context_schema' section must be an object mapping field names to schemas"
+        )
+
+    for field_name, field_schema in context_schema.items():
+        if not isinstance(field_schema, (dict, str)):
+            raise WorkflowValidationError(
+                f"context_schema.{field_name}: schema must be an object or type string"
+            )
+
+
+def _validate_identities_section(identities: Dict[str, str]) -> None:
+    """
+    Validate identities section of config.
+
+    Args:
+        identities: Identity definitions (name -> system prompt)
+
+    Raises:
+        WorkflowValidationError: If identity format is invalid
+    """
+    if not isinstance(identities, dict):
+        raise WorkflowValidationError(
+            "'identities' section must be an object mapping identity names to prompts"
+        )
+
+    for identity_name, identity_prompt in identities.items():
+        if not isinstance(identity_prompt, str):
+            raise WorkflowValidationError(
+                f"identities.{identity_name}: identity prompt must be a string, "
+                f"got {type(identity_prompt).__name__}"
+            )
+
+
+def validate_config(config) -> Dict[str, Any]:
+    """
+    Parse and validate config.
+
+    Supports two formats:
+    1. Legacy format: Dict of workflow definitions directly
+    2. Combined config format: Dict with 'workflows', 'context_schema', 'identities' keys
+
+    Args:
+        config: YAML string or dict (workflows only or combined config)
+
+    Returns:
+        Parsed config dict (either workflows directly or combined structure)
+
+    Raises:
+        WorkflowValidationError: If any configuration is invalid
+    """
+    parsed = parse_yaml(config)
+
+    if "workflows" in parsed:
+        workflows = parsed["workflows"]
+        if not isinstance(workflows, dict):
+            raise WorkflowValidationError(
+                "'workflows' section must be an object containing workflow definitions"
+            )
+        for workflow_name, workflow in workflows.items():
+            if not isinstance(workflow, dict):
+                raise WorkflowValidationError(
+                    f"Workflow '{workflow_name}' must be an object containing node definitions"
+                )
+            _validate_workflow_section(workflow_name, workflow)
+
+        context_schema = parsed.get("context_schema")
+        if context_schema is not None:
+            _validate_context_schema_section(context_schema)
+
+        identities = parsed.get("identities")
+        if identities is not None:
+            _validate_identities_section(identities)
+    else:
+        for workflow_name, workflow in parsed.items():
+            if not isinstance(workflow, dict):
+                raise WorkflowValidationError(
+                    f"Workflow '{workflow_name}' must be an object containing node definitions"
+                )
+            _validate_workflow_section(workflow_name, workflow)
+
+    return parsed
+
+
+validate_workflow = _validate_workflow_section
+
+
+def validate_orchestrate_params(
+    initial_workflow_name: str,
+    initial_signals: list,
+) -> None:
+    """Validate orchestrate() parameters before execution starts."""
+    if not isinstance(initial_signals, list):
+        raise WorkflowValidationError(
+            f"'initial_signals' must be a list, got {type(initial_signals).__name__}. "
+            f"Example: initial_signals=['START']"
+        )
+    if not initial_signals:
+        raise WorkflowValidationError(
+            "'initial_signals' cannot be empty - at least one signal is required to start execution"
+        )
+    if not isinstance(initial_workflow_name, str) or not initial_workflow_name:
+        raise WorkflowValidationError(
+            "'initial_workflow_name' must be a non-empty string"
+        )

soe/validation/jinja.py

@@ -0,0 +1,54 @@
+"""
+Jinja template validation utilities.
+
+Used during config validation to catch Jinja errors early.
+"""
+
+from jinja2 import Environment, BaseLoader, TemplateSyntaxError
+from ..types import WorkflowValidationError
+
+
+def _dummy_accumulated_filter(value):
+    """Dummy accumulated filter for validation - just returns value as list."""
+    return [value] if value is not None else []
+
+
+def validate_jinja_syntax(template: str, context_description: str) -> None:
+    """
+    Validate Jinja template syntax at config time.
+
+    Called during config validation to catch Jinja errors early.
+
+    Catches:
+    - Unclosed braces {{ without }}
+    - Unknown filters like | capitalize_all
+    - Basic syntax errors
+
+    Does NOT catch:
+    - Runtime errors like division by zero (depends on context values)
+    - Undefined variables (depends on context at runtime)
+
+    Args:
+        template: The Jinja template string to validate
+        context_description: Description for error messages (e.g., "condition for signal 'DONE'")
+
+    Raises:
+        WorkflowValidationError: If template has syntax or filter errors
+    """
+    if not template or ("{{" not in template and "{%" not in template):
+        return
+    try:
+        env = Environment(loader=BaseLoader())
+        env.filters["accumulated"] = _dummy_accumulated_filter
+        env.parse(template)
+        env.from_string(template)
+    except TemplateSyntaxError as e:
+        raise WorkflowValidationError(
+            f"{context_description}: Jinja syntax error - {e.message}"
+        )
+    except Exception as e:
+        error_msg = str(e)
+        if "filter" in error_msg.lower():
+            raise WorkflowValidationError(
+                f"{context_description}: {error_msg}"
+            )