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

orca_runtime_python/persistence.py

@@ -0,0 +1,83 @@
+"""
+Pluggable persistence adapters for Orca machine state.
+
+PersistenceAdapter is a Protocol — any object implementing save/load/exists
+can be used. FilePersistence is the bundled default (zero extra dependencies).
+
+Usage:
+    from orca_runtime_python import FilePersistence
+
+    fp = FilePersistence("./runs")
+    await run_pipeline(machines, ctx, persistence=fp, run_id="exp-001")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PersistenceAdapter(Protocol):
+    """
+    Protocol for Orca machine state persistence.
+
+    Implementations must support three operations keyed by run_id:
+    save, load (returns None if not found), and exists.
+    """
+
+    def save(self, run_id: str, snapshot: dict[str, Any]) -> None:
+        """Persist snapshot under run_id. Overwrites any prior snapshot."""
+        ...
+
+    def load(self, run_id: str) -> dict[str, Any] | None:
+        """Return the snapshot for run_id, or None if it doesn't exist."""
+        ...
+
+    def exists(self, run_id: str) -> bool:
+        """Return True if a snapshot exists for run_id."""
+        ...
+
+
+class FilePersistence:
+    """
+    File-based persistence adapter.
+
+    Snapshots are stored as JSON files under base_dir:
+        {base_dir}/{run_id}.json
+
+    Writes are atomic: the file is written to a .tmp sibling and then
+    renamed, so a crash mid-write leaves the previous snapshot intact.
+
+    Example:
+        fp = FilePersistence("./runs")
+        fp.save("exp-001", machine.snapshot())
+        snap = fp.load("exp-001")   # dict or None
+    """
+
+    def __init__(self, base_dir: str | Path):
+        self._base = Path(base_dir)
+
+    def _path(self, run_id: str) -> Path:
+        return self._base / f"{run_id}.json"
+
+    def save(self, run_id: str, snapshot: dict[str, Any]) -> None:
+        """Write snapshot atomically. Creates base_dir if needed."""
+        self._base.mkdir(parents=True, exist_ok=True)
+        target = self._path(run_id)
+        tmp = target.with_suffix(".tmp")
+        tmp.write_text(json.dumps(snapshot, indent=2, default=str))
+        os.replace(tmp, target)
+
+    def load(self, run_id: str) -> dict[str, Any] | None:
+        """Return snapshot dict, or None if run_id has no saved state."""
+        path = self._path(run_id)
+        if not path.exists():
+            return None
+        return json.loads(path.read_text())
+
+    def exists(self, run_id: str) -> bool:
+        """True if a snapshot exists for run_id."""
+        return self._path(run_id).exists()

orca_runtime_python/types.py

