smartify-ai 0.1.0__py3-none-any.whl

smartify/engine/scheduler.py

@@ -0,0 +1,380 @@
+"""DAG-based scheduler for Grid execution.
+
+The scheduler determines node execution order based on:
+1. Parent-child relationships (when executionMode is 'parent')
+2. Explicit edges (when executionMode is 'explicit')
+3. runAfter dependencies
+4. Parallel execution settings
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional, Set
+from collections import defaultdict
+
+from smartify.models.grid import (
+    GridSpec,
+    NodeSpec,
+    NodeKind,
+    ExecutionMode,
+)
+
+
+class NodeState(str, Enum):
+    """Execution state of a node."""
+    PENDING = "pending"       # Not yet ready to run
+    READY = "ready"           # Dependencies satisfied, can run
+    RUNNING = "running"       # Currently executing
+    COMPLETED = "completed"   # Finished successfully
+    FAILED = "failed"         # Finished with error
+    SKIPPED = "skipped"       # Skipped due to condition
+    BLOCKED = "blocked"       # Waiting on external input
+
+
+@dataclass
+class NodeExecution:
+    """Tracks execution state for a node."""
+    node: NodeSpec
+    state: NodeState = NodeState.PENDING
+    dependencies: Set[str] = field(default_factory=set)
+    dependents: Set[str] = field(default_factory=set)
+    output: Optional[dict] = None
+    error: Optional[str] = None
+    attempt: int = 0
+
+
+class DAGScheduler:
+    """Schedules node execution based on dependency graph.
+    
+    Usage:
+        scheduler = DAGScheduler(grid)
+        scheduler.build_graph()
+        
+        while not scheduler.is_complete():
+            ready_nodes = scheduler.get_ready_nodes()
+            for node_id in ready_nodes:
+                scheduler.mark_running(node_id)
+                # Execute node...
+                scheduler.mark_completed(node_id, output)
+    """
+    
+    def __init__(self, grid: GridSpec):
+        self.grid = grid
+        self.nodes: Dict[str, NodeExecution] = {}
+        self.execution_order: List[str] = []
+        self._built = False
+    
+    def build_graph(self) -> None:
+        """Build the dependency graph from grid topology."""
+        if self._built:
+            return
+        
+        # Initialize all nodes
+        for node in self.grid.topology.nodes:
+            self.nodes[node.id] = NodeExecution(node=node)
+        
+        # Build dependencies based on execution mode
+        if self.grid.topology.executionMode == ExecutionMode.EXPLICIT:
+            self._build_explicit_dependencies()
+        else:
+            # Default: parent mode
+            self._build_parent_dependencies()
+        
+        # Add runAfter dependencies (applies to both modes)
+        self._add_run_after_dependencies()
+        
+        # Validate no cycles
+        self._detect_cycles()
+        
+        # Mark initial ready nodes
+        self._update_ready_nodes()
+        
+        self._built = True
+    
+    def _build_parent_dependencies(self) -> None:
+        """Build dependencies from parent-child relationships.
+        
+        In parent mode:
+        - Children depend on their parent completing
+        - Siblings run in parallel by default (unless parallel=False)
+        - Controller runs first, then its children, etc.
+        """
+        # Find the controller (root)
+        controller_id = None
+        for node in self.grid.topology.nodes:
+            if node.kind == NodeKind.CONTROLLER:
+                controller_id = node.id
+                break
+        
+        if not controller_id:
+            return
+        
+        # Build parent -> children map
+        children_map: Dict[str, List[str]] = defaultdict(list)
+        for node in self.grid.topology.nodes:
+            if node.parent:
+                children_map[node.parent].append(node.id)
+        
+        # Set dependencies: children depend on parent
+        for node in self.grid.topology.nodes:
+            if node.parent and node.parent in self.nodes:
+                self.nodes[node.id].dependencies.add(node.parent)
+                self.nodes[node.parent].dependents.add(node.id)
+        
+        # Handle sequential execution (parallel=False)
+        for parent_id, child_ids in children_map.items():
+            sequential_children = []
+            for child_id in child_ids:
+                node = self.nodes[child_id].node
+                if not node.parallel:
+                    sequential_children.append(child_id)
+            
+            # Sequential children depend on all parallel siblings completing
+            if sequential_children:
+                parallel_siblings = [c for c in child_ids if c not in sequential_children]
+                for seq_child in sequential_children:
+                    for par_sibling in parallel_siblings:
+                        self.nodes[seq_child].dependencies.add(par_sibling)
+                        self.nodes[par_sibling].dependents.add(seq_child)
+    
+    def _build_explicit_dependencies(self) -> None:
+        """Build dependencies from explicit edges."""
+        if not self.grid.topology.edges:
+            return
+        
+        for edge in self.grid.topology.edges:
+            from_id = edge.from_
+            targets = edge.to if isinstance(edge.to, list) else [edge.to]
+            
+            for to_id in targets:
+                if from_id in self.nodes and to_id in self.nodes:
+                    self.nodes[to_id].dependencies.add(from_id)
+                    self.nodes[from_id].dependents.add(to_id)
+    
+    def _add_run_after_dependencies(self) -> None:
+        """Add runAfter dependencies."""
+        for node in self.grid.topology.nodes:
+            if node.runAfter:
+                for dep_id in node.runAfter:
+                    if dep_id in self.nodes:
+                        self.nodes[node.id].dependencies.add(dep_id)
+                        self.nodes[dep_id].dependents.add(node.id)
+    
+    def _detect_cycles(self) -> None:
+        """Detect cycles in the dependency graph using DFS."""
+        WHITE, GRAY, BLACK = 0, 1, 2
+        color: Dict[str, int] = {node_id: WHITE for node_id in self.nodes}
+        
+        def dfs(node_id: str, path: List[str]) -> Optional[List[str]]:
+            color[node_id] = GRAY
+            path.append(node_id)
+            
+            for dep_id in self.nodes[node_id].dependents:
+                if color[dep_id] == GRAY:
+                    # Found cycle
+                    cycle_start = path.index(dep_id)
+                    return path[cycle_start:] + [dep_id]
+                elif color[dep_id] == WHITE:
+                    cycle = dfs(dep_id, path)
+                    if cycle:
+                        return cycle
+            
+            color[node_id] = BLACK
+            path.pop()
+            return None
+        
+        for node_id in self.nodes:
+            if color[node_id] == WHITE:
+                cycle = dfs(node_id, [])
+                if cycle:
+                    raise ValueError(f"Cycle detected in dependency graph: {' -> '.join(cycle)}")
+    
+    def _update_ready_nodes(self) -> None:
+        """Update which nodes are ready to execute."""
+        for node_id, execution in self.nodes.items():
+            if execution.state == NodeState.PENDING:
+                # Check if all dependencies are completed
+                deps_satisfied = all(
+                    self.nodes[dep].state == NodeState.COMPLETED
+                    for dep in execution.dependencies
+                )
+                if deps_satisfied:
+                    # Check 'when' condition if present
+                    if self._evaluate_when_condition(execution.node):
+                        execution.state = NodeState.READY
+                    else:
+                        execution.state = NodeState.SKIPPED
+                        # Propagate skip to dependents that have no other path
+                        self._propagate_skip(node_id)
+    
+    def _evaluate_when_condition(self, node: NodeSpec) -> bool:
+        """Evaluate a node's 'when' condition.
+        
+        TODO: Implement proper expression evaluation.
+        For now, always returns True.
+        """
+        if not node.when:
+            return True
+        
+        # TODO: Parse and evaluate expression with context
+        # Expression context includes: inputs, outputs (from completed nodes), env
+        return True
+    
+    def _propagate_skip(self, skipped_node_id: str) -> None:
+        """Propagate skip status to dependents if they have no other active path."""
+        # Simple implementation: just mark direct dependents that only depend on skipped nodes
+        for dep_id in self.nodes[skipped_node_id].dependents:
+            dep_execution = self.nodes[dep_id]
+            if dep_execution.state == NodeState.PENDING:
+                # Check if ALL dependencies are skipped
+                all_skipped = all(
+                    self.nodes[d].state == NodeState.SKIPPED
+                    for d in dep_execution.dependencies
+                )
+                if all_skipped:
+                    dep_execution.state = NodeState.SKIPPED
+                    self._propagate_skip(dep_id)
+    
+    def get_ready_nodes(self) -> List[str]:
+        """Get list of node IDs that are ready to execute."""
+        return [
+            node_id for node_id, execution in self.nodes.items()
+            if execution.state == NodeState.READY
+        ]
+    
+    def get_running_nodes(self) -> List[str]:
+        """Get list of node IDs currently running."""
+        return [
+            node_id for node_id, execution in self.nodes.items()
+            if execution.state == NodeState.RUNNING
+        ]
+    
+    def mark_running(self, node_id: str) -> None:
+        """Mark a node as running."""
+        if node_id not in self.nodes:
+            raise ValueError(f"Unknown node: {node_id}")
+        
+        execution = self.nodes[node_id]
+        if execution.state != NodeState.READY:
+            raise ValueError(f"Node {node_id} is not ready (state: {execution.state})")
+        
+        execution.state = NodeState.RUNNING
+        execution.attempt += 1
+    
+    def mark_completed(self, node_id: str, output: Optional[dict] = None) -> None:
+        """Mark a node as completed."""
+        if node_id not in self.nodes:
+            raise ValueError(f"Unknown node: {node_id}")
+        
+        execution = self.nodes[node_id]
+        if execution.state != NodeState.RUNNING:
+            raise ValueError(f"Node {node_id} is not running (state: {execution.state})")
+        
+        execution.state = NodeState.COMPLETED
+        execution.output = output
+        self.execution_order.append(node_id)
+        
+        # Update ready status for dependents
+        self._update_ready_nodes()
+    
+    def mark_failed(self, node_id: str, error: str) -> None:
+        """Mark a node as failed."""
+        if node_id not in self.nodes:
+            raise ValueError(f"Unknown node: {node_id}")
+        
+        execution = self.nodes[node_id]
+        execution.state = NodeState.FAILED
+        execution.error = error
+    
+    def can_retry(self, node_id: str) -> bool:
+        """Check if a node can be retried."""
+        if node_id not in self.nodes:
+            return False
+        
+        execution = self.nodes[node_id]
+        node = execution.node
+        
+        if not node.retry:
+            return False
+        
+        return execution.attempt < node.retry.maxAttempts
+    
+    def reset_for_retry(self, node_id: str) -> None:
+        """Reset a failed node for retry."""
+        if node_id not in self.nodes:
+            raise ValueError(f"Unknown node: {node_id}")
+        
+        execution = self.nodes[node_id]
+        if execution.state != NodeState.FAILED:
+            raise ValueError(f"Node {node_id} is not failed (state: {execution.state})")
+        
+        if not self.can_retry(node_id):
+            raise ValueError(f"Node {node_id} has exceeded retry limit")
+        
+        execution.state = NodeState.READY
+        execution.error = None
+    
+    def is_complete(self) -> bool:
+        """Check if all nodes have finished (completed, failed, or skipped)."""
+        terminal_states = {NodeState.COMPLETED, NodeState.FAILED, NodeState.SKIPPED}
+        return all(
+            execution.state in terminal_states
+            for execution in self.nodes.values()
+        )
+    
+    def is_successful(self) -> bool:
+        """Check if grid completed successfully (all nodes completed or skipped)."""
+        success_states = {NodeState.COMPLETED, NodeState.SKIPPED}
+        return all(
+            execution.state in success_states
+            for execution in self.nodes.values()
+        )
+    
+    def get_state_summary(self) -> Dict[NodeState, int]:
+        """Get count of nodes in each state."""
+        summary: Dict[NodeState, int] = defaultdict(int)
+        for execution in self.nodes.values():
+            summary[execution.state] += 1
+        return dict(summary)
+    
+    def get_node_state(self, node_id: str) -> Optional[NodeState]:
+        """Get the state of a specific node."""
+        if node_id in self.nodes:
+            return self.nodes[node_id].state
+        return None
+    
+    def get_node_output(self, node_id: str) -> Optional[dict]:
+        """Get the output of a completed node."""
+        if node_id in self.nodes:
+            return self.nodes[node_id].output
+        return None
+    
+    def get_execution_order(self) -> List[str]:
+        """Get the order in which nodes completed."""
+        return self.execution_order.copy()
+    
+    def visualize(self) -> str:
+        """Generate a simple text visualization of the DAG."""
+        lines = ["DAG Scheduler State:", "=" * 40]
+        
+        state_symbols = {
+            NodeState.PENDING: "○",
+            NodeState.READY: "◎",
+            NodeState.RUNNING: "●",
+            NodeState.COMPLETED: "✓",
+            NodeState.FAILED: "✗",
+            NodeState.SKIPPED: "⊘",
+            NodeState.BLOCKED: "⊗",
+        }
+        
+        for node_id, execution in self.nodes.items():
+            symbol = state_symbols.get(execution.state, "?")
+            deps = ", ".join(execution.dependencies) if execution.dependencies else "none"
+            lines.append(f"  {symbol} {node_id} ({execution.state.value})")
+            lines.append(f"      deps: {deps}")
+        
+        lines.append("=" * 40)
+        summary = self.get_state_summary()
+        lines.append(f"Summary: {dict(summary)}")
+        
+        return "\n".join(lines)

smartify/engine/spark.py

@@ -0,0 +1,294 @@
+"""Spark node spawning for dynamic agent creation.
+
+Sparks are lightweight helper agents spawned at runtime to assist
+substations with parallelizable workloads. They are created dynamically
+based on workload analysis and subject to spawning limits.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+from uuid import uuid4
+
+from smartify.models.grid import (
+    NodeSpec,
+    NodeKind,
+    DynamicSpawningSpec,
+)
+
+if TYPE_CHECKING:
+    from smartify.engine.orchestrator import GridRun
+    from smartify.engine.scheduler import DAGScheduler
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SparkRequest:
+    """Request to spawn a new Spark node."""
+    parent_id: str          # Substation requesting the spawn
+    task: str               # Task description for the spark
+    context: Dict[str, Any] = field(default_factory=dict)  # Context from parent
+    priority: int = 0       # Higher = more important
+    
+    # Optional constraints
+    tools: Optional[List[str]] = None
+    max_tokens: Optional[int] = None
+    timeout_seconds: Optional[int] = None
+
+
+@dataclass
+class SparkNode:
+    """Runtime representation of a spawned Spark node."""
+    id: str
+    parent_id: str
+    task: str
+    context: Dict[str, Any]
+    created_at: datetime
+    
+    # Runtime state
+    status: str = "pending"  # pending, running, completed, failed
+    output: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+    tokens_used: int = 0
+
+
+class SparkManager:
+    """Manages dynamic Spark node spawning and execution.
+    
+    Usage:
+        manager = SparkManager(spawning_config, scheduler)
+        
+        # Request a spark from a substation
+        spark = await manager.spawn(SparkRequest(
+            parent_id="substation-1",
+            task="Analyze this file",
+            context={"file": "data.csv"}
+        ))
+        
+        # Execute all pending sparks
+        results = await manager.execute_pending(run, adapter)
+    """
+    
+    def __init__(
+        self,
+        config: DynamicSpawningSpec,
+        scheduler: "DAGScheduler",
+    ):
+        self.config = config
+        self.scheduler = scheduler
+        
+        # Track spawned sparks
+        self.sparks: Dict[str, SparkNode] = {}
+        self.sparks_by_parent: Dict[str, List[str]] = {}
+        
+        # Counters for limit enforcement
+        self._total_spawned = 0
+    
+    @property
+    def enabled(self) -> bool:
+        """Check if spark spawning is enabled."""
+        return self.config.enabled and self.config.enableSparks
+    
+    def can_spawn(self, parent_id: str) -> bool:
+        """Check if a new spark can be spawned for the given parent."""
+        if not self.enabled:
+            return False
+        
+        limits = self.config.limits
+        
+        # Check total limit
+        if len(self.sparks) >= limits.maxTotalNodes:
+            logger.warning(f"Total node limit reached: {limits.maxTotalNodes}")
+            return False
+        
+        # Check per-substation limit
+        parent_sparks = self.sparks_by_parent.get(parent_id, [])
+        if len(parent_sparks) >= limits.maxSparksPerSubstation:
+            logger.warning(
+                f"Spark limit for {parent_id} reached: {limits.maxSparksPerSubstation}"
+            )
+            return False
+        
+        return True
+    
+    async def spawn(self, request: SparkRequest) -> Optional[SparkNode]:
+        """Spawn a new Spark node.
+        
+        Args:
+            request: SparkRequest with task and context
+            
+        Returns:
+            SparkNode if spawned, None if limits exceeded or disabled
+        """
+        if not self.can_spawn(request.parent_id):
+            return None
+        
+        # Check if approval is required
+        if self.config.requireApproval:
+            logger.warning(
+                f"Spark spawn requires approval (not implemented) - auto-approving"
+            )
+            # TODO: Implement approval flow
+        
+        # Create spark node
+        spark_id = f"spark-{request.parent_id}-{uuid4().hex[:8]}"
+        
+        spark = SparkNode(
+            id=spark_id,
+            parent_id=request.parent_id,
+            task=request.task,
+            context=request.context,
+            created_at=datetime.now(),
+        )
+        
+        # Register spark
+        self.sparks[spark_id] = spark
+        
+        if request.parent_id not in self.sparks_by_parent:
+            self.sparks_by_parent[request.parent_id] = []
+        self.sparks_by_parent[request.parent_id].append(spark_id)
+        
+        self._total_spawned += 1
+        
+        logger.info(
+            f"Spawned spark {spark_id} for {request.parent_id}: {request.task[:50]}..."
+        )
+        
+        return spark
+    
+    async def spawn_batch(
+        self,
+        requests: List[SparkRequest],
+    ) -> List[SparkNode]:
+        """Spawn multiple sparks (respects limits)."""
+        spawned = []
+        for request in requests:
+            spark = await self.spawn(request)
+            if spark:
+                spawned.append(spark)
+            else:
+                logger.warning(
+                    f"Could not spawn spark for {request.parent_id} - limits reached"
+                )
+                break  # Stop if we hit limits
+        return spawned
+    
+    def get_pending_sparks(self) -> List[SparkNode]:
+        """Get all sparks in pending status."""
+        return [s for s in self.sparks.values() if s.status == "pending"]
+    
+    def get_sparks_for_parent(self, parent_id: str) -> List[SparkNode]:
+        """Get all sparks spawned by a specific parent."""
+        spark_ids = self.sparks_by_parent.get(parent_id, [])
+        return [self.sparks[sid] for sid in spark_ids if sid in self.sparks]
+    
+    def mark_running(self, spark_id: str) -> None:
+        """Mark a spark as running."""
+        if spark_id in self.sparks:
+            self.sparks[spark_id].status = "running"
+    
+    def mark_completed(
+        self,
+        spark_id: str,
+        output: Dict[str, Any],
+        tokens_used: int = 0,
+    ) -> None:
+        """Mark a spark as completed."""
+        if spark_id in self.sparks:
+            spark = self.sparks[spark_id]
+            spark.status = "completed"
+            spark.output = output
+            spark.tokens_used = tokens_used
+    
+    def mark_failed(self, spark_id: str, error: str) -> None:
+        """Mark a spark as failed."""
+        if spark_id in self.sparks:
+            spark = self.sparks[spark_id]
+            spark.status = "failed"
+            spark.error = error
+    
+    def get_completed_outputs(self, parent_id: str) -> List[Dict[str, Any]]:
+        """Get outputs from all completed sparks for a parent."""
+        outputs = []
+        for spark in self.get_sparks_for_parent(parent_id):
+            if spark.status == "completed" and spark.output:
+                outputs.append({
+                    "spark_id": spark.id,
+                    "task": spark.task,
+                    "output": spark.output,
+                })
+        return outputs
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get spark manager statistics."""
+        by_status = {}
+        for spark in self.sparks.values():
+            by_status[spark.status] = by_status.get(spark.status, 0) + 1
+        
+        return {
+            "enabled": self.enabled,
+            "total_spawned": self._total_spawned,
+            "active": len(self.sparks),
+            "by_status": by_status,
+            "limits": {
+                "max_total": self.config.limits.maxTotalNodes,
+                "max_per_substation": self.config.limits.maxSparksPerSubstation,
+            },
+        }
+
+
+def analyze_workload_for_sparks(
+    task: str,
+    context: Dict[str, Any],
+) -> List[SparkRequest]:
+    """Analyze a task to determine if it can be parallelized with sparks.
+    
+    This is a simple heuristic-based analyzer. In production, this could
+    use an LLM to intelligently decompose tasks.
+    
+    Returns:
+        List of SparkRequests for parallel subtasks
+    """
+    requests = []
+    
+    # Check for list processing patterns
+    for key, value in context.items():
+        if isinstance(value, list) and len(value) > 1:
+            # Potential fan-out: process each item in parallel
+            for i, item in enumerate(value):
+                requests.append(SparkRequest(
+                    parent_id="",  # Will be set by caller
+                    task=f"Process item {i+1}/{len(value)}: {task}",
+                    context={key: item, "index": i, "total": len(value)},
+                    priority=i,  # Process in order if needed
+                ))
+    
+    return requests
+
+
+def create_spark_node_spec(
+    spark: SparkNode,
+    default_agent: Optional[str] = None,
+) -> NodeSpec:
+    """Create a NodeSpec for a spawned Spark.
+    
+    This allows the spark to be tracked in the scheduler alongside
+    static nodes if needed.
+    
+    Uses model_construct() to bypass validation since SPARK nodes
+    can only be created programmatically at runtime, not in user YAML.
+    """
+    # Use model_construct to bypass the validator that blocks SPARK kind
+    # from user-defined specs. This is intentional for runtime-created sparks.
+    return NodeSpec.model_construct(
+        id=spark.id,
+        kind=NodeKind.SPARK,
+        name=f"Spark: {spark.task[:30]}...",
+        description=spark.task,
+        parent=spark.parent_id,
+        agent=default_agent,
+        capabilities=["execute", "report"],
+    )

smartify/guardrails/__init__.py

@@ -0,0 +1,22 @@
+"""Guardrails module for Smartify.
+
+Provides breaker management and safety limits for grid execution.
+"""
+
+from smartify.guardrails.breakers import (
+    BreakerManager,
+    BreakerState,
+    BreakerTrip,
+    BreakerType,
+    BreakerError,
+    RateLimitState,
+)
+
+__all__ = [
+    "BreakerManager",
+    "BreakerState",
+    "BreakerTrip",
+    "BreakerType",
+    "BreakerError",
+    "RateLimitState",
+]