soe-ai 0.2.0b1__py3-none-any.whl

soe/builtin_tools/soe_inject_identity.py

@@ -0,0 +1,64 @@
+"""Built-in identity injection tool."""
+
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_inject_identity_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_inject_identity tool.
+
+    Args:
+        execution_id: ID to access identity data via backends
+        backends: Backend services to fetch/update identities
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_inject_identity function that can add/update identities
+    """
+
+    def soe_inject_identity(identity_name: str, system_prompt: str) -> Dict[str, Any]:
+        """
+        Add or update an identity definition.
+
+        Args:
+            identity_name: Name/key for the identity
+            system_prompt: The system prompt text for this identity
+
+        Returns:
+            Success confirmation with identity info and action taken
+        """
+        identities = backends.identity.get_identities(execution_id)
+
+        if identities is None:
+            identities = {}
+
+        action = "updated" if identity_name in identities else "created"
+
+        identities[identity_name] = system_prompt
+        backends.identity.save_identities(execution_id, identities)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_inject_identity",
+                "identity_name": identity_name,
+                "action": action,
+            },
+        )
+
+        return {
+            "success": True,
+            "identity_name": identity_name,
+            "action": action,
+            "message": f"Successfully {action} identity '{identity_name}'",
+        }
+
+    return soe_inject_identity

soe/builtin_tools/soe_inject_node.py

@@ -0,0 +1,86 @@
+"""Built-in node configuration injection tool."""
+
+import json
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+from ..lib.yaml_parser import parse_yaml
+
+
+def create_soe_inject_node_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_inject_node tool with workflow access
+
+    Args:
+        execution_id: ID to access workflow data via backends
+        backends: Backend services to fetch/update workflows
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_inject_node function that can inject node config into workflows
+    """
+
+    def soe_soe_inject_node(
+        workflow_name: str, node_name: str, node_config_data: str
+    ) -> Dict[str, Any]:
+        """
+        Built-in tool: Inject a node configuration into an existing workflow
+
+        Args:
+            workflow_name: Name of the workflow to modify
+            node_name: Name of the node to inject
+            node_config_data: YAML or JSON string containing the node configuration
+
+        Returns:
+            Success confirmation with injected node info
+        """
+
+        # Get current workflows registry and validate workflow exists
+        workflows_registry = backends.workflow.get_workflows_registry(execution_id)
+
+        if workflow_name not in workflows_registry:
+            raise ValueError(
+                f"Workflow '{workflow_name}' not found in workflows registry"
+            )
+
+        # Parse the node configuration data (prefer JSON, fallback to YAML)
+        node_config = None
+
+        try:
+            node_config = json.loads(node_config_data)
+        except json.JSONDecodeError:
+            node_config = parse_yaml(node_config_data)
+
+        if not isinstance(node_config, dict):
+            raise ValueError("Node configuration must be a dictionary/object")
+
+        # Inject the node configuration into the workflow
+        target_workflow = workflows_registry[workflow_name]
+        target_workflow[node_name] = node_config
+
+        # Save the updated workflows registry back
+        backends.workflow.save_workflows_registry(execution_id, workflows_registry)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_inject_node",
+                "workflow_name": workflow_name,
+                "node_name": node_name,
+            },
+        )
+
+        return {
+            "injected": True,
+            "workflow_name": workflow_name,
+            "node_name": node_name,
+            "message": f"Successfully injected node '{node_name}' into workflow '{workflow_name}'",
+        }
+
+    return soe_soe_inject_node

soe/builtin_tools/soe_inject_workflow.py

