commandnet 0.2.2__tar.gz → 0.4.0__tar.gz

{commandnet-0.2.2 → commandnet-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: commandnet
-Version: 0.2.2
+Version: 0.4.0
 Summary: A lightweight, Pydantic-powered, distributed event-driven state machine and typed node graph runtime.
 Author: Christopher Vaz
 Author-email: christophervaz160@gmail.com
@@ -53,7 +53,7 @@ pip install commandnet
 ## 🛠️ Quick Start
 
 ### 1. Define Your Context
-The "Context" is the persistent state of your agent, defined using Pydantic.
+The "Context" is the persistent state of your subject, defined using Pydantic.
 
 ```python
 from pydantic import BaseModel
@@ -139,7 +139,7 @@ engine = Engine(persistence=db, event_bus=bus)
 await engine.start_worker()
 
 # Trigger an execution
-await engine.trigger_agent("agent-123", CheckRisk, WorkflowCtx(user_id="user_abc"))
+await engine.trigger_subject("subject-123", CheckRisk, WorkflowCtx(user_id="user_abc"))
 ```
 
 ---
@@ -172,3 +172,4 @@ print(dag) # {'CheckRisk': ['ProcessPayment'], 'ProcessPayment': []}
 
 MIT
 
+

{commandnet-0.2.2 → commandnet-0.4.0}/README.md

@@ -30,7 +30,7 @@ pip install commandnet
 ## 🛠️ Quick Start
 
 ### 1. Define Your Context
-The "Context" is the persistent state of your agent, defined using Pydantic.
+The "Context" is the persistent state of your subject, defined using Pydantic.
 
 ```python
 from pydantic import BaseModel
@@ -116,7 +116,7 @@ engine = Engine(persistence=db, event_bus=bus)
 await engine.start_worker()
 
 # Trigger an execution
-await engine.trigger_agent("agent-123", CheckRisk, WorkflowCtx(user_id="user_abc"))
+await engine.trigger_subject("subject-123", CheckRisk, WorkflowCtx(user_id="user_abc"))
 ```
 
 ---
@@ -148,3 +148,4 @@ print(dag) # {'CheckRisk': ['ProcessPayment'], 'ProcessPayment': []}
 ## 📄 License
 
 MIT
+

{commandnet-0.2.2 → commandnet-0.4.0}/commandnet/__init__.py

@@ -1,5 +1,5 @@
 from .core.models import Event
-from .core.node import Node, Parallel, ParallelTask, Schedule
+from .core.node import Node, Parallel, ParallelTask, Schedule, Wait, Call, Interrupt
 from .core.graph import GraphAnalyzer
 from .interfaces.persistence import Persistence
 from .interfaces.event_bus import EventBus
@@ -9,4 +9,6 @@ from .engine.runtime import Engine
 __all__ = [
     "Event", "Node", "Parallel", "ParallelTask", "GraphAnalyzer", 
     "Persistence", "EventBus", "Observer", "Engine", "Schedule",
+    "Call", "Interrupt",
 ]
+

{commandnet-0.2.2 → commandnet-0.4.0}/commandnet/core/graph.py

@@ -96,3 +96,4 @@ class GraphAnalyzer:
                         f"({source_ctx.__name__} -> {target_ctx.__name__})"
                     )
         return True
+

{commandnet-0.2.2 → commandnet-0.4.0}/commandnet/core/models.py

@@ -8,10 +8,11 @@ def utcnow_iso() -> str:
 
 class Event(BaseModel):
     event_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
-    agent_id: str
+    subject_id: str
     node_name: str
     payload: Optional[Dict[str, Any]] = None
     
     timestamp: str = Field(default_factory=utcnow_iso)
     run_at: str = Field(default_factory=utcnow_iso) 
     idempotency_key: Optional[str] = None
+

commandnet-0.4.0/commandnet/core/node.py

