soe-ai 0.2.0b1__py3-none-any.whl

soe/__init__.py

@@ -0,0 +1,50 @@
+"""
+Orchestration Engine - MVP
+Agent orchestration with event-driven workflow engine
+"""
+
+from .broker import orchestrate, broadcast_signals
+from .nodes import (
+    AgentRequest,
+    AgentResponse,
+    ToolNodeConfigurationError,
+    ToolParameterError,
+)
+from .types import (
+    # Backend protocols - for building custom backends
+    Backends,
+    ContextBackend,
+    WorkflowBackend,
+    TelemetryBackend,
+    ConversationHistoryBackend,
+    ContextSchemaBackend,
+    IdentityBackend,
+    # LLM protocol - for integrating custom LLM providers
+    CallLlm,
+)
+from .init import create_all_nodes, setup_orchestration
+
+__all__ = [
+    # Core functions
+    "orchestrate",
+    "broadcast_signals",
+    # Easy setup
+    "create_all_nodes",
+    "setup_orchestration",
+    # Agent types
+    "AgentRequest",
+    "AgentResponse",
+    # Tool errors
+    "ToolNodeConfigurationError",
+    "ToolParameterError",
+    # Backend protocols
+    "Backends",
+    "ContextBackend",
+    "WorkflowBackend",
+    "TelemetryBackend",
+    "ConversationHistoryBackend",
+    "ContextSchemaBackend",
+    "IdentityBackend",
+    # LLM protocol
+    "CallLlm",
+]

soe/broker.py

@@ -0,0 +1,168 @@
+from uuid import uuid4
+from typing import Dict, List, Any, Union, Optional
+from .types import Backends, BroadcastSignalsCaller, NodeCaller, EventTypes, WorkflowValidationError
+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,
+)
+from .validation import validate_config, validate_operational, validate_orchestrate_params
+from .types import WorkflowValidationError
+
+
+def orchestrate(
+    config: Optional[Union[str, Dict[str, Any]]],
+    initial_workflow_name: str,
+    initial_signals: List[str],
+    initial_context: Dict[str, Any],
+    backends: Backends,
+    broadcast_signals_caller: BroadcastSignalsCaller,
+    inherit_config_from_id: Optional[str] = None,
+    inherit_context_from_id: Optional[str] = None,
+) -> str:
+    """
+    Initialize orchestration with config and trigger initial signals.
+
+    Config can be either:
+
+    1. Workflows only (legacy format):
+       config = {
+           "workflow_name": {
+               "node_name": {...}
+           }
+       }
+
+    2. Combined config with workflows, context_schema, and identities:
+       config = {
+           "workflows": {...},
+           "context_schema": {...},  # optional
+           "identities": {...}       # optional
+       }
+
+    3. Inherited config (config=None, inherit_config_from_id provided):
+       Inherits workflows, identities, and context_schema from an existing
+       execution. Useful for workflow chaining and continuation.
+
+    Inheritance options:
+
+    - inherit_config_from_id: Copy workflows, identities, and context_schema
+      from the specified execution ID. When provided, config is optional.
+
+    - inherit_context_from_id: Copy context from the specified execution ID,
+      but ALWAYS reset __operational__ state. Useful for continuing work
+      with existing context data.
+
+    When context_schema and identities are present (either from config or
+    inherited), they are automatically saved to their respective backends,
+    keyed by the main execution ID so children can access them.
+    """
+    validate_orchestrate_params(initial_workflow_name, initial_signals)
+
+    if config is None and inherit_config_from_id is None:
+        raise WorkflowValidationError(
+            "Either 'config' or 'inherit_config_from_id' must be provided"
+        )
+
+    id = str(uuid4())
+
+    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:
+            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)
+
+    register_event(
+        backends, id, EventTypes.ORCHESTRATION_START,
+        {"workflow_name": initial_workflow_name}
+    )
+
+    backends.workflow.save_workflows_registry(id, 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)
+
+    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)
+
+    broadcast_signals_caller(id, initial_signals)
+
+    return id
+
+
+def broadcast_signals(
+    id: str,
+    signals: List[str],
+    nodes: Dict[str, NodeCaller],
+    backends: Backends,
+) -> None:
+    """Broadcast signals to matching nodes in the current workflow"""
+    context = validate_operational(id, backends)
+
+    register_event(backends, id, EventTypes.SIGNALS_BROADCAST, {"signals": signals})
+
+    workflows_registry = backends.workflow.get_workflows_registry(id)
+
+    workflow_name = backends.workflow.get_current_workflow_name(id)
+    workflow = workflows_registry.get(workflow_name, {})
+
+    for node_name, node_config in workflow.items():
+        triggers = node_config.get("event_triggers", [])
+        if set(triggers) & set(signals):
+            node_type = node_config["node_type"]
+            node_executor = nodes[node_type]
+
+            register_event(
+                backends, id, EventTypes.NODE_EXECUTION,
+                {"node_name": node_name, "node_type": node_type}
+            )
+
+            node_config["name"] = node_name
+            node_executor(id, node_config)
+
+    context = backends.context.get_context(id)
+    parent_id, signals_to_sync = get_signals_for_parent(signals, context)
+
+    if parent_id and signals_to_sync:
+        register_event(
+            backends, id, EventTypes.SIGNALS_TO_PARENT,
+            {"signals": signals_to_sync, "parent_id": parent_id}
+        )
+        broadcast_signals(parent_id, signals_to_sync, nodes, backends)