@@ -0,0 +1,105 @@
+"""Built-in workflow injection tool."""
+
+import json
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+from ..lib.yaml_parser import parse_yaml
+
+
+def create_soe_inject_workflow_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_inject_workflow tool with workflow access
+
+    Args:
+        execution_id: ID to access workflow data via backends
+        backends: Backend services to fetch/update workflows
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_inject_workflow function that can inject new workflows
+    """
+
+    def soe_inject_workflow(workflow_name: str, workflow_data: str) -> Dict[str, Any]:
+        """
+        Built-in tool: Inject a new workflow into the global workflows configuration
+
+        Args:
+            workflow_name: Name of the new workflow to inject
+            workflow_data: JSON or YAML string containing the workflow definition
+
+        Returns:
+            Success confirmation with injected workflow info
+        """
+
+        # Parse the workflow definition (prefer JSON, fallback to YAML)
+        parsed_workflow = None
+
+        try:
+            parsed_workflow = json.loads(workflow_data)
+        except json.JSONDecodeError:
+            parsed_workflow = parse_yaml(workflow_data)
+
+        if not isinstance(parsed_workflow, dict):
+            raise ValueError("Workflow data must be a dictionary/object")
+
+        # Determine the workflow definition to inject
+        workflow_definition = None
+
+        # If workflow_name is specified in the parsed data, use that specific workflow
+        if workflow_name in parsed_workflow:
+            workflow_definition = parsed_workflow[workflow_name]
+        else:
+            # Check if all keys in parsed_workflow look like node names (have node_type)
+            all_nodes = True
+            for _, value in parsed_workflow.items():
+                if not isinstance(value, dict) or "node_type" not in value:
+                    all_nodes = False
+                    break
+
+            if all_nodes:
+                # All top-level keys are nodes, use the entire structure as the workflow
+                workflow_definition = parsed_workflow
+            elif len(parsed_workflow) == 1:
+                # Single non-node entry, assume it's a workflow container
+                first_workflow_key = list(parsed_workflow.keys())[0]
+                workflow_definition = parsed_workflow[first_workflow_key]
+            else:
+                # Multiple entries, assume entire structure is the workflow
+                workflow_definition = parsed_workflow
+
+        if not workflow_definition:
+            raise ValueError(f"No workflow definition found for injection")
+
+        # Validate the workflow before injecting
+        from ..validation.config import validate_workflow
+        validate_workflow(workflow_name, workflow_definition)
+
+        # Get current workflows registry via backends and inject new workflow
+        workflows_registry = backends.workflow.get_workflows_registry(execution_id)
+        workflows_registry[workflow_name] = workflow_definition
+
+        # Save the updated workflows registry back
+        backends.workflow.save_workflows_registry(execution_id, workflows_registry)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_inject_workflow",
+                "workflow_name": workflow_name,
+            },
+        )
+
+        return {
+            "injected": True,
+            "workflow_name": workflow_name,
+            "message": f"Successfully injected workflow '{workflow_name}'",
+        }
+
+    return soe_inject_workflow

soe/builtin_tools/soe_list_contexts.py

@@ -0,0 +1,73 @@
+"""
+Built-in tool: list_contexts
+Allows agents to list available execution contexts.
+"""
+
+from typing import List, Dict, Any
+import os
+import json
+
+
+def create_soe_list_contexts_tool(backends, execution_id: str, tools_registry=None):
+    """
+    Factory that creates a list_contexts 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 list_contexts(include_current: bool = True) -> Dict[str, Any]:
+        """
+        List available execution contexts.
+
+        Args:
+            include_current: Whether to include current execution in list
+
+        Returns:
+            Dict with current_execution_id and list of context summaries
+        """
+        result = {
+            "current_execution_id": execution_id,
+            "contexts": []
+        }
+
+        # Get context storage directory from backend
+        storage_dir = getattr(backends.context, 'storage_dir', None)
+        if not storage_dir or not os.path.exists(storage_dir):
+            return result
+
+        for filename in os.listdir(storage_dir):
+            if not filename.endswith('.json'):
+                continue
+
+            ctx_id = filename.replace('.json', '')
+
+            if not include_current and ctx_id == execution_id:
+                continue
+
+            # Read minimal info from each context
+            filepath = os.path.join(storage_dir, filename)
+            try:
+                with open(filepath, 'r') as f:
+                    ctx = json.load(f)
+
+                # Get summary info
+                ops = ctx.get("__operational__", {})
+                result["contexts"].append({
+                    "execution_id": ctx_id,
+                    "is_current": ctx_id == execution_id,
+                    "user_request": ctx.get("user_request", [])[-1] if ctx.get("user_request") else None,
+                    "signals": ops.get("signals", [])[-5:],  # Last 5 signals
+                    "node_count": sum(ops.get("nodes", {}).values()),
+                })
+            except Exception:
+                continue
+
+        return result
+
+    return list_contexts