@@ -0,0 +1,65 @@
+from typing import Generic, TypeVar, Type, Optional, Union, List, Any
+from pydantic import BaseModel, ConfigDict
+
+C = TypeVar('C', bound=BaseModel) # Context
+P = TypeVar('P', bound=BaseModel) # Payload
+
+# The Recursive Type Definition
+Target = Union[Type['Node'], 'Parallel', 'Schedule', 'Wait', 'Call', 'Interrupt', None]
+
+class ParallelTask(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    action: Target 
+    sub_context_path: str 
+    payload: Optional[Any] = None
+
+class Parallel(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    branches: List[Union[ParallelTask, 'Wait']] 
+    join_node: Optional[Type['Node']] = None 
+
+class Schedule(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    action: Target
+    delay_seconds: int
+    payload: Optional[Any] = None
+    idempotency_key: Optional[str] = None
+
+class Wait(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    signal_id: str
+    resume_action: Target
+    sub_context_path: Optional[str] = None 
+
+class Call(BaseModel):
+    """The 'Await' type: Deduplicates execution based on an idempotency key."""
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    node_cls: Type['Node']
+    idempotency_key: str
+    payload: Optional[Any] = None
+    # After the called node finishes, the caller resumes at this node
+    resume_action: Target = None 
+
+class Interrupt(BaseModel):
+    """Signals the engine to stop execution."""
+    subject_id: str
+    hard: bool = True # True = kill task, False = flag for soft exit
+
+TransitionResult = Target
+
+class Node(Generic[C, P]):
+    @classmethod
+    def get_node_name(cls) -> str:
+        return cls.__name__
+
+    async def run(self, ctx: C, payload: Optional[P] = None) -> TransitionResult:
+        """Executes node logic. Returns a Target (Node class, Parallel, Schedule, Wait, or None)."""
+        pass
+
+    async def on_signal(self, ctx: C, signal_id: str, payload: Any) -> Target:
+        """
+        CALLBACK: Called when a 'Wait' state is resolved or an external signal 
+        is sent to this node specifically.
+        """
+        return None
+

commandnet-0.4.0/commandnet/engine/runtime.py

@@ -0,0 +1,402 @@
+import asyncio
+import logging
+from datetime import datetime, timezone, timedelta
+from typing import Optional, Type, Iterable, Dict, Any, Union, List
+
+from ..core.models import Event
+from ..core.node import (
+    Node,
+    Parallel,
+    Schedule,
+    Wait,
+    Target,
+    ParallelTask,
+    Call,
+    Interrupt,
+)
+from ..core.graph import GraphAnalyzer
+from ..interfaces.persistence import Persistence
+from ..interfaces.event_bus import EventBus
+from ..interfaces.observer import Observer
+
+
+class Engine:
+    def __init__(
+        self,
+        persistence: Persistence,
+        event_bus: EventBus,
+        nodes: Iterable[Type[Node]],
+        observer: Optional[Observer] = None,
+    ):
+        self.db = persistence
+        self.bus = event_bus
+        self.observer = observer or Observer()
+        self.logger = logging.getLogger("CommandNet")
+        self._scheduler_task: Optional[asyncio.Task] = None
+        self._active_tasks: Dict[str, asyncio.Task] = {}
+        self._registry: Dict[str, Type[Node]] = {n.get_node_name(): n for n in nodes}
+
+    def _dump_ctx(self, ctx: Any) -> dict:
+        return ctx.model_dump() if hasattr(ctx, "model_dump") else ctx
+
+    def _get_path(self, obj: Any, path: str) -> Any:
+        if isinstance(obj, dict):
+            return obj.get(path)
+        return getattr(obj, path)
+
+    # --- CORE WORKER LOGIC ---
+
+    async def process_event(self, event: Event):
+        # 1. Internal Control (Cross-worker Hard Cancel)
+        if event.node_name == "__CONTROL__":
+            action = (event.payload or {}).get("action")
+            if action == "HARD_CANCEL" and event.subject_id in self._active_tasks:
+                self._active_tasks[event.subject_id].cancel()
+            return
+
+        # 2. Check cancellation status
+        if await self.db.is_cancelled(event.subject_id):
+            return
+
+        # 3. Task Tracking for Local Hard Cancel
+        task = asyncio.create_task(self._run_node_logic(event))
+        self._active_tasks[event.subject_id] = task
+        try:
+            await task
+        except asyncio.CancelledError:
+            self.logger.warning(f"Task {event.subject_id} hard-cancelled.")
+        finally:
+            self._active_tasks.pop(event.subject_id, None)
+
+    async def _run_node_logic(self, event: Event):
+        subject_id = event.subject_id
+        # We allow "AWAITING_CALL" because an subject wakes up from that state when a 'Call' resolves
+        node_name, ctx_dict = await self.db.lock_and_load(subject_id)
+        if not node_name or (
+            node_name != event.node_name and node_name != "AWAITING_CALL"
+        ):
+            if node_name:
+                await self.db.unlock_subject(subject_id)
+            return
+
+        try:
+            node_cls = self._registry.get(event.node_name)
+            if not node_cls:
+                raise RuntimeError(f"Node '{event.node_name}' not found.")
+
+            ctx_type = GraphAnalyzer.get_context_type(node_cls)
+            payload_type = GraphAnalyzer.get_payload_type(node_cls)
+
+            ctx = (
+                ctx_type.model_validate(ctx_dict)
+                if hasattr(ctx_type, "model_validate")
+                else ctx_dict
+            )
+            payload = (
+                payload_type.model_validate(event.payload)
+                if (event.payload and hasattr(payload_type, "model_validate"))
+                else event.payload
+            )
+
+            # Support Soft-Cancel checking inside Node.run
+            if hasattr(ctx, "is_cancelled"):
+                ctx.is_cancelled = await self.db.is_cancelled(subject_id)
+
+            start_t = asyncio.get_event_loop().time()
+            result = await node_cls().run(ctx, payload)
+
+            await self._apply_target(
+                subject_id,
+                ctx,
+                result,
+                (asyncio.get_event_loop().time() - start_t) * 1000,
+            )
+        except Exception as e:
+            await self.observer.on_error(subject_id, event.node_name, e)
+            raise
+        finally:
+            await self.db.unlock_subject(subject_id)
+
+    # --- RECURSIVE TARGET RESOLVER ---
+
+    async def _apply_target(
+        self,
+        subject_id: str,
+        context: Any,
+        target: Target,
+        duration: float = 0.0,
+        payload: Any = None,
+    ):
+        # 1. Interrupt (Cancellation)
+        if isinstance(target, Interrupt):
+            await self.cancel_subject(target.subject_id, target.hard)
+            return
+
+        # 2. Call (Idempotent Await)
+        if isinstance(target, Call):
+            is_leader = await self.db.add_call_waiter(
+                target.idempotency_key,
+                subject_id,
+                target.resume_action,
+                self._dump_ctx(context),
+            )
+            await self.observer.on_transition(
+                subject_id, "RUN", f"CALLING:{target.node_cls.get_node_name()}", duration
+            )
+            await self.db.save_state(
+                subject_id, "AWAITING_CALL", self._dump_ctx(context), None
+            )
+            if is_leader:
+                await self.trigger_subject(
+                    f"call#{target.idempotency_key}",
+                    target.node_cls,
+                    context,
+                    target.payload,
+                )
+            return
+
+        # 3. Terminal State
+        if target is None:
+            await self.observer.on_transition(subject_id, "RUN", "TERMINAL", duration)
+            ctx_dict = self._dump_ctx(context)
+
+            # Resolve Callers if this was a shared Virtual subject
+            if subject_id.startswith("call#"):
+                key = subject_id.split("#")[1]
+                waiters = await self.db.resolve_call_group(key)
+                for w in waiters:
+                    # Resume waiters using the final context of the shared node as payload
+                    await self._apply_target(
+                        w["subject_id"],
+                        w["context"],
+                        w["resume_target"],
+                        payload=ctx_dict,
+                    )
+
+            # Parallel Sub-task Completion Logic
+            if "#" in subject_id and not subject_id.startswith("call#"):
+                parent_id = subject_id.split("#")[0]
+                await self.db.save_sub_state(
+                    subject_id, parent_id, "TERMINAL", ctx_dict, None
+                )
+                join_node_name = await self.db.register_sub_task_completion(subject_id)
+                if join_node_name:
+                    await self._trigger_recompose(parent_id, join_node_name)
+            else:
+                await self.db.save_state(subject_id, "TERMINAL", ctx_dict, None)
+            return
+
+        # 4. Standard Node Transition
+        if isinstance(target, type) and issubclass(target, Node):
+            node_name = target.get_node_name()
+            await self.observer.on_transition(subject_id, "RUN", node_name, duration)
+
+            p_load = payload.model_dump() if hasattr(payload, "model_dump") else payload
+            evt = Event(subject_id=subject_id, node_name=node_name, payload=p_load)
+            ctx_dict = self._dump_ctx(context)
+
+            if "#" in subject_id:
+                await self.db.save_sub_state(
+                    subject_id, subject_id.split("#")[0], node_name, ctx_dict, evt
+                )
+            else:
+                await self.db.save_state(subject_id, node_name, ctx_dict, evt)
+
+            await self.bus.publish(evt)
+            return
+
+        # 5. Wait / Signal Parking
+        if isinstance(target, Wait):
+            actual_id = subject_id
+            actual_ctx = context
+            if target.sub_context_path and "#" not in subject_id:
+                actual_id = f"{subject_id}#{target.sub_context_path}"
+                actual_ctx = self._get_path(context, target.sub_context_path)
+
+            await self.observer.on_transition(
+                actual_id, "RUN", f"WAIT:{target.signal_id}", duration
+            )
+            await self.db.park_subject(
+                actual_id,
+                target.signal_id,
+                target.resume_action,
+                self._dump_ctx(actual_ctx),
+            )
+            return
+
+        # 6. Parallel Fan-out
+        if isinstance(target, Parallel):
+            join_name = target.join_node.get_node_name() if target.join_node else "FORK"
+            await self.observer.on_transition(
+                subject_id, "RUN", f"PARALLEL:{join_name}", duration
+            )
+
+            if target.join_node:
+                await self.db.create_task_group(
+                    subject_id, join_name, len(target.branches)
+                )
+
+            for branch in target.branches:
+                # Normalize branch to ParallelTask without stripping Wait wrappers
+                if isinstance(branch, ParallelTask):
+                    task = branch
+                else:
+                    # If it's a Wait or a Node class, wrap it but keep the action intact
+                    path = (
+                        branch.sub_context_path
+                        if isinstance(branch, Wait) and branch.sub_context_path
+                        else "default"
+                    )
+                    task = ParallelTask(action=branch, sub_context_path=path)
+
+                sub_ctx = self._get_path(context, task.sub_context_path)
+                await self._apply_target(
+                    f"{subject_id}#{task.sub_context_path}",
+                    sub_ctx,
+                    task.action,
+                    payload=task.payload,
+                )
+
+            if target.join_node:
+                await self.db.save_state(
+                    subject_id, "WAITING_FOR_JOIN", self._dump_ctx(context), None
+                )
+            else:
+                await self._apply_target(subject_id, context, None)
+            return
+
+        # 7. Schedule (Delayed Execution)
+        if isinstance(target, Schedule):
+            if not (
+                isinstance(target.action, type) and issubclass(target.action, Node)
+            ):
+                raise TypeError("Schedule.action must be a Node class.")
+
+            target_node_name = target.action.get_node_name()
+            await self.observer.on_transition(
+                subject_id, "RUN", f"SCHEDULED:{target_node_name}", duration
+            )
+
+            run_at_dt = datetime.now(timezone.utc) + timedelta(
+                seconds=target.delay_seconds
+            )
+            p_load = (
+                target.payload.model_dump()
+                if hasattr(target.payload, "model_dump")
+                else target.payload
+            )
+
+            scheduled_evt = Event(
+                subject_id=subject_id,
+                node_name=target_node_name,
+                payload=p_load,
+                run_at=run_at_dt.isoformat(),
+                idempotency_key=target.idempotency_key,
+            )
+
+            await self.db.schedule_event(scheduled_evt)
+            await self.db.save_state(
+                subject_id, target_node_name, self._dump_ctx(context), None
+            )
+            return
+
+    # --- EXTERNAL CONTROL & SIGNALS ---
+
+    async def signal_node(self, subject_id: str, signal_id: str, payload: Any = None):
+        """Resumes subject and triggers its specific on_signal instance method."""
+        node_name, ctx_dict = await self.db.lock_and_load(subject_id)
+        if not node_name:
+            return
+        try:
+            node_cls = self._registry.get(node_name)
+            node_inst = node_cls()
+            ctx_type = GraphAnalyzer.get_context_type(node_cls)
+            ctx = (
+                ctx_type.model_validate(ctx_dict)
+                if hasattr(ctx_type, "model_validate")
+                else ctx_dict
+            )
+
+            result = await node_inst.on_signal(ctx, signal_id, payload)
+            await self._apply_target(subject_id, ctx, result)
+        finally:
+            await self.db.unlock_subject(subject_id)
+
+    async def release_signal(self, signal_id: str, payload: Any = None):
+        """Standard mass-resume for parked subjects."""
+        waiters = await self.db.get_and_clear_waiters(signal_id)
+        for waiter in waiters:
+            subject_id = waiter["subject_id"]
+            await self.db.lock_and_load(subject_id)
+            try:
+                await self._apply_target(
+                    subject_id=subject_id,
+                    context=waiter["context"],
+                    target=waiter["next_target"],
+                    payload=payload,
+                )
+            finally:
+                await self.db.unlock_subject(subject_id)
+
+    async def cancel_subject(self, subject_id: str, hard: bool = True):
+        await self.db.set_cancel_flag(subject_id, hard)
+        if hard:
+            if subject_id in self._active_tasks:
+                self._active_tasks[subject_id].cancel()
+            await self.bus.publish(
+                Event(
+                    subject_id=subject_id,
+                    node_name="__CONTROL__",
+                    payload={"action": "HARD_CANCEL"},
+                )
+            )
+
+    # --- LIFECYCLE & HELPERS ---
+
+    async def _trigger_recompose(self, parent_id: str, join_node_name: str):
+        await self.db.lock_and_load(parent_id)
+        merged_ctx_dict = await self.db.recompose_parent(parent_id)
+        await self._apply_target(
+            parent_id, merged_ctx_dict, self._registry[join_node_name]
+        )
+
+    async def start_worker(self, poll_interval: float = 1.0):
+        await self.bus.subscribe(self.process_event)
+        self._scheduler_task = asyncio.create_task(self._scheduler_loop(poll_interval))
+
+    async def _scheduler_loop(self, poll_interval: float):
+        while True:
+            try:
+                due = await self.db.pop_due_events()
+                for evt in due:
+                    await self.bus.publish(evt)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                self.logger.error(f"Scheduler: {e}")
+            await asyncio.sleep(poll_interval)
+
+    async def trigger_subject(
+        self,
+        subject_id: str,
+        start_node: Type[Node],
+        initial_context: Any,
+        payload: Any = None,
+    ):
+        node_name = start_node.get_node_name()
+        p_load = payload.model_dump() if hasattr(payload, "model_dump") else payload
+        evt = Event(subject_id=subject_id, node_name=node_name, payload=p_load)
+        await self.db.save_state(
+            subject_id, node_name, self._dump_ctx(initial_context), evt
+        )
+        await self.bus.publish(evt)
+
+    async def stop(self):
+        if self._scheduler_task:
+            self._scheduler_task.cancel()
+        for task in self._active_tasks.values():
+            task.cancel()
+
+    def validate_graph(self, start_node: Type[Node]):
+        return GraphAnalyzer.validate(start_node, self._registry)
+

{commandnet-0.2.2 → commandnet-0.4.0}/commandnet/interfaces/event_bus.py

@@ -10,3 +10,4 @@ class EventBus(ABC):
     @abstractmethod
     async def subscribe(self, handler: Callable[[Event], Coroutine]):
         pass
+

commandnet-0.4.0/commandnet/interfaces/observer.py

@@ -0,0 +1,6 @@
+from abc import ABC
+
+class Observer(ABC):
+    async def on_transition(self, subject_id: str, from_node: str, to_node: str, duration_ms: float): pass
+    async def on_error(self, subject_id: str, node: str, error: Exception): pass
+

commandnet-0.4.0/commandnet/interfaces/persistence.py

@@ -0,0 +1,66 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Optional, Tuple, List, Any
+from ..core.models import Event
+
+class Persistence(ABC):
+    @abstractmethod
+    async def lock_and_load(self, subject_id: str) -> Tuple[Optional[str], Optional[Dict]]:
+        pass
+        
+    @abstractmethod
+    async def unlock_subject(self, subject_id: str):
+        pass
+
+    @abstractmethod
+    async def save_state(self, subject_id: str, node_name: str, context: Dict, event: Optional[Event]):
+        pass
+
+    @abstractmethod
+    async def save_sub_state(self, sub_id: str, parent_id: str, node_name: str, ctx: dict, evt: Optional[Event]):
+        pass
+
+    @abstractmethod
+    async def create_task_group(self, parent_id: str, join_node_name: str, task_count: int):
+        pass
+
+    @abstractmethod
+    async def register_sub_task_completion(self, sub_id: str) -> Optional[str]:
+        pass
+
+    @abstractmethod
+    async def recompose_parent(self, parent_id: str) -> dict:
+        pass
+
+    @abstractmethod
+    async def schedule_event(self, event: Event) -> bool:
+        pass
+
+    @abstractmethod
+    async def pop_due_events(self) -> List[Event]:
+        pass
+
+    @abstractmethod
+    async def park_subject(self, subject_id: str, signal_id: str, next_target: Any, context: Dict):
+        pass
+
+    @abstractmethod
+    async def get_and_clear_waiters(self, signal_id: str) -> List[Dict]:
+        pass
+
+    @abstractmethod
+    async def set_cancel_flag(self, subject_id: str, hard: bool):
+        pass
+
+    @abstractmethod
+    async def is_cancelled(self, subject_id: str) -> bool:
+        pass
+
+    @abstractmethod
+    async def add_call_waiter(self, key: str, subject_id: str, resume_target: Any, context: dict) -> bool:
+        """Returns True if this is the first waiter for this key (the 'leader')."""
+        pass
+
+    @abstractmethod
+    async def resolve_call_group(self, key: str) -> List[Dict[str, Any]]:
+        pass
+

{commandnet-0.2.2 → commandnet-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "commandnet"
-version = "0.2.2"
+version = "0.4.0"
 description = "A lightweight, Pydantic-powered, distributed event-driven state machine and typed node graph runtime."
 authors = [
     { name = "Christopher Vaz", email = "christophervaz160@gmail.com" }
@@ -41,3 +41,4 @@ build-backend = "poetry.core.masonry.api"
 asyncio_mode = "strict"
 asyncio_default_test_loop_scope = "function"
 asyncio_default_fixture_loop_scope = "function"
+

commandnet-0.2.2/commandnet/core/node.py

@@ -1,36 +0,0 @@
-import inspect
-from typing import Generic, TypeVar, Type, Optional, Union, List, Dict, Any
-from pydantic import BaseModel, ConfigDict
-
-C = TypeVar('C', bound=BaseModel) # Context
-P = TypeVar('P', bound=BaseModel) # Payload (Optional)
-
-class ParallelTask(BaseModel):
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-    node_cls: Type['Node']
-    payload: Optional[Any] = None
-    sub_context_path: str 
-
-class Parallel(BaseModel):
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-    branches: List[ParallelTask]
-    join_node: Type['Node']
-
-class Schedule(BaseModel):
-    model_config = ConfigDict(arbitrary_types_allowed=True)
-    node_cls: Type['Node']
-    delay_seconds: int
-    payload: Optional[Any] = None
-    idempotency_key: Optional[str] = None
-
-# Minor typing improvement for readability
-TransitionResult = Union[Type['Node'], Parallel, Schedule, None]
-
-class Node(Generic[C, P]):
-    @classmethod
-    def get_node_name(cls) -> str:
-        return cls.__name__
-
-    async def run(self, ctx: C, payload: Optional[P] = None) -> TransitionResult:
-        """Executes node logic. Returns the Next Node, a Parallel request, a Schedule request, or None."""
-        pass

commandnet-0.2.2/commandnet/engine/runtime.py

@@ -1,211 +0,0 @@
-import asyncio
-import logging
-from datetime import datetime, timezone, timedelta
-from typing import Optional, Type, Iterable, Dict
-from pydantic import BaseModel
-
-from ..core.models import Event
-from ..core.node import Node, Parallel, Schedule
-from ..core.graph import GraphAnalyzer
-from ..interfaces.persistence import Persistence
-from ..interfaces.event_bus import EventBus
-from ..interfaces.observer import Observer
-
-class Engine:
-    def __init__(
-        self, 
-        persistence: Persistence, 
-        event_bus: EventBus, 
-        nodes: Iterable[Type[Node]],
-        observer: Optional[Observer] = None
-    ):
-        self.db = persistence
-        self.bus = event_bus
-        self.observer = observer or Observer()
-        self.logger = logging.getLogger("CommandNet")
-        self._scheduler_task: Optional[asyncio.Task] = None
-        
-        # Build Engine-scoped registry
-        self._registry: Dict[str, Type[Node]] = {}
-        for node_cls in nodes:
-            name = node_cls.get_node_name()
-            if name in self._registry and self._registry[name] is not node_cls:
-                raise RuntimeError(f"Node name collision in Engine: '{name}'")
-            self._registry[name] = node_cls
-
-    def validate_graph(self, start_node: Type[Node]):
-        """Helper to validate the graph using this engine's registry."""
-        return GraphAnalyzer.validate(start_node, self._registry)
-
-    async def start_worker(self, poll_interval: float = 1.0):
-        await self.bus.subscribe(self.process_event)
-        self._scheduler_task = asyncio.create_task(self._scheduler_loop(poll_interval))
-        self.logger.info("Worker and Scheduler started.")
-
-    async def _scheduler_loop(self, poll_interval: float):
-        while True:
-            try:
-                due_events = await self.db.pop_due_events()
-                for evt in due_events:
-                    await self.bus.publish(evt)
-            except asyncio.CancelledError:
-                break
-            except Exception as e:
-                self.logger.error(f"Scheduler Error: {e}")
-            await asyncio.sleep(poll_interval)
-
-    async def stop(self):
-        if self._scheduler_task:
-            self._scheduler_task.cancel()
-            try:
-                await self._scheduler_task
-            except asyncio.CancelledError:
-                pass
-
-    async def trigger_agent(self, agent_id: str, start_node: Type[Node], initial_context: BaseModel, payload: Optional[BaseModel] = None):
-        node_name = start_node.get_node_name()
-        if node_name not in self._registry:
-            raise ValueError(f"Node '{node_name}' is not registered with this Engine.")
-            
-        start_event = Event(
-            agent_id=agent_id, 
-            node_name=node_name,
-            payload=payload.model_dump() if hasattr(payload, "model_dump") else payload
-        )
-        await self.db.save_state(agent_id, node_name, initial_context.model_dump(), start_event)
-        await self.bus.publish(start_event)
-
-    async def process_event(self, event: Event):
-        start_time = asyncio.get_event_loop().time()
-        
-        current_node_name, ctx_dict = await self.db.load_and_lock_agent(event.agent_id)
-        if not current_node_name:
-            return
-
-        locked = True
-        try:
-            if current_node_name != event.node_name:
-                # Same logic as before for sub-state/state
-                if "#" in event.agent_id:
-                    parent_id = event.agent_id.split("#")[0]
-                    await self.db.save_sub_state(event.agent_id, parent_id, current_node_name, ctx_dict, None)
-                else:
-                    await self.db.save_state(event.agent_id, current_node_name, ctx_dict, None)
-                locked = False
-                return
-
-            node_cls = self._registry.get(current_node_name)
-            if not node_cls:
-                raise RuntimeError(f"Node '{current_node_name}' not found in this Engine's registry.")
-            
-            ctx_type = GraphAnalyzer.get_context_type(node_cls)
-            payload_type = GraphAnalyzer.get_payload_type(node_cls)
-            
-            ctx = ctx_type.model_validate(ctx_dict) if issubclass(ctx_type, BaseModel) else ctx_dict
-            
-            payload = None
-            if event.payload is not None:
-                if isinstance(payload_type, type) and issubclass(payload_type, BaseModel):
-                    payload = payload_type.model_validate(event.payload)
-                else:
-                    payload = event.payload
-
-            node_instance = node_cls()
-            result = await node_instance.run(ctx, payload)
-            duration = (asyncio.get_event_loop().time() - start_time) * 1000
-            
-            if isinstance(result, Parallel):
-                await self._handle_parallel_start(event.agent_id, ctx, result, duration)
-            elif isinstance(result, Schedule):
-                await self._handle_schedule(event.agent_id, current_node_name, ctx, result, duration)
-            elif result:
-                await self._handle_transition(event.agent_id, current_node_name, result, ctx, duration)
-            else:
-                await self._handle_terminal(event.agent_id, current_node_name, ctx, duration)
-                
-            locked = False 
-            
-        except Exception as e:
-            await self.observer.on_error(event.agent_id, current_node_name, e)
-            raise
-        finally:
-            if locked:
-                await self.db.unlock_agent(event.agent_id)
-
-    # Remaining _handle_* methods use self._registry and self.validate_graph
-    async def _handle_transition(self, agent_id: str, from_node: str, next_node_cls: Type[Node], ctx: BaseModel, duration: float):
-        next_name = next_node_cls.get_node_name()
-        if next_name not in self._registry:
-            raise RuntimeError(f"Transition target '{next_name}' not in registry.")
-            
-        await self.observer.on_transition(agent_id, from_node, next_name, duration)
-        next_event = Event(agent_id=agent_id, node_name=next_name)
-        await self.db.save_state(agent_id, next_name, ctx.model_dump(), next_event)
-        await self.bus.publish(next_event)
-
-    async def _handle_parallel_start(self, parent_id: str, parent_ctx: BaseModel, parallel: Parallel, duration: float):
-        join_name = parallel.join_node.get_node_name()
-        await self.observer.on_transition(parent_id, "ParallelStart", join_name, duration)
-        await self.db.create_task_group(parent_id=parent_id, join_node_name=join_name, task_count=len(parallel.branches))
-        
-        for task in parallel.branches:
-            if not hasattr(parent_ctx, task.sub_context_path):
-                raise RuntimeError(f"Context missing path: '{task.sub_context_path}'.")
-                
-            sub_ctx = getattr(parent_ctx, task.sub_context_path)
-            sub_id = f"{parent_id}#{task.sub_context_path}"
-            node_name = task.node_cls.get_node_name()
-            
-            evt = Event(
-                agent_id=sub_id, 
-                node_name=node_name,
-                payload=task.payload.model_dump() if hasattr(task.payload, "model_dump") else task.payload
-            )
-            await self.db.save_sub_state(sub_id, parent_id, node_name, sub_ctx.model_dump(), evt)
-            await self.bus.publish(evt)
-            
-        await self.db.save_state(parent_id, "WAITING_FOR_JOIN", parent_ctx.model_dump(), None)
-
-    async def _handle_terminal(self, agent_id: str, from_node: str, ctx: BaseModel, duration: float):
-        await self.observer.on_transition(agent_id, from_node, "TERMINAL", duration)
-        if "#" in agent_id:
-            parent_id = agent_id.split("#")[0]
-            await self.db.save_sub_state(agent_id, parent_id, "TERMINAL", ctx.model_dump(), None)
-            join_node_name = await self.db.register_sub_task_completion(agent_id)
-            if join_node_name:
-                await self._trigger_recompose(parent_id, join_node_name)
-        else:
-            await self.db.save_state(agent_id, "TERMINAL", ctx.model_dump(), None)
-
-    async def _handle_schedule(self, agent_id: str, from_node: str, ctx: BaseModel, schedule: Schedule, duration: float):
-        target_name = schedule.node_cls.get_node_name()
-        await self.observer.on_transition(agent_id, from_node, f"SCHEDULED:{target_name}", duration)
-        run_at_dt = datetime.now(timezone.utc) + timedelta(seconds=schedule.delay_seconds)
-        
-        evt = Event(
-            agent_id=agent_id, 
-            node_name=target_name,
-            payload=schedule.payload.model_dump() if hasattr(schedule.payload, "model_dump") else schedule.payload,
-            run_at=run_at_dt.isoformat(),
-            idempotency_key=schedule.idempotency_key
-        )
-        
-        scheduled = await self.db.schedule_event(evt)
-        next_node = target_name if scheduled else "TERMINAL"
-        
-        if "#" in agent_id:
-            parent_id = agent_id.split("#")[0]
-            await self.db.save_sub_state(agent_id, parent_id, next_node, ctx.model_dump(), None)
-            if not scheduled:
-                join_node_name = await self.db.register_sub_task_completion(agent_id)
-                if join_node_name:
-                    await self._trigger_recompose(parent_id, join_node_name)
-        else:
-            await self.db.save_state(agent_id, next_node, ctx.model_dump(), None)
-
-    async def _trigger_recompose(self, parent_id: str, join_node_name: str):
-        await self.db.load_and_lock_agent(parent_id)
-        merged_ctx_dict = await self.db.recompose_parent(parent_id)
-        join_event = Event(agent_id=parent_id, node_name=join_node_name)
-        await self.db.save_state(parent_id, join_node_name, merged_ctx_dict, join_event)
-        await self.bus.publish(join_event)

commandnet-0.2.2/commandnet/interfaces/observer.py

@@ -1,5 +0,0 @@
-from abc import ABC
-
-class Observer(ABC):
-    async def on_transition(self, agent_id: str, from_node: str, to_node: str, duration_ms: float): pass
-    async def on_error(self, agent_id: str, node: str, error: Exception): pass

commandnet-0.2.2/commandnet/interfaces/persistence.py

@@ -1,41 +0,0 @@
-from abc import ABC, abstractmethod
-from typing import Dict, Optional, Tuple, List
-from ..core.models import Event
-
-class Persistence(ABC):
-    @abstractmethod
-    async def load_and_lock_agent(self, agent_id: str) -> Tuple[Optional[str], Optional[Dict]]:
-        pass
-        
-    @abstractmethod
-    async def unlock_agent(self, agent_id: str):
-        """Releases the row lock. Called automatically by the engine if an exception occurs."""
-        pass
-
-    @abstractmethod
-    async def save_state(self, agent_id: str, node_name: str, context: Dict, event: Optional[Event]):
-        pass
-
-    @abstractmethod
-    async def save_sub_state(self, sub_id: str, parent_id: str, node_name: str, ctx: dict, evt: Optional[Event]):
-        pass
-
-    @abstractmethod
-    async def create_task_group(self, parent_id: str, join_node_name: str, task_count: int):
-        pass
-
-    @abstractmethod
-    async def register_sub_task_completion(self, sub_id: str) -> Optional[str]:
-        pass
-
-    @abstractmethod
-    async def recompose_parent(self, parent_id: str) -> dict:
-        pass
-
-    @abstractmethod
-    async def schedule_event(self, event: Event) -> bool:
-        pass
-
-    @abstractmethod
-    async def pop_due_events(self) -> List[Event]:
-        pass