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

soe/lib/child_context.py

@@ -0,0 +1,46 @@
+"""
+Child context preparation utilities.
+
+Prepares initial context for child workflows with parent metadata.
+"""
+
+import copy
+from typing import Any, Dict
+
+from .context_fields import get_field
+
+
+PARENT_INFO_KEY = "__parent__"
+
+
+def prepare_child_context(
+    parent_context: Dict[str, Any],
+    node_config: Dict[str, Any],
+    parent_execution_id: str,
+    main_execution_id: str,
+) -> Dict[str, Any]:
+    """
+    Prepare initial context for child workflow.
+
+    Includes:
+    - Input fields copied from parent context (current value, not full history)
+    - __parent__ metadata for communication back to parent
+    """
+    child_context: Dict[str, Any] = {}
+
+    # Copy specified input fields from parent (current value only)
+    # orchestrate() will wrap these in history lists
+    for field_name in node_config.get("input_fields", []):
+        if field_name in parent_context:
+            # Use get_field to get current value, not full history
+            child_context[field_name] = copy.deepcopy(get_field(parent_context, field_name))
+
+    # Inject parent info for child-to-parent communication
+    child_context[PARENT_INFO_KEY] = {
+        "parent_execution_id": parent_execution_id,
+        "signals_to_parent": node_config.get("signals_to_parent", []),
+        "context_updates_to_parent": node_config.get("context_updates_to_parent", []),
+        "main_execution_id": main_execution_id,
+    }
+
+    return child_context

soe/lib/context_fields.py

@@ -0,0 +1,51 @@
+"""
+Context field utilities for history-aware field storage.
+
+Fields are stored as lists to maintain update history.
+Reading always returns the last (most recent) value.
+"""
+
+from typing import Any, Dict, List
+
+
+def set_field(context: Dict[str, Any], field: str, value: Any) -> None:
+    """Set a context field, appending to history list."""
+    if field.startswith("__"):
+        context[field] = value
+        return
+
+    if field not in context:
+        context[field] = [value]
+    else:
+        context[field].append(value)
+
+
+def get_field(context: Dict[str, Any], field: str) -> Any:
+    """Get a context field value (last item in history list)."""
+    if field.startswith("__"):
+        return context.get(field)
+
+    value = context.get(field)
+    if value is None:
+        return None
+
+    return value[-1]
+
+
+def get_accumulated(context: Dict[str, Any], field: str) -> List[Any]:
+    """
+    Get full accumulated history for a field.
+
+    If history has exactly one entry and it's a list, returns that list
+    (common case: initial context passed a list as value for fan-out).
+    """
+    if field not in context:
+        return []
+
+    history = context[field]
+
+    # If history has exactly one entry and it's a list, return that list
+    if len(history) == 1 and isinstance(history[0], list):
+        return list(history[0])
+
+    return list(history)

soe/lib/inheritance.py

