commandnet 0.2.0__tar.gz → 0.2.2__tar.gz

commandnet-0.2.2/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: commandnet
+Version: 0.2.2
+Summary: A lightweight, Pydantic-powered, distributed event-driven state machine and typed node graph runtime.
+Author: Christopher Vaz
+Author-email: christophervaz160@gmail.com
+Requires-Python: >=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Provides-Extra: dev
+Requires-Dist: pydantic (>=2.0.0)
+Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: pytest-asyncio ; extra == "dev"
+Project-URL: Homepage, https://github.com/NullAxon/commandnet
+Project-URL: Issues, https://github.com/NullAxon/commandnet/issues
+Project-URL: Repository, https://github.com/NullAxon/commandnet
+Description-Content-Type: text/markdown
+
+# 🕸️ CommandNet
+
+**CommandNet** is a lightweight, distributed, event-driven state machine and typed node graph runtime for Python 3.11+.
+
+It enables you to build durable, asynchronous workflows using strictly typed Python classes and Pydantic models. Unlike heavy orchestrators, CommandNet provides a minimal core that executes graph-based logic across distributed workers using your choice of database and message broker.
+
+---
+
+## 🚀 Installation
+
+Install CommandNet via pip:
+
+```bash
+pip install commandnet
+```
+
+---
+
+## ✨ Key Features
+
+- **Type-Safe Transitions**: The execution graph is inferred directly from Python type hints (`-> Union[Type[NodeA], Type[NodeB]]`). No external JSON/YAML definitions.
+- **Pydantic State Management**: Context is automatically serialized and rehydrated into Pydantic models with full validation.
+- **Distributed by Design**: Built-in row-level locking and idempotency support for safe execution across horizontally scaled workers.
+- **Fan-out / Fan-in (Parallel)**: Native support for triggering multiple concurrent sub-tasks and merging results back into the parent state.
+- **Native Scheduling**: Schedule nodes to run after a specific delay with built-in idempotency keys to prevent duplicate execution.
+- **Static Validation**: Validate your entire workflow graph (types and connectivity) before a single event is processed.
+
+---
+
+## 🛠️ Quick Start
+
+### 1. Define Your Context
+The "Context" is the persistent state of your agent, defined using Pydantic.
+
+```python
+from pydantic import BaseModel
+
+class WorkflowCtx(BaseModel):
+    user_id: str
+    status: str = "pending"
+    attempts: int = 0
+```
+
+### 2. Define Your Nodes
+Nodes are the building blocks of your graph. The return type hint of the `run` method defines the edges of your DAG.
+
+```python
+from typing import Union, Type, Optional
+from commandnet import Node
+
+class ProcessPayment(Node[WorkflowCtx, None]):
+    async def run(self, ctx: WorkflowCtx, payload: None) -> None:
+        print(f"Processing for {ctx.user_id}...")
+        ctx.status = "complete"
+        return None # Terminal state
+
+class CheckRisk(Node[WorkflowCtx, None]):
+    # The return type explicitly defines the possible next nodes
+    async def run(self, ctx: WorkflowCtx, payload: None) -> Union[Type[ProcessPayment], None]:
+        ctx.attempts += 1
+        if ctx.attempts > 3:
+            return None # Failure/Stop
+        return ProcessPayment
+```
+
+### 3. Advanced Routing (Parallel & Scheduled)
+CommandNet supports complex workflow patterns beyond simple linear transitions.
+
+#### Parallel Fan-out
+```python
+from commandnet import Parallel, ParallelTask
+
+class StartAnalysis(Node[WorkflowCtx, None]):
+    async def run(self, ctx: WorkflowCtx, payload: None) -> Parallel:
+        return Parallel(
+            branches=[
+                ParallelTask(node_cls=SubTaskNode, sub_context_path="sub_data_1"),
+                ParallelTask(node_cls=SubTaskNode, sub_context_path="sub_data_2")
+            ],
+            join_node=FinalMergeNode
+        )
+```
+
+#### Delayed Scheduling
+```python
+from commandnet import Schedule
+
+class RetryNode(Node[WorkflowCtx, None]):
+    async def run(self, ctx: WorkflowCtx, payload: None) -> Schedule:
+        return Schedule(
+            node_cls=CheckRisk,
+            delay_seconds=300,
+            idempotency_key=f"retry-{ctx.attempts}"
+        )
+```
+
+---
+
+## 🏗️ Infrastructure Integration
+
+CommandNet is unopinionated about your stack. You simply implement two abstract interfaces:
+
+1.  **`Persistence`**: Handles locking state in your DB (Postgres, Redis, DynamoDB).
+2.  **`EventBus`**: Handles moving events between workers (RabbitMQ, NATS, SQS).
+
+```python
+from commandnet import Engine
+
+# Implement these interfaces for your specific stack
+db = MyPostgresAdapter()
+bus = MyRabbitMQAdapter()
+
+engine = Engine(persistence=db, event_bus=bus)
+
+# Start the worker loop
+await engine.start_worker()
+
+# Trigger an execution
+await engine.trigger_agent("agent-123", CheckRisk, WorkflowCtx(user_id="user_abc"))
+```
+
+---
+
+## 🔍 Static Analysis & Safety
+
+Prevent runtime failures by validating your graph during CI/CD or at startup. The `GraphAnalyzer` checks for disconnected nodes and ensures that if `NodeA` transitions to `NodeB`, they share compatible `Context` types.
+
+```python
+from commandnet import GraphAnalyzer
+
+# This will raise a TypeError if types don't match or a ValueError if edges are broken
+GraphAnalyzer.validate(CheckRisk)
+
+# Generate a dictionary representation of your DAG
+dag = GraphAnalyzer.build_graph(CheckRisk)
+print(dag) # {'CheckRisk': ['ProcessPayment'], 'ProcessPayment': []}
+```
+
+---
+
+## ⚖️ Design Philosophy
+
+1.  **Code as Truth**: If your IDE can navigate it, CommandNet can run it. No "magic strings."
+2.  **Stateless Execution**: Workers don't keep local state. Every node execution starts with a fresh database fetch and lock.
+3.  **Zero Magic**: No hidden background threads or global singletons. You control the `Engine` lifecycle.
+4.  **Ownership**: CommandNet provides the orchestration logic; you provide the infrastructure.
+
+## 📄 License
+
+MIT
+