soe/builtin_tools/__init__.py

@@ -0,0 +1,51 @@
+"""
+Built-in tools registry
+"""
+
+from .soe_inject_workflow import create_soe_inject_workflow_tool
+from .soe_inject_node import create_soe_inject_node_tool
+from .soe_get_workflows import create_soe_get_workflows_tool
+from .soe_get_available_tools import create_soe_get_available_tools_tool
+from .soe_explore_docs import create_soe_explore_docs_tool
+from .soe_remove_workflow import create_soe_remove_workflow_tool
+from .soe_remove_node import create_soe_remove_node_tool
+from .soe_get_context import create_soe_get_context_tool
+from .soe_update_context import create_soe_update_context_tool
+from .soe_copy_context import create_soe_copy_context_tool
+from .soe_list_contexts import create_soe_list_contexts_tool
+from .soe_add_signal import create_soe_add_signal_tool
+from .soe_call_tool import create_soe_call_tool_tool
+from .soe_get_identities import create_soe_get_identities_tool
+from .soe_inject_identity import create_soe_inject_identity_tool
+from .soe_remove_identity import create_soe_remove_identity_tool
+from .soe_get_context_schema import create_soe_get_context_schema_tool
+from .soe_inject_context_schema_field import create_soe_inject_context_schema_field_tool
+from .soe_remove_context_schema_field import create_soe_remove_context_schema_field_tool
+
+# Registry of all available built-in tools
+BUILTIN_TOOLS = {
+    "soe_inject_workflow": create_soe_inject_workflow_tool,
+    "soe_inject_node": create_soe_inject_node_tool,
+    "soe_get_workflows": create_soe_get_workflows_tool,
+    "soe_get_available_tools": create_soe_get_available_tools_tool,
+    "soe_explore_docs": create_soe_explore_docs_tool,
+    "soe_remove_workflow": create_soe_remove_workflow_tool,
+    "soe_remove_node": create_soe_remove_node_tool,
+    "soe_get_context": create_soe_get_context_tool,
+    "soe_update_context": create_soe_update_context_tool,
+    "soe_copy_context": create_soe_copy_context_tool,
+    "soe_list_contexts": create_soe_list_contexts_tool,
+    "soe_add_signal": create_soe_add_signal_tool,
+    "soe_call_tool": create_soe_call_tool_tool,
+    "soe_get_identities": create_soe_get_identities_tool,
+    "soe_inject_identity": create_soe_inject_identity_tool,
+    "soe_remove_identity": create_soe_remove_identity_tool,
+    "soe_get_context_schema": create_soe_get_context_schema_tool,
+    "soe_inject_context_schema_field": create_soe_inject_context_schema_field_tool,
+    "soe_remove_context_schema_field": create_soe_remove_context_schema_field_tool,
+}
+
+
+def get_builtin_tool_factory(tool_name: str):
+    """Get factory function for built-in tool"""
+    return BUILTIN_TOOLS.get(tool_name)

