soe-ai 0.2.0b1__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/types.py

@@ -0,0 +1,209 @@
+"""
+Types for orchestration system
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, Optional, Any, Dict, List
+
+
+class EventTypes:
+    """Constants for telemetry event types"""
+
+    ORCHESTRATION_START = "orchestration_start"
+    SIGNALS_BROADCAST = "signals_broadcast"
+    NODE_EXECUTION = "node_execution"
+    TOOL_CALL = "tool_call"
+    LLM_CALL = "llm_call"
+    SIGNALS_TO_PARENT = "signals_to_parent"
+    NODE_ERROR = "node_error"
+    CONTEXT_WARNING = "context_warning"
+    AGENT_TOOLS_LOADED = "agent_tools_loaded"
+    AGENT_TOOL_CALL = "agent_tool_call"
+    AGENT_TOOL_RESULT = "agent_tool_result"
+    AGENT_TOOL_NOT_FOUND = "agent_tool_not_found"
+    CONFIG_INHERITANCE_START = "config_inheritance_start"
+    CONTEXT_INHERITANCE_START = "context_inheritance_start"
+    CONTEXT_MERGE = "context_merge"
+
+
+class TelemetryBackend(Protocol):
+    """Protocol for telemetry backend"""
+
+    def log_event(self, execution_id: str, event_type: str, **event_data) -> None:
+        ...
+
+
+class ContextBackend(Protocol):
+    """Protocol for context backend"""
+
+    def save_context(self, id: str, context: dict) -> None:
+        ...
+
+    def get_context(self, id: str) -> dict:
+        ...
+
+
+class WorkflowBackend(Protocol):
+    """Protocol for workflow backend"""
+
+    def save_workflows_registry(self, id: str, workflows: Dict[str, Any]) -> None:
+        ...
+
+    def get_workflows_registry(self, id: str) -> Any:
+        ...
+
+    def save_current_workflow_name(self, id: str, name: str) -> None:
+        ...
+
+    def get_current_workflow_name(self, id: str) -> str:
+        ...
+
+
+class BroadcastSignalsCaller(Protocol):
+    """Protocol for broadcast signals caller function"""
+
+    def __call__(self, execution_id: str, signals: List[str]) -> None:
+        ...
+
+
+class NodeCaller(Protocol):
+    """Protocol for node caller function"""
+
+    def __call__(self, execution_id: str, node_config: Dict[str, Any]) -> None:
+        ...
+
+
+class LlmNodeCaller(NodeCaller):
+    """Protocol for LLM node caller function"""
+    pass
+
+
+class RouterNodeCaller(NodeCaller):
+    """Protocol for router node caller function"""
+    pass
+
+
+class AgentNodeCaller(NodeCaller):
+    """Protocol for agent node caller function"""
+    pass
+
+
+class ToolNodeCaller(NodeCaller):
+    """Protocol for tool node caller function"""
+    pass
+
+
+class ChildNodeCaller(NodeCaller):
+    """Protocol for child node caller function"""
+    pass
+
+
+class OrchestrateCaller(Protocol):
+    """Protocol for starting child workflows (wrapper around orchestrate)"""
+
+    def __call__(
+        self,
+        config: Any,
+        initial_workflow_name: str,
+        initial_signals: List[str],
+        initial_context: Dict[str, Any],
+        backends: "Backends",
+        inherit_config_from_id: Optional[str] = None,
+        inherit_context_from_id: Optional[str] = None,
+    ) -> str:
+        ...
+
+
+class CallLlm(Protocol):
+    """Protocol for LLM caller function"""
+
+    def __call__(self, prompt: str, config: Dict[str, Any]) -> str:
+        ...
+
+
+class ConversationHistoryBackend(Protocol):
+    """Protocol for conversation history backend"""
+
+    def get_conversation_history(self, identity: str) -> List[Dict[str, Any]]:
+        ...
+
+    def append_to_conversation_history(self, identity: str, entry: Dict[str, Any]) -> None:
+        ...
+
+    def save_conversation_history(self, identity: str, history: List[Dict[str, Any]]) -> None:
+        ...
+
+    def delete_conversation_history(self, identity: str) -> None:
+        ...
+
+
+class ContextSchemaBackend(Protocol):
+    """Protocol for context schema backend - stores workflow context field schemas.
+
+    Context schemas define the structure and types of context fields used in workflows.
+    These are keyed by execution_id (main_execution_id) so children can access parent's schemas.
+    """
+
+    def save_context_schema(self, execution_id: str, schema: Dict[str, Any]) -> None:
+        """Save context schema for an execution."""
+        ...
+
+    def get_context_schema(self, execution_id: str) -> Optional[Dict[str, Any]]:
+        """Get context schema for an execution."""
+        ...
+
+    def delete_context_schema(self, execution_id: str) -> bool:
+        """Delete context schema for an execution."""
+        ...
+
+
+class IdentityBackend(Protocol):
+    """Protocol for identity backend - stores workflow identity definitions.
+
+    Identities define the participating personas/roles in a workflow.
+    These are used as the initial system prompt for conversation history.
+    Keyed by execution_id (main_execution_id) so children can access parent's identities.
+
+    Identity format is simple: identity_name -> system_prompt (string)
+    Example:
+        assistant: "You are a helpful assistant."
+        coding_expert: "You are an expert programmer."
+    """
+
+    def save_identities(self, execution_id: str, identities: Dict[str, str]) -> None:
+        """Save identity definitions for an execution."""
+        ...
+
+    def get_identities(self, execution_id: str) -> Optional[Dict[str, str]]:
+        """Get all identity definitions for an execution."""
+        ...
+
+    def get_identity(self, execution_id: str, identity_name: str) -> Optional[str]:
+        """Get a specific identity's system prompt."""
+        ...
+
+    def delete_identities(self, execution_id: str) -> bool:
+        """Delete identity definitions for an execution."""
+        ...
+
+
+class Backends(Protocol):
+    """Protocol for orchestration backends"""
+
+    context: ContextBackend
+    workflow: WorkflowBackend
+    telemetry: Optional[TelemetryBackend]
+    conversation_history: Optional[ConversationHistoryBackend]
+    context_schema: Optional[ContextSchemaBackend]
+    identity: Optional[IdentityBackend]
+
+
+class SoeError(Exception):
+    """Base class for all SOE exceptions"""
+    pass
+
+
+class WorkflowValidationError(SoeError):
+    """Raised when workflow or node configuration is invalid (static/startup)"""
+    pass

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",
+]