commandnet-0.2.2/README.md

@@ -0,0 +1,150 @@
+# 🕸️ CommandNet
+
+**CommandNet** is a lightweight, distributed, event-driven state machine and typed node graph runtime for Python 3.11+.
+
+It enables you to build durable, asynchronous workflows using strictly typed Python classes and Pydantic models. Unlike heavy orchestrators, CommandNet provides a minimal core that executes graph-based logic across distributed workers using your choice of database and message broker.
+
+---
+
+## 🚀 Installation
+
+Install CommandNet via pip:
+
+```bash
+pip install commandnet
+```
+
+---
+
+## ✨ Key Features
+
+- **Type-Safe Transitions**: The execution graph is inferred directly from Python type hints (`-> Union[Type[NodeA], Type[NodeB]]`). No external JSON/YAML definitions.
+- **Pydantic State Management**: Context is automatically serialized and rehydrated into Pydantic models with full validation.
+- **Distributed by Design**: Built-in row-level locking and idempotency support for safe execution across horizontally scaled workers.
+- **Fan-out / Fan-in (Parallel)**: Native support for triggering multiple concurrent sub-tasks and merging results back into the parent state.
+- **Native Scheduling**: Schedule nodes to run after a specific delay with built-in idempotency keys to prevent duplicate execution.
+- **Static Validation**: Validate your entire workflow graph (types and connectivity) before a single event is processed.
+
+---
+
+## 🛠️ Quick Start
+
+### 1. Define Your Context
+The "Context" is the persistent state of your agent, defined using Pydantic.
+
+```python
+from pydantic import BaseModel
+
+class WorkflowCtx(BaseModel):
+    user_id: str
+    status: str = "pending"
+    attempts: int = 0
+```
+
+### 2. Define Your Nodes
+Nodes are the building blocks of your graph. The return type hint of the `run` method defines the edges of your DAG.
+
+```python
+from typing import Union, Type, Optional
+from commandnet import Node
+
+class ProcessPayment(Node[WorkflowCtx, None]):
+    async def run(self, ctx: WorkflowCtx, payload: None) -> None:
+        print(f"Processing for {ctx.user_id}...")
+        ctx.status = "complete"
+        return None # Terminal state
+
+class CheckRisk(Node[WorkflowCtx, None]):
+    # The return type explicitly defines the possible next nodes
+    async def run(self, ctx: WorkflowCtx, payload: None) -> Union[Type[ProcessPayment], None]:
+        ctx.attempts += 1
+        if ctx.attempts > 3:
+            return None # Failure/Stop
+        return ProcessPayment
+```
+
+### 3. Advanced Routing (Parallel & Scheduled)
+CommandNet supports complex workflow patterns beyond simple linear transitions.
+
+#### Parallel Fan-out
+```python
+from commandnet import Parallel, ParallelTask
+
+class StartAnalysis(Node[WorkflowCtx, None]):
+    async def run(self, ctx: WorkflowCtx, payload: None) -> Parallel:
+        return Parallel(
+            branches=[
+                ParallelTask(node_cls=SubTaskNode, sub_context_path="sub_data_1"),
+                ParallelTask(node_cls=SubTaskNode, sub_context_path="sub_data_2")
+            ],
+            join_node=FinalMergeNode
+        )
+```
+
+#### Delayed Scheduling
+```python
+from commandnet import Schedule
+
+class RetryNode(Node[WorkflowCtx, None]):
+    async def run(self, ctx: WorkflowCtx, payload: None) -> Schedule:
+        return Schedule(
+            node_cls=CheckRisk,
+            delay_seconds=300,
+            idempotency_key=f"retry-{ctx.attempts}"
+        )
+```
+
+---
+
+## 🏗️ Infrastructure Integration
+
+CommandNet is unopinionated about your stack. You simply implement two abstract interfaces:
+
+1.  **`Persistence`**: Handles locking state in your DB (Postgres, Redis, DynamoDB).
+2.  **`EventBus`**: Handles moving events between workers (RabbitMQ, NATS, SQS).
+
+```python
+from commandnet import Engine
+
+# Implement these interfaces for your specific stack
+db = MyPostgresAdapter()
+bus = MyRabbitMQAdapter()
+
+engine = Engine(persistence=db, event_bus=bus)
+
+# Start the worker loop
+await engine.start_worker()
+
+# Trigger an execution
+await engine.trigger_agent("agent-123", CheckRisk, WorkflowCtx(user_id="user_abc"))
+```
+
+---
+
+## 🔍 Static Analysis & Safety
+
+Prevent runtime failures by validating your graph during CI/CD or at startup. The `GraphAnalyzer` checks for disconnected nodes and ensures that if `NodeA` transitions to `NodeB`, they share compatible `Context` types.
+
+```python
+from commandnet import GraphAnalyzer
+
+# This will raise a TypeError if types don't match or a ValueError if edges are broken
+GraphAnalyzer.validate(CheckRisk)
+
+# Generate a dictionary representation of your DAG
+dag = GraphAnalyzer.build_graph(CheckRisk)
+print(dag) # {'CheckRisk': ['ProcessPayment'], 'ProcessPayment': []}
+```
+
+---
+
+## ⚖️ Design Philosophy
+
+1.  **Code as Truth**: If your IDE can navigate it, CommandNet can run it. No "magic strings."
+2.  **Stateless Execution**: Workers don't keep local state. Every node execution starts with a fresh database fetch and lock.
+3.  **Zero Magic**: No hidden background threads or global singletons. You control the `Engine` lifecycle.
+4.  **Ownership**: CommandNet provides the orchestration logic; you provide the infrastructure.
+
+## 📄 License
+
+MIT

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

