commandnet 0.1.0__tar.gz

commandnet-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: commandnet
+Version: 0.1.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.1.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 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.1.0/commandnet/__init__.py

@@ -0,0 +1,12 @@
+from .core.models import Event
+from .core.node import Node
+from .core.graph import GraphAnalyzer
+from .interfaces.persistence import Persistence
+from .interfaces.event_bus import EventBus
+from .interfaces.observer import Observer
+from .engine.runtime import Engine
+
+__all__ = [
+    "Event", "Node", "GraphAnalyzer", 
+    "Persistence", "EventBus", "Observer", "Engine"
+]

commandnet-0.1.0/commandnet/core/graph.py

@@ -0,0 +1,69 @@
+import typing
+from typing import Any, Dict, List, Set, Type, Union
+from .node import Node, NODE_REGISTRY
+
+class GraphAnalyzer:
+    """Introspects Python annotations to derive transitions using the Node Registry."""
+
+    @staticmethod
+    def get_context_type(node_cls: Type[Node]) -> Type[Any]:
+        """Extracts the expected Context type from the run() method signature."""
+        hints = typing.get_type_hints(node_cls.run)
+        for param_name, param_type in hints.items():
+            if param_name != 'return':
+                return param_type
+        return dict  # Fallback
+
+    @staticmethod
+    def _get_node_names(type_hint: Any) -> List[str]:
+        """Recursively extracts node names from a type hint (handling Union)."""
+        # Handle Union types (e.g., Union[A, B] or A | B)
+        origin = typing.get_origin(type_hint)
+        if origin is Union:
+            return [name for arg in typing.get_args(type_hint) for name in GraphAnalyzer._get_node_names(arg)]
+        
+        # Handle ForwardRefs (strings in annotations)
+        if isinstance(type_hint, typing.ForwardRef):
+            return [type_hint.__forward_arg__]
+        
+        # Handle actual classes
+        if isinstance(type_hint, type) and issubclass(type_hint, Node):
+            return [type_hint.__name__]
+            
+        return []
+
+    @staticmethod
+    def get_transitions(node_cls: Type[Node]) -> Set[Type[Node]]:
+        """Extracts possible next nodes by looking up names in the NODE_REGISTRY."""
+        # Access the raw annotation directly from the function
+        ret_annotation = node_cls.run.__annotations__.get("return")
+        if not ret_annotation:
+            return set()
+
+        # Get the names of the next nodes
+        node_names = GraphAnalyzer._get_node_names(ret_annotation)
+        
+        # Resolve names to actual classes using our Registry
+        return {NODE_REGISTRY[name] for name in node_names if name in NODE_REGISTRY}
+
+    @staticmethod
+    def build_graph(start_node: Type[Node]) -> Dict[str, List[str]]:
+        """Recursively builds the execution DAG."""
+        graph = {}
+        visited = set()
+        queue = [start_node]
+
+        while queue:
+            current = queue.pop(0)
+            if current in visited:
+                continue
+            
+            visited.add(current)
+            transitions = GraphAnalyzer.get_transitions(current)
+            graph[current.__name__] = [t.__name__ for t in transitions]
+
+            for t in transitions:
+                if t not in visited:
+                    queue.append(t)
+                    
+        return graph

commandnet-0.1.0/commandnet/core/models.py

@@ -0,0 +1,15 @@
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field
+
+def utcnow_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+class Event(BaseModel):
+    """Represents a state transition event triggering a node execution."""
+    event_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    agent_id: str
+    node_name: str
+    payload: Optional[Dict[str, Any]] = None
+    timestamp: str = Field(default_factory=utcnow_iso)

commandnet-0.1.0/commandnet/core/node.py

@@ -0,0 +1,22 @@
+import inspect
+from abc import ABC, abstractmethod
+from typing import Dict, Generic, Optional, Type, TypeVar
+
+C = TypeVar('C')  # Generic Context Type
+NODE_REGISTRY: Dict[str, Type['Node']] = {}
+
+class Node(Generic[C], ABC):
+    """
+    Stateless unit of execution.
+    Subclasses must implement `run` and type-hint the return with next Node classes.
+    """
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        # Automatically register non-abstract nodes
+        if not inspect.isabstract(cls):
+            NODE_REGISTRY[cls.__name__] = cls
+
+    @abstractmethod
+    async def run(self, ctx: C) -> Optional[Type['Node']]:
+        """Executes node logic. Returns the next Node class, or None if terminal."""
+        pass

commandnet-0.1.0/commandnet/engine/runtime.py