@@ -0,0 +1,172 @@
+"""
+Configuration and context inheritance utilities.
+
+Handles:
+- Extracting and saving config sections (workflows, identity, schema) from parsed config
+- Inheriting config from existing executions
+- Inheriting context from existing executions
+
+Used for workflow initialization and chaining.
+"""
+
+import copy
+from typing import Dict, Any, Optional
+
+from ..types import Backends
+
+
+def save_config_sections(
+    execution_id: str,
+    backends: Backends,
+    identities: Optional[Dict[str, str]] = None,
+    context_schema: Optional[Dict[str, Any]] = None,
+) -> None:
+    """
+    Save identities and context_schema to their respective backends.
+
+    This is the shared logic for both:
+    - Extracting sections from new config
+    - Inheriting sections from existing execution
+
+    Args:
+        execution_id: Target execution ID
+        backends: Backend services
+        identities: Identity definitions to save (optional)
+        context_schema: Context schema to save (optional)
+    """
+    if identities and backends.identity:
+        backends.identity.save_identities(execution_id, identities)
+
+    if context_schema and backends.context_schema:
+        backends.context_schema.save_context_schema(execution_id, context_schema)
+
+
+def extract_and_save_config_sections(
+    parsed_config: Dict[str, Any],
+    execution_id: str,
+    backends: Backends,
+) -> Dict[str, Any]:
+    """
+    Extract workflows, context_schema, and identities from config.
+
+    If config has 'workflows' key, it's the combined structure:
+    - Extract and save context_schema to context_schema backend
+    - Extract and save identities to identity backend
+    - Return just the workflows portion
+
+    Args:
+        parsed_config: Parsed config dictionary
+        execution_id: Execution ID to save sections under
+        backends: Backend services
+
+    Returns:
+        The workflows registry portion of the config
+    """
+    if "workflows" in parsed_config:
+        workflows = parsed_config["workflows"]
+
+        save_config_sections(
+            execution_id=execution_id,
+            backends=backends,
+            identities=parsed_config.get("identities"),
+            context_schema=parsed_config.get("context_schema"),
+        )
+
+        return workflows
+
+    # Simple/Legacy structure - entire config is workflows
+    return parsed_config
+
+
+def inherit_config(
+    source_execution_id: str,
+    target_execution_id: str,
+    backends: Backends,
+) -> Dict[str, Any]:
+    """
+    Inherit configuration from source execution to target execution.
+
+    Copies:
+    - Workflows registry
+    - Identities (if available)
+    - Context schema (if available)
+
+    Args:
+        source_execution_id: Execution ID to inherit from
+        target_execution_id: Execution ID to inherit to
+        backends: Backend services
+
+    Returns:
+        The workflows registry (for validation and use)
+
+    Raises:
+        ValueError: If source execution has no workflows registry
+    """
+    workflows_registry = backends.workflow.get_workflows_registry(source_execution_id)
+    if not workflows_registry:
+        raise ValueError(
+            f"Cannot inherit config from execution '{source_execution_id}': "
+            "no workflows registry found"
+        )
+
+    # Copy workflows to new execution
+    backends.workflow.save_workflows_registry(target_execution_id, workflows_registry)
+
+    # Get source identities and schema
+    source_identities = None
+    source_schema = None
+
+    if backends.identity:
+        source_identities = backends.identity.get_identities(source_execution_id)
+
+    if backends.context_schema:
+        source_schema = backends.context_schema.get_context_schema(source_execution_id)
+
+    # Save to target using shared logic
+    save_config_sections(
+        execution_id=target_execution_id,
+        backends=backends,
+        identities=source_identities,
+        context_schema=source_schema,
+    )
+
+    return workflows_registry
+
+
+def inherit_context(
+    source_execution_id: str,
+    backends: Backends,
+) -> Dict[str, Any]:
+    """
+    Inherit context from source execution, resetting operational state.
+
+    Copies all context fields except __operational__, which is reset
+    for the new execution.
+
+    Args:
+        source_execution_id: Execution ID to inherit context from
+        backends: Backend services
+
+    Returns:
+        Context dictionary ready for new execution (without __operational__)
+
+    Raises:
+        ValueError: If source execution has no context
+    """
+    source_context = backends.context.get_context(source_execution_id)
+    if not source_context:
+        raise ValueError(
+            f"Cannot inherit context from execution '{source_execution_id}': "
+            "no context found"
+        )
+
+    # Deep copy context, excluding internal fields (will be reset for new execution)
+    # __operational__ - execution tracking state
+    # __parent__ - parent workflow metadata (not relevant for new execution)
+    inherited_context = {
+        k: copy.deepcopy(v)
+        for k, v in source_context.items()
+        if k not in ("__operational__", "__parent__")
+    }
+
+    return inherited_context

soe/lib/jinja_render.py

