loopgraph 0.2.0__py3-none-any.whl

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/_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/bus/__init__.py

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

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/concurrency/__init__.py

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

loopgraph/concurrency/policies.py

@@ -0,0 +1,181 @@
+"""Concurrency control policies."""
+
+from __future__ import annotations
+
+import asyncio
+import heapq
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from typing import AsyncContextManager, AsyncIterator, List, Protocol
+
+from .._debug import log_branch, log_parameter, log_variable_change
+
+
+class ConcurrencyManager(Protocol):
+    """Protocol describing a priority-aware concurrency controller."""
+
+    def slot(self, key: str, priority: int = 0) -> AsyncContextManager[None]:
+        """Acquire a concurrency slot honoring the provided priority."""
+        ...
+
+
+class SemaphorePolicy(ConcurrencyManager):
+    """Manage shared concurrency with an asyncio semaphore.
+
+    >>> async def demo():
+    ...     policy = SemaphorePolicy(limit=2)
+    ...     async with policy.slot("worker", priority=0):
+    ...         return policy.available_permits
+    >>> import asyncio
+    >>> asyncio.run(demo())
+    1
+    """
+
+    def __init__(self, limit: int) -> None:
+        func_name = "SemaphorePolicy.__init__"
+        log_parameter(func_name, limit=limit)
+        if limit <= 0:
+            log_branch(func_name, "invalid_limit")
+            raise ValueError("limit must be positive")
+        log_branch(func_name, "valid_limit")
+        self._limit = limit
+        log_variable_change(func_name, "self._limit", self._limit)
+        self._semaphore = asyncio.Semaphore(limit)
+        log_variable_change(func_name, "self._semaphore", self._semaphore)
+
+    @property
+    def available_permits(self) -> int:
+        """Return currently available semaphore permits.
+
+        >>> policy = SemaphorePolicy(limit=1)
+        >>> policy.available_permits
+        1
+        """
+
+        func_name = "SemaphorePolicy.available_permits"
+        log_parameter(func_name)
+        permits = int(getattr(self._semaphore, "_value", 0))
+        log_variable_change(func_name, "permits", permits)
+        return permits
+
+    def slot(self, key: str, priority: int = 0) -> AsyncContextManager[None]:
+        """Acquire a semaphore slot for the duration of the context."""
+
+        @asynccontextmanager
+        async def _slot() -> AsyncIterator[None]:
+            func_name = "SemaphorePolicy.slot"
+            log_parameter(func_name, key=key, priority=priority)
+            await self._semaphore.acquire()
+            log_variable_change(
+                func_name, "permits_after_acquire", self.available_permits
+            )
+            try:
+                log_branch(func_name, "enter_context")
+                yield
+            finally:
+                log_branch(func_name, "exit_context")
+                self._semaphore.release()
+                log_variable_change(
+                    func_name, "permits_after_release", self.available_permits
+                )
+
+        return _slot()
+
+
+@dataclass(order=True)
+class _PriorityEntry:
+    priority: int
+    order: int
+    key: str = field(compare=False)
+
+
+class PrioritySemaphorePolicy(ConcurrencyManager):
+    """Semaphore implementation that releases slots in priority order.
+
+    >>> async def demo():
+    ...     policy = PrioritySemaphorePolicy(limit=1)
+    ...     order: List[str] = []
+    ...
+    ...     async def worker(name: str, priority: int, delay: float = 0.0) -> None:
+    ...         await asyncio.sleep(delay)
+    ...         async with policy.slot(name, priority=priority):
+    ...             order.append(name)
+    ...
+    ...     await asyncio.gather(
+    ...         worker("low", priority=10, delay=0.01),
+    ...         worker("high", priority=0, delay=0.0),
+    ...     )
+    ...     return order
+    >>> import asyncio
+    >>> asyncio.run(demo())
+    ['high', 'low']
+    """
+
+    def __init__(self, limit: int) -> None:
+        func_name = "PrioritySemaphorePolicy.__init__"
+        log_parameter(func_name, limit=limit)
+        if limit <= 0:
+            log_branch(func_name, "invalid_limit")
+            raise ValueError("limit must be positive")
+        log_branch(func_name, "valid_limit")
+        self._limit = limit
+        log_variable_change(func_name, "self._limit", self._limit)
+        self._available = limit
+        log_variable_change(func_name, "self._available", self._available)
+        self._queue: List[_PriorityEntry] = []
+        log_variable_change(func_name, "self._queue", self._queue)
+        self._order = 0
+        log_variable_change(func_name, "self._order", self._order)
+        self._condition = asyncio.Condition()
+        log_variable_change(func_name, "self._condition", self._condition)
+
+    def slot(self, key: str, priority: int = 0) -> AsyncContextManager[None]:
+        """Acquire a slot honoring the lowest priority value first."""
+
+        @asynccontextmanager
+        async def _slot() -> AsyncIterator[None]:
+            func_name = "PrioritySemaphorePolicy.slot"
+            log_parameter(func_name, key=key, priority=priority)
+            entry = _PriorityEntry(priority=priority, order=self._order, key=key)
+            self._order += 1
+            log_variable_change(func_name, "entry", entry)
+            async with self._condition:
+                heapq.heappush(self._queue, entry)
+                log_variable_change(func_name, "queue", list(self._queue))
+                while not self._can_acquire(entry):
+                    log_branch(func_name, "wait_for_turn")
+                    await self._condition.wait()
+                log_branch(func_name, "acquired_priority_slot")
+                self._available -= 1
+                heapq.heappop(self._queue)
+                log_variable_change(func_name, "self._available", self._available)
+            try:
+                log_branch(func_name, "enter_context")
+                yield
+            finally:
+                async with self._condition:
+                    log_branch(func_name, "release_slot")
+                    self._available += 1
+                    log_variable_change(func_name, "self._available", self._available)
+                    self._condition.notify_all()
+
+        return _slot()
+
+    def _can_acquire(self, entry: _PriorityEntry) -> bool:
+        """Return True if the entry can take a slot."""
+
+        func_name = "PrioritySemaphorePolicy._can_acquire"
+        log_parameter(func_name, entry=entry)
+        if self._available <= 0:
+            log_branch(func_name, "no_available_permits")
+            return False
+        if not self._queue:
+            log_branch(func_name, "queue_empty")
+            return False
+        head = self._queue[0]
+        log_variable_change(func_name, "head", head)
+        if head is not entry:
+            log_branch(func_name, "not_head_of_queue")
+            return False
+        log_branch(func_name, "can_acquire")
+        return True

loopgraph/core/__init__.py

@@ -0,0 +1,18 @@
+"""Core domain models for LoopGraph."""
+
+from .graph import Edge, Graph, Node
+from .state import ExecutionState, NodeRuntimeState, NodeVisit
+from .types import EventType, NodeKind, NodeStatus, VisitOutcome
+
+__all__ = [
+    "Edge",
+    "Graph",
+    "Node",
+    "ExecutionState",
+    "NodeRuntimeState",
+    "NodeKind",
+    "EventType",
+    "NodeStatus",
+    "NodeVisit",
+    "VisitOutcome",
+]