soe/builtin_tools/soe_add_signal.py

@@ -0,0 +1,82 @@
+"""Built-in tool to add a signal to a node's event emissions."""
+
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_add_signal_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create add_signal tool.
+    """
+
+    def add_signal(
+        workflow_name: str, node_name: str, signal_name: str, condition: str
+    ) -> Dict[str, Any]:
+        """
+        Add a signal to a node's event_emissions list.
+
+        Args:
+            workflow_name: Name of the workflow
+            node_name: Name of the node
+            signal_name: Name of the signal to add
+            condition: Jinja condition for the signal
+
+        Returns:
+            Success confirmation
+        """
+        workflows_registry = backends.workflow.get_workflows_registry(execution_id)
+
+        if workflow_name not in workflows_registry:
+            raise ValueError(f"Workflow '{workflow_name}' not found")
+
+        workflow = workflows_registry[workflow_name]
+        if node_name not in workflow:
+            raise ValueError(f"Node '{node_name}' not found in workflow '{workflow_name}'")
+
+        node_config = workflow[node_name]
+
+        if "event_emissions" not in node_config:
+            node_config["event_emissions"] = []
+
+        # Check if signal already exists
+        for emission in node_config["event_emissions"]:
+            if emission.get("signal_name") == signal_name:
+                # Update existing
+                emission["condition"] = condition
+                backends.workflow.save_workflows_registry(execution_id, workflows_registry)
+                return {
+                    "status": "updated",
+                    "message": f"Updated signal '{signal_name}' in node '{node_name}'"
+                }
+
+        # Add new signal
+        node_config["event_emissions"].append({
+            "signal_name": signal_name,
+            "condition": condition
+        })
+
+        backends.workflow.save_workflows_registry(execution_id, workflows_registry)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "add_signal",
+                "workflow_name": workflow_name,
+                "node_name": node_name,
+                "signal": signal_name
+            },
+        )
+
+        return {
+            "status": "added",
+            "message": f"Added signal '{signal_name}' to node '{node_name}'"
+        }
+
+    return add_signal

soe/builtin_tools/soe_call_tool.py

@@ -0,0 +1,111 @@
+"""
+Built-in dynamic tool invocation.
+
+Allows LLMs to call any registered tool by name at runtime.
+This enables meta-level tool orchestration.
+"""
+
+import json
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_call_tool_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict,
+) -> Callable:
+    """
+    Factory function to create call_tool with access to tools registry.
+
+    Args:
+        execution_id: Current execution ID
+        backends: Backend services
+        tools_registry: Registry of available tools {name: {"function": callable, ...}}
+
+    Returns:
+        Configured call_tool function
+    """
+
+    def call_tool(tool_name: str, arguments: str = "{}") -> Dict[str, Any]:
+        """
+        Dynamically invoke a registered tool by name.
+
+        This is a meta-tool that allows calling any other tool at runtime.
+        Useful for dynamic workflows where the tool to call is determined
+        by context or user input.
+
+        Args:
+            tool_name: Name of the tool to invoke (must be registered)
+            arguments: JSON string of arguments to pass to the tool
+
+        Returns:
+            The result from the invoked tool, or an error dict
+
+        Example:
+            call_tool("get_secret", '{"key": "password"}')
+            call_tool("write_file", '{"path": "test.txt", "content": "hello"}')
+        """
+        # Parse arguments
+        try:
+            args = json.loads(arguments) if arguments else {}
+        except json.JSONDecodeError as e:
+            return {
+                "error": f"Invalid JSON arguments: {e}",
+                "tool_name": tool_name,
+            }
+
+        # Check if tool exists
+        if tool_name not in tools_registry:
+            available = list(tools_registry.keys())
+            return {
+                "error": f"Tool '{tool_name}' not found",
+                "available_tools": available[:20],  # Limit to avoid huge responses
+            }
+
+        # Get tool function
+        tool_entry = tools_registry[tool_name]
+        if isinstance(tool_entry, dict):
+            tool_func = tool_entry.get("function")
+        elif callable(tool_entry):
+            tool_func = tool_entry
+        else:
+            return {"error": f"Invalid tool registry entry for '{tool_name}'"}
+
+        if not callable(tool_func):
+            return {"error": f"Tool '{tool_name}' is not callable"}
+
+        # Log the dynamic invocation
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.TOOL_CALL,
+            {
+                "meta_tool": "call_tool",
+                "invoked_tool": tool_name,
+                "arguments": args,
+            },
+        )
+
+        # Invoke the tool
+        try:
+            result = tool_func(**args)
+            return {
+                "success": True,
+                "tool_name": tool_name,
+                "result": result,
+            }
+        except TypeError as e:
+            # Argument mismatch
+            return {
+                "error": f"Argument error for '{tool_name}': {e}",
+                "tool_name": tool_name,
+            }
+        except Exception as e:
+            return {
+                "error": f"Tool '{tool_name}' failed: {e}",
+                "tool_name": tool_name,
+            }
+
+    return call_tool

soe/builtin_tools/soe_copy_context.py

@@ -0,0 +1,80 @@
+"""
+Built-in tool: copy_context
+Allows agents to copy context fields between executions or within the same execution.
+"""
+
+from typing import Dict, Any, Optional
+
+
+def create_soe_copy_context_tool(backends, execution_id: str, tools_registry=None):
+    """
+    Factory that creates a copy_context tool bound to the current execution.
+
+    Args:
+        backends: Backend instances (needs context backend)
+        execution_id: Current execution ID
+        tools_registry: Tool registry (unused, for interface compatibility)
+
+    Returns:
+        Configured tool function
+    """
+
+    def copy_context(
+        source_execution_id: Optional[str] = None,
+        fields: Optional[Dict[str, str]] = None,
+        all_fields: bool = False,
+        target_execution_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Copy context fields between executions or within the same execution.
+
+        Args:
+            source_execution_id: Execution ID to copy from (default: current)
+            fields: Dict of {source_field: target_field} to copy
+            all_fields: If True, copy all non-operational fields
+            target_execution_id: Execution ID to copy to (default: current)
+
+        Returns:
+            Dict with copy results
+        """
+        source_id = source_execution_id or execution_id
+        target_id = target_execution_id or execution_id
+
+        # Get source context
+        source_context = backends.context.get_context(source_id)
+
+        # Filter out operational fields
+        source_filtered = {k: v for k, v in source_context.items() if not k.startswith("__")}
+
+        # Get target context
+        target_context = backends.context.get_context(target_id)
+
+        copied_fields = {}
+
+        if all_fields:
+            # Copy all non-operational fields
+            for field, value in source_filtered.items():
+                target_context[field] = value
+                copied_fields[field] = field
+        elif fields:
+            # Copy specific field mappings
+            for source_field, target_field in fields.items():
+                if source_field in source_filtered:
+                    target_context[target_field] = source_filtered[source_field]
+                    copied_fields[source_field] = target_field
+                else:
+                    return {"error": f"Source field '{source_field}' not found in execution {source_id}"}
+        else:
+            return {"error": "Must specify either 'fields' mapping or 'all_fields=True'"}
+
+        # Save target context
+        backends.context.save_context(target_id, target_context)
+
+        return {
+            "status": "copied",
+            "source_execution": source_id,
+            "target_execution": target_id,
+            "fields_copied": copied_fields,
+        }
+
+    return copy_context