orca-runtime-python 0.1.0__py3-none-any.whl

orca_runtime_python/__init__.py

@@ -0,0 +1,69 @@
+"""
+Orca Runtime Python
+
+A first-class Python async runtime for Orca state machines.
+"""
+
+from .types import (
+    StateDef,
+    Transition,
+    GuardDef,
+    ActionSignature,
+    EffectDef,
+    MachineDef,
+    StateValue,
+    Context,
+    Effect,
+    EffectResult,
+    EffectStatus,
+)
+
+from .bus import (
+    EventBus,
+    Event,
+    EventType,
+    get_event_bus,
+)
+
+from .machine import OrcaMachine
+
+from .parser import parse_orca_md, parse_orca_auto
+
+from .persistence import PersistenceAdapter, FilePersistence
+
+from .logging import LogSink, FileSink, ConsoleSink, MultiSink
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Types
+    "StateDef",
+    "Transition",
+    "GuardDef",
+    "ActionSignature",
+    "EffectDef",
+    "MachineDef",
+    "StateValue",
+    "Context",
+    "Effect",
+    "EffectResult",
+    "EffectStatus",
+    # Bus
+    "EventBus",
+    "Event",
+    "EventType",
+    "get_event_bus",
+    # Machine
+    "OrcaMachine",
+    # Parser
+    "parse_orca_md",
+    "parse_orca_auto",
+    # Persistence
+    "PersistenceAdapter",
+    "FilePersistence",
+    # Logging
+    "LogSink",
+    "FileSink",
+    "ConsoleSink",
+    "MultiSink",
+]

orca_runtime_python/bus.py

