quartermaster-engine 0.0.1__py3-none-any.whl

quartermaster_engine/__init__.py

@@ -0,0 +1,75 @@
+"""quartermaster-engine: Execution engine for AI agent graphs."""
+
+from quartermaster_engine.context.execution_context import ExecutionContext
+from quartermaster_engine.context.node_execution import NodeExecution, NodeStatus
+from quartermaster_engine.events import (
+    FlowError,
+    FlowEvent,
+    FlowFinished,
+    NodeFinished,
+    NodeStarted,
+    TokenGenerated,
+    UserInputRequired,
+)
+from quartermaster_engine.memory.flow_memory import FlowMemory
+from quartermaster_engine.memory.persistent_memory import InMemoryPersistence, PersistentMemory
+from quartermaster_engine.messaging.context_manager import ContextManager
+from quartermaster_engine.messaging.message_router import MessageRouter
+from quartermaster_engine.runner.flow_runner import FlowRunner
+from quartermaster_engine.stores.base import ExecutionStore
+from quartermaster_engine.example_runner import run_graph
+from quartermaster_engine.stores.memory_store import InMemoryStore
+from quartermaster_engine.types import (
+    ErrorStrategy,
+    GraphEdge,
+    GraphNode,
+    Message,
+    MessageRole,
+    MessageType,
+    NodeType,
+    ThoughtType,
+    TraverseIn,
+    TraverseOut,
+)
+
+__all__ = [
+    # Context
+    "ExecutionContext",
+    "NodeExecution",
+    "NodeStatus",
+    # Types & Enums
+    "NodeType",
+    "TraverseIn",
+    "TraverseOut",
+    "ThoughtType",
+    "MessageType",
+    "ErrorStrategy",
+    "GraphNode",
+    "GraphEdge",
+    "Message",
+    "MessageRole",
+    # Events
+    "FlowEvent",
+    "NodeStarted",
+    "TokenGenerated",
+    "NodeFinished",
+    "FlowFinished",
+    "UserInputRequired",
+    "FlowError",
+    # Stores
+    "ExecutionStore",
+    "InMemoryStore",
+    # Runner
+    "FlowRunner",
+    # Memory
+    "FlowMemory",
+    "PersistentMemory",
+    "InMemoryPersistence",
+    # Messaging
+    "MessageRouter",
+    "ContextManager",
+    # Example runner
+    "run_graph",
+]
+
+__version__ = "0.1.0"

quartermaster_engine/context/__init__.py

@@ -0,0 +1,6 @@
+"""Execution context and node state tracking."""
+
+from quartermaster_engine.context.execution_context import ExecutionContext
+from quartermaster_engine.context.node_execution import NodeExecution, NodeStatus
+
+__all__ = ["ExecutionContext", "NodeExecution", "NodeStatus"]

quartermaster_engine/context/execution_context.py

@@ -0,0 +1,64 @@
+"""Execution context — the runtime state passed to each node during flow execution."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import UUID
+
+from quartermaster_engine.context.node_execution import NodeStatus
+from quartermaster_engine.types import AgentGraph, GraphNode, Message
+
+
+@dataclass
+class ExecutionContext:
+    """Runtime context for node execution.
+
+    Carries the full state needed by a node to execute: the graph definition,
+    current node reference, conversation history, flow-scoped memory, and
+    callbacks for streaming and status updates.
+    """
+
+    flow_id: UUID
+    node_id: UUID
+    graph: AgentGraph
+    current_node: GraphNode
+    messages: list[Message] = field(default_factory=list)
+    memory: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    # Execution state
+    status: NodeStatus = NodeStatus.PENDING
+    parent_context: ExecutionContext | None = None
+
+    # Callbacks for real-time streaming
+    on_message: Callable[[str], None] | None = None
+    on_status_change: Callable[[NodeStatus], None] | None = None
+    on_token: Callable[[str], None] | None = None
+
+    def get_meta(self, key: str, default: Any = None) -> Any:
+        """Get a value from the node's metadata, falling back to graph metadata."""
+        if key in self.current_node.metadata:
+            return self.current_node.metadata[key]
+        return self.metadata.get(key, default)
+
+    def set_meta(self, key: str, value: Any) -> None:
+        """Set a metadata value on this context."""
+        self.metadata[key] = value
+
+    def emit_token(self, token: str) -> None:
+        """Emit a streaming token if a callback is registered."""
+        if self.on_token:
+            self.on_token(token)
+
+    def emit_message(self, content: str) -> None:
+        """Emit a complete message if a callback is registered."""
+        if self.on_message:
+            self.on_message(content)
+
+    def update_status(self, status: NodeStatus) -> None:
+        """Update this context's status and fire the callback."""
+        self.status = status
+        if self.on_status_change:
+            self.on_status_change(status)

