mycorrhizal 0.1.0__py3-none-any.whl

mycorrhizal/hypha/core/specs.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+"""
+Hypha DSL - Specification Layer
+
+Core data structures representing the declarative specification of a Petri net.
+These are built by the decorator API and used to instantiate runtime objects.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional, Callable, Dict, List, Any, Tuple
+from enum import Enum, auto
+
+
+class PlaceType(Enum):
+    """Type of place storage mechanism"""
+    BAG = auto()  # Unordered collection
+    QUEUE = auto()  # FIFO ordered collection
+
+
+@dataclass
+class PlaceSpec:
+    """Specification for a place in the Petri net"""
+    name: str  # Local name only, e.g. "waiting"
+    place_type: PlaceType
+    handler: Optional[Callable] = None  # For IOPlaces
+    state_factory: Optional[Callable] = None
+    is_io_input: bool = False
+    is_io_output: bool = False
+
+
+@dataclass
+class GuardSpec:
+    """Specification for a guard function"""
+    func: Callable  # Signature: (tokens, bb, timebase) -> Iterator[tuple]
+
+
+@dataclass
+class TransitionSpec:
+    """Specification for a transition in the Petri net"""
+    name: str  # Local name only, e.g. "process_task"
+    handler: Callable  # Signature: async (consumed, bb, timebase, [state]) -> yields
+    guard: Optional[GuardSpec] = None
+    state_factory: Optional[Callable] = None
+
+
+@dataclass
+class ArcSpec:
+    """Specification for an arc connecting places and transitions"""
+    source: 'PlaceRef | TransitionRef'  # Reference objects, not strings
+    target: 'PlaceRef | TransitionRef'  # Reference objects, not strings
+    weight: int = 1
+    name: Optional[str] = None
+
+    # Computed canonical parts for source/target (tuple of name components)
+    source_parts: Tuple[str, ...] = field(init=False)
+    target_parts: Tuple[str, ...] = field(init=False)
+
+    def __post_init__(self):
+        # Helper to extract parts from a ref/string/tuple
+        def _parts_of(obj) -> Tuple[str, ...]:
+            try:
+                parts = obj.get_parts()
+                return tuple(parts)
+            except Exception:
+                # obj might be a dotted string or a tuple/list
+                if isinstance(obj, str):
+                    return tuple(obj.split('.'))
+                if isinstance(obj, (list, tuple)):
+                    return tuple(obj)
+                # Fallback: stringify
+                return tuple(str(obj).split('.'))
+
+        self.source_parts = _parts_of(self.source)
+        self.target_parts = _parts_of(self.target)
+
+
+@dataclass
+class NetSpec:
+    """Complete specification of a Petri net"""
+    name: str  # Local name only, e.g. "SimpleProcessor"
+    parent: Optional['NetSpec'] = None  # Parent spec for hierarchy
+    places: Dict[str, PlaceSpec] = field(default_factory=dict)  # Local names as keys
+    transitions: Dict[str, TransitionSpec] = field(default_factory=dict)  # Local names as keys
+    arcs: List[ArcSpec] = field(default_factory=list)
+    subnets: Dict[str, 'NetSpec'] = field(default_factory=dict)  # Local names as keys
+    
+    def get_fqn(self, local_name: Optional[str] = None) -> str:
+        """Compute fully qualified name by walking parent chain"""
+        return '.'.join(self.get_parts(local_name))
+
+    def get_parts(self, local_name: Optional[str] = None) -> List[str]:
+        """Return the fully qualified name as a list of path components.
+
+        If local_name is provided, returns the parts for that member
+        under this spec (e.g. ['Parent', 'Spec', 'local']). Otherwise
+        returns the parts for this spec itself.
+        """
+        parts: List[str] = []
+        if self.parent:
+            parts.extend(self.parent.get_parts())
+
+        parts.append(self.name)
+
+        if local_name is not None:
+            parts.append(local_name)
+
+        return parts
+    
+    def to_mermaid(self) -> str:
+        """Generate Mermaid diagram of the net"""
+        lines = ["graph TD"]
+        
+        def add_subnet(spec: NetSpec, indent: str = "    "):
+            spec_fqn = spec.get_fqn()
+            
+            if spec.subnets:
+                for subnet_name, subnet_spec in spec.subnets.items():
+                    subnet_fqn = subnet_spec.get_fqn()
+                    lines.append(f"{indent}subgraph {subnet_fqn}")
+                    add_subnet(subnet_spec, indent + "    ")
+                    lines.append(f"{indent}end")
+            
+            for place_name, place_spec in spec.places.items():
+                place_fqn = spec.get_fqn(place_name)
+                shape = "((" 
+                close = "))" 
+                prefix = "[INPUT]</br>" if place_spec.is_io_input else "[OUTPUT]</br>" if place_spec.is_io_output else "" 
+                lines.append(f"{indent}{place_fqn}{shape}\"{prefix}{place_fqn}\"{close}")
+            
+            for trans_name in spec.transitions.keys():
+                trans_fqn = spec.get_fqn(trans_name)
+                lines.append(f"{indent}{trans_fqn}[{trans_fqn}]")
+            
+            for arc in spec.arcs:
+                source_fqn = arc.source.get_fqn()
+                target_fqn = arc.target.get_fqn()
+                weight_label = f"|weight={arc.weight}|" if arc.weight > 1 else ""
+                lines.append(f"{indent}{source_fqn} -->{weight_label} {target_fqn}")
+        
+        add_subnet(self)
+        
+        return "\n".join(lines)
+
+
+class PlaceRef:
+    """Reference to a place for use in arc definitions"""
+    def __init__(self, local_name: str, parent_spec: NetSpec):
+        self.local_name = local_name
+        self.parent_spec = parent_spec
+    
+    def get_fqn(self) -> str:
+        """Compute FQN dynamically"""
+        return '.'.join(self.get_parts())
+    
+    # For backward compatibility
+    @property
+    def fqn(self) -> str:
+        return self.get_fqn()
+
+    def get_parts(self) -> List[str]:
+        """Return the FQN as list of parts for this place ref."""
+        return self.parent_spec.get_parts(self.local_name)
+
+    @property
+    def parts(self) -> List[str]:
+        return self.get_parts()
+    
+    def __repr__(self):
+        return f"PlaceRef({self.get_fqn()})"
+
+
+class TransitionRef:
+    """Reference to a transition for use in arc definitions"""
+    def __init__(self, local_name: str, parent_spec: NetSpec):
+        self.local_name = local_name
+        self.parent_spec = parent_spec
+    
+    def get_fqn(self) -> str:
+        """Compute FQN dynamically"""
+        return '.'.join(self.get_parts())
+    # For backward compatibility
+    @property
+    def fqn(self) -> str:
+        return self.get_fqn()
+    
+    def __repr__(self):
+        return f"TransitionRef({self.get_fqn()})"
+
+    def get_parts(self) -> List[str]:
+        return self.parent_spec.get_parts(self.local_name)
+
+    @property
+    def parts(self) -> List[str]:
+        return self.get_parts()
+
+
+class SubnetRef:
+    """Reference to a subnet instance for accessing its places/transitions"""
+    def __init__(self, spec: NetSpec):
+        self.spec = spec
+    
+    def get_fqn(self) -> str:
+        """Compute FQN dynamically"""
+        return '.'.join(self.get_parts())
+    
+    # For backward compatibility
+    @property
+    def fqn(self) -> str:
+        return self.get_fqn()
+    
+    def __getattr__(self, name: str):
+        # Check places
+        if name in self.spec.places:
+            return PlaceRef(name, self.spec)
+        
+        # Check transitions
+        if name in self.spec.transitions:
+            return TransitionRef(name, self.spec)
+        
+        # Check subnets
+        if name in self.spec.subnets:
+            return SubnetRef(self.spec.subnets[name])
+        
+        raise AttributeError(f"No place, transition, or subnet named {name} in {self.get_fqn()}")
+    
+    def __repr__(self):
+        return f"SubnetRef({self.get_fqn()})"
+
+    def get_parts(self) -> List[str]:
+        return self.spec.get_parts()
+
+    @property
+    def parts(self) -> List[str]:
+        return self.get_parts()

mycorrhizal/hypha/util.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""
+Hypha Petri Net Utilities
+
+Utility functions for Petri net operations like Mermaid diagram generation.
+"""
+from .core.specs import NetSpec
+
+
+def to_mermaid(spec: NetSpec) -> str:
+    """
+    Generate Mermaid diagram from a NetSpec.
+
+    This is a utility wrapper around NetSpec.to_mermaid() for convenience.
+    Use this when you have a spec object and want to generate a diagram.
+
+    Args:
+        spec: The NetSpec to generate a diagram for
+
+    Returns:
+        Mermaid diagram as a string
+
+    Example:
+        ```python
+        from mycorrhizal.hypha.core import pn
+        from mycorrhizal.hypha.util import to_mermaid
+
+        @pn.net
+        def MyNet(builder):
+            # ... define net ...
+            pass
+
+        # Generate diagram
+        mermaid_diagram = to_mermaid(MyNet._spec)
+        print(mermaid_diagram)
+        ```
+    """
+    return spec.to_mermaid()

