loopgraph 0.2.0__tar.gz

loopgraph-0.2.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: loopgraph
+Version: 0.2.0
+Summary: Event-driven graph workflow engine with native loop support.
+Author: LoopGraph Team
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.6.4; extra == "lint"
+Requires-Dist: mypy>=1.11.0; extra == "lint"
+
+# LoopGraph
+
+**The agent workflow engine that treats loops as a first-class citizen.**
+
+Build graph-based AI agent workflows where cycles, re-entry, and iterative reasoning are native — not hacks. More intuitive and lightweight than LangGraph, with loops as a first-class primitive.
+
+- **Zero dependencies** — pure Python 3.10+, nothing to install beyond your own agents
+- **Native loop support** — cycles in your graph are validated, tracked, and safe by design
+- **Event-driven** — every state transition emits events; hook in logging, metrics, or triggers anywhere
+- **Async-first** — built on `asyncio`, handles concurrent nodes without blocking
+- **Recoverable** — snapshot and replay any run from any point
+
+```bash
+pip install loopgraph
+```
+
+---
+
+## Quickstart
+
+```python
+import asyncio
+from loopgraph.core.graph import Graph, Node, Edge, NodeKind
+from loopgraph.bus.eventbus import EventBus
+from loopgraph.registry.function_registry import FunctionRegistry
+from loopgraph.scheduler.scheduler import Scheduler
+
+async def my_agent(payload):
+    # your agent logic here
+    return {"result": "done", "loop_again": False}
+
+async def router(payload):
+    # return the next node id
+    return "end" if not payload.get("loop_again") else "agent"
+
+graph = Graph(
+    nodes=[
+        Node(id="agent", kind=NodeKind.TASK),
+        Node(id="router", kind=NodeKind.SWITCH),
+        Node(id="end", kind=NodeKind.TASK),
+    ],
+    edges=[
+        Edge(source="agent", target="router"),
+        Edge(source="router", target="agent"),   # the loop back-edge
+        Edge(source="router", target="end"),
+    ],
+    entry="agent",
+)
+
+registry = FunctionRegistry()
+registry.register("agent", my_agent)
+registry.register("router", router)
+registry.register("end", lambda p: p)
+
+bus = EventBus()
+scheduler = Scheduler(graph=graph, registry=registry, bus=bus)
+
+asyncio.run(scheduler.run(payload={"input": "hello"}))
+```
+
+---
+
+## Why LoopGraph?
+
+Most workflow engines assume a DAG — a graph with no cycles. That works for linear pipelines, but agent workflows are inherently iterative: an agent reasons, reflects, decides to try again, and loops back. Forcing that into a DAG requires awkward workarounds.
+
+LoopGraph makes loops explicit and safe:
+
+- **Back-edges are first-class** — declare a cycle in your graph and the engine handles reset, visit tracking, and state management automatically
+- **Loop safety** — the engine validates your graph at construction time; overlapping loops that share nodes are rejected before anything runs
+- **Full observability** — every loop iteration emits events (`NODE_SCHEDULED`, `NODE_COMPLETED`, `NODE_FAILED`) so you always know where you are
+
+---
+
+## Event Hooks
+
+Subscribe to any workflow event to add logging, metrics, or side effects:
+
+```python
+from loopgraph.core.types import EventType
+
+async def on_completed(event):
+    print(f"{event.node_id} finished → {event.payload}")
+
+bus.subscribe(EventType.NODE_COMPLETED, on_completed)
+```
+
+Available events: `NODE_SCHEDULED`, `NODE_STARTED`, `NODE_COMPLETED`, `NODE_FAILED`.
+
+---
+
+## Custom Events from Handlers
+
+Wrap your handler in a closure to emit custom events mid-execution:
+
+```python
+def make_handler(bus, base_handler):
+    async def wrapper(payload):
+        await bus.emit(Event(id="pre", graph_id="g", node_id="n",
+                             type=EventType.NODE_SCHEDULED, payload={"stage": "pre"}))
+        result = await base_handler(payload)
+        await bus.emit(Event(id="post", graph_id="g", node_id="n",
+                             type=EventType.NODE_COMPLETED, payload={"stage": "post"}))
+        return result
+    return wrapper
+
+registry.register("my_node", make_handler(bus, my_agent))
+```
+
+---
+
+## Loop Re-entry Rules
+
+- Re-entry is triggered by a `SWITCH` node selecting a back-edge
+- Only `COMPLETED` nodes can be reset for re-entry
+- Reset clears upstream-completion tracking and preserves cumulative `visit_count`
+- Overlapping loops sharing any node are rejected at graph construction time
+
+---
+
+## Installation
+
+```bash
+pip install loopgraph
+```
+
+Requires Python 3.10+. No runtime dependencies.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/your-org/loopgraph
+cd loopgraph
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[test,lint]"
+pytest
+```
+
+---
+
+## Design Principles
+
+- **Keep the core compact.** Nodes stay stateless and the scheduler stays simple, with minimum opinionated design and maximum freedom for users to compose their own workflow patterns. Handlers capture their own context (event bus, metrics, side effects) so the framework never grows special cases for custom behaviour.
+- **Push heavy lifting to the edge.** Long-running work should run via remote APIs, threads, or separate nodes/clusters. We avoid building a distributed fan-out scheduler; users orchestrate their own parallelism while the engine focuses on deterministic single-node execution.
+- **Flexible aggregation semantics.** Aggregator nodes may proceed when only a subset of upstream nodes finish — as long as those nodes reach a terminal state. Fail-fast and error-tolerance are user-level workflow patterns, and the engine stays policy-light so users can implement either.
+- **Retries live with handlers.** The framework doesn't implement automatic retries. Each handler decides whether to retry, abort, or compensate, keeping recovery logic close to the business code.
+- **Pluggable concurrency.** A shared ConcurrencyManager (semaphore or priority-aware) controls global slots. Multiple schedulers can share one manager, but there's no hidden magic — users choose the policy, preserving clarity and control.
+- **Recovery through snapshots.** The engine snapshots execution state and event logs so users can resume or replay runs without re-executing nodes. Payloads flow naturally between nodes, satisfying replay needs without extra APIs.

loopgraph-0.2.0/README.md

@@ -0,0 +1,150 @@
+# LoopGraph
+
+**The agent workflow engine that treats loops as a first-class citizen.**
+
+Build graph-based AI agent workflows where cycles, re-entry, and iterative reasoning are native — not hacks. More intuitive and lightweight than LangGraph, with loops as a first-class primitive.
+
+- **Zero dependencies** — pure Python 3.10+, nothing to install beyond your own agents
+- **Native loop support** — cycles in your graph are validated, tracked, and safe by design
+- **Event-driven** — every state transition emits events; hook in logging, metrics, or triggers anywhere
+- **Async-first** — built on `asyncio`, handles concurrent nodes without blocking
+- **Recoverable** — snapshot and replay any run from any point
+
+```bash
+pip install loopgraph
+```
+
+---
+
+## Quickstart
+
+```python
+import asyncio
+from loopgraph.core.graph import Graph, Node, Edge, NodeKind
+from loopgraph.bus.eventbus import EventBus
+from loopgraph.registry.function_registry import FunctionRegistry
+from loopgraph.scheduler.scheduler import Scheduler
+
+async def my_agent(payload):
+    # your agent logic here
+    return {"result": "done", "loop_again": False}
+
+async def router(payload):
+    # return the next node id
+    return "end" if not payload.get("loop_again") else "agent"
+
+graph = Graph(
+    nodes=[
+        Node(id="agent", kind=NodeKind.TASK),
+        Node(id="router", kind=NodeKind.SWITCH),
+        Node(id="end", kind=NodeKind.TASK),
+    ],
+    edges=[
+        Edge(source="agent", target="router"),
+        Edge(source="router", target="agent"),   # the loop back-edge
+        Edge(source="router", target="end"),
+    ],
+    entry="agent",
+)
+
+registry = FunctionRegistry()
+registry.register("agent", my_agent)
+registry.register("router", router)
+registry.register("end", lambda p: p)
+
+bus = EventBus()
+scheduler = Scheduler(graph=graph, registry=registry, bus=bus)
+
+asyncio.run(scheduler.run(payload={"input": "hello"}))
+```
+
+---
+
+## Why LoopGraph?
+
+Most workflow engines assume a DAG — a graph with no cycles. That works for linear pipelines, but agent workflows are inherently iterative: an agent reasons, reflects, decides to try again, and loops back. Forcing that into a DAG requires awkward workarounds.
+
+LoopGraph makes loops explicit and safe:
+
+- **Back-edges are first-class** — declare a cycle in your graph and the engine handles reset, visit tracking, and state management automatically
+- **Loop safety** — the engine validates your graph at construction time; overlapping loops that share nodes are rejected before anything runs
+- **Full observability** — every loop iteration emits events (`NODE_SCHEDULED`, `NODE_COMPLETED`, `NODE_FAILED`) so you always know where you are
+
+---
+
+## Event Hooks
+
+Subscribe to any workflow event to add logging, metrics, or side effects:
+
+```python
+from loopgraph.core.types import EventType
+
+async def on_completed(event):
+    print(f"{event.node_id} finished → {event.payload}")
+
+bus.subscribe(EventType.NODE_COMPLETED, on_completed)
+```
+
+Available events: `NODE_SCHEDULED`, `NODE_STARTED`, `NODE_COMPLETED`, `NODE_FAILED`.
+
+---
+
+## Custom Events from Handlers
+
+Wrap your handler in a closure to emit custom events mid-execution:
+
+```python
+def make_handler(bus, base_handler):
+    async def wrapper(payload):
+        await bus.emit(Event(id="pre", graph_id="g", node_id="n",
+                             type=EventType.NODE_SCHEDULED, payload={"stage": "pre"}))
+        result = await base_handler(payload)
+        await bus.emit(Event(id="post", graph_id="g", node_id="n",
+                             type=EventType.NODE_COMPLETED, payload={"stage": "post"}))
+        return result
+    return wrapper
+
+registry.register("my_node", make_handler(bus, my_agent))
+```
+
+---
+
+## Loop Re-entry Rules
+
+- Re-entry is triggered by a `SWITCH` node selecting a back-edge
+- Only `COMPLETED` nodes can be reset for re-entry
+- Reset clears upstream-completion tracking and preserves cumulative `visit_count`
+- Overlapping loops sharing any node are rejected at graph construction time
+
+---
+
+## Installation
+
+```bash
+pip install loopgraph
+```
+
+Requires Python 3.10+. No runtime dependencies.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/your-org/loopgraph
+cd loopgraph
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[test,lint]"
+pytest
+```
+
+---
+
+## Design Principles
+
+- **Keep the core compact.** Nodes stay stateless and the scheduler stays simple, with minimum opinionated design and maximum freedom for users to compose their own workflow patterns. Handlers capture their own context (event bus, metrics, side effects) so the framework never grows special cases for custom behaviour.
+- **Push heavy lifting to the edge.** Long-running work should run via remote APIs, threads, or separate nodes/clusters. We avoid building a distributed fan-out scheduler; users orchestrate their own parallelism while the engine focuses on deterministic single-node execution.
+- **Flexible aggregation semantics.** Aggregator nodes may proceed when only a subset of upstream nodes finish — as long as those nodes reach a terminal state. Fail-fast and error-tolerance are user-level workflow patterns, and the engine stays policy-light so users can implement either.
+- **Retries live with handlers.** The framework doesn't implement automatic retries. Each handler decides whether to retry, abort, or compensate, keeping recovery logic close to the business code.
+- **Pluggable concurrency.** A shared ConcurrencyManager (semaphore or priority-aware) controls global slots. Multiple schedulers can share one manager, but there's no hidden magic — users choose the policy, preserving clarity and control.
+- **Recovery through snapshots.** The engine snapshots execution state and event logs so users can resume or replay runs without re-executing nodes. Payloads flow naturally between nodes, satisfying replay needs without extra APIs.