quartermaster_engine/context/node_execution.py

@@ -0,0 +1,84 @@
+"""Node execution state tracking."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+
+class NodeStatus(str, Enum):
+    """Lifecycle status of a node during flow execution."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    WAITING_USER = "waiting_user"
+    WAITING_TOOL = "waiting_tool"
+    FINISHED = "finished"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+    @property
+    def is_terminal(self) -> bool:
+        """Whether this status represents a completed state."""
+        return self in (NodeStatus.FINISHED, NodeStatus.FAILED, NodeStatus.SKIPPED)
+
+    @property
+    def is_active(self) -> bool:
+        """Whether this status represents an active (non-terminal) state."""
+        return not self.is_terminal and self != NodeStatus.PENDING
+
+
+@dataclass
+class NodeExecution:
+    """Tracks the execution state of a single node within a flow."""
+
+    node_id: UUID
+    status: NodeStatus = NodeStatus.PENDING
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    result: str | None = None
+    error: str | None = None
+    retry_count: int = 0
+    output_data: dict[str, Any] = field(default_factory=dict)
+
+    def start(self) -> None:
+        """Mark this node as running."""
+        self.status = NodeStatus.RUNNING
+        self.started_at = datetime.now(UTC)
+
+    def finish(self, result: str | None = None, output_data: dict[str, Any] | None = None) -> None:
+        """Mark this node as successfully finished."""
+        self.status = NodeStatus.FINISHED
+        self.finished_at = datetime.now(UTC)
+        self.result = result
+        if output_data:
+            self.output_data.update(output_data)
+
+    def fail(self, error: str) -> None:
+        """Mark this node as failed."""
+        self.status = NodeStatus.FAILED
+        self.finished_at = datetime.now(UTC)
+        self.error = error
+
+    def skip(self) -> None:
+        """Mark this node as skipped."""
+        self.status = NodeStatus.SKIPPED
+        self.finished_at = datetime.now(UTC)
+
+    def wait_for_user(self) -> None:
+        """Mark this node as waiting for user input."""
+        self.status = NodeStatus.WAITING_USER
+
+    def wait_for_tool(self) -> None:
+        """Mark this node as waiting for tool execution."""
+        self.status = NodeStatus.WAITING_TOOL
+
+    @property
+    def duration_seconds(self) -> float | None:
+        """Execution duration in seconds, or None if not yet finished."""
+        if self.started_at and self.finished_at:
+            return (self.finished_at - self.started_at).total_seconds()
+        return None

quartermaster_engine/dispatchers/__init__.py

@@ -0,0 +1,8 @@
+"""Task dispatchers — pluggable strategies for executing successor nodes."""
+
+from quartermaster_engine.dispatchers.async_dispatcher import AsyncDispatcher
+from quartermaster_engine.dispatchers.base import TaskDispatcher
+from quartermaster_engine.dispatchers.sync_dispatcher import SyncDispatcher
+from quartermaster_engine.dispatchers.thread_dispatcher import ThreadDispatcher
+
+__all__ = ["AsyncDispatcher", "TaskDispatcher", "SyncDispatcher", "ThreadDispatcher"]

quartermaster_engine/dispatchers/async_dispatcher.py