mycorrhizal/rhizomorph/README.md

@@ -0,0 +1,220 @@
+
+# Rhizomorph
+
+Asyncio-friendly **Behavior Trees** for Python, designed for clarity, composability, and ergonomics in asynchronous systems.
+
+- **Fluent decorator chains**: `bt.failer().gate(N.condition).timeout(0.5)(N.action)`
+- **Owner-aware composites**: factories expand with the correct class owner, so large trees can be split across modules
+- **Cross-tree composition**: embed full subtrees with `bt.subtree()` or borrow composites with `bt.bind()`
+- **Mermaid diagrams**: export static structure diagrams for documentation/debugging
+- **Timebases**: simulate or control time with pluggable clocks (wall/UTC/monotonic/cycle/dictated)
+
+---
+
+## Quick Example
+```python
+from rhizomorph.core import bt, Runner, Status
+
+class BB:
+    def __init__(self, waypoints):
+        self.waypoints = waypoints
+
+@bt.tree
+def Patrol():
+    @bt.action
+    async def go_to_next(bb):
+        if bb.waypoints <= 0:
+            return Status.SUCCESS
+        bb.waypoints -= 1
+        return Status.RUNNING if bb.waypoints > 0 else Status.SUCCESS
+
+    @bt.condition
+    def has_waypoints(bb):
+        return getattr(bb, "waypoints", 0) > 0
+
+    @bt.root
+    @bt.sequence(memory=True)
+    def root(N):
+        yield N.has_waypoints
+        yield bt.timeout(1.0)(N.go_to_next)
+
+async def main():
+    bb = BB(waypoints=3)
+    runner = Runner(Patrol, bb=bb)
+    while True:
+        status = await runner.tick()
+        print("Status:", status.name, "remaining:", bb.waypoints)
+        if status in (Status.SUCCESS, Status.FAILURE):
+            break
+```
+
+---
+
+## Fluent Decorator Chains
+
+Decorator wrappers are available via **fluent chains** that read left→right and apply to a child when called at the end:
+
+```python
+yield bt.failer().gate(N.battery_ok).timeout(0.25)(N.engage)
+```
+
+**Reads left→right:**
+
+1. `failer()` → forces **FAILURE** once the child completes (whether the child succeeds or fails). While the child is RUNNING, RUNNING bubbles.
+2. `gate(N.battery_ok)` → only ticks the child if `battery_ok` returns SUCCESS. If the condition returns RUNNING, the whole gate is RUNNING. If it returns FAILURE, the gate returns FAILURE without ticking the child.
+3. `timeout(0.25)` → if the child does not finish before 0.25 (per the configured timebase), it is cancelled/reset and the decorator returns FAILURE.
+4. Applied to `N.engage`.
+
+### Wrapper Cheat‑Sheet
+
+| Wrapper | Signature | RUNNING behavior | On child SUCCESS | On child FAILURE/ERROR/CANCELLED | Notes |
+|---|---|---|---|---|---|
+| `inverter()` | `bt.inverter()` | Pass-through | **FAILURE** | **SUCCESS** (for FAILURE); ERROR/CANCELLED pass through | Only flips SUCCESS/FAILURE; other statuses bubble |
+| `succeeder()` | `bt.succeeder()` | Pass-through | **SUCCESS** | **SUCCESS** | Forces success once child completes |
+| `failer()` | `bt.failer()` | Pass-through | **FAILURE** | **FAILURE** | Forces failure once child completes |
+| `timeout()` | `bt.timeout(seconds: float)` | RUNNING until deadline; then **FAILURE** | Child status on completion | Child status on completion (unless deadline hit) | Uses the tree’s `Timebase`; cancels child when expired |
+| `retry()` | `bt.retry(max_attempts: int, retry_on=(FAILURE, ERROR))` | Pass-through | **SUCCESS** and resets attempt count | Retries while child in `retry_on` until attempts exhausted → **FAILURE** | Does not retry on RUNNING or CANCELLED by default |
+| `ratelimit()` | `bt.ratelimit(hz: float=None, period: float=None)` | If child is currently RUNNING, pass-through (no throttling) | Propagates child result and schedules next allowed start | If throttled: returns **RUNNING** (child not started) | Accepts exactly one of `hz` or `period` |
+| `gate()` | `bt.gate(condition: NodeSpec | @bt.condition)` | If condition RUNNING → **RUNNING** | Ticks child and propagates its terminal status | If condition not SUCCESS → **FAILURE** | Condition is built owner‑aware under the hood |
+
+> Tip: You can compose wrappers in any order. The chain is applied **outside‑in** (the leftmost wrapper becomes the outermost decorator).
+
+---
+
+## Nodes & Composites
+
+### Leaves
+
+- `@bt.action` — wraps an async or sync function.  
+  - May return `Status`, `bool`, or `None` (treated as `SUCCESS`).  
+  - Exceptions become `ERROR` (except `asyncio.CancelledError` → `CANCELLED`).
+
+- `@bt.condition` — wraps an async or sync predicate.  
+  - Truthy → `SUCCESS`, falsy → `FAILURE`.  
+  - Returning a `Status` is allowed but discouraged; use plain booleans.
+
+### Composites (owner‑aware factories)
+
+Define composites as **generator factories** that yield children. The factory receives the **owner class** `N`, so you reference members with `N.<member>` (no strings).
+
+- `@bt.sequence(memory: bool = True)`  
+  **AND**: ticks children in order.  
+  - Fail/err/cancel **fast** (propagate child status).  
+  - `RUNNING` bubbles.  
+  - All `SUCCESS` → `SUCCESS`.  
+  - With `memory=True`, on a subsequent tick it **resumes from the last RUNNING child**. With `memory=False`, it restarts from the first child each tick.
+
+- `@bt.selector(memory: bool = True)`  
+  **OR**: ticks children until one returns `SUCCESS`.  
+  - `RUNNING` bubbles (and may set/resume index depending on `memory`/`reactive`).  
+  - If none succeed → `FAILURE`.  
+  - With `memory=True`, the selector **remembers the last RUNNING child** and resumes there next tick.  
+
+
+- `@bt.parallel(success_threshold: int, failure_threshold: Optional[int] = None)`  
+  Ticks all children concurrently per tick.  
+  - Success if at least `success_threshold` children return `SUCCESS`.  
+  - Failure if at least `failure_threshold` children are in {`FAILURE`, `ERROR`, `CANCELLED`}.  
+  - Otherwise `RUNNING`.  
+  - Default `failure_threshold = n - success_threshold + 1` (i.e., once success is impossible).
+
+#### On owner‑aware expansion
+
+Inside diagramming and building, composites are expanded with the correct **owner class** context. This lets you split behavior across modules while keeping references (`N.something`) type‑safe and string‑free.
+
+---
+
+## Cross‑Tree Composition
+
+- `bt.subtree(OtherTree)` — mounts another tree’s `ROOT` as a child; for Mermaid export the `ROOT` spec is attached so it expands visually.  
+- `bt.bind(Owner, Owner.Composite)` — borrows a composite from another class and expands it using that **Owner** as the context.
+
+**Example**
+
+```python
+# Engage subtree
+@bt.tree
+def Engage():
+    @bt.condition
+    def threat_detected(bb): ...
+
+    @bt.action
+    def engage(bb): ...
+
+    @bt.root
+    @bt.sequence(memory=False)
+    def engage_threat(N):
+        yield N.threat_detected
+        yield bt.failer().timeout(0.25)(N.engage)
+
+# Telemetry subtree
+@bt.tree
+def Telemetry():
+    @bt.action
+    def push(bb): ...
+
+    @bt.root
+    @bt.sequence()
+    def telemetry_seq(N):
+        yield bt.ratelimit(hz=2.0)(N.push)
+
+# Main tree
+@bt.tree
+def Main():
+    @bt.root
+    @bt.selector(reactive=True, memory=True)
+    def root(N):
+        yield bt.subtree(Engage)
+        yield bt.bind(Telemetry, Telemetry.telemetry_seq)
+```
+
+---
+
+## Mermaid Export
+
+```python
+from rhizomorph.core import bt
+
+@bt.tree
+def MainTree():
+  ...
+
+diagram = MainTree.to_mermaid()
+print(diagram)
+```
+
+Paste the output into the Mermaid Live Editor.
+
+---
+
+
+---
+
+## Runner & Tree
+
+
+- **Tree** — a plain namespace (e.g., from `bt.tree(lambda: None)`) holding your decorated functions and a `root` composite.  
+- **Runner(tree, bb=None, tb=None)** — ticks the tree.  
+  - `await runner.tick()` — ticks once; advances the timebase if it supports `.advance()`.  
+  - `await runner.tick_until_complete(timeout: Optional[float]=None)` — loops until terminal status or timeout.
+
+---
+
+## Status Values
+
+- `SUCCESS`, `FAILURE`, `RUNNING`, `CANCELLED`, `ERROR`
+
+---
+
+## Design Principles
+
+- **Async‑first** — every node can be `async def`; scheduling is `asyncio`‑based.  
+- **String‑free** — reference nodes via `N.<member>` (no magic strings).  
+- **Composable** — split and recombine trees across modules with `subtree`/`bind`.  
+- **Fluent‑only** — decorator chains read naturally left→right.
+
+---
+
+## License
+
+MIT