@@ -0,0 +1,87 @@
+import asyncio
+import logging
+import uuid
+from typing import Any, Optional, Type
+from pydantic import BaseModel
+
+from ..core.models import Event
+from ..core.node import Node, NODE_REGISTRY
+from ..core.graph import GraphAnalyzer
+from ..interfaces.persistence import Persistence
+from ..interfaces.event_bus import EventBus
+from ..interfaces.observer import Observer
+
+class Engine:
+    """Manages event-driven transitions, state rehydration, and execution."""
+    
+    def __init__(
+        self, 
+        persistence: Persistence, 
+        event_bus: EventBus,
+        observer: Optional[Observer] = None
+    ):
+        self.db = persistence
+        self.bus = event_bus
+        self.observer = observer or Observer()
+        self.logger = logging.getLogger("TypedEngine")
+
+    async def start_worker(self):
+        """Subscribes the engine to the event bus."""
+        await self.bus.subscribe(self.process_event)
+        self.logger.info("Worker started, listening for events.")
+
+    async def trigger_agent(self, agent_id: str, start_node: Type[Node], initial_context: Any):
+        """Initializes a new agent and pushes the first event."""
+        ctx_dict = initial_context.model_dump() if isinstance(initial_context, BaseModel) else initial_context
+        
+        start_event = Event(agent_id=agent_id, node_name=start_node.__name__)
+        await self.db.save_state(agent_id, start_node.__name__, ctx_dict, start_event)
+        await self.bus.publish(start_event)
+
+    async def process_event(self, event: Event):
+        """Core state machine worker loop."""
+        start_time = asyncio.get_event_loop().time()
+        
+        # 1. Concurrency safe load
+        current_node_name, ctx_dict = await self.db.load_and_lock_agent(event.agent_id)
+        if not current_node_name:
+            return
+
+        # 2. Idempotency Check
+        if current_node_name != event.node_name:
+            self.logger.info(f"Stale event {event.event_id} for {event.agent_id}. Ignoring.")
+            return
+
+        node_cls = NODE_REGISTRY.get(current_node_name)
+        if not node_cls:
+            raise RuntimeError(f"Node '{current_node_name}' missing from registry.")
+
+        # 3. Pydantic Automatic Rehydration
+        ctx_type = GraphAnalyzer.get_context_type(node_cls)
+        try:
+            ctx = ctx_type.model_validate(ctx_dict) if issubclass(ctx_type, BaseModel) else ctx_dict
+        except Exception as e:
+            self.logger.error(f"Context validation failed for {event.agent_id}: {e}")
+            raise
+
+        # 4. Execute
+        node_instance = node_cls()
+        try:
+            next_node_cls = await node_instance.run(ctx)
+        except Exception as e:
+            await self.observer.on_error(event.agent_id, current_node_name, e)
+            raise  # Handled by external broker retry policy
+            
+        # 5. Determine transition & serialize context
+        duration = (asyncio.get_event_loop().time() - start_time) * 1000
+        new_ctx_dict = ctx.model_dump() if isinstance(ctx, BaseModel) else ctx
+        
+        if next_node_cls:
+            next_name = next_node_cls.__name__
+            await self.observer.on_transition(event.agent_id, current_node_name, next_name, duration)
+            
+            next_event = Event(agent_id=event.agent_id, node_name=next_name)
+            await self.db.save_state(event.agent_id, next_name, new_ctx_dict, next_event)
+            await self.bus.publish(next_event)
+        else:
+            await self.observer.on_transition(event.agent_id, current_node_name, "TERMINAL", duration)

commandnet-0.1.0/commandnet/interfaces/event_bus.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+from typing import Callable, Coroutine
+from ..core.models import Event
+
+class EventBus(ABC):
+    @abstractmethod
+    async def publish(self, event: Event):
+        """Publishes an event to the queue/broker."""
+        pass
+
+    @abstractmethod
+    async def subscribe(self, handler: Callable[[Event], Coroutine]):
+        """Registers a worker callback to process incoming events."""
+        pass

commandnet-0.1.0/commandnet/interfaces/observer.py

@@ -0,0 +1,6 @@
+from abc import ABC
+
+class Observer(ABC):
+    """Optional hooks for distributed tracing, metrics, and logging."""
+    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.1.0/commandnet/interfaces/persistence.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Optional, Tuple
+from ..core.models import Event
+
+class Persistence(ABC):
+    @abstractmethod
+    async def load_and_lock_agent(self, agent_id: str) -> Tuple[Optional[str], Optional[Dict]]:
+        """Loads state and locks the DB row. Returns (node_name, context_dict)."""
+        pass
+
+    @abstractmethod
+    async def save_state(self, agent_id: str, node_name: str, context: Dict, event: Event):
+        """Persists the updated context and records the transition event."""
+        pass

commandnet-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "commandnet"
+version = "0.1.0"
+description = "A lightweight, Pydantic-powered, distributed event-driven state machine and typed node graph runtime."
+authors = [
+    { name = "Christopher Vaz", email = "christophervaz160@gmail.com" }
+]
+readme = "README.md"
+requires-python = ">=3.11"
+
+dependencies = [
+    "pydantic>=2.0.0"
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio"
+]
+
+[project.urls]
+Homepage = "https://github.com/NullAxon/commandnet"
+Repository = "https://github.com/NullAxon/commandnet"
+Issues = "https://github.com/NullAxon/commandnet/issues"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+asyncio_default_test_loop_scope = "function"