commandnet 0.2.0__tar.gz → 0.3.0__tar.gz

commandnet-0.3.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: commandnet
+Version: 0.3.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 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.3.0/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.3.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
 from .core.graph import GraphAnalyzer
 from .interfaces.persistence import Persistence
 from .interfaces.event_bus import EventBus

{commandnet-0.2.0 → commandnet-0.3.0}/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.3.0/commandnet/core/node.py

@@ -0,0 +1,43 @@
+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', 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 
+
+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