@@ -1,7 +1,7 @@
 import typing
 import inspect
 from typing import Any, Dict, List, Set, Type, Union, get_args, get_origin
-from .node import Node, NODE_REGISTRY
+from .node import Node
 
 class GraphAnalyzer:
     @staticmethod
@@ -25,16 +25,12 @@ class GraphAnalyzer:
     @staticmethod
     def _get_node_names(type_hint: Any) -> List[str]:
         origin = typing.get_origin(type_hint)
-        
-        # 1. Handle Union (and Optional)
         if origin is Union:
             names = []
             for arg in typing.get_args(type_hint):
                 if arg is type(None): continue
                 names.extend(GraphAnalyzer._get_node_names(arg))
             return names
-            
-        # 2. Handle Type[X] or typing.Type[X]
         if origin in (type, typing.Type):
             arg = typing.get_args(type_hint)[0]
             if inspect.isclass(arg) and issubclass(arg, Node):
@@ -43,15 +39,12 @@ class GraphAnalyzer:
                 return [arg.__forward_arg__]
             if isinstance(arg, str):
                 return [arg]
-                
-        # 3. Direct class references
         if inspect.isclass(type_hint) and issubclass(type_hint, Node):
             return [type_hint.get_node_name()]
-            
         return []
 
     @staticmethod
