soe-ai 0.2.0b1__py3-none-any.whl

soe/local_backends/storage/conversation_history.py

@@ -0,0 +1,82 @@
+"""
+Local file-based conversation history backend
+
+This backend stores conversation history by identity, allowing agents
+to persist their conversation state across different node executions.
+"""
+
+import json
+from pathlib import Path
+from typing import List, Dict, Any
+
+
+class LocalConversationHistoryBackend:
+    """File-based conversation history storage backend"""
+
+    def __init__(self, storage_dir: str = "./orchestration_data/conversations"):
+        """
+        Initialize local conversation history backend
+
+        Args:
+            storage_dir: Directory to store conversation history files
+        """
+        self.storage_dir = Path(storage_dir)
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+
+    def get_conversation_history(self, identity: str) -> List[Dict[str, Any]]:
+        """
+        Get conversation history for an identity
+
+        Args:
+            identity: Unique identity identifier for the agent
+
+        Returns:
+            List of conversation entries, empty if not found
+        """
+        history_file = self.storage_dir / f"{identity}.json"
+
+        if not history_file.exists():
+            return []
+
+        with open(history_file, "r") as f:
+            return json.load(f)
+
+    def append_to_conversation_history(
+        self, identity: str, entry: Dict[str, Any]
+    ) -> None:
+        """
+        Append a single entry to the conversation history
+
+        Args:
+            identity: Unique identity identifier for the agent
+            entry: Conversation entry to append
+        """
+        history = self.get_conversation_history(identity)
+        history.append(entry)
+        self.save_conversation_history(identity, history)
+
+    def save_conversation_history(
+        self, identity: str, history: List[Dict[str, Any]]
+    ) -> None:
+        """
+        Save full conversation history for an identity
+
+        Args:
+            identity: Unique identity identifier for the agent
+            history: Full conversation history list to save
+        """
+        history_file = self.storage_dir / f"{identity}.json"
+
+        with open(history_file, "w") as f:
+            json.dump(history, f, indent=2, default=str)
+
+    def delete_conversation_history(self, identity: str) -> None:
+        """Delete conversation history for an identity."""
+        history_file = self.storage_dir / f"{identity}.json"
+        if history_file.exists():
+            history_file.unlink()
+
+    def cleanup_all(self) -> None:
+        """Delete all conversation history files. Used for test cleanup."""
+        for history_file in self.storage_dir.glob("*.json"):
+            history_file.unlink()

soe/local_backends/storage/identity.py

@@ -0,0 +1,118 @@
+"""
+Identity backend for workflow identity definitions.
+
+Stores and retrieves identities that define the participating personas/roles
+in a workflow. These are used as initial system prompts for conversation history.
+Keyed by execution_id (main_execution_id) so children can access parent's identities.
+Dumb storage only - no validation logic.
+
+Identity format is simple: identity_name -> system_prompt (string)
+Example:
+    assistant: "You are a helpful assistant."
+    coding_expert: "You are an expert programmer."
+"""
+
+from typing import Dict, Optional
+import os
+import yaml
+
+from ...lib.yaml_parser import parse_yaml
+
+
+class LocalIdentityBackend:
+    """
+    Local file-based identity storage backend.
+
+    Stores identity definitions as YAML files keyed by execution_id.
+    """
+
+    def __init__(self, storage_dir: str = "./orchestration_data/identities"):
+        self.storage_dir = storage_dir
+        os.makedirs(storage_dir, exist_ok=True)
+        self._cache: Dict[str, Dict[str, str]] = {}
+
+    def _get_identity_path(self, execution_id: str) -> str:
+        """Get file path for an execution's identities."""
+        return os.path.join(self.storage_dir, f"{execution_id}.yaml")
+
+    def save_identities(self, execution_id: str, identities: Dict[str, str]) -> None:
+        """
+        Save identity definitions for an execution.
+
+        Args:
+            execution_id: Execution ID (typically main_execution_id)
+            identities: Identity definitions (identity_name -> system_prompt)
+        """
+        path = self._get_identity_path(execution_id)
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.dump(identities, f, default_flow_style=False)
+        self._cache[execution_id] = identities
+
+    def get_identities(self, execution_id: str) -> Optional[Dict[str, str]]:
+        """
+        Get identity definitions for an execution.
+
+        Args:
+            execution_id: Execution ID (typically main_execution_id)
+
+        Returns:
+            Identity definitions dict (identity_name -> system_prompt) or None if not found
+        """
+        if execution_id in self._cache:
+            return self._cache[execution_id]
+
+        path = self._get_identity_path(execution_id)
+        if os.path.exists(path):
+            with open(path, "r", encoding="utf-8") as f:
+                identities = parse_yaml(f.read())
+            self._cache[execution_id] = identities
+            return identities
+
+        return None
+
+    def get_identity(self, execution_id: str, identity_name: str) -> Optional[str]:
+        """
+        Get a specific identity's system prompt.
+
+        Args:
+            execution_id: Execution ID (typically main_execution_id)
+            identity_name: Name of the identity
+
+        Returns:
+            System prompt string or None if not found
+        """
+        identities = self.get_identities(execution_id)
+        if identities and identity_name in identities:
+            return identities[identity_name]
+        return None
+
+    def delete_identities(self, execution_id: str) -> bool:
+        """
+        Delete an execution's identity definitions.
+
+        Args:
+            execution_id: Execution ID (typically main_execution_id)
+
+        Returns:
+            True if deleted, False if not found
+        """
+        path = self._get_identity_path(execution_id)
+        deleted = False
+
+        if execution_id in self._cache:
+            del self._cache[execution_id]
+            deleted = True
+
+        if os.path.exists(path):
+            os.remove(path)
+            deleted = True
+
+        return deleted
+
+    def cleanup_all(self) -> None:
+        """Cleanup all stored data."""
+        self._cache.clear()
+        if os.path.exists(self.storage_dir):
+            for filename in os.listdir(self.storage_dir):
+                if filename.endswith(".yaml"):
+                    os.remove(os.path.join(self.storage_dir, filename))