soe/builtin_tools/soe_remove_context_schema_field.py

@@ -0,0 +1,61 @@
+"""Built-in context schema field removal tool."""
+
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_remove_context_schema_field_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_remove_context_schema_field tool.
+
+    Args:
+        execution_id: ID to access context schema data via backends
+        backends: Backend services to fetch/update context schema
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_remove_context_schema_field function
+    """
+
+    def soe_remove_context_schema_field(field_name: str) -> Dict[str, Any]:
+        """
+        Remove a field from the context schema.
+
+        Args:
+            field_name: Name of the field to remove
+
+        Returns:
+            Success confirmation with removed field info
+        """
+        schema = backends.context_schema.get_context_schema(execution_id)
+
+        if schema is None or field_name not in schema:
+            raise ValueError(
+                f"Field '{field_name}' not found in context schema"
+            )
+
+        del schema[field_name]
+        backends.context_schema.save_context_schema(execution_id, schema)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_remove_context_schema_field",
+                "field_name": field_name,
+            },
+        )
+
+        return {
+            "removed": True,
+            "field_name": field_name,
+            "message": f"Successfully removed field '{field_name}' from context schema",
+        }
+
+    return soe_remove_context_schema_field

soe/builtin_tools/soe_remove_identity.py

@@ -0,0 +1,61 @@
+"""Built-in identity removal tool."""
+
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_remove_identity_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_remove_identity tool.
+
+    Args:
+        execution_id: ID to access identity data via backends
+        backends: Backend services to fetch/update identities
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_remove_identity function that can remove identities
+    """
+
+    def soe_remove_identity(identity_name: str) -> Dict[str, Any]:
+        """
+        Remove an identity definition.
+
+        Args:
+            identity_name: Name of the identity to remove
+
+        Returns:
+            Success confirmation with removed identity info
+        """
+        identities = backends.identity.get_identities(execution_id)
+
+        if identities is None or identity_name not in identities:
+            raise ValueError(
+                f"Identity '{identity_name}' not found"
+            )
+
+        del identities[identity_name]
+        backends.identity.save_identities(execution_id, identities)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_remove_identity",
+                "identity_name": identity_name,
+            },
+        )
+
+        return {
+            "removed": True,
+            "identity_name": identity_name,
+            "message": f"Successfully removed identity '{identity_name}'",
+        }
+
+    return soe_remove_identity

soe/builtin_tools/soe_remove_node.py