@@ -0,0 +1,279 @@
+"""
+Core type definitions for Orca runtime.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, TypedDict
+
+
+# Context type - represents the machine's state
+Context = dict[str, Any]
+
+
+@dataclass
+class RegionDef:
+    """Region definition inside a parallel state."""
+    name: str
+    states: list[StateDef] = field(default_factory=list)
+
+
+@dataclass
+class ParallelDef:
+    """Parallel regions definition."""
+    regions: list[RegionDef] = field(default_factory=list)
+    sync: str | None = None  # all-final, any-final, custom
+
+
+@dataclass
+class InvokeDef:
+    """Machine invocation definition."""
+    machine: str
+    input: dict[str, str] | None = None
+    on_done: str | None = None
+    on_error: str | None = None
+
+
+@dataclass
+class StateDef:
+    """State definition in an Orca machine."""
+    name: str
+    is_initial: bool = False
+    is_final: bool = False
+    on_entry: str | None = None
+    on_exit: str | None = None
+    on_done: str | None = None
+    description: str | None = None
+    contains: list[StateDef] = field(default_factory=list)
+    parallel: ParallelDef | None = None
+    parent: str | None = None
+    timeout: dict[str, str] | None = None  # {duration, target}
+    ignored_events: list[str] = field(default_factory=list)
+    invoke: InvokeDef | None = None
+
+
+@dataclass
+class Transition:
+    """Transition between states."""
+    source: str
+    event: str
+    target: str
+    guard: str | None = None
+    action: str | None = None
+
+
+@dataclass
+class GuardDef:
+    """Guard condition definition."""
+    name: str
+    expression: GuardExpression
+
+
+@dataclass
+class ActionSignature:
+    """Action function signature."""
+    name: str
+    parameters: list[str]
+    return_type: str
+    has_effect: bool = False
+    effect_type: str | None = None
+
+
+@dataclass
+class EffectDef:
+    """Effect type declaration from the ## effects section."""
+    name: str
+    input: str   # type description (e.g. '{ cmd: string, cwd: string }')
+    output: str  # type description (e.g. '{ exit_code: int, stdout: string }')
+
+
+@dataclass
+class MachineDef:
+    """Complete Orca machine definition."""
+    name: str
+    context: dict[str, Any]
+    events: list[str]
+    states: list[StateDef]
+    transitions: list[Transition]
+    guards: dict[str, GuardExpression] = field(default_factory=dict)
+    actions: list[ActionSignature] = field(default_factory=list)
+    effects: list[EffectDef] = field(default_factory=list)
+
+
+class GuardExpression:
+    """Union type for guard expressions."""
+    pass
+
+
+@dataclass
+class GuardTrue(GuardExpression):
+    """True literal guard."""
+    pass
+
+
+@dataclass
+class GuardFalse(GuardExpression):
+    """False literal guard."""
+    pass
+
+
+@dataclass
+class GuardCompare(GuardExpression):
+    """Comparison guard: left op right"""
+    op: str  # eq, ne, lt, gt, le, ge
+    left: VariableRef
+    right: ValueRef
+
+
+@dataclass
+class GuardAnd(GuardExpression):
+    """And guard: left and right"""
+    left: GuardExpression
+    right: GuardExpression
+
+
+@dataclass
+class GuardOr(GuardExpression):
+    """Or guard: left or right"""
+    left: GuardExpression
+    right: GuardExpression
+
+
+@dataclass
+class GuardNot(GuardExpression):
+    """Not guard: not expr"""
+    expr: GuardExpression
+
+
+@dataclass
+class GuardNullcheck(GuardExpression):
+    """Null check guard: expr is (not) null"""
+    expr: VariableRef
+    is_null: bool
+
+
+@dataclass
+class VariableRef:
+    """Variable path reference."""
+    path: list[str]
+
+
+@dataclass
+class ValueRef:
+    """Value literal reference."""
+    type: str  # string, number, boolean, null
+    value: str | int | float | bool | None
+
+
+@dataclass
+class Effect:
+    """Represents an effect (async operation) to be executed."""
+    type: str
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class EffectResult:
+    """Result of an effect execution."""
+    status: EffectStatus
+    data: Any = None
+    error: str | None = None
+
+
+class EffectStatus:
+    """Effect execution status."""
+    SUCCESS = "success"
+    FAILURE = "failure"
+
+
+class StateValue:
+    """
+    Represents the current state of a machine.
+    Supports both simple (string) and compound (nested) states.
+    """
+
+    def __init__(self, value: str | dict[str, Any]):
+        self.value = value
+
+    def __str__(self) -> str:
+        if isinstance(self.value, str):
+            return self.value
+        return self._format_compound()
+
+    def __repr__(self) -> str:
+        return f"StateValue({self.value!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, StateValue):
+            return self.value == other.value
+        if isinstance(other, str):
+            return self.value == other
+        if isinstance(other, dict):
+            return self.value == other
+        return False
+
+    def _format_compound(self) -> str:
+        """Format compound state as dot-notation string."""
+        if isinstance(self.value, str):
+            return self.value
+
+        def format_recursive(d: dict[str, Any], prefix: str = "") -> str:
+            parts = []
+            for key, val in d.items():
+                if isinstance(val, dict) and val:
+                    # Non-empty nested dict, recurse deeper
+                    parts.append(format_recursive(val, prefix + key + "."))
+                else:
+                    # Empty dict or non-dict - key is a leaf state
+                    parts.append(prefix + key)
+            return ", ".join(parts) if parts else str(d)
+
+        return format_recursive(self.value)
+
+    def is_compound(self) -> bool:
+        """Check if this is a compound (nested) state."""
+        return isinstance(self.value, dict)
+
+    def leaf(self) -> str:
+        """Get the leaf state name from compound state."""
+        if isinstance(self.value, str):
+            return self.value
+        if isinstance(self.value, dict):
+            # Recursively find the deepest state
+            for key, val in self.value.items():
+                if isinstance(val, dict) and val:
+                    # Non-empty nested dict, recurse
+                    result = StateValue(val).leaf()
+                    if result:
+                        return result
+                else:
+                    # Empty dict or non-dict value - 'key' is the leaf
+                    return key
+        return str(self.value)
+
+    def leaves(self) -> list[str]:
+        """Get all leaf state names (one per active region in parallel states)."""
+        if isinstance(self.value, str):
+            return [self.value]
+
+        result: list[str] = []
+
+        def collect_leaves(obj: dict[str, Any]) -> None:
+            for key, val in obj.items():
+                if isinstance(val, dict) and val:
+                    collect_leaves(val)
+                else:
+                    result.append(key)
+
+        if isinstance(self.value, dict):
+            collect_leaves(self.value)
+        return result if result else [str(self.value)]
+
+    def parent_names(self) -> list[str]:
+        """Get all parent state names (for nested states)."""
+        if isinstance(self.value, str):
+            return []
+        if isinstance(self.value, dict):
+            return list(self.value.keys())
+        return []

