soe-ai 0.2.0b1__py3-none-any.whl

soe/lib/register_event.py

@@ -0,0 +1,75 @@
+"""
+Unified event registration for telemetry and operational state.
+
+Records events to telemetry backend and updates operational context state
+(signals, nodes, llm_calls, tool_calls, errors).
+"""
+
+from datetime import datetime
+from typing import Dict, Any, Optional
+from ..types import Backends, EventTypes
+
+
+def register_event(
+    backends: Backends,
+    execution_id: str,
+    event_type: str,
+    data: Optional[Dict[str, Any]] = None
+) -> None:
+    """
+    Log telemetry and update operational state based on event type.
+
+    Args:
+        backends: Backend services
+        execution_id: The execution ID
+        event_type: Event type from EventTypes enum
+        data: Event-specific data
+    """
+    data = data or {}
+
+    # Log to telemetry if available
+    if backends.telemetry is not None:
+        backends.telemetry.log_event(
+            execution_id,
+            event_type,
+            timestamp=datetime.utcnow().isoformat() + "Z",
+            context=data
+        )
+
+    # Update operational state based on event type
+
+    if event_type == EventTypes.SIGNALS_BROADCAST:
+        context = backends.context.get_context(execution_id)
+        operational = context["__operational__"]
+        signals = data.get("signals", [])
+        operational["signals"].extend(signals)
+        backends.context.save_context(execution_id, context)
+
+    elif event_type == EventTypes.NODE_EXECUTION:
+        node_name = data.get("node_name")
+        if node_name:
+            context = backends.context.get_context(execution_id)
+            operational = context["__operational__"]
+            nodes = operational["nodes"]
+            if node_name not in nodes:
+                nodes[node_name] = 0
+            nodes[node_name] += 1
+            backends.context.save_context(execution_id, context)
+
+    elif event_type == EventTypes.LLM_CALL:
+        context = backends.context.get_context(execution_id)
+        operational = context["__operational__"]
+        operational["llm_calls"] += 1
+        backends.context.save_context(execution_id, context)
+
+    elif event_type == EventTypes.NODE_ERROR:
+        context = backends.context.get_context(execution_id)
+        operational = context["__operational__"]
+        operational["errors"] += 1
+        backends.context.save_context(execution_id, context)
+
+    elif event_type in (EventTypes.TOOL_CALL, EventTypes.AGENT_TOOL_CALL):
+        context = backends.context.get_context(execution_id)
+        operational = context["__operational__"]
+        operational["tool_calls"] += 1
+        backends.context.save_context(execution_id, context)

soe/lib/schema_validation.py