@@ -0,0 +1,113 @@
+"""
+Jinja template rendering utilities for prompt processing.
+"""
+
+import re
+from typing import Dict, Any, Set, List, Tuple
+
+from jinja2 import Environment, BaseLoader, TemplateSyntaxError
+
+from .context_fields import get_field
+
+
+def _create_accumulated_filter(full_context: Dict[str, Any]):
+    """Create an accumulated filter that returns full history for a field."""
+    def accumulated_filter(value):
+        """
+        Return the full accumulated history list for a context field.
+
+        Usage in templates:
+            {{ context.field | accumulated }}  - returns full list
+            {{ context.field | accumulated | length }}  - count of items
+            {{ context.field | accumulated | join(', ') }}  - join all items
+
+        If history has exactly one entry and it's a list, returns that list
+        (common case: initial context passed a list as value).
+        """
+        # Find the field in full_context by matching the last value
+        for key, hist_list in full_context.items():
+            if key.startswith("__"):
+                continue
+            if isinstance(hist_list, list) and hist_list and hist_list[-1] == value:
+                # If history has exactly one entry and it's a list, return that list
+                if len(hist_list) == 1 and isinstance(hist_list[0], list):
+                    return hist_list[0]
+                return hist_list
+        # Fallback: return value as single-item list
+        return [value] if value is not None else []
+
+    return accumulated_filter
+
+
+def _extract_context_variables(template: str) -> Set[str]:
+    """Extract variable names from a Jinja template."""
+    if not template:
+        return set()
+
+    variables = set()
+
+    dot_pattern = r'\{\{[^}]*context\.([a-zA-Z_][a-zA-Z0-9_]*)'
+    for match in re.finditer(dot_pattern, template):
+        variables.add(match.group(1))
+
+    bracket_pattern = r"\{\{[^}]*context\[['\"]([a-zA-Z_][a-zA-Z0-9_]*)['\"]"
+    for match in re.finditer(bracket_pattern, template):
+        variables.add(match.group(1))
+
+    return variables
+
+
+def get_context_for_prompt(
+    full_context: Dict[str, Any],
+    template: str
+) -> Tuple[Dict[str, Any], List[str]]:
+    """Extract the context needed for a prompt template."""
+    required_fields = _extract_context_variables(template)
+    filtered_context = {}
+    warnings = []
+
+    for field in required_fields:
+        if field not in full_context:
+            warnings.append(f"Context field '{field}' referenced in prompt but not found in context")
+        else:
+            value = get_field(full_context, field)
+            if value is None:
+                warnings.append(f"Context field '{field}' is None")
+                filtered_context[field] = None
+            elif value == "":
+                warnings.append(f"Context field '{field}' is empty string")
+                filtered_context[field] = ""
+            else:
+                filtered_context[field] = value
+
+    return filtered_context, warnings
+
+
+def render_prompt(prompt: str, context: Dict[str, Any]) -> Tuple[str, List[str]]:
+    """Render a Jinja template prompt with the given context."""
+    if not prompt:
+        return prompt, []
+
+    if "{{" not in prompt and "{%" not in prompt:
+        return prompt, []
+
+    _, warnings = get_context_for_prompt(context, prompt)
+
+    unwrapped = {k: get_field(context, k) for k in context if not k.startswith("__")}
+    for k, v in context.items():
+        if k.startswith("__"):
+            unwrapped[k] = v
+
+    try:
+        jinja_env = Environment(loader=BaseLoader())
+        # Register custom filters
+        jinja_env.filters["accumulated"] = _create_accumulated_filter(context)
+        template = jinja_env.from_string(prompt)
+        rendered = template.render(context=unwrapped)
+        return rendered, warnings
+    except TemplateSyntaxError as e:
+        warnings.append(f"Jinja syntax error: {e}")
+        return prompt, warnings
+    except Exception as e:
+        warnings.append(f"Template rendering error: {e}")
+        return prompt, warnings

soe/lib/operational.py