-    def get_transitions(node_cls: Type[Node]) -> Set[Type[Node]]:
+    def get_transitions(node_cls: Type[Node], registry: Dict[str, Type[Node]]) -> Set[Type[Node]]:
         ret_annotation = node_cls.run.__annotations__.get("return")
         if not ret_annotation: return set()
         
@@ -59,47 +52,42 @@ class GraphAnalyzer:
         transitions = set()
         
         for name in node_names:
-            if name not in NODE_REGISTRY:
+            if name not in registry:
                 raise RuntimeError(
                     f"Graph Error: Node '{node_cls.get_node_name()}' references unknown node '{name}'. "
-                    "Ensure it is imported and subclasses CommandNet Node."
+                    "Ensure it is passed to the Engine/Registry."
                 )
-            transitions.add(NODE_REGISTRY[name])
-            
+            transitions.add(registry[name])
         return transitions
 
     @staticmethod
-    def build_graph(start_node: Type[Node]) -> Dict[str, List[str]]:
+    def build_graph(start_node: Type[Node], registry: Dict[str, Type[Node]]) -> Dict[str, List[str]]:
         graph = {}
         visited, queue = set(), [start_node]
         while queue:
             current = queue.pop(0)
             if current in visited: continue
             visited.add(current)
-            transitions = GraphAnalyzer.get_transitions(current)
+            transitions = GraphAnalyzer.get_transitions(current, registry)
             graph[current.get_node_name()] = [t.get_node_name() for t in transitions]
             for t in transitions:
                 if t not in visited: queue.append(t)
         return graph
 
     @staticmethod
-    def validate(start_node: Type[Node]):
-        """Static analysis of the DAG to prevent runtime crashes."""
-        graph = GraphAnalyzer.build_graph(start_node)
-        
+    def validate(start_node: Type[Node], registry: Dict[str, Type[Node]]):
+        graph = GraphAnalyzer.build_graph(start_node, registry)
         for node_name, edges in graph.items():
-            node_cls = NODE_REGISTRY.get(node_name)
+            node_cls = registry.get(node_name)
             if not node_cls:
                 raise ValueError(f"Validation Error: Node '{node_name}' missing from registry.")
             
             source_ctx = GraphAnalyzer.get_context_type(node_cls)
-            
             for edge in edges:
-                target_cls = NODE_REGISTRY.get(edge)
+                target_cls = registry.get(edge)
                 if not target_cls:
                     raise ValueError(f"Validation Error: Edge '{edge}' from '{node_name}' does not exist.")
                 