@@ -0,0 +1,93 @@
+"""Async dispatcher — executes nodes in parallel using asyncio.create_task.
+
+Provides concurrent execution for branches using asyncio tasks. Ideal for
+I/O-bound node execution in async web applications (FastAPI, aiohttp, etc.).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from uuid import UUID
+
+
+class AsyncDispatcher:
+    """Execute nodes concurrently using asyncio tasks.
+
+    Parallel branches are dispatched as asyncio tasks via ``asyncio.create_task``.
+    ``wait_all()`` awaits all pending tasks. Because the underlying
+    ``execute_fn`` is synchronous (it comes from FlowRunner), each call is
+    wrapped in ``loop.run_in_executor`` so the event loop is never blocked.
+    """
+
+    def __init__(self) -> None:
+        self._tasks: list[asyncio.Task[None]] = []
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    def _get_loop(self) -> asyncio.AbstractEventLoop:
+        """Return the running event loop, or create a new one if needed."""
+        if self._loop is None or self._loop.is_closed():
+            try:
+                self._loop = asyncio.get_running_loop()
+            except RuntimeError:
+                self._loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(self._loop)
+        return self._loop
+
+    def dispatch(
+        self,
+        flow_id: UUID,
+        node_id: UUID,
+        execute_fn: Callable[[UUID, UUID], None],
+    ) -> None:
+        """Dispatch a node for execution as an asyncio task.
+
+        The synchronous *execute_fn* is scheduled on the event loop's default
+        executor so it does not block the loop.
+
+        Args:
+            flow_id: The flow this node belongs to.
+            node_id: The node to execute.
+            execute_fn: A callable that executes the node — signature (flow_id, node_id).
+        """
+        loop = self._get_loop()
+
+        async def _run() -> None:
+            await loop.run_in_executor(None, execute_fn, flow_id, node_id)
+
+        task = asyncio.ensure_future(_run(), loop=loop)
+        self._tasks.append(task)
+
+    def wait_all(self) -> None:
+        """Block until all dispatched tasks have completed.
+
+        Gathers all pending asyncio tasks and re-raises any exceptions
+        that occurred during branch execution.
+        """
+        if not self._tasks:
+            return
+
+        loop = self._get_loop()
+
+        async def _gather() -> None:
+            results = await asyncio.gather(*self._tasks, return_exceptions=True)
+            exceptions = [r for r in results if isinstance(r, Exception)]
+            self._tasks.clear()
+            if exceptions:
+                raise ExceptionGroup("Errors in async branches", exceptions)
+
+        if loop.is_running():
+            # We are inside an async context — schedule and block via a helper
+            import concurrent.futures
+
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                future = pool.submit(asyncio.run, _gather())
+                future.result()
+        else:
+            loop.run_until_complete(_gather())
+
+    def shutdown(self) -> None:
+        """Cancel any remaining tasks and clean up resources."""
+        for task in self._tasks:
+            task.cancel()
+        self._tasks.clear()

quartermaster_engine/dispatchers/base.py

@@ -0,0 +1,41 @@
+"""TaskDispatcher protocol — pluggable execution strategy for successor nodes."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Protocol
+from uuid import UUID
+
+
+class TaskDispatcher(Protocol):
+    """Protocol for dispatching node execution tasks.
+
+    Implementations control how successor nodes are executed:
+    synchronously (in-process), via threads, asyncio, or external task queues.
+    """
+
+    def dispatch(
+        self,
+        flow_id: UUID,
+        node_id: UUID,
+        execute_fn: Callable[[UUID, UUID], None],
+    ) -> None:
+        """Dispatch a node for execution.
+
+        Args:
+            flow_id: The flow this node belongs to.
+            node_id: The node to execute.
+            execute_fn: A callable that executes the node — signature (flow_id, node_id).
+        """
+        ...
+
+    def wait_all(self) -> None:
+        """Block until all dispatched tasks have completed.
+
+        Called at synchronization points (e.g., merge nodes) and at flow end.
+        """
+        ...
+
+    def shutdown(self) -> None:
+        """Clean up resources. Called when the flow runner is done."""
+        ...

quartermaster_engine/dispatchers/sync_dispatcher.py