@@ -0,0 +1,51 @@
+"""
+Operational context initialization.
+
+This module handles initialization of the operational state structure.
+Runtime updates are handled by register_event.py.
+"""
+
+from typing import Dict, Any
+
+PARENT_INFO_KEY = "__parent__"
+
+
+def wrap_context_fields(context: Dict[str, Any]) -> Dict[str, Any]:
+    """Wrap context field values in lists for history tracking.
+
+    Internal fields (starting with __) are not wrapped.
+    If context has __parent__, fields are already wrapped (from parent workflow).
+    """
+    # Child workflows receive pre-wrapped fields from parent
+    if PARENT_INFO_KEY in context:
+        return context
+
+    return {
+        k: [v] if not k.startswith("__") else v
+        for k, v in context.items()
+    }
+
+
+def add_operational_state(
+    execution_id: str,
+    context: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Add operational state to context if not present. Returns new context dict."""
+    if "__operational__" in context:
+        return context
+
+    parent_info = context.get(PARENT_INFO_KEY, {})
+    inherited_main_id = parent_info.get("main_execution_id")
+    main_id = inherited_main_id if inherited_main_id else execution_id
+
+    return {
+        **context,
+        "__operational__": {
+            "signals": [],
+            "nodes": {},
+            "llm_calls": 0,
+            "tool_calls": 0,
+            "errors": 0,
+            "main_execution_id": main_id
+        }
+    }

soe/lib/parent_sync.py

@@ -0,0 +1,71 @@
+"""
+Parent sync utilities for sub-orchestration.
+
+These functions check if a signal or context update should be propagated
+to the parent workflow based on the injected __parent__ metadata.
+"""
+
+from typing import Dict, Any, Tuple, Optional, List
+from ..types import Backends
+
+PARENT_INFO_KEY = "__parent__"
+
+
+def get_signals_for_parent(
+    signals: List[str], context: Dict[str, Any]
+) -> Tuple[Optional[str], List[str]]:
+    """Get the subset of signals that should be propagated to the parent."""
+    parent_info = context.get(PARENT_INFO_KEY)
+    if not parent_info:
+        return (None, [])
+
+    parent_execution_id = parent_info.get("parent_execution_id")
+    signals_to_parent = set(parent_info.get("signals_to_parent", []))
+    matching_signals = [s for s in signals if s in signals_to_parent]
+
+    return (parent_execution_id, matching_signals)
+
+
+def _check_parent_context_sync(
+    key: str, context: Dict[str, Any]
+) -> Tuple[Optional[str], bool]:
+    """Determine if a context update should be propagated to the parent."""
+    parent_info = context.get(PARENT_INFO_KEY)
+    if not parent_info:
+        return (None, False)
+
+    parent_execution_id = parent_info.get("parent_execution_id")
+    context_updates_to_parent = parent_info.get("context_updates_to_parent", [])
+
+    if key in context_updates_to_parent:
+        return (parent_execution_id, True)
+
+    return (parent_execution_id, False)
+
+
+def sync_context_to_parent(
+    context: Dict[str, Any],
+    updated_keys: List[str],
+    backends: Backends,
+) -> None:
+    """Sync updated context keys to the parent workflow if configured.
+
+    For each key in updated_keys that is configured for parent sync:
+    - If parent doesn't have the key, copy the full list from child
+    - If parent already has the key, extend with new items from child
+    """
+    for key in updated_keys:
+        parent_id, should_sync = _check_parent_context_sync(key, context)
+        if should_sync and parent_id:
+            parent_context = backends.context.get_context(parent_id)
+            child_history = context[key]
+
+            if key in parent_context:
+                # Append new items from child to parent's existing list
+                parent_context[key].extend(child_history)
+            else:
+                # Initialize parent with child's history
+                parent_context[key] = child_history
+
+            backends.context.save_context(parent_id, parent_context)
+            sync_context_to_parent(parent_context, [key], backends)

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)