loopgraph-0.2.0/loopgraph/__init__.py

@@ -0,0 +1,38 @@
+"""LoopGraph package root exporting shared logging helpers."""
+
+from __future__ import annotations
+
+import logging
+
+from ._debug import (
+    log_branch,
+    log_loop_iteration,
+    log_parameter,
+    log_variable_change,
+)
+
+__all__ = [
+    "log_branch",
+    "log_loop_iteration",
+    "log_parameter",
+    "log_variable_change",
+]
+
+
+def configure_default_logging(level: int = logging.DEBUG) -> None:
+    """Configure a default logging handler for debugging heavy modules.
+
+    >>> configure_default_logging()
+    >>> logging.getLogger("loopgraph").getEffectiveLevel() == logging.DEBUG
+    True
+    """
+    log_parameter("configure_default_logging", level=level)
+    logging.basicConfig(level=level, force=True)
+    logger = logging.getLogger("loopgraph")
+    log_variable_change("configure_default_logging", "logger_level", logger.level)
+    effective_level = logger.getEffectiveLevel()
+    log_variable_change(
+        "configure_default_logging",
+        "effective_level",
+        effective_level,
+    )

loopgraph-0.2.0/loopgraph/_debug.py

@@ -0,0 +1,45 @@
+"""Utilities to standardise verbose debug logging across the codebase."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+LOGGER = logging.getLogger("loopgraph")
+
+
+def log_parameter(func_name: str, **params: Any) -> None:
+    """Log each parameter passed into a function.
+
+    >>> log_parameter("demo_func", alpha=1, beta="two")
+    """
+    LOGGER.debug("function=%s parameters=%r", func_name, params)
+
+
+def log_variable_change(func_name: str, name: str, value: Any) -> None:
+    """Log a variable change to comply with the DevSOP rules.
+
+    >>> log_variable_change("demo_func", "counter", 10)
+    """
+    LOGGER.debug("function=%s variable=%s value=%r", func_name, name, value)
+
+
+def log_branch(func_name: str, branch: str) -> None:
+    """Log which branch of conditional logic is being executed.
+
+    >>> log_branch("demo_func", "if_true")
+    """
+    LOGGER.debug("function=%s branch=%s", func_name, branch)
+
+
+def log_loop_iteration(func_name: str, loop_name: str, iteration: int) -> None:
+    """Log loop iteration counts to support replay-friendly diagnostics.
+
+    >>> log_loop_iteration("demo_func", "main", 3)
+    """
+    LOGGER.debug(
+        "function=%s loop=%s iteration=%d",
+        func_name,
+        loop_name,
+        iteration,
+    )

loopgraph-0.2.0/loopgraph/bus/__init__.py

@@ -0,0 +1,5 @@
+"""Event bus implementations."""
+
+from .eventbus import ErrorHandler, Event, EventBus, EventListener
+
+__all__ = ["ErrorHandler", "Event", "EventBus", "EventListener"]

loopgraph-0.2.0/loopgraph/bus/eventbus.py

@@ -0,0 +1,186 @@
+"""Asynchronous event bus implementation."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Coroutine, Dict, List, Optional
+
+from .._debug import (
+    log_branch,
+    log_loop_iteration,
+    log_parameter,
+    log_variable_change,
+)
+from ..core.types import EventType, NodeStatus
+
+EventListener = Callable[["Event"], Coroutine[Any, Any, None]]
+ErrorHandler = Callable[[Exception, "Event"], Coroutine[Any, Any, None]]
+
+
+@dataclass(frozen=True)
+class Event:
+    """Event emitted during workflow execution.
+
+    >>> evt = Event(
+    ...     id="evt-1",
+    ...     graph_id="graph-1",
+    ...     node_id="node-1",
+    ...     type=EventType.NODE_COMPLETED,
+    ... )
+    >>> evt.type
+    <EventType.NODE_COMPLETED: 'node_completed'>
+    """
+
+    id: str
+    graph_id: str
+    node_id: Optional[str]
+    type: EventType
+    payload: Any = None
+    timestamp: float = field(default_factory=lambda: time.time())
+    replay: bool = False
+    visit_count: Optional[int] = None
+    status: Optional[NodeStatus] = None
+
+
+class EventBus:
+    """Simple in-memory event bus.
+
+    >>> async def demo():
+    ...     bus = EventBus()
+    ...     received = []
+    ...
+    ...     async def listener(event: Event) -> None:
+    ...         received.append(event.id)
+    ...
+    ...     bus.subscribe(EventType.NODE_COMPLETED, listener)
+    ...     await bus.emit(
+    ...         Event(
+    ...             id="evt",
+    ...             graph_id="g",
+    ...             node_id="n",
+    ...             type=EventType.NODE_COMPLETED,
+    ...         )
+    ...     )
+    ...     return received
+    >>> asyncio.run(demo())
+    ['evt']
+    """
+
+    def __init__(self, on_error: Optional[ErrorHandler] = None) -> None:
+        """Initialize the event bus.
+
+        Args:
+            on_error: Optional async callback invoked when a listener raises an exception.
+                      Signature: async def handler(exc: Exception, event: Event) -> None
+                      If on_error itself raises, the exception propagates to the caller.
+        """
+        func_name = "EventBus.__init__"
+        log_parameter(func_name, on_error=on_error)
+        self._listeners: Dict[Optional[EventType], List[EventListener]] = {}
+        self._on_error = on_error
+        log_variable_change(func_name, "self._listeners", self._listeners)
+        log_variable_change(func_name, "self._on_error", self._on_error)
+
+    def subscribe(
+        self,
+        event_type: Optional[EventType],
+        listener: EventListener,
+    ) -> None:
+        """Register a listener for a specific event type or all events.
+
+        >>> bus = EventBus()
+        >>> async def noop(_event: Event) -> None:
+        ...     pass
+        >>> bus.subscribe(None, noop)
+        """
+        func_name = "EventBus.subscribe"
+        log_parameter(func_name, event_type=event_type, listener=listener)
+        listeners = self._listeners.setdefault(event_type, [])
+        log_variable_change(func_name, "listeners_before", list(listeners))
+        listeners.append(listener)
+        log_variable_change(func_name, "listeners_after", list(listeners))
+
+    def unsubscribe(
+        self,
+        event_type: Optional[EventType],
+        listener: EventListener,
+    ) -> None:
+        """Remove a listener from the bus if present.
+
+        >>> bus = EventBus()
+        >>> async def noop(_event: Event) -> None:
+        ...     pass
+        >>> bus.subscribe(None, noop)
+        >>> bus.unsubscribe(None, noop)
+        """
+        func_name = "EventBus.unsubscribe"
+        log_parameter(func_name, event_type=event_type, listener=listener)
+        listeners = self._listeners.get(event_type, [])
+        log_variable_change(func_name, "listeners_before", list(listeners))
+        if listener in listeners:
+            log_branch(func_name, "listener_present")
+            listeners.remove(listener)
+            log_variable_change(func_name, "listeners_after", list(listeners))
+        else:
+            log_branch(func_name, "listener_missing")
+
+    async def emit(self, event: Event) -> List[Any]:
+        """Emit an event to all registered listeners.
+
+        If a listener raises an exception and an on_error handler is configured,
+        the handler is invoked with the exception and event. If on_error raises,
+        the exception propagates to the caller.
+
+        >>> async def demo():
+        ...     bus = EventBus()
+        ...     events: List[str] = []
+        ...
+        ...     async def collector(evt: Event) -> None:
+        ...         events.append(evt.id)
+        ...
+        ...     bus.subscribe(None, collector)
+        ...     await bus.emit(
+        ...         Event(
+        ...             id="evt-1",
+        ...             graph_id="g",
+        ...             node_id=None,
+        ...             type=EventType.WORKFLOW_COMPLETED,
+        ...         )
+        ...     )
+        ...     return events
+        >>> asyncio.run(demo())
+        ['evt-1']
+        """
+        func_name = "EventBus.emit"
+        log_parameter(func_name, event=event)
+        listeners = list(self._listeners.get(event.type, []))
+        log_variable_change(func_name, "typed_listeners", listeners)
+        global_listeners = list(self._listeners.get(None, []))
+        log_variable_change(func_name, "global_listeners", global_listeners)
+        all_listeners: List[EventListener] = listeners + global_listeners
+        log_variable_change(func_name, "all_listeners", all_listeners)
+        if not all_listeners:
+            log_branch(func_name, "no_listeners")
+            return []
+        log_branch(func_name, "dispatch_listeners")
+        tasks: List[asyncio.Task[None]] = []
+        log_variable_change(func_name, "tasks", tasks)
+        for iteration, listener in enumerate(all_listeners):
+            log_loop_iteration(func_name, "listeners", iteration)
+            task = asyncio.create_task(listener(event))
+            log_variable_change(func_name, "task", task)
+            tasks.append(task)
+            log_variable_change(func_name, "tasks", list(tasks))
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        log_variable_change(func_name, "results", results)
+
+        # Invoke on_error handler for any exceptions
+        if self._on_error is not None:
+            for result in results:
+                if isinstance(result, Exception):
+                    log_branch(func_name, "on_error_invoked")
+                    await self._on_error(result, event)
+
+        return results

loopgraph-0.2.0/loopgraph/concurrency/__init__.py

@@ -0,0 +1,5 @@
+"""Concurrency policy definitions."""
+
+from .policies import ConcurrencyManager, PrioritySemaphorePolicy, SemaphorePolicy
+
+__all__ = ["ConcurrencyManager", "SemaphorePolicy", "PrioritySemaphorePolicy"]