@@ -0,0 +1,227 @@
+"""
+Async event bus with pub/sub and request/response patterns.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Awaitable, Callable
+from uuid import uuid4
+
+from .types import Effect, EffectResult, EffectStatus
+
+
+class EventType(Enum):
+    """Standard Orca event types."""
+
+    # State machine events
+    STATE_CHANGED = "orca.state.changed"
+    TRANSITION_STARTED = "orca.transition.started"
+    TRANSITION_COMPLETED = "orca.transition.completed"
+    EFFECT_EXECUTING = "orca.effect.executing"
+    EFFECT_COMPLETED = "orca.effect.completed"
+    EFFECT_FAILED = "orca.effect.failed"
+    MACHINE_STARTED = "orca.machine.started"
+    MACHINE_STOPPED = "orca.machine.stopped"
+
+    # Workflow events
+    WORKFLOW_STATE_CHANGED = "workflow.state.changed"
+
+    # Agent events
+    AGENT_TASK_ASSIGNED = "agent.task.assigned"
+    AGENT_TASK_COMPLETED = "agent.task.completed"
+
+    # Scheduling events
+    SCHEDULING_QUERY = "scheduling.query"
+    SCHEDULING_QUERY_RESPONSE = "scheduling.query_response"
+
+
+@dataclass
+class Event:
+    """
+    Represents a typed event with correlation IDs and source tracking.
+    """
+    type: EventType
+    source: str
+    event_name: str | None = None  # Original event name for custom events
+    correlation_id: str | None = None
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        return f"Event({self.type.value}, source={self.source})"
+
+
+# Type alias for effect handlers
+EffectHandler = Callable[[Effect], Awaitable[EffectResult]]
+
+# Type alias for event handlers
+EventHandler = Callable[[Event], Awaitable[None]]
+
+
+class EventBus:
+    """
+    Async event bus with pub/sub and request/response patterns.
+
+    Supports:
+    - Subscribe/unsubscribe to event types
+    - Publish events to all subscribers
+    - Request/response pattern with correlation IDs
+    - Effect handler registration and execution
+    """
+
+    def __init__(self):
+        self._subscribers: dict[EventType, list[EventHandler]] = {}
+        self._effect_handlers: dict[str, EffectHandler] = {}
+        self._response_queues: dict[str, asyncio.Queue[Event]] = {}
+
+    def subscribe(self, event_type: EventType, handler: EventHandler) -> None:
+        """Subscribe a handler to an event type."""
+        if event_type not in self._subscribers:
+            self._subscribers[event_type] = []
+        if handler not in self._subscribers[event_type]:
+            self._subscribers[event_type].append(handler)
+
+    def unsubscribe(self, event_type: EventType, handler: EventHandler) -> None:
+        """Unsubscribe a handler from an event type."""
+        if event_type in self._subscribers:
+            if handler in self._subscribers[event_type]:
+                self._subscribers[event_type].remove(handler)
+
+    async def publish(self, event: Event) -> None:
+        """
+        Publish an event to all subscribers.
+
+        All handlers are executed concurrently with return_exceptions=True
+        so one handler's exception doesn't affect others.
+        """
+        if event.type in self._subscribers:
+            handlers = list(self._subscribers[event.type])
+            await asyncio.gather(
+                *[handler(event) for handler in handlers],
+                return_exceptions=True
+            )
+
+    def register_effect_handler(self, effect_type: str, handler: EffectHandler) -> None:
+        """
+        Register an effect handler for a specific effect type.
+
+        Effect handlers are async functions that receive an Effect
+        and return an EffectResult.
+        """
+        self._effect_handlers[effect_type] = handler
+
+    async def execute_effect(self, effect: Effect) -> EffectResult:
+        """
+        Execute an effect via registered handler.
+
+        Returns EffectResult with status SUCCESS or FAILURE.
+        """
+        if effect.type not in self._effect_handlers:
+            return EffectResult(
+                status=EffectStatus.FAILURE,
+                error=f"No handler registered for effect type: {effect.type}"
+            )
+
+        handler = self._effect_handlers[effect.type]
+        try:
+            return await handler(effect)
+        except Exception as e:
+            return EffectResult(
+                status=EffectStatus.FAILURE,
+                error=str(e)
+            )
+
+    async def request_response(
+        self,
+        request_type: EventType,
+        request_payload: dict[str, Any],
+        response_type: EventType,
+        correlation_id: str | None = None,
+        timeout: float = 5.0,
+        source: str = "orca",
+    ) -> Any:
+        """
+        Request/response pattern via event bus.
+
+        Publishes a request event and waits for a matching response
+        with the same correlation ID.
+
+        Args:
+            request_type: Event type for the request
+            request_payload: Data to send with request
+            response_type: Event type expected for response
+            correlation_id: Optional correlation ID (generated if not provided)
+            timeout: Seconds to wait for response
+            source: Source identifier for the request event
+
+        Returns:
+            The payload from the response event
+
+        Raises:
+            TimeoutError: If response not received within timeout
+        """
+        corr_id = correlation_id or str(uuid4())
+
+        response_queue: asyncio.Queue[Event] = asyncio.Queue()
+        self._response_queues[corr_id] = response_queue
+
+        async def response_handler(event: Event) -> None:
+            if event.correlation_id == corr_id:
+                await response_queue.put(event)
+
+        self.subscribe(response_type, response_handler)
+
+        try:
+            # Publish request
+            await self.publish(Event(
+                type=request_type,
+                source=source,
+                correlation_id=corr_id,
+                payload=request_payload
+            ))
+
+            # Wait for response
+            try:
+                response_event = await asyncio.wait_for(
+                    response_queue.get(),
+                    timeout=timeout
+                )
+                return response_event.payload
+            except asyncio.TimeoutError:
+                raise TimeoutError(
+                    f"Request {corr_id} timed out after {timeout}s"
+                )
+        finally:
+            self.unsubscribe(response_type, response_handler)
+            del self._response_queues[corr_id]
+
+    @property
+    def effect_handler_types(self) -> list[str]:
+        """List of registered effect handler types."""
+        return list(self._effect_handlers.keys())
+
+
+# Global event bus instance
+_bus: EventBus | None = None
+
+
+def get_event_bus() -> EventBus:
+    """
+    Get the global event bus instance.
+
+    Creates a new EventBus if one doesn't exist.
+    """
+    global _bus
+    if _bus is None:
+        _bus = EventBus()
+    return _bus
+
+
+def reset_event_bus() -> None:
+    """Reset the global event bus (useful for testing)."""
+    global _bus
+    _bus = None

orca_runtime_python/effects.py

@@ -0,0 +1,216 @@
+"""
+Effect system for Orca runtime.
+
+Provides effect types and utilities for async operations
+that can be executed by the runtime.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable
+
+from .types import Effect, EffectResult, EffectStatus
+
+
+# Type alias for effect handlers
+EffectHandler = Callable[[Effect], Awaitable[EffectResult]]
+
+
+@dataclass
+class EffectType:
+    """
+    Defines an effect type with its handler.
+    """
+    name: str
+    handler: EffectHandler
+
+    async def execute(self, payload: dict[str, Any]) -> EffectResult:
+        """Execute this effect with the given payload."""
+        effect = Effect(type=self.name, payload=payload)
+        return await self.handler(effect)
+
+
+class EffectRegistry:
+    """
+    Registry for effect types and handlers.
+
+    Allows registering effect handlers and creating effect instances.
+    """
+
+    def __init__(self):
+        self._handlers: dict[str, EffectHandler] = {}
+
+    def register(self, effect_type: str, handler: EffectHandler) -> None:
+        """Register a handler for an effect type."""
+        self._handlers[effect_type] = handler
+
+    def get_handler(self, effect_type: str) -> EffectHandler | None:
+        """Get the handler for an effect type."""
+        return self._handlers.get(effect_type)
+
+    def has_handler(self, effect_type: str) -> bool:
+        """Check if a handler is registered for an effect type."""
+        return effect_type in self._handlers
+
+    @property
+    def effect_types(self) -> list[str]:
+        """List all registered effect types."""
+        return list(self._handlers.keys())
+
+    async def execute(self, effect: Effect) -> EffectResult:
+        """Execute an effect using the registered handler."""
+        if effect.type not in self._handlers:
+            return EffectResult(
+                status=EffectStatus.FAILURE,
+                error=f"No handler registered for effect type: {effect.type}"
+            )
+
+        handler = self._handlers[effect.type]
+        try:
+            return await handler(effect)
+        except Exception as e:
+            return EffectResult(
+                status=EffectStatus.FAILURE,
+                error=str(e)
+            )
+
+
+# Common effect payload types
+
+@dataclass
+class NarrativeRequest:
+    """Request for narrative generation (LLM)."""
+    action: str  # look, move, take, etc.
+    context: dict[str, Any]
+    event: dict[str, Any] | None = None
+
+
+@dataclass
+class NarrativeResponse:
+    """Response from narrative generation."""
+    narrative: str
+    new_location: str | None = None
+
+
+@dataclass
+class MoveRequest:
+    """Request to move to a new location."""
+    direction: str
+    context: dict[str, Any]
+
+
+@dataclass
+class MoveResponse:
+    """Response from move operation."""
+    new_location: str
+    description: str
+    visited: bool = False
+
+
+@dataclass
+class SaveRequest:
+    """Request to save state."""
+    session_id: str
+
+
+@dataclass
+class SaveResponse:
+    """Response from save operation."""
+    saved: bool
+    timestamp: int
+
+
+@dataclass
+class LoadRequest:
+    """Request to load state."""
+    session_id: str
+
+
+@dataclass
+class LoadResponse:
+    """Response from load operation."""
+    loaded: bool
+    context: dict[str, Any]
+
+
+# Default effect handlers
+
+async def default_narrative_handler(effect: Effect) -> EffectResult:
+    """Default narrative handler for development/testing."""
+    payload = effect.payload
+
+    narrative = f"The world shifts around you... (action: {payload.get('action', 'unknown')})"
+
+    return EffectResult(
+        status=EffectStatus.SUCCESS,
+        data={
+            "narrative": narrative,
+            "new_location": payload.get("context", {}).get("current_location"),
+        }
+    )
+
+
+async def default_effect_handler(effect: Effect) -> EffectResult:
+    """Default handler that returns success with no data."""
+    return EffectResult(
+        status=EffectStatus.SUCCESS,
+        data=None
+    )
+
+
+# Decorator for creating effect handlers
+
+def effect_handler(effect_type: str):
+    """
+    Decorator to register an effect handler.
+
+    Usage:
+        @effect_handler("NarrativeRequest")
+        async def handle_narrative(effect: Effect) -> EffectResult:
+            # Process the effect
+            return EffectResult(status=EffectStatus.SUCCESS, data={...})
+    """
+    def decorator(handler: EffectHandler) -> EffectHandler:
+        # Store the effect type on the handler for later registration
+        handler._effect_type = effect_type  # type: ignore
+        return handler
+
+    return decorator
+
+
+def register_effect_handlers(
+    registry: EffectRegistry,
+    handlers: dict[str, EffectHandler] | None = None
+) -> None:
+    """
+    Register multiple effect handlers with a registry.
+
+    Args:
+        registry: EffectRegistry to register with
+        handlers: Dict mapping effect type names to handlers
+    """
+    if handlers:
+        for effect_type, handler in handlers.items():
+            registry.register(effect_type, handler)
+
+
+# Global registry
+_global_registry: EffectRegistry | None = None
+
+
+def get_effect_registry() -> EffectRegistry:
+    """Get the global effect registry."""
+    global _global_registry
+    if _global_registry is None:
+        _global_registry = EffectRegistry()
+        # Register default handlers
+        _global_registry.register("NarrativeRequest", default_narrative_handler)
+        _global_registry.register("Effect", default_effect_handler)
+    return _global_registry
+
+
+def reset_effect_registry() -> None:
+    """Reset the global effect registry."""
+    global _global_registry
+    _global_registry = None

