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

soe/broker.py

@@ -1,7 +1,6 @@
 from uuid import uuid4
-from typing import Dict, List, Any, Union, Callable, Optional
-from .types import Backends, BroadcastSignalsCaller
-from .local_backends import EventTypes
+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
@@ -131,7 +130,7 @@ def orchestrate(
 def broadcast_signals(
     id: str,
     signals: List[str],
-    nodes: Dict[str, Callable[[str, Dict[str, Any]], None]],
+    nodes: Dict[str, NodeCaller],
     backends: Backends,
 ) -> None:
     """Broadcast signals to matching nodes in the current workflow"""
@@ -139,7 +138,7 @@ def broadcast_signals(
 
     register_event(backends, id, EventTypes.SIGNALS_BROADCAST, {"signals": signals})
 
-    workflows_registry = backends.workflow.soe_get_workflows_registry(id)
+    workflows_registry = backends.workflow.get_workflows_registry(id)
 
     workflow_name = backends.workflow.get_current_workflow_name(id)
     workflow = workflows_registry.get(workflow_name, {})

soe/builtin_tools/__init__.py

@@ -0,0 +1,39 @@
+"""
+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
+
+# 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,
+}
+
+
+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

soe/builtin_tools/soe_explore_docs.py

@@ -0,0 +1,290 @@
+from typing import Literal, Optional, List, Callable
+from pathlib import Path
+import os
+
+from soe.docs_index import DOCS_INDEX
+
+# Get the SOE package root directory (where soe/docs/ lives)
+# This goes from soe/builtin_tools/soe_explore_docs.py → soe/builtin_tools → soe/soe → soe/
+SOE_ROOT = Path(__file__).resolve().parent.parent.parent
+
+
+def create_soe_explore_docs_tool(
+    execution_id: str = None,
+    backends = None,
+    tools_registry: dict = None,
+) -> Callable:
+    """
+    Factory for the soe_explore_docs tool.
+
+    Args:
+        execution_id: ID to access workflow data via backends (unused by this tool)
+        backends: Backend services (unused by this tool)
+        tools_registry: Optional registry of available tools (unused by this tool)
+
+    Returns:
+        Configured soe_explore_docs function
+    """
+    return soe_explore_docs
+
+
+def soe_explore_docs(
+    path: str,
+    action: Literal["list", "read", "search", "tree", "get_tags"],
+    query: Optional[str] = None,
+    tag: Optional[str] = None
+) -> str:
+    """
+    Explore SOE documentation using a file-system-like interface.
+
+    This tool lets you navigate and read the SOE documentation hierarchy.
+    Start with action='list' at path='/' to see available docs.
+
+    Args:
+        path: Path to explore. Use '/' for root, 'docs/guide_01_basics.md' for a file,
+              or 'docs/guide_01_basics.md/Section Title' for a specific section.
+        action: What to do at the path:
+            - 'list': Show children (files in a dir, sections in a file)
+            - 'read': Get the content of a file or section
+            - 'tree': Show recursive structure from this path
+            - 'search': Find docs matching query/tag (path ignored)
+            - 'get_tags': List all available tags (path ignored)
+        query: Search term for 'search' action. Matches against path/title.
+        tag: Filter by tag for 'search' action. Use 'get_tags' to see available tags.
+
+    Returns:
+        For 'list': Lines like "[DIR] name/", "[FILE] name.md", "[SEC] Section Title"
+        For 'read': The markdown content of the file or section
+        For 'tree': Indented tree structure with [D]/[F]/[S] markers
+        For 'search': List of matching paths
+        For 'get_tags': List of available tags
+
+    Examples:
+        soe_explore_docs(path="/", action="list")  # See all docs
+        soe_explore_docs(path="docs/guide_01_basics.md", action="list")  # See sections
+        soe_explore_docs(path="docs/guide_01_basics.md", action="read")  # Read full file
+        soe_explore_docs(path="docs/guide_01_basics.md/Quick Start", action="read")  # Read section
+        soe_explore_docs(path="/", action="search", query="agent")  # Find agent-related docs
+    """
+    # Normalize path
+    # Remove leading slash if present to match index keys (which are relative paths like 'soe/docs/...')
+    # But handle root '/' as well
+    clean_path = path.strip("/")
+
+    # Special case: "/" means the main docs directory
+    if clean_path == "" or path == "/":
+        clean_path = "soe/docs"
+
+    # Dispatch actions
+    if action == "list":
+        return _handle_list(clean_path)
+    elif action == "read":
+        return _handle_read(clean_path)
+    elif action == "tree":
+        return _handle_tree(clean_path)
+    elif action == "search":
+        return _handle_search(query, tag)
+    elif action == "get_tags":
+        return _handle_get_tags()
+    else:
+        return f"Error: Unknown action '{action}'"
+
+def _handle_list(path: str) -> str:
+    # If path is empty/root, return root children
+    if path == "" or path == ".":
+        children = DOCS_INDEX.get("root_children", [])
+        return _format_list(children)
+
+    # Check if path exists in index
+    # Try exact match first
+    # Index keys usually end with / for dirs? My build script adds / for dirs.
+
+    # Try as directory
+    dir_key = path if path.endswith("/") else path + "/"
+    if dir_key in DOCS_INDEX["items"]:
+        item = DOCS_INDEX["items"][dir_key]
+        return _format_list(item.get("children", []))
+
+    # Try as file or section (no trailing slash)
+    file_key = path.rstrip("/")
+    if file_key in DOCS_INDEX["items"]:
+        item = DOCS_INDEX["items"][file_key]
+        return _format_list(item.get("children", []))
+
+    return f"Error: Path '{path}' not found in index."
+
+def _format_list(children: List[str]) -> str:
+    if not children:
+        return "(empty)"
+
+    lines = []
+    for child in sorted(children):
+        item = DOCS_INDEX["items"][child]  # Children are always valid in well-formed index
+        type_ = item.get("type", "unknown")
+
+        # Display name is the last part of the path
+        # For sections: docs/file.md/Section -> Section
+        # For files: docs/file.md -> file.md
+        display_name = child.rstrip("/").split("/")[-1]
+
+        if type_ == "dir":
+            lines.append(f"[DIR] {display_name}/")
+        elif type_ == "file":
+            lines.append(f"[FILE] {display_name}")
+        elif type_ == "section":
+            lines.append(f"[SEC] {display_name}")
+
+    return "\n".join(lines)
+
+def _handle_read(path: str) -> str:
+    # Normalize
+    key = path.rstrip("/")
+
+    # Check if it exists as a file/section (exact match on stripped key)
+    if key in DOCS_INDEX["items"]:
+        item = DOCS_INDEX["items"][key]
+        type_ = item.get("type")
+
+        if type_ == "dir":
+            return f"Error: '{path}' is a directory. Use action='list' or 'tree'."
+
+    # Check if it exists as a directory (key + "/")
+    elif (key + "/") in DOCS_INDEX["items"]:
+        return f"Error: '{path}' is a directory. Use action='list' or 'tree'."
+
+    else:
+        return f"Error: Path '{path}' not found."
+
+    # Get file path
+    file_path_str = item.get("file_path") or item.get("path")  # For files, path is file_path
+
+    # Read file relative to SOE package root
+    full_path = SOE_ROOT / file_path_str
+    try:
+        content = full_path.read_text()
+    except FileNotFoundError:
+        return f"Error: File not found at '{full_path}'. The docs index may be out of date."
+    lines = content.splitlines()
+
+    if type_ == "file":
+        return content
+
+    # type_ == "section"
+    start = item["start_line"] - 1
+    end = item["end_line"]
+    if end == -1:
+        end = len(lines)
+
+    section_lines = lines[start:end]
+    return "\n".join(section_lines)
+
+
+def _handle_tree(path: str) -> str:
+    # Recursive listing
+    # We can use the index structure
+
+    # Normalize
+    if path == "" or path == ".":
+        roots = DOCS_INDEX.get("root_children", [])
+        return _build_tree_str(roots, indent=0)
+
+    key = path if path.endswith("/") else path + "/"
+    # Try dir
+    if key in DOCS_INDEX["items"]:
+        return _build_tree_str([key], indent=0)
+
+    # Try file
+    key = path.rstrip("/")
+    if key in DOCS_INDEX["items"]:
+        return _build_tree_str([key], indent=0)
+
+    return f"Error: Path '{path}' not found."
+
+def _build_tree_str(paths: List[str], indent: int) -> str:
+    out = []
+    for p in sorted(paths):
+        item = DOCS_INDEX["items"].get(p)
+        if not item: continue
+
+        display_name = p.rstrip("/").split("/")[-1]
+        prefix = "  " * indent
+
+        type_ = item.get("type")
+        marker = "[D]" if type_ == "dir" else "[F]" if type_ == "file" else "[S]"
+
+        out.append(f"{prefix}{marker} {display_name}")
+
+        # Recurse
+        children = item.get("children", [])
+        if children:
+            out.append(_build_tree_str(children, indent + 1))
+
+    return "\n".join(out)
+
+def _handle_search(query: str, tag: str) -> str:
+    if not query and not tag:
+        return "Error: Provide 'query' or 'tag' for search."
+
+    # Tag filter
+    candidate_paths = set(DOCS_INDEX["items"].keys())
+    if tag:
+        if tag in DOCS_INDEX["tags"]:
+            candidate_paths = set(DOCS_INDEX["tags"][tag])
+        else:
+            return f"No results for tag '{tag}'"
+
+    # Text search - split query into words and match ANY word
+    # Also search in content_preview for better results
+    final_results = set()
+
+    if query:
+        # Split query into words, filter out common words
+        stop_words = {"and", "or", "the", "a", "an", "in", "on", "at", "to", "for", "of", "with", "how", "does", "do", "is", "are", "what"}
+        query_words = [w.lower() for w in query.split() if w.lower() not in stop_words and len(w) > 1]
+
+        if not query_words:
+            # Fall back to full query if all words were filtered
+            query_words = [query.lower()]
+
+        for p in candidate_paths:
+            item = DOCS_INDEX["items"].get(p, {})
+
+            # Search in path, title, and content_preview
+            searchable_text = p.lower()
+            if "title" in item:
+                searchable_text += " " + item["title"].lower()
+            if "content_preview" in item:
+                searchable_text += " " + item["content_preview"].lower()
+
+            # Match if ANY query word is found
+            for word in query_words:
+                if word in searchable_text:
+                    final_results.add(p)
+                    break
+    else:
+        # Tag only search
+        final_results = candidate_paths
+
+    if not final_results:
+        return f"No results found for: {query_words if query else tag}"
+
+    # Dedupe: skip sections if parent file is also in results
+    deduped = set()
+    for r in final_results:
+        parts = r.rsplit("/", 1)
+        if len(parts) == 2 and parts[0] in final_results:
+            continue  # Skip section if parent file matches
+        deduped.add(r)
+
+    # Format results - limit to 20 most relevant
+    sorted_results = sorted(deduped)[:20]
+    result_text = "\n".join(sorted_results)
+
+    if len(deduped) > 20:
+        result_text += f"\n... and {len(deduped) - 20} more results"
+
+    return result_text
+
+def _handle_get_tags() -> str:
+    tags = sorted(DOCS_INDEX.get("tags", {}).keys())
+    return f"Available tags: {tags}"

soe/builtin_tools/soe_get_available_tools.py

@@ -0,0 +1,42 @@
+"""Built-in tool to list available tools."""
+
+from typing import Dict, Any, Callable, List
+
+
+def create_soe_get_available_tools_tool(
+    execution_id: str,
+    backends,
+    tools_registry: Dict[str, Any] = None,
+) -> Callable:
+    """
+    Factory function to create soe_get_available_tools tool.
+
+    Args:
+        execution_id: ID for the execution
+        backends: Backend services
+        tools_registry: Registry of user-provided tools
+
+    Returns:
+        Configured soe_get_available_tools function
+    """
+    from . import BUILTIN_TOOLS
+
+    def soe_get_available_tools() -> Dict[str, List[str]]:
+        """
+        Get all available tools that can be used in workflows.
+
+        Returns:
+            {
+                "builtin_tools": [...list of builtin tool names...],
+                "user_tools": [...list of user-provided tool names...]
+            }
+        """
+        builtin_names = list(BUILTIN_TOOLS.keys())
+        user_names = list(tools_registry.keys()) if tools_registry else []
+
+        return {
+            "builtin_tools": builtin_names,
+            "user_tools": user_names,
+        }
+
+    return soe_get_available_tools