-                # STRICT CONTEXT MATCHING
                 target_ctx = GraphAnalyzer.get_context_type(target_cls)
                 if source_ctx is not target_ctx and not issubclass(source_ctx, target_ctx):
                     raise TypeError(
@@ -107,5 +95,4 @@ class GraphAnalyzer:
                         f"but their Context types do not match! "
                         f"({source_ctx.__name__} -> {target_ctx.__name__})"
                     )
-        
         return True

{commandnet-0.2.0 → commandnet-0.2.2}/commandnet/core/node.py

@@ -5,8 +5,6 @@ from pydantic import BaseModel, ConfigDict
 C = TypeVar('C', bound=BaseModel) # Context
 P = TypeVar('P', bound=BaseModel) # Payload (Optional)
 
-NODE_REGISTRY: Dict[str, Type['Node']] = {}
-
 class ParallelTask(BaseModel):
     model_config = ConfigDict(arbitrary_types_allowed=True)
     node_cls: Type['Node']
@@ -33,18 +31,6 @@ class Node(Generic[C, P]):
     def get_node_name(cls) -> str:
         return cls.__name__
 
-    def __init_subclass__(cls, **kwargs):
-        super().__init_subclass__(**kwargs)
-        if not inspect.isabstract(cls):
-            name = cls.get_node_name()
-            # Prevent registry collisions across modules
-            if name in NODE_REGISTRY and NODE_REGISTRY[name] is not cls:
-                raise RuntimeError(
-                    f"NODE_REGISTRY Collision: '{name}' is already registered by {NODE_REGISTRY[name].__module__}. "
-                    f"Override `get_node_name()` on {cls.__module__}.{name} to ensure uniqueness."
-                )
-            NODE_REGISTRY[name] = cls
-
     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.0 → commandnet-0.2.2}/commandnet/engine/runtime.py

@@ -1,23 +1,41 @@
 import asyncio
 import logging
 from datetime import datetime, timezone, timedelta
-from typing import Optional, Type
+from typing import Optional, Type, Iterable, Dict
 from pydantic import BaseModel
 
 from ..core.models import Event
-from ..core.node import Node, NODE_REGISTRY, Parallel, Schedule
+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, observer: Optional[Observer] = None):
+    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)
@@ -46,6 +64,9 @@ class Engine:
 
     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,
@@ -64,6 +85,7 @@ class Engine:
         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)
@@ -72,9 +94,9 @@ class Engine:
                 locked = False
                 return
 
-            node_cls = NODE_REGISTRY.get(current_node_name)
+            node_cls = self._registry.get(current_node_name)
             if not node_cls:
-                raise RuntimeError(f"Node '{current_node_name}' missing from registry.")
+                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)
@@ -101,20 +123,22 @@ class Engine:
             else:
                 await self._handle_terminal(event.agent_id, current_node_name, ctx, duration)
                 
-            locked = False # Success! The handle_* methods performed a save_state, which released the lock.
+            locked = False 
             
         except Exception as e:
             await self.observer.on_error(event.agent_id, current_node_name, e)
             raise
         finally:
             if locked:
-                # Deadlock prevention: Exception occurred before state was saved
                 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)
@@ -122,33 +146,31 @@ class Engine:
     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}'. Cannot fan out.")