@@ -0,0 +1,134 @@
+"""
+Schema validation utilities for Pydantic model generation.
+
+Converts schema definitions to Pydantic models for runtime validation.
+Logic extracted from backends to centralize in lib.
+"""
+
+from typing import Dict, Any, Optional, Type, List
+from pydantic import BaseModel, create_model, Field, RootModel
+import json
+
+
+# Type mapping from schema types to Python types
+TYPE_MAPPING = {
+    "string": str,
+    "text": str,
+    "str": str,
+    "integer": int,
+    "int": int,
+    "number": float,
+    "float": float,
+    "boolean": bool,
+    "bool": bool,
+    "list": list,
+    "array": list,
+    "dict": dict,
+    "object": dict,
+    "any": Any,
+}
+
+
+def _schema_field_to_type(field_def: Any, model_name: str) -> Any:
+    """Resolve a schema field definition to a Python type (supports nested properties/items)."""
+    if isinstance(field_def, str):
+        field_def = {"type": field_def}
+
+    if not isinstance(field_def, dict):
+        return Any
+
+    type_name = field_def.get("type", "any").lower()
+
+    if type_name in ("object", "dict"):
+        properties = field_def.get("properties")
+        if isinstance(properties, dict) and properties:
+            nested_model = schema_to_pydantic(properties, model_name=f"{model_name}Nested")
+            return nested_model
+        return dict
+
+    if type_name in ("list", "array"):
+        items = field_def.get("items")
+        if items:
+            if isinstance(items, str):
+                items = {"type": items}
+            item_type = _schema_field_to_type(items, model_name=f"{model_name}Item")
+            return List[item_type]
+        return list
+
+    return TYPE_MAPPING.get(type_name, Any)
+
+
+def schema_to_root_model(
+    field_def: Dict[str, Any],
+    model_name: str = "RootModel"
+) -> Type[BaseModel]:
+    """Convert a single field schema into a RootModel for flat output validation."""
+    if isinstance(field_def, str):
+        field_def = {"type": field_def}
+
+    root_type = _schema_field_to_type(field_def, model_name=model_name)
+
+    class DynamicRoot(RootModel[root_type]):
+        pass
+
+    DynamicRoot.__name__ = model_name
+    return DynamicRoot
+
+
+def schema_to_pydantic(
+    schema: Dict[str, Any],
+    model_name: str = "DynamicModel"
+) -> Type[BaseModel]:
+    """
+    Convert a schema dict to a Pydantic model.
+
+    Schema format:
+    {
+        "field_name": {
+            "type": "string",
+            "description": "Field description",  # optional
+            "required": true,  # optional, default true
+            "default": null  # optional
+        }
+    }
+
+    Args:
+        schema: Dict mapping field names to field definitions
+        model_name: Name for the generated Pydantic model
+
+    Returns:
+        Dynamically created Pydantic model class
+    """
+    fields = {}
+
+    for field_name, field_def in schema.items():
+        # Handle simple type definition (just the type name as string)
+        if isinstance(field_def, str):
+            field_def = {"type": field_def}
+
+        # Get Python type (supports nested properties/items)
+        python_type = _schema_field_to_type(field_def, model_name=f"{model_name}{field_name.title()}")
+
+        # Get field metadata
+        description = field_def.get("description", "")
+        required = field_def.get("required", True)
+        default = field_def.get("default", None)
+
+        # Build field tuple
+        if required and default is None:
+            # Required field with no default
+            if description:
+                field_info = (python_type, Field(..., description=description))
+            else:
+                field_info = (python_type, ...)
+        else:
+            # Optional field or has default
+            if description:
+                field_info = (Optional[python_type], Field(default=default, description=description))
+            else:
+                field_info = (Optional[python_type], default)
+
+        fields[field_name] = field_info
+
+    # Allow extra fields to be preserved (important for nested partial schemas)
+    return create_model(model_name, **fields, __config__={"extra": "allow"})

soe/lib/yaml_parser.py

@@ -0,0 +1,14 @@
+"""YAML parsing utilities."""
+
+import yaml
+from typing import Dict, Any, Union
+
+
+def parse_yaml(data: Union[str, Dict[str, Any]]) -> Dict[str, Any]:
+    """Parse YAML string to dict, or return dict as-is."""
+    if isinstance(data, str):
+        try:
+            return yaml.safe_load(data)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid YAML configuration: {e}")
+    return data

soe/local_backends/__init__.py

@@ -0,0 +1,18 @@
+"""
+Local file-based backends for orchestration testing
+"""
+
+from .storage.context import LocalContextBackend
+from .storage.workflow import LocalWorkflowBackend
+from .storage.telemetry import LocalTelemetryBackend
+from .storage.conversation_history import LocalConversationHistoryBackend
+from .factory import create_local_backends, create_in_memory_backends
+
+__all__ = [
+    "LocalContextBackend",
+    "LocalWorkflowBackend",
+    "LocalTelemetryBackend",
+    "LocalConversationHistoryBackend",
+    "create_local_backends",
+    "create_in_memory_backends",
+]

soe/local_backends/factory.py