orca_runtime_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: orca-runtime-python
+Version: 0.1.0
+Summary: Python async runtime for Orca state machines
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/orca-lang/orca-lang
+Project-URL: Repository, https://github.com/orca-lang/orca-lang-python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+
+# Orca Runtime Python
+
+A first-class Python async runtime for [Orca](https://github.com/orca-lang/orca-lang) state machines.
+
+## Overview
+
+Orca is a state machine language designed for LLM code generation. This package provides a Python runtime that executes Orca machine definitions with:
+
+- **Async-first** - Native `async/await` throughout
+- **Event bus integration** - Decoupled pub/sub for agentic systems
+- **Effect system** - Typed async operations with handler registration
+- **Hierarchical states** - Nested/compound state support
+
+## Installation
+
+```bash
+pip install orca-runtime-python
+```
+
+## Quick Start
+
+```python
+import asyncio
+from orca_runtime_python import (
+    parse_orca,
+    OrcaMachine,
+    get_event_bus,
+)
+
+# Define an Orca machine
+orca_source = """
+machine OrderProcessor
+
+context {
+    order_id: ""
+    status: "pending"
+}
+
+state pending [initial] "Order received"
+state fulfilled [final] "Order complete"
+
+transitions {
+    pending + ORDER_PLACED -> pending
+    pending + ORDER_FULFILLED -> fulfilled
+}
+"""
+
+async def main():
+    # Parse and create machine
+    machine_def = parse_orca(orca_source)
+    machine = OrcaMachine(machine_def)
+
+    # Register effect handlers
+    bus = get_event_bus()
+    bus.register_effect_handler("Effect", lambda e: EffectResult(
+        status="success", data=e.payload
+    ))
+
+    # Start and run
+    await machine.start()
+    print(f"Initial state: {machine.state}")
+
+    await machine.send("ORDER_FULFILLED")
+    print(f"After event: {machine.state}")
+
+    await machine.stop()
+
+asyncio.run(main())
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        OrcaMachine                               │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
+│  │ State Store  │  │ Transition   │  │ Effect Executor      │  │
+│  │ (current)    │  │ Evaluator    │  │ (async handlers)     │  │
+│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
+│          │                │                      │               │
+│          └────────────────┼──────────────────────┘               │
+│                           ▼                                      │
+│                  ┌──────────────────┐                           │
+│                  │   EventBus       │  (pub/sub)                 │
+│                  └──────────────────┘                           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### OrcaMachine
+
+The main runtime class that executes state machines:
+
+```python
+machine = OrcaMachine(
+    definition=machine_def,
+    event_bus=get_event_bus(),
+    context={"order_id": "123"},
+    on_transition=lambda old, new: print(f"{old} -> {new}"),
+)
+```
+
+### EventBus
+
+Async event bus with pub/sub and request/response:
+
+```python
+bus = get_event_bus()
+
+# Subscribe to events
+bus.subscribe(EventType.STATE_CHANGED, handler)
+
+# Publish events
+await bus.publish(Event(
+    type=EventType.STATE_CHANGED,
+    source="OrderProcessor",
+    payload={"from": "pending", "to": "fulfilled"},
+))
+
+# Request/response pattern
+response = await bus.request_response(
+    request_type=EventType.SCHEDULING_QUERY,
+    request_payload={"type": "availability"},
+    response_type=EventType.SCHEDULING_QUERY_RESPONSE,
+)
+```
+
+### Effect Handlers
+
+Register async handlers for effect types:
+
+```python
+async def handle_narrative(effect: Effect) -> EffectResult:
+    narrative = await generate_narrative(effect.payload)
+    return EffectResult(status="success", data={"narrative": narrative})
+
+bus.register_effect_handler("NarrativeRequest", handle_narrative)
+```
+
+## Orca DSL Syntax
+
+```orca
+machine GameEngine
+
+context {
+    health: int = 100
+    inventory: string[]
+}
+
+events {
+    start_game
+    attack
+    heal
+}
+
+state idle [initial] {
+    description: "Waiting for player input"
+}
+
+state combat {
+    description: "In combat"
+
+    state fighting [initial] {
+        description: "Actively fighting"
+    }
+
+    state defending {
+        description: "Blocking attacks"
+    }
+}
+
+state game_over [final] {
+    description: "Game ended"
+}
+
+guards {
+    can_heal: ctx.health < 100
+}
+
+transitions {
+    idle + start_game -> combat : start_combat
+    combat + attack -> combat : resolve_attack
+    combat + heal [can_heal] -> combat : apply_heal
+    combat + attack [health <= 0] -> game_over : end_game
+}
+
+actions {
+    start_combat: (ctx: Context) -> Context
+    resolve_attack: (ctx: Context) -> Context + Effect<DamageRequest>
+    apply_heal: (ctx: Context) -> Context
+    end_game: (ctx: Context) -> Context
+}
+```
+
+## Hierarchy
+
+```
+orca-runtime-python/
+├── orca_runtime_python/    # Main package
+│   ├── __init__.py
+│   ├── types.py            # Core types
+│   ├── parser.py           # DSL parser
+│   ├── machine.py          # OrcaMachine runtime
+│   ├── bus.py              # EventBus
+│   └── effects.py          # Effect system
+├── pyproject.toml
+└── README.md
+```
+
+## Relationship to Other Implementations
+
+| Package | Language | Purpose |
+|---------|----------|---------|
+| `orca` (npm) | TypeScript/JS | Core implementation (parser, verifier, compiler) |
+| `orca-runtime-python` | Python | Python async runtime |
+
+The Orca language is defined once and implemented across platforms. The Python runtime executes machines compiled from Orca DSL.
+
+## License
+
+Apache 2.0

orca_runtime_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+orca_runtime_python/__init__.py,sha256=RgEnSjy5mJO_M6_3exaoWmmEK_5aXYPRMS82naWcebk,1139
+orca_runtime_python/bus.py,sha256=kCdMwm3O97wlX5hr3_aK-YkhABO7Z0M-eaYPYJAIa9g,7171
+orca_runtime_python/effects.py,sha256=eAkm2JdHSH5wUm8ZQjBf7ncgMI1iw7xq9bKi5X1AJEM,5649
+orca_runtime_python/logging.py,sha256=Bnw_PCGlMQaDbti3UNMudhj0RcOckF_7YYt_5yWatGY,4360
+orca_runtime_python/machine.py,sha256=6gccjFkD96Wpzo1VWXGTbS7gkcIzdu3w88ZTu1ey_C8,33126
+orca_runtime_python/parser.py,sha256=wu9Dlv7O7xOurRr3--lO5X-v57LkVvkbtAfcc3ez8cg,30714
+orca_runtime_python/persistence.py,sha256=lsQlvGXPelZ5u2Ote-OegtmE6Rk10fa-qj9Dkg-zl9E,2590
+orca_runtime_python/types.py,sha256=YlYcyvGHI9myHq5XDinGTjPIKadyG4kuGQvMPtU0eCo,7232
+orca_runtime_python-0.1.0.dist-info/METADATA,sha256=HUc6tUpkq4KfD0Qs1AjP6MWpHzW72gljNrABKBj4sCs,7164
+orca_runtime_python-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+orca_runtime_python-0.1.0.dist-info/top_level.txt,sha256=r7KIKsP_6Io6KiMqlBoNEc4IwzaE7O3VTG-PSEu0wVY,20
+orca_runtime_python-0.1.0.dist-info/RECORD,,

orca_runtime_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

orca_runtime_python-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+orca_runtime_python