@@ -0,0 +1,31 @@
+"""Synchronous dispatcher — executes nodes immediately in the current thread.
+
+Simple, predictable, and great for testing. No true parallelism.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from uuid import UUID
+
+
+class SyncDispatcher:
+    """Execute nodes synchronously in the calling thread.
+
+    This is the simplest dispatcher. Successor nodes are executed one at a time
+    in the order they appear. No parallelism, but no concurrency issues either.
+    """
+
+    def dispatch(
+        self,
+        flow_id: UUID,
+        node_id: UUID,
+        execute_fn: Callable[[UUID, UUID], None],
+    ) -> None:
+        execute_fn(flow_id, node_id)
+
+    def wait_all(self) -> None:
+        pass  # Nothing to wait for — everything is already done
+
+    def shutdown(self) -> None:
+        pass  # No resources to clean up

quartermaster_engine/dispatchers/thread_dispatcher.py

@@ -0,0 +1,48 @@
+"""Thread-based dispatcher — executes nodes in parallel using a thread pool.
+
+Provides true parallelism for branches. Suitable for I/O-bound node execution
+(LLM API calls, tool invocations) which is the common case for agent graphs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from concurrent.futures import Future, ThreadPoolExecutor
+from uuid import UUID
+
+
+class ThreadDispatcher:
+    """Execute nodes in parallel using a thread pool.
+
+    Parallel branches are submitted to a ThreadPoolExecutor.
+    `wait_all()` blocks until all pending tasks complete.
+    """
+
+    def __init__(self, max_workers: int = 4) -> None:
+        self._pool = ThreadPoolExecutor(max_workers=max_workers)
+        self._futures: list[Future[None]] = []
+
+    def dispatch(
+        self,
+        flow_id: UUID,
+        node_id: UUID,
+        execute_fn: Callable[[UUID, UUID], None],
+    ) -> None:
+        future = self._pool.submit(execute_fn, flow_id, node_id)
+        self._futures.append(future)
+
+    def wait_all(self) -> None:
+        """Block until all dispatched tasks complete, then collect exceptions."""
+        exceptions: list[Exception] = []
+        for future in self._futures:
+            try:
+                future.result()
+            except Exception as e:
+                exceptions.append(e)
+        self._futures.clear()
+        if exceptions:
+            raise ExceptionGroup("Errors in parallel branches", exceptions)
+
+    def shutdown(self) -> None:
+        self._pool.shutdown(wait=True)
+        self._futures.clear()

quartermaster_engine/events.py

@@ -0,0 +1,68 @@
+"""Flow execution events for real-time streaming."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import UUID
+
+from quartermaster_engine.types import NodeType
+
+
+@dataclass
+class FlowEvent:
+    """Base class for all flow execution events."""
+
+    flow_id: UUID
+
+
+@dataclass
+class NodeStarted(FlowEvent):
+    """Emitted when a node begins execution."""
+
+    node_id: UUID = field(default_factory=lambda: UUID(int=0))
+    node_type: NodeType = NodeType.START
+    node_name: str = ""
+
+
+@dataclass
+class TokenGenerated(FlowEvent):
+    """Emitted for each streaming token from an LLM node."""
+
+    node_id: UUID = field(default_factory=lambda: UUID(int=0))
+    token: str = ""
+
+
+@dataclass
+class NodeFinished(FlowEvent):
+    """Emitted when a node completes execution."""
+
+    node_id: UUID = field(default_factory=lambda: UUID(int=0))
+    result: str = ""
+    output_data: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class FlowFinished(FlowEvent):
+    """Emitted when the entire flow completes."""
+
+    final_output: str = ""
+    output_data: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class UserInputRequired(FlowEvent):
+    """Emitted when a node is waiting for user input."""
+
+    node_id: UUID = field(default_factory=lambda: UUID(int=0))
+    prompt: str = ""
+    options: list[str] = field(default_factory=list)
+
+
+@dataclass
+class FlowError(FlowEvent):
+    """Emitted when a node fails."""
+
+    node_id: UUID = field(default_factory=lambda: UUID(int=0))
+    error: str = ""
+    recoverable: bool = False