@@ -0,0 +1,124 @@
+"""
+Factory for creating local backends
+"""
+
+from typing import Optional, Any
+from .storage.context import LocalContextBackend
+from .storage.workflow import LocalWorkflowBackend
+from .storage.telemetry import LocalTelemetryBackend
+from .storage.conversation_history import LocalConversationHistoryBackend
+from .storage.schema import LocalContextSchemaBackend
+from .storage.identity import LocalIdentityBackend
+from .in_memory.context import InMemoryContextBackend
+from .in_memory.workflow import InMemoryWorkflowBackend
+from .in_memory.telemetry import InMemoryTelemetryBackend
+from .in_memory.conversation_history import InMemoryConversationHistoryBackend
+from .in_memory.schema import InMemoryContextSchemaBackend
+from .in_memory.identity import InMemoryIdentityBackend
+
+
+class LocalBackends:
+    """Container for local backends"""
+
+    def __init__(
+        self,
+        context_backend: Any,
+        workflow_backend: Any,
+        telemetry_backend: Optional[Any] = None,
+        conversation_history_backend: Optional[Any] = None,
+        context_schema_backend: Optional[Any] = None,
+        identity_backend: Optional[Any] = None,
+    ):
+        self.context = context_backend
+        self.workflow = workflow_backend
+        self.telemetry = telemetry_backend
+        self.conversation_history = conversation_history_backend
+        self.context_schema = context_schema_backend
+        self.identity = identity_backend
+
+    def cleanup_all(self) -> None:
+        """
+        Cleanup all backend data
+
+        This method is useful for test cleanup to remove all stored data
+        """
+        self.context.cleanup_all()
+        self.workflow.cleanup_all()
+        if self.telemetry:
+            self.telemetry.cleanup_all()
+        if self.conversation_history:
+            self.conversation_history.cleanup_all()
+        if self.context_schema:
+            self.context_schema.cleanup_all()
+        if self.identity:
+            self.identity.cleanup_all()
+
+
+def create_local_backends(
+    context_storage_dir: str = "./orchestration_data/contexts",
+    workflow_storage_dir: str = "./orchestration_data/workflows",
+    telemetry_storage_dir: Optional[str] = None,
+    conversation_history_storage_dir: Optional[str] = "./orchestration_data/conversations",
+    context_schema_storage_dir: Optional[str] = "./orchestration_data/schemas",
+    identity_storage_dir: Optional[str] = "./orchestration_data/identities",
+) -> LocalBackends:
+    """
+    Create local file-based backends for testing and development
+
+    Args:
+        context_storage_dir: Directory for context storage
+        workflow_storage_dir: Directory for workflow storage
+        telemetry_storage_dir: Directory for telemetry storage (optional)
+        conversation_history_storage_dir: Directory for conversation history storage (optional)
+        context_schema_storage_dir: Directory for context schema storage (optional)
+        identity_storage_dir: Directory for identity storage (optional)
+
+    Returns:
+        LocalBackends instance with context, workflow, and optional backends
+    """
+    context_backend = LocalContextBackend(context_storage_dir)
+    workflow_backend = LocalWorkflowBackend(workflow_storage_dir)
+
+    telemetry_backend = None
+    if telemetry_storage_dir:
+        telemetry_backend = LocalTelemetryBackend(telemetry_storage_dir)
+
+    conversation_history_backend = None
+    if conversation_history_storage_dir:
+        conversation_history_backend = LocalConversationHistoryBackend(
+            conversation_history_storage_dir
+        )
+
+    context_schema_backend = None
+    if context_schema_storage_dir:
+        context_schema_backend = LocalContextSchemaBackend(context_schema_storage_dir)
+
+    identity_backend = None
+    if identity_storage_dir:
+        identity_backend = LocalIdentityBackend(identity_storage_dir)
+
+    return LocalBackends(
+        context_backend,
+        workflow_backend,
+        telemetry_backend,
+        conversation_history_backend,
+        context_schema_backend,
+        identity_backend,
+    )
+
+
+def create_in_memory_backends() -> LocalBackends:
+    """
+    Create in-memory backends for testing
+
+    Returns:
+        LocalBackends instance with in-memory backends
+    """
+    return LocalBackends(
+        context_backend=InMemoryContextBackend(),
+        workflow_backend=InMemoryWorkflowBackend(),
+        telemetry_backend=InMemoryTelemetryBackend(),
+        conversation_history_backend=InMemoryConversationHistoryBackend(),
+        context_schema_backend=InMemoryContextSchemaBackend(),
+        identity_backend=InMemoryIdentityBackend(),
+    )

soe/local_backends/in_memory/context.py