@@ -0,0 +1,72 @@
+"""Built-in node removal tool."""
+
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_remove_node_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_remove_node tool with workflow access
+
+    Args:
+        execution_id: ID to access workflow data via backends
+        backends: Backend services to fetch/update workflows
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_remove_node function that can remove nodes from workflows
+    """
+
+    def soe_remove_node(workflow_name: str, node_name: str) -> Dict[str, Any]:
+        """
+        Built-in tool: Remove a node from an existing workflow
+
+        Args:
+            workflow_name: Name of the workflow to modify
+            node_name: Name of the node to remove
+
+        Returns:
+            Success confirmation with removed node info
+        """
+        workflows_registry = backends.workflow.get_workflows_registry(execution_id)
+
+        if workflow_name not in workflows_registry:
+            raise ValueError(
+                f"Workflow '{workflow_name}' not found in workflows registry"
+            )
+
+        target_workflow = workflows_registry[workflow_name]
+
+        if node_name not in target_workflow:
+            raise ValueError(
+                f"Node '{node_name}' not found in workflow '{workflow_name}'"
+            )
+
+        del target_workflow[node_name]
+
+        backends.workflow.save_workflows_registry(execution_id, workflows_registry)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_remove_node",
+                "workflow_name": workflow_name,
+                "node_name": node_name,
+            },
+        )
+
+        return {
+            "removed": True,
+            "workflow_name": workflow_name,
+            "node_name": node_name,
+            "message": f"Successfully removed node '{node_name}' from workflow '{workflow_name}'",
+        }
+
+    return soe_remove_node

soe/builtin_tools/soe_remove_workflow.py

@@ -0,0 +1,62 @@
+"""Built-in workflow removal tool."""
+
+from typing import Dict, Any, Callable
+from ..types import EventTypes
+from ..lib.register_event import register_event
+
+
+def create_soe_remove_workflow_tool(
+    execution_id: str,
+    backends,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory function to create soe_remove_workflow tool with workflow access
+
+    Args:
+        execution_id: ID to access workflow data via backends
+        backends: Backend services to fetch/update workflows
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_remove_workflow function that can remove workflows
+    """
+
+    def soe_remove_workflow(workflow_name: str) -> Dict[str, Any]:
+        """
+        Built-in tool: Remove a workflow from the global workflows configuration
+
+        Args:
+            workflow_name: Name of the workflow to remove
+
+        Returns:
+            Success confirmation with removed workflow info
+        """
+        workflows_registry = backends.workflow.get_workflows_registry(execution_id)
+
+        if workflow_name not in workflows_registry:
+            raise ValueError(
+                f"Workflow '{workflow_name}' not found in workflows registry"
+            )
+
+        del workflows_registry[workflow_name]
+
+        backends.workflow.save_workflows_registry(execution_id, workflows_registry)
+
+        register_event(
+            backends,
+            execution_id,
+            EventTypes.NODE_EXECUTION,
+            {
+                "tool": "soe_remove_workflow",
+                "workflow_name": workflow_name,
+            },
+        )
+
+        return {
+            "removed": True,
+            "workflow_name": workflow_name,
+            "message": f"Successfully removed workflow '{workflow_name}'",
+        }
+
+    return soe_remove_workflow

soe/builtin_tools/soe_update_context.py

@@ -0,0 +1,54 @@
+"""
+Built-in tool: update_context
+Allows agents to write context fields dynamically.
+"""
+
+from typing import Any, Dict
+
+
+def create_soe_update_context_tool(backends, execution_id: str, tools_registry=None):
+    """
+    Factory that creates an update_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 update_context(updates: Dict[str, Any]) -> Dict[str, str]:
+        """
+        Update context fields for the current execution.
+
+        Args:
+            updates: Dictionary of field names to values to set
+
+        Returns:
+            Confirmation of updated fields
+        """
+        if not updates:
+            return {"status": "no updates provided"}
+
+        # Don't allow updating operational fields
+        filtered_updates = {
+            k: v for k, v in updates.items()
+            if not k.startswith("__")
+        }
+
+        if not filtered_updates:
+            return {"status": "no valid updates (operational fields cannot be updated)"}
+
+        # Get current context and update
+        context = backends.context.get_context(execution_id)
+        context.update(filtered_updates)
+        backends.context.save_context(execution_id, context)
+
+        return {
+            "status": "updated",
+            "fields": list(filtered_updates.keys())
+        }
+
+    return update_context

soe/docs/_config.yml

@@ -0,0 +1,10 @@
+title: SOE - Signal-driven Orchestration Engine
+description: Infrastructure-agnostic AI workflow orchestration
+theme: jekyll-theme-minimal
+markdown: GFM
+highlighter: rouge
+
+# Navigation structure
+header_pages:
+  - index.md
+  - guide_00_getting_started.md