orca_runtime_python/logging.py

@@ -0,0 +1,161 @@
+"""
+Pluggable log sinks for Orca machine audit trails.
+
+LogSink is a Protocol — any object implementing write/close can be used.
+Three sinks are bundled:
+
+  FileSink    — JSONL file, one entry per line, append-safe for resume
+  ConsoleSink — human-readable transitions printed to stdout
+  MultiSink   — fan-out to multiple sinks simultaneously
+
+Usage:
+    from orca_runtime_python import FileSink, ConsoleSink, MultiSink
+
+    sink = MultiSink(
+        FileSink("./runs/exp-001/audit.jsonl"),
+        ConsoleSink(),
+    )
+    await run_pipeline(machines, ctx, run_id="exp-001", log_sink=sink)
+    sink.close()
+
+Log entry format (dict written to each sink):
+    {
+        "ts":            "2026-03-27T10:15:32.123456Z",
+        "run_id":        "exp-001",
+        "machine":       "TrainingLab",
+        "event":         "DATA_READY",
+        "from":          "data_prep",
+        "to":            "hyper_search",
+        "context_delta": {"vocab_size": 65, "train_tokens": 900000}
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class LogSink(Protocol):
+    """Protocol for Orca audit log destinations."""
+
+    def write(self, entry: dict[str, Any]) -> None:
+        """Record a single log entry."""
+        ...
+
+    def close(self) -> None:
+        """Flush and release any held resources."""
+        ...
+
+
+class FileSink:
+    """
+    Appends log entries as newline-delimited JSON (JSONL) to a file.
+
+    Opens in append mode so resumed runs extend the same audit log
+    rather than overwriting it.
+
+    Example:
+        sink = FileSink("./runs/exp-001/audit.jsonl")
+        sink.write({"event": "DATA_READY", ...})
+        sink.close()
+    """
+
+    def __init__(self, path: str | Path):
+        self._path = Path(path)
+        self._f = None
+
+    def _ensure_open(self) -> None:
+        if self._f is None:
+            self._path.parent.mkdir(parents=True, exist_ok=True)
+            self._f = open(self._path, "a", encoding="utf-8")
+
+    def write(self, entry: dict[str, Any]) -> None:
+        self._ensure_open()
+        self._f.write(json.dumps(entry, default=str) + "\n")  # type: ignore[union-attr]
+        self._f.flush()  # type: ignore[union-attr]
+
+    def close(self) -> None:
+        if self._f is not None:
+            self._f.close()
+            self._f = None
+
+
+class ConsoleSink:
+    """
+    Prints a compact, human-readable line for each transition.
+
+    Format:
+        [HH:MM:SS] Machine  from → to  (EVENT)  key=val key=val
+    """
+
+    def __init__(self, file=None):
+        self._file = file or sys.stdout
+
+    def write(self, entry: dict[str, Any]) -> None:
+        ts = entry.get("ts", "")
+        time_part = ts[11:19] if len(ts) >= 19 else ts  # HH:MM:SS
+        machine = entry.get("machine", "")
+        from_s = entry.get("from", "?")
+        to_s = entry.get("to", "?")
+        event = entry.get("event", "")
+        delta = entry.get("context_delta", {})
+
+        delta_str = "  " + "  ".join(
+            f"{k}={v}" for k, v in delta.items()
+            if k != "error_message" or v
+        ) if delta else ""
+
+        event_str = f"  ({event})" if event else ""
+        print(
+            f"[{time_part}] {machine:<14} {from_s} → {to_s}{event_str}{delta_str}",
+            file=self._file,
+        )
+
+    def close(self) -> None:
+        pass
+
+
+class MultiSink:
+    """
+    Fan-out sink that writes each entry to multiple sinks.
+
+    Example:
+        sink = MultiSink(FileSink("audit.jsonl"), ConsoleSink())
+    """
+
+    def __init__(self, *sinks: LogSink):
+        self._sinks = list(sinks)
+
+    def write(self, entry: dict[str, Any]) -> None:
+        for sink in self._sinks:
+            sink.write(entry)
+
+    def close(self) -> None:
+        for sink in self._sinks:
+            sink.close()
+
+
+def _make_entry(
+    *,
+    run_id: str,
+    machine: str,
+    event: str,
+    from_state: str,
+    to_state: str,
+    context_delta: dict[str, Any],
+) -> dict[str, Any]:
+    """Build a standard log entry dict."""
+    return {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "run_id": run_id,
+        "machine": machine,
+        "event": event,
+        "from": from_state,
+        "to": to_state,
+        "context_delta": context_delta,
+    }