@@ -0,0 +1,38 @@
+"""
+In-memory context backend
+"""
+
+from typing import Dict, Any
+
+
+class InMemoryContextBackend:
+    """In-memory context storage backend"""
+
+    def __init__(self):
+        self._storage: Dict[str, Dict[str, Any]] = {}
+
+    def get_context(self, execution_id: str) -> Dict[str, Any]:
+        """
+        Get context for execution ID
+
+        Args:
+            execution_id: Unique execution identifier
+
+        Returns:
+            Context dictionary, empty if not found
+        """
+        return self._storage.get(execution_id, {})
+
+    def save_context(self, execution_id: str, context: Dict[str, Any]) -> None:
+        """
+        Save context for execution ID
+
+        Args:
+            execution_id: Unique execution identifier
+            context: Context dictionary to save
+        """
+        self._storage[execution_id] = context.copy()
+
+    def cleanup_all(self) -> None:
+        """Cleanup all data"""
+        self._storage.clear()

soe/local_backends/in_memory/conversation_history.py

@@ -0,0 +1,60 @@
+"""
+In-memory conversation history backend
+"""
+
+from typing import Dict, Any, List
+
+
+class InMemoryConversationHistoryBackend:
+    """In-memory conversation history backend"""
+
+    def __init__(self):
+        self._history: Dict[str, List[Dict[str, Any]]] = {}
+
+    def get_conversation_history(self, identity: str) -> List[Dict[str, Any]]:
+        """
+        Get conversation history for identity
+
+        Args:
+            identity: User/Agent identity
+
+        Returns:
+            List of conversation messages
+        """
+        return self._history.get(identity, [])
+
+    def append_to_conversation_history(self, identity: str, entry: Dict[str, Any]) -> None:
+        """
+        Append entry to conversation history
+
+        Args:
+            identity: User/Agent identity
+            entry: Message entry to append
+        """
+        if identity not in self._history:
+            self._history[identity] = []
+        self._history[identity].append(entry)
+
+    def save_conversation_history(self, identity: str, history: List[Dict[str, Any]]) -> None:
+        """
+        Save full conversation history
+
+        Args:
+            identity: User/Agent identity
+            history: Full history list
+        """
+        self._history[identity] = history
+
+    def delete_conversation_history(self, identity: str) -> None:
+        """
+        Delete conversation history for identity
+
+        Args:
+            identity: User/Agent identity
+        """
+        if identity in self._history:
+            del self._history[identity]
+
+    def cleanup_all(self) -> None:
+        """Cleanup all data"""
+        self._history.clear()

soe/local_backends/in_memory/identity.py