+                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=task.node_cls.get_node_name(),
+                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, task.node_cls.get_node_name(), sub_ctx.model_dump(), evt)
+            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)
@@ -158,7 +180,6 @@ class Engine:
     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(
@@ -175,7 +196,6 @@ class Engine:
         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:

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

@@ -1,6 +1,6 @@
 [project]
 name = "commandnet"
-version = "0.2.0"
+version = "0.2.2"
 description = "A lightweight, Pydantic-powered, distributed event-driven state machine and typed node graph runtime."
 authors = [
     { name = "Christopher Vaz", email = "christophervaz160@gmail.com" }

commandnet-0.2.0/PKG-INFO

@@ -1,174 +0,0 @@
-Metadata-Version: 2.4
-Name: commandnet
-Version: 0.2.0
-Summary: A lightweight, Pydantic-powered, distributed event-driven state machine and typed node graph runtime.
-Author: Christopher Vaz
-Author-email: christophervaz160@gmail.com
-Requires-Python: >=3.11
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Topic :: System :: Distributed Computing
-Provides-Extra: dev
-Requires-Dist: pydantic (>=2.0.0)
-Requires-Dist: pytest ; extra == "dev"
-Requires-Dist: pytest-asyncio ; extra == "dev"
-Project-URL: Homepage, https://github.com/NullAxon/commandnet
-Project-URL: Issues, https://github.com/NullAxon/commandnet/issues
-Project-URL: Repository, https://github.com/NullAxon/commandnet
-Description-Content-Type: text/markdown
-
-# CommandNet
-
-**CommandNet** is a lightweight, distributed, event-driven state machine and typed node graph runtime for Python 3.11+.
-
-It allows you to build durable, asynchronous workflow graphs using strictly typed Python classes and Pydantic models. **CommandNet is not an orchestrator** (no built-in crons, external scheduling, or magic workflow DSLs). Instead, it provides a minimal, dependency-free (except Pydantic) core for executing graph-based logic across distributed workers using any database and message broker you choose.
-
-## Features
-
-- **Strictly Typed Transitions**: Execution graphs are inferred directly from Python type hints (`-> NextNode`). No string-based identifiers.
-- **First-Class Pydantic Support**: Context state is automatically serialized to your database and strictly rehydrated into Pydantic models before node execution.
-- **Distributed-Worker Ready**: Safely runs across multiple horizontally scaled consumers via row-level locking patterns and idempotency checks.
-- **Bring Your Own Infrastructure**: Clean abstract interfaces for `Persistence` (Postgres, SQLite) and `EventBus` (RabbitMQ, NATS, Redis).
-- **Zero Magic**: Deterministic execution, highly observable, and easy to test.
-
----
-
-## Installation
-
-```bash
-pip install commandnet
-```
-*Or with Poetry:*
-```bash
-poetry add commandnet
-```
-
----
-
-## Quick Start
-
-### 1. Define your State (Context)
-Use Pydantic to define the mutable state that will be passed through your graph. CommandNet will automatically validate and rehydrate this data from your database.
-
-```python
-from pydantic import BaseModel, Field
-
-class AgentContext(BaseModel):
-    user_query: str
-    is_authenticated: bool = False
-    attempts: int = Field(default=0, ge=0)
-```
-
-### 2. Define your Nodes
-Nodes subclass `Node` and must implement an `async def run(self, ctx)`. The **return type hint** dictates the execution graph!
-
-```python
-from typing import Union, Type
-from commandnet import Node
-
-class Denied(Node[AgentContext]):
-    async def run(self, ctx: AgentContext) -> None: # Returning None means Terminal state
-        print(f"[{ctx.user_query}] -> Access Denied.")
-        return None
-
-class Executing(Node[AgentContext]):
-    async def run(self, ctx: AgentContext) -> None: 
-        print(f"[{ctx.user_query}] -> Running task successfully!")
-        return None
-
-class AuthCheck(Node[AgentContext]):
-    # The return type explicitly defines the DAG edges:
-    async def run(self, ctx: AgentContext) -> Union[Type[Executing], Type[Denied]]:
-        print(f"[{ctx.user_query}] -> Checking Auth...")
-        ctx.attempts += 1
-        
-        if ctx.user_query == "hack_system":
-            return Denied
-            
-        ctx.is_authenticated = True
-        return Executing
-```
-
-### 3. Run the Engine
-Implement the `Persistence` and `EventBus` interfaces for your infrastructure (or use in-memory mocks for testing), and trigger the agent.
-
-```python
-import asyncio
-from commandnet import Engine, GraphAnalyzer
-
-# Note: You must implement Persistence and EventBus interfaces
-# See the `interfaces/` directory for expected methods.
-from my_app.adapters import PostgresPersistence, RabbitMQBus 
-
-async def main():
-    # 1. (Optional) Introspect your graph to visualize or validate it
-    dag = GraphAnalyzer.build_graph(AuthCheck)
-    print("Graph Structure:", dag) 
-    # Output: {'AuthCheck': ['Executing', 'Denied'], 'Executing': [], 'Denied': []}
-
-    # 2. Initialize Engine
-    db = PostgresPersistence()
-    bus = RabbitMQBus()
-    engine = Engine(persistence=db, event_bus=bus)
-    
-    # 3. Start listening to the event queue
-    await engine.start_worker()
-    
-    # 4. Trigger an execution
-    initial_context = AgentContext(user_query="clean_logs")
-    await engine.trigger_agent(
-        agent_id="agent-001", 
-        start_node=AuthCheck, 
-        initial_context=initial_context
-    )
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
----
-
-## Pluggable Architecture
-
-CommandNet forces you to own your infrastructure. You connect it to your stack by implementing three simple interfaces:
-
-### `Persistence`
-Handles locking, saving, and loading the agent's context.
-```python
-class Persistence(ABC):
-    async def load_and_lock_agent(self, agent_id: str) -> Tuple[Optional[str], Optional[Dict]]: ...
-    async def save_state(self, agent_id: str, node_name: str, context: Dict, event: Event): ...
-```
-
-### `EventBus`
-Handles emitting transitions and consuming events in your worker loop.
-```python
-class EventBus(ABC):
-    async def publish(self, event: Event): ...
-    async def subscribe(self, handler: Callable[[Event], Coroutine]): ...
-```
-
-### `Observer` (Optional)
-Hooks for integrating OpenTelemetry, Prometheus, or custom logging.
-```python
-class Observer(ABC):
-    async def on_transition(self, agent_id: str, from_node: str, to_node: str, duration_ms: float): ...
-    async def on_error(self, agent_id: str, node: str, error: Exception): ...
-```
-
----
-
-## Design Principles
-
-1. **Minimalism**: CommandNet aims to be under 1,000 lines of core code. It does one thing perfectly: reliably transitioning state machines via queue events.
-2. **Stateless Nodes**: Node classes are instantiated fresh on every execution. All mutable state lives exclusively in the Pydantic `Context`.
-3. **No String Magic**: You shouldn't need a massive JSON file or string literals to define your graph. Python's `typing` module is powerful enough. If your IDE can autocomple it, CommandNet can route it.
-
-## License
-
-MIT
-

commandnet-0.2.0/README.md

@@ -1,150 +0,0 @@
-# CommandNet
-
-**CommandNet** is a lightweight, distributed, event-driven state machine and typed node graph runtime for Python 3.11+.
-
-It allows you to build durable, asynchronous workflow graphs using strictly typed Python classes and Pydantic models. **CommandNet is not an orchestrator** (no built-in crons, external scheduling, or magic workflow DSLs). Instead, it provides a minimal, dependency-free (except Pydantic) core for executing graph-based logic across distributed workers using any database and message broker you choose.
-
-## Features
-
-- **Strictly Typed Transitions**: Execution graphs are inferred directly from Python type hints (`-> NextNode`). No string-based identifiers.
-- **First-Class Pydantic Support**: Context state is automatically serialized to your database and strictly rehydrated into Pydantic models before node execution.
-- **Distributed-Worker Ready**: Safely runs across multiple horizontally scaled consumers via row-level locking patterns and idempotency checks.
-- **Bring Your Own Infrastructure**: Clean abstract interfaces for `Persistence` (Postgres, SQLite) and `EventBus` (RabbitMQ, NATS, Redis).
-- **Zero Magic**: Deterministic execution, highly observable, and easy to test.
-
----
-
-## Installation
-
-```bash
-pip install commandnet
-```
-*Or with Poetry:*
-```bash
-poetry add commandnet
-```
-
----
-
-## Quick Start
-
-### 1. Define your State (Context)
-Use Pydantic to define the mutable state that will be passed through your graph. CommandNet will automatically validate and rehydrate this data from your database.
-
-```python
-from pydantic import BaseModel, Field
-
-class AgentContext(BaseModel):
-    user_query: str
-    is_authenticated: bool = False
-    attempts: int = Field(default=0, ge=0)
-```
-
-### 2. Define your Nodes
-Nodes subclass `Node` and must implement an `async def run(self, ctx)`. The **return type hint** dictates the execution graph!
-
-```python
-from typing import Union, Type
-from commandnet import Node
-
-class Denied(Node[AgentContext]):
-    async def run(self, ctx: AgentContext) -> None: # Returning None means Terminal state
-        print(f"[{ctx.user_query}] -> Access Denied.")
-        return None
-
-class Executing(Node[AgentContext]):
-    async def run(self, ctx: AgentContext) -> None: 
-        print(f"[{ctx.user_query}] -> Running task successfully!")
-        return None
-
-class AuthCheck(Node[AgentContext]):
-    # The return type explicitly defines the DAG edges:
-    async def run(self, ctx: AgentContext) -> Union[Type[Executing], Type[Denied]]:
-        print(f"[{ctx.user_query}] -> Checking Auth...")
-        ctx.attempts += 1
-        
-        if ctx.user_query == "hack_system":
-            return Denied
-            
-        ctx.is_authenticated = True
-        return Executing
-```
-
-### 3. Run the Engine
-Implement the `Persistence` and `EventBus` interfaces for your infrastructure (or use in-memory mocks for testing), and trigger the agent.
-
-```python
-import asyncio
-from commandnet import Engine, GraphAnalyzer
-
-# Note: You must implement Persistence and EventBus interfaces
-# See the `interfaces/` directory for expected methods.
-from my_app.adapters import PostgresPersistence, RabbitMQBus 
-
-async def main():
-    # 1. (Optional) Introspect your graph to visualize or validate it
-    dag = GraphAnalyzer.build_graph(AuthCheck)
-    print("Graph Structure:", dag) 
-    # Output: {'AuthCheck': ['Executing', 'Denied'], 'Executing': [], 'Denied': []}
-
-    # 2. Initialize Engine
-    db = PostgresPersistence()
-    bus = RabbitMQBus()
-    engine = Engine(persistence=db, event_bus=bus)
-    
-    # 3. Start listening to the event queue
-    await engine.start_worker()
-    
-    # 4. Trigger an execution
-    initial_context = AgentContext(user_query="clean_logs")
-    await engine.trigger_agent(
-        agent_id="agent-001", 
-        start_node=AuthCheck, 
-        initial_context=initial_context
-    )
-
-if __name__ == "__main__":
-    asyncio.run(main())
-```
-
----
-
-## Pluggable Architecture
-
-CommandNet forces you to own your infrastructure. You connect it to your stack by implementing three simple interfaces:
-
-### `Persistence`
-Handles locking, saving, and loading the agent's context.
-```python
-class Persistence(ABC):
-    async def load_and_lock_agent(self, agent_id: str) -> Tuple[Optional[str], Optional[Dict]]: ...
-    async def save_state(self, agent_id: str, node_name: str, context: Dict, event: Event): ...
-```
-
-### `EventBus`
-Handles emitting transitions and consuming events in your worker loop.
-```python
-class EventBus(ABC):
-    async def publish(self, event: Event): ...
-    async def subscribe(self, handler: Callable[[Event], Coroutine]): ...
-```
-
-### `Observer` (Optional)
-Hooks for integrating OpenTelemetry, Prometheus, or custom logging.
-```python
-class Observer(ABC):
-    async def on_transition(self, agent_id: str, from_node: str, to_node: str, duration_ms: float): ...
-    async def on_error(self, agent_id: str, node: str, error: Exception): ...
-```
-
----
-
-## Design Principles
-
-1. **Minimalism**: CommandNet aims to be under 1,000 lines of core code. It does one thing perfectly: reliably transitioning state machines via queue events.
-2. **Stateless Nodes**: Node classes are instantiated fresh on every execution. All mutable state lives exclusively in the Pydantic `Context`.
-3. **No String Magic**: You shouldn't need a massive JSON file or string literals to define your graph. Python's `typing` module is powerful enough. If your IDE can autocomple it, CommandNet can route it.
-
-## License
-
-MIT