soe/local_backends/storage/schema.py

@@ -0,0 +1,96 @@
+"""
+Context schema backend for workflow context field validation.
+
+Stores and retrieves schemas that define the structure of workflow context fields.
+Keyed by execution_id (main_execution_id) so children can access parent's schemas.
+Dumb storage only - no validation logic (see soe/lib/schema_validation.py).
+"""
+
+from typing import Dict, Any, Optional
+import os
+import yaml
+
+from ...lib.yaml_parser import parse_yaml
+
+
+class LocalContextSchemaBackend:
+    """
+    Local file-based context schema storage backend.
+
+    Stores context schemas as YAML files keyed by execution_id.
+    """
+
+    def __init__(self, storage_dir: str = "./orchestration_data/schemas"):
+        self.storage_dir = storage_dir
+        os.makedirs(storage_dir, exist_ok=True)
+        self._cache: Dict[str, Dict[str, Any]] = {}
+
+    def _get_schema_path(self, execution_id: str) -> str:
+        """Get file path for an execution's context schema."""
+        return os.path.join(self.storage_dir, f"{execution_id}.yaml")
+
+    def save_context_schema(self, execution_id: str, schema: Dict[str, Any]) -> None:
+        """
+        Save a context schema for an execution.
+
+        Args:
+            execution_id: Execution ID (typically main_execution_id)
+            schema: Schema definition dict
+        """
+        path = self._get_schema_path(execution_id)
+        with open(path, "w", encoding="utf-8") as f:
+            yaml.dump(schema, f, default_flow_style=False)
+        self._cache[execution_id] = schema
+
+    def get_context_schema(self, execution_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get context schema for an execution.
+
+        Args:
+            execution_id: Execution ID (typically main_execution_id)
+
+        Returns:
+            Schema dict or None if not found
+        """
+        # Check cache first
+        if execution_id in self._cache:
+            return self._cache[execution_id]
+
+        # Load from file
+        path = self._get_schema_path(execution_id)
+        if os.path.exists(path):
+            with open(path, "r", encoding="utf-8") as f:
+                schema = parse_yaml(f.read())
+            self._cache[execution_id] = schema
+            return schema
+
+        return None
+
+    def delete_context_schema(self, execution_id: str) -> bool:
+        """
+        Delete an execution's context schema.
+
+        Args:
+            execution_id: Execution ID (typically main_execution_id)
+
+        Returns:
+            True if deleted, False if not found
+        """
+        path = self._get_schema_path(execution_id)
+        if os.path.exists(path):
+            os.remove(path)
+            self._cache.pop(execution_id, None)
+            return True
+        return False
+
+    def cleanup_all(self) -> None:
+        """
+        Remove all stored context schemas.
+
+        This method is useful for test cleanup to remove all stored data.
+        """
+        import shutil
+        if os.path.exists(self.storage_dir):
+            shutil.rmtree(self.storage_dir)
+            os.makedirs(self.storage_dir, exist_ok=True)
+        self._cache.clear()

soe/local_backends/storage/telemetry.py

@@ -0,0 +1,72 @@
+"""
+Local file-based telemetry backend - dumb storage only.
+"""
+
+import json
+from pathlib import Path
+from typing import Dict, Any
+from ...types import EventTypes
+
+
+class LocalTelemetryBackend:
+    """File-based telemetry storage backend"""
+
+    def __init__(self, storage_dir: str = "./orchestration_data/telemetry"):
+        """
+        Initialize local telemetry backend
+
+        Args:
+            storage_dir: Directory to store telemetry files
+        """
+        self.storage_dir = Path(storage_dir)
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+
+    def log_event(self, execution_id: str, event_type: str, **event_data) -> None:
+        """
+        Log an event for an execution ID
+
+        Args:
+            execution_id: Unique execution identifier
+            event_type: Type of event (use EventTypes constants)
+            **event_data: Additional event-specific data (caller provides timestamp)
+        """
+        event = {
+            "event_type": event_type,
+            **event_data,
+        }
+
+        telemetry_file = self.storage_dir / f"{execution_id}.jsonl"
+
+        with open(telemetry_file, "a") as f:
+            f.write(json.dumps(event) + "\n")
+
+    def get_events(self, execution_id: str) -> list[Dict[str, Any]]:
+        """
+        Get all events for execution ID
+
+        Args:
+            execution_id: Unique execution identifier
+
+        Returns:
+            List of event dictionaries, empty if not found
+        """
+        telemetry_file = self.storage_dir / f"{execution_id}.jsonl"
+
+        if not telemetry_file.exists():
+            return []
+
+        events = []
+        with open(telemetry_file, "r") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        events.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        continue
+        return events
+
+    def cleanup_all(self) -> None:
+        """Delete all telemetry files. Used for test cleanup."""
+        for telemetry_file in self.storage_dir.glob("*.jsonl"):
+            telemetry_file.unlink()

soe/local_backends/storage/workflow.py

@@ -0,0 +1,56 @@
+"""Local file-based workflow backend - dumb storage only."""
+
+import json
+from pathlib import Path
+from typing import Dict, Any
+
+
+class LocalWorkflowBackend:
+    """File-based workflow storage backend."""
+
+    def __init__(self, storage_dir: str = "./orchestration_data/workflows"):
+        self.storage_dir = Path(storage_dir)
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+
+    def save_workflows_registry(
+        self, execution_id: str, workflows_registry: Dict[str, Any]
+    ) -> None:
+        """Save workflows registry for execution ID."""
+        workflows_file = self.storage_dir / f"{execution_id}_workflows.json"
+
+        with open(workflows_file, "w") as f:
+            json.dump(workflows_registry, f, indent=2, default=str)
+
+    def get_workflows_registry(self, execution_id: str) -> Dict[str, Any]:
+        """Get workflows registry for execution ID."""
+        workflows_file = self.storage_dir / f"{execution_id}_workflows.json"
+
+        if not workflows_file.exists():
+            return {}
+
+        with open(workflows_file, "r") as f:
+            return json.load(f)
+
+    def save_current_workflow_name(self, execution_id: str, workflow_name: str) -> None:
+        """Save current workflow name for execution ID."""
+        current_workflow_file = self.storage_dir / f"{execution_id}_current.txt"
+
+        with open(current_workflow_file, "w") as f:
+            f.write(workflow_name)
+
+    def get_current_workflow_name(self, execution_id: str) -> str:
+        """Get current workflow name for execution ID."""
+        current_workflow_file = self.storage_dir / f"{execution_id}_current.txt"
+
+        if not current_workflow_file.exists():
+            return ""
+
+        with open(current_workflow_file, "r") as f:
+            return f.read().strip()
+
+    def cleanup_all(self) -> None:
+        """Delete all workflow files. Used for test cleanup."""
+        for workflow_file in self.storage_dir.glob("*_workflows.json"):
+            workflow_file.unlink()
+        for current_file in self.storage_dir.glob("*_current.txt"):
+            current_file.unlink()

soe/nodes/__init__.py

@@ -0,0 +1,13 @@
+"""
+Orchestration nodes - different types of workflow nodes
+"""
+
+from .agent.types import AgentRequest, AgentResponse
+from .tool.types import ToolNodeConfigurationError, ToolParameterError
+
+__all__ = [
+    "AgentRequest",
+    "AgentResponse",
+    "ToolNodeConfigurationError",
+    "ToolParameterError",
+]

soe/nodes/agent/__init__.py

@@ -0,0 +1,10 @@
+"""
+Agent node - AI reasoning with tool execution capabilities
+"""
+
+from .types import AgentRequest, AgentResponse
+
+__all__ = [
+    "AgentRequest",
+    "AgentResponse",
+]

soe/nodes/agent/factory.py

@@ -0,0 +1,134 @@
+"""
+Agent node factory
+
+Orchestrates the multi-stage loop (Router -> Response/Parameter -> Execution)
+using the AgentLoopState for internal tracking.
+"""
+
+from typing import Dict, Any, Callable, List
+from .state import get_operational_state, prepare_agent_context
+from .lib.loop_state import AgentLoopState
+from .lib.tools import load_tools_and_build_signatures
+from .lib.loop_handlers import handle_finish_action, handle_tool_call_action
+from .stages import execute_router_stage
+from ..lib.signal_emission import emit_completion_signals, handle_llm_failure
+from ...types import BroadcastSignalsCaller, AgentNodeCaller, EventTypes
+from ...lib.register_event import register_event
+from ..lib.context import save_output_to_context
+from ...validation.operational import validate_operational
+from .validation import validate_node_config
+
+
+def create_agent_node_caller(
+    backends,
+    tools: List[Dict[str, Any]],
+    call_llm: Callable,
+    broadcast_signals_caller: BroadcastSignalsCaller,
+) -> AgentNodeCaller:
+    """
+    Create agent node caller with pre-loaded dependencies.
+
+    Args:
+        backends: Backend services
+        tools: List of tool configs, each with {"function": callable, "max_retries": int, "failure_signal": str}
+        call_llm: LLM caller function
+        broadcast_signals_caller: Signal broadcaster
+    """
+    tools_registry: Dict[str, Dict[str, Any]] = {
+        tool_config["function"].__name__: tool_config for tool_config in tools
+    }
+
+    def execute_agent_node(execution_id: str, node_config: Dict[str, Any]) -> None:
+        validate_operational(execution_id, backends)
+        validate_node_config(node_config)
+
+        operational_state = get_operational_state(execution_id, node_config, backends)
+
+        register_event(backends, execution_id, EventTypes.LLM_CALL, {"stage": "router"})
+
+        loop_state = AgentLoopState.create(
+            history_key=operational_state.history_key,
+            backends=backends,
+            max_retries=operational_state.max_retries
+        )
+
+        agent_context = prepare_agent_context(execution_id, node_config, backends, loop_state.tool_responses)
+        tools_signature = load_tools_and_build_signatures(
+            agent_context.tool_names, tools_registry, execution_id, backends
+        )
+
+        register_event(
+            backends=backends,
+            execution_id=execution_id,
+            event_type=EventTypes.AGENT_TOOLS_LOADED,
+            data={
+                "node_name": node_config.get("name", "unknown"),
+                "agent_tools": agent_context.tool_names,
+                "registry_tools": list(tools_registry.keys()),
+            }
+        )
+
+        while loop_state.can_retry():
+            router_response = execute_router_stage(
+                call_llm=call_llm,
+                agent_context=agent_context,
+                loop_state=loop_state,
+                tools_signature=tools_signature,
+                config=node_config,
+                max_retries=operational_state.max_retries,
+            )
+
+            if router_response.action == "finish":
+                final_response = handle_finish_action(
+                    call_llm=call_llm,
+                    agent_context=agent_context,
+                    loop_state=loop_state,
+                    node_config=node_config,
+                    backends=backends,
+                    operational_state=operational_state,
+                )
+
+                save_output_to_context(execution_id, operational_state.output_field, final_response.output, backends)
+
+                if operational_state.output_field:
+                    if operational_state.output_field in operational_state.context:
+                        operational_state.context[operational_state.output_field].append(final_response.output)
+                    else:
+                        operational_state.context[operational_state.output_field] = [final_response.output]
+
+                emit_completion_signals(
+                    selected_signal=final_response.selected_signal,
+                    node_config=node_config,
+                    operational_state=operational_state,
+                    broadcast_signals_caller=broadcast_signals_caller,
+                    execution_id=execution_id,
+                )
+                return
+
+            elif router_response.action == "call_tool":
+                handle_tool_call_action(
+                    call_llm=call_llm,
+                    tool_name=router_response.tool_name,
+                    tools_registry=tools_registry,
+                    agent_context=agent_context,
+                    loop_state=loop_state,
+                    node_config=node_config,
+                    operational_state=operational_state,
+                    backends=backends,
+                    execution_id=execution_id,
+                )
+
+        error_msg = f"Agent execution exceeded max retries ({loop_state.max_retries})."
+        if loop_state.errors:
+            error_msg += f" Last error: {loop_state.errors[-1]}"
+
+        handle_llm_failure(
+            failure_signal=operational_state.llm_failure_signal,
+            error_message=error_msg,
+            node_type="agent",
+            execution_id=execution_id,
+            backends=backends,
+            broadcast_signals_caller=broadcast_signals_caller,
+        )
+
+    return execute_agent_node