@@ -0,0 +1,52 @@
+"""In-memory identity backend - dumb storage only.
+
+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."
+"""
+
+from typing import Dict, Optional
+
+
+class InMemoryIdentityBackend:
+    """In-memory identity backend.
+
+    Stores identity definitions per execution. Identities define the
+    participating personas/roles and are used as initial system prompts.
+    """
+
+    def __init__(self):
+        self._identities: Dict[str, Dict[str, str]] = {}
+
+    def save_identities(self, execution_id: str, identities: Dict[str, str]) -> None:
+        """Save identity definitions for execution."""
+        self._identities[execution_id] = identities
+
+    def get_identities(self, execution_id: str) -> Optional[Dict[str, str]]:
+        """Get identity definitions for execution."""
+        return self._identities.get(execution_id)
+
+    def get_identity(self, execution_id: str, identity_name: str) -> Optional[str]:
+        """Get a specific identity's system prompt."""
+        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 identity definitions for execution.
+
+        Returns:
+            True if deleted, False if not found
+        """
+        if execution_id in self._identities:
+            del self._identities[execution_id]
+            return True
+        return False
+
+    def cleanup_all(self) -> None:
+        """Cleanup all data."""
+        self._identities.clear()

soe/local_backends/in_memory/schema.py

@@ -0,0 +1,40 @@
+"""In-memory context schema backend - dumb storage only.
+
+Keyed by execution_id (main_execution_id) so children can access parent's schemas.
+"""
+
+from typing import Dict, Any, Optional
+
+
+class InMemoryContextSchemaBackend:
+    """In-memory context schema backend."""
+
+    def __init__(self):
+        self._schemas: Dict[str, Dict[str, Any]] = {}
+
+    def save_context_schema(self, execution_id: str, schema: Dict[str, Any]) -> None:
+        """Save context schema for execution."""
+        self._schemas[execution_id] = schema
+
+    def get_context_schema(self, execution_id: str) -> Optional[Dict[str, Any]]:
+        """Get context schema for execution."""
+        return self._schemas.get(execution_id)
+
+    def delete_context_schema(self, execution_id: str) -> bool:
+        """
+        Delete context schema for execution.
+
+        Args:
+            execution_id: Execution ID (typically main_execution_id)
+
+        Returns:
+            True if deleted, False if not found
+        """
+        if execution_id in self._schemas:
+            del self._schemas[execution_id]
+            return True
+        return False
+
+    def cleanup_all(self) -> None:
+        """Cleanup all data"""
+        self._schemas.clear()

soe/local_backends/in_memory/telemetry.py

@@ -0,0 +1,38 @@
+"""
+In-memory telemetry backend - dumb storage only.
+"""
+
+from typing import Dict, Any, List
+
+
+class InMemoryTelemetryBackend:
+    """In-memory telemetry backend"""
+
+    def __init__(self):
+        self._events: Dict[str, List[Dict[str, Any]]] = {}
+
+    def log_event(self, execution_id: str, event_type: str, **event_data) -> None:
+        """
+        Log telemetry event
+
+        Args:
+            execution_id: Execution ID
+            event_type: Type of event
+            **event_data: Additional event data
+        """
+        if execution_id not in self._events:
+            self._events[execution_id] = []
+
+        event = {
+            "event_type": event_type,
+            **event_data
+        }
+        self._events[execution_id].append(event)
+
+    def get_events(self, execution_id: str) -> List[Dict[str, Any]]:
+        """Get all events for an execution ID"""
+        return self._events.get(execution_id, [])
+
+    def cleanup_all(self) -> None:
+        """Cleanup all data"""
+        self._events.clear()

soe/local_backends/in_memory/workflow.py

@@ -0,0 +1,33 @@
+"""In-memory workflow backend - dumb storage only."""
+
+from typing import Dict, Any
+import copy
+
+
+class InMemoryWorkflowBackend:
+    """In-memory workflow storage backend."""
+
+    def __init__(self):
+        self._registries: Dict[str, Any] = {}
+        self._current_workflows: Dict[str, str] = {}
+
+    def save_workflows_registry(self, id: str, workflows: Dict[str, Any]) -> None:
+        """Save workflows registry for execution ID."""
+        self._registries[id] = copy.deepcopy(workflows)
+
+    def get_workflows_registry(self, id: str) -> Any:
+        """Get workflows registry for execution ID."""
+        return copy.deepcopy(self._registries.get(id))
+
+    def save_current_workflow_name(self, id: str, name: str) -> None:
+        """Save current workflow name for execution ID."""
+        self._current_workflows[id] = name
+
+    def get_current_workflow_name(self, id: str) -> str:
+        """Get current workflow name for execution ID."""
+        return self._current_workflows.get(id, "")
+
+    def cleanup_all(self) -> None:
+        """Cleanup all data."""
+        self._registries.clear()
+        self._current_workflows.clear()

soe/local_backends/storage/context.py

@@ -0,0 +1,57 @@
+"""
+Local file-based context backend
+"""
+
+import json
+from pathlib import Path
+from typing import Dict, Any
+
+
+class LocalContextBackend:
+    """File-based context storage backend"""
+
+    def __init__(self, storage_dir: str = "./orchestration_data/contexts"):
+        """
+        Initialize local context backend
+
+        Args:
+            storage_dir: Directory to store context files
+        """
+        self.storage_dir = Path(storage_dir)
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+
+    def get_context(self, execution_id: str) -> Dict[str, Any]:
+        """
+        Get context for execution ID
+
+        Args:
+            execution_id: Unique execution identifier
+
+        Returns:
+            Context dictionary, empty if not found
+        """
+        context_file = self.storage_dir / f"{execution_id}.json"
+
+        if not context_file.exists():
+            return {}
+
+        with open(context_file, "r") as f:
+            return json.load(f)
+
+    def save_context(self, execution_id: str, context: Dict[str, Any]) -> None:
+        """
+        Save context for execution ID
+
+        Args:
+            execution_id: Unique execution identifier
+            context: Context dictionary to save
+        """
+        context_file = self.storage_dir / f"{execution_id}.json"
+
+        with open(context_file, "w") as f:
+            json.dump(context, f, indent=2, default=str)
+
+    def cleanup_all(self) -> None:
+        """Delete all context files. Used for test cleanup."""
+        for context_file in self.storage_dir.glob("*.json"):
+            context_file.unlink()