mycorrhizal 0.1.2__py3-none-any.whl → 0.2.1__py3-none-any.whl

mycorrhizal/mycelium/tree_builder.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""
+Tree builder - collects tree metadata during decoration.
+
+This module provides the MyceliumTreeBuilder which is responsible for
+collecting FSM/BT integrations, BT nodes, and other metadata during the
+@tree decoration phase.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, Optional
+
+from .tree_spec import MyceliumTreeSpec, FSMIntegration, BTIntegration, NodeDefinition
+from .exceptions import TreeDefinitionError
+
+
+class MyceliumTreeBuilder:
+    """
+    Builder that collects tree metadata during decoration.
+
+    This is used internally by the @tree decorator to gather all
+    FSM/BT integrations, BT nodes, and other metadata before creating
+    the final MyceliumTreeSpec.
+    """
+
+    def __init__(self, name: str, tree_func: Callable):
+        self.name = name
+        self.tree_func = tree_func
+        self.actions: Dict[str, NodeDefinition] = {}
+        self.conditions: Dict[str, NodeDefinition] = {}
+        self.root_node: Optional[NodeDefinition] = None
+        self.fsm_integrations: Dict[str, FSMIntegration] = {}
+        self.bt_integrations: Dict[str, BTIntegration] = {}
+
+    def add_action(self, node_def: NodeDefinition) -> None:
+        """Add an action node definition."""
+        # Allow replacing (func() may be called multiple times)
+        self.actions[node_def.name] = node_def
+
+    def add_condition(self, node_def: NodeDefinition) -> None:
+        """Add a condition node definition."""
+        # Allow replacing (func() may be called multiple times)
+        self.conditions[node_def.name] = node_def
+
+    def set_root(self, node_def: NodeDefinition) -> None:
+        """Set the root node."""
+        # Allow replacing (func() may be called multiple times)
+        self.root_node = node_def
+
+    def add_fsm_integration(self, integration: FSMIntegration) -> None:
+        """Add an FSM integration for an action."""
+        self.fsm_integrations[integration.action_name] = integration
+
+    def add_bt_integration(self, integration: BTIntegration) -> None:
+        """Add a BT integration for a state."""
+        self.bt_integrations[integration.state_name] = integration
+
+    def build(self) -> MyceliumTreeSpec:
+        """
+        Build the final MyceliumTreeSpec.
+
+        Returns:
+            Complete tree specification
+
+        Raises:
+            TreeDefinitionError: If validation fails
+        """
+        # Create tree spec
+        spec = MyceliumTreeSpec(
+            name=self.name,
+            tree_func=self.tree_func,
+            actions=self.actions,
+            conditions=self.conditions,
+            root_node=self.root_node,
+            fsm_integrations=self.fsm_integrations,
+            bt_integrations=self.bt_integrations,
+        )
+
+        # Validate
+        errors = spec.validate()
+        if errors:
+            raise TreeDefinitionError(
+                "Tree validation failed:\n" + "\n".join(f"  - {e}" for e in errors)
+            )
+
+        return spec
+
+
+# Context variable to track current tree builder
+_current_builder: Optional[MyceliumTreeBuilder] = None
+
+
+def get_current_builder() -> Optional[MyceliumTreeBuilder]:
+    """Get the currently active tree builder (if any)."""
+    return _current_builder
+
+
+def set_current_builder(builder: Optional[MyceliumTreeBuilder]) -> None:
+    """Set the current tree builder."""
+    global _current_builder
+    _current_builder = builder

mycorrhizal/mycelium/tree_spec.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""
+Tree specification - metadata about a Mycelium tree.
+
+This module defines the data structures that hold tree metadata,
+including FSM/BT integrations, BT nodes, and their relationships.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Type, Callable
+
+
+@dataclass
+class FSMIntegration:
+    """Metadata about an FSM integrated into a BT action."""
+
+    initial_state: Type  # StateSpec or callable returning StateSpec
+    action_name: str  # The action that uses this FSM
+
+    def __post_init__(self):
+        """Validate FSM integration."""
+        if not self.action_name:
+            raise ValueError("Action name cannot be empty")
+
+
+@dataclass
+class BTIntegration:
+    """Metadata about a BT integrated into an FSM state."""
+
+    bt_tree: Any  # BT namespace from bt.tree()
+    state_name: str  # The state that uses this BT (fully qualified)
+    state_func: Callable  # The on_state function
+
+    def __post_init__(self):
+        """Validate BT integration."""
+        if not self.state_name:
+            raise ValueError("State name cannot be empty")
+
+
+@dataclass
+class PNIntegration:
+    """Metadata about a BT or FSM integrated into a PN transition."""
+
+    transition_name: str  # The transition that uses this integration
+    integration_type: str = "bt"  # "bt" or "fsm"
+    mode: str = "token"  # "token" or "batch" (BT only)
+
+    # BT integration fields
+    bt_tree: Any = None  # BT namespace from bt.tree()
+
+    # FSM integration fields
+    initial_state: Any = None  # Initial state for FSM (StateSpec or callable)
+
+    # Output destinations
+    output_places: Optional[List[Any]] = None  # List of PlaceRef objects (output destinations)
+
+    def __post_init__(self):
+        """Validate PN integration."""
+        if not self.transition_name:
+            raise ValueError("Transition name cannot be empty")
+
+        # Validate integration type
+        if self.integration_type not in ("bt", "fsm"):
+            raise ValueError(f"Invalid integration_type: {self.integration_type}. Must be 'bt' or 'fsm'")
+
+        # Validate BT-specific fields
+        if self.integration_type == "bt":
+            if self.bt_tree is None:
+                raise ValueError("BT integration requires bt_tree parameter")
+            if self.mode not in ("token", "batch"):
+                raise ValueError(f"Invalid mode: {self.mode}. Must be 'token' or 'batch'")
+
+        # Validate FSM-specific fields
+        if self.integration_type == "fsm":
+            if self.initial_state is None:
+                raise ValueError("FSM integration requires initial_state parameter")
+
+        # Initialize output_places if None
+        if self.output_places is None:
+            self.output_places = []
+
+    @property
+    def fsm_state_name(self) -> str:
+        """Get the name of the FSM initial state for display purposes."""
+        if self.initial_state is None:
+            return "Unknown"
+
+        # If it's a StateSpec, extract the name
+        if hasattr(self.initial_state, 'name'):
+            name = self.initial_state.name
+            # Extract just the simple name (last component after dot)
+            if '.' in name:
+                return name.split('.')[-1]
+            return name
+
+        # Try to get the name from the state
+        if hasattr(self.initial_state, '__name__'):
+            return self.initial_state.__name__
+
+        return str(self.initial_state)
+
+
+@dataclass
+class NodeDefinition:
+    """
+    Metadata about a BT node defined in a tree.
+
+    Now includes optional FSM integration for actions.
+    """
+
+    name: str
+    node_type: str  # "action", "condition", "sequence", "selector", "parallel"
+    func: Optional[Callable] = None
+    children: List[NodeDefinition] = field(default_factory=list)
+    is_root: bool = False
+    fsm_integration: Optional[FSMIntegration] = None  # FSM for actions
+
+    def __post_init__(self):
+        """Validate node definition."""
+        if not self.name:
+            raise ValueError("Node name cannot be empty")
+
+
+@dataclass
+class MyceliumTreeSpec:
+    """
+    Complete specification of a Mycelium tree.
+
+    Contains all metadata about FSM/BT integrations, BT nodes, and their relationships.
+    This is what gets built by the @tree decorator and used by TreeInstance.
+    """
+
+    name: str
+    tree_func: Optional[Callable] = None  # The original @tree decorated function (for reference)
+    bt_namespace: Optional[Any] = None  # The BT namespace returned by bt.tree() (set after build)
+    actions: Dict[str, NodeDefinition] = field(default_factory=dict)
+    conditions: Dict[str, NodeDefinition] = field(default_factory=dict)
+    root_node: Optional[NodeDefinition] = None
+    # FSM integrations keyed by action name
+    fsm_integrations: Dict[str, FSMIntegration] = field(default_factory=dict)
+    # BT integrations keyed by state name (fully qualified)
+    bt_integrations: Dict[str, BTIntegration] = field(default_factory=dict)
+    # PN integrations keyed by transition name (fully qualified)
+    pn_integrations: Dict[str, PNIntegration] = field(default_factory=dict)
+
+    @property
+    def fsms(self) -> Dict[str, FSMIntegration]:
+        """
+        Access FSM integrations (alias for fsm_integrations).
+
+        This provides convenient access like:
+            spec.fsms['robot']
+        """
+        return self.fsm_integrations
+
+    def get_action(self, name: str) -> Optional[NodeDefinition]:
+        """Get action definition by name."""
+        return self.actions.get(name)
+
+    def get_condition(self, name: str) -> Optional[NodeDefinition]:
+        """Get condition definition by name."""
+        return self.conditions.get(name)
+
+    def get_fsm_integration(self, action_name: str) -> Optional[FSMIntegration]:
+        """Get FSM integration for an action."""
+        return self.fsm_integrations.get(action_name)
+
+    def get_bt_integration(self, state_name: str) -> Optional[BTIntegration]:
+        """Get BT integration for a state."""
+        return self.bt_integrations.get(state_name)
+
+    def get_pn_integration(self, transition_name: str) -> Optional["PNIntegration"]:
+        """Get PN integration for a transition."""
+        return self.pn_integrations.get(transition_name)
+
+    def validate(self) -> List[str]:
+        """
+        Validate the tree specification.
+
+        Returns:
+            List of error messages (empty if valid)
+        """
+        errors = []
+
+        # Check root node exists
+        if self.root_node is None:
+            errors.append("Tree has no root node")
+
+        # Check action names don't collide with condition names
+        all_names = list(self.actions.keys()) + list(self.conditions.keys())
+        duplicates = [name for name in set(all_names) if all_names.count(name) > 1]
+        if duplicates:
+            errors.append(f"Duplicate names: {duplicates}")
+
+        return errors

mycorrhizal/rhizomorph/README.md

@@ -3,9 +3,9 @@
 
 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)`
+- **Fluent decorator chains**: `bt.failer().gate(condition).timeout(0.5)(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()`
+- **Cross-tree composition**: embed full subtrees with `bt.subtree()`
 - **Mermaid diagrams**: export static structure diagrams for documentation/debugging
 - **Timebases**: simulate or control time with pluggable clocks (wall/UTC/monotonic/cycle/dictated)
 
@@ -34,9 +34,9 @@ def Patrol():
 
     @bt.root
     @bt.sequence(memory=True)
-    def root(N):
-        yield N.has_waypoints
-        yield bt.timeout(1.0)(N.go_to_next)
+    def root():
+        yield has_waypoints
+        yield bt.timeout(1.0)(go_to_next)
 
 async def main():
     bb = BB(waypoints=3)
@@ -55,15 +55,15 @@ async def main():
 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)
+yield bt.failer().gate(battery_ok).timeout(0.25)(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.
+2. `gate(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`.
+4. Applied to `engage`.
 
 ### Wrapper Cheat‑Sheet
 
@@ -75,7 +75,7 @@ yield bt.failer().gate(N.battery_ok).timeout(0.25)(N.engage)
 | `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 |
+| `gate()` | `bt.gate(condition: NodeSpec | @bt.condition)` | If condition RUNNING → **RUNNING** | Ticks child and propagates its terminal status | If condition not SUCCESS → **FAILURE** | Condition node is resolved from the owning tree |
 
 > Tip: You can compose wrappers in any order. The chain is applied **outside‑in** (the leftmost wrapper becomes the outermost decorator).
 
@@ -93,9 +93,9 @@ yield bt.failer().gate(N.battery_ok).timeout(0.25)(N.engage)
   - Truthy → `SUCCESS`, falsy → `FAILURE`.  
   - Returning a `Status` is allowed but discouraged; use plain booleans.
 
-### Composites (owner‑aware factories)
+### Composites
 
-Define composites as **generator factories** that yield children. The factory receives the **owner class** `N`, so you reference members with `N.<member>` (no strings).
+Define composites as **generator factories** that yield children. Node references are resolved directly by name from the owning tree.
 
 - `@bt.sequence(memory: bool = True)`  
   **AND**: ticks children in order.  
@@ -104,11 +104,12 @@ Define composites as **generator factories** that yield children. The factory re
   - 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.selector(memory: bool = True)`
+  **OR**: ticks children until one returns `SUCCESS`.
+  - `RUNNING` bubbles (and may set/resume index depending on `memory`).
+  - If none succeed → `FAILURE`.
+  - With `memory=True`, the selector **remembers the last RUNNING child** and resumes there next tick.
+  - With `memory=False` (reactive mode), the selector **re-evaluates from the first child** each tick.  
 
 
 - `@bt.parallel(success_threshold: int, failure_threshold: Optional[int] = None)`  
@@ -118,16 +119,15 @@ Define composites as **generator factories** that yield children. The factory re
   - Otherwise `RUNNING`.  
   - Default `failure_threshold = n - success_threshold + 1` (i.e., once success is impossible).
 
-#### On owner‑aware expansion
+#### On node resolution
 
-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.
+Inside diagramming and building, composites are expanded with the correct **owner class** context. This lets you split behavior across modules while keeping references 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.
+- `bt.subtree(OtherTree)` — mounts another tree's `ROOT` as a child; for Mermaid export the `ROOT` spec is attached so it expands visually.
 
 **Example**
 
@@ -143,9 +143,9 @@ def Engage():
 
     @bt.root
     @bt.sequence(memory=False)
-    def engage_threat(N):
-        yield N.threat_detected
-        yield bt.failer().timeout(0.25)(N.engage)
+    def engage_threat():
+        yield threat_detected
+        yield bt.failer().timeout(0.25)(engage)
 
 # Telemetry subtree
 @bt.tree
@@ -155,17 +155,17 @@ def Telemetry():
 
     @bt.root
     @bt.sequence()
-    def telemetry_seq(N):
-        yield bt.ratelimit(hz=2.0)(N.push)
+    def telemetry_seq():
+        yield bt.ratelimit(hz=2.0)(push)
 
-# Main tree
+# Main tree - compose both subtrees
 @bt.tree
 def Main():
     @bt.root
-    @bt.selector(reactive=True, memory=True)
-    def root(N):
+    @bt.selector(memory=False)
+    def root():
         yield bt.subtree(Engage)
-        yield bt.bind(Telemetry, Telemetry.telemetry_seq)
+        yield bt.subtree(Telemetry)
 ```
 
 ---
@@ -183,7 +183,56 @@ diagram = MainTree.to_mermaid()
 print(diagram)
 ```
 
-Paste the output into the Mermaid Live Editor.
+Paste the output into the Mermaid Live Editor or any Markdown viewer that supports Mermaid.
+
+### Example Diagram
+
+Here's an example behavior tree diagram showing a threat response system:
+
+```mermaid
+flowchart TD
+  N1["Selector<br/>root"]
+  N1 --> N2
+  N2["Subtree<br/>Engage"]
+  N2 --> N3
+  N3["Sequence<br/>engage_threat"]
+  N3 --> N4
+  N4((CONDITION<br/>threat_detected))
+  N3 --> N5
+  N5["Decor<br/>Failer(Gate(cond=battery_ok)(Timeout(0.12s)(engage)))"]
+  N5 --> N6
+  N6["Decor<br/>Gate(cond=battery_ok)(Timeout(0.12s)(engage))"]
+  N6 --> N7
+  N7["Decor<br/>Timeout(0.12s)(engage)"]
+  N7 --> N8
+  N8((ACTION<br/>engage))
+  N1 --> N9
+  N9["Sequence<br/>patrol"]
+  N9 --> N10
+  N10((CONDITION<br/>has_waypoints))
+  N9 --> N11
+  N11((ACTION<br/>go_to_next))
+  N9 --> N12
+  N12["Decor<br/>Succeeder(Retry(3)(Timeout(1.0s)(scan_area)))"]
+  N12 --> N13
+  N13["Decor<br/>Retry(3)(Timeout(1.0s)(scan_area))"]
+  N13 --> N14
+  N14["Decor<br/>Timeout(1.0s)(scan_area)"]
+  N14 --> N15
+  N15((ACTION<br/>scan_area))
+  N1 --> N16
+  N16["Decor<br/>Failer(RateLimit(0.200000s)(telemetry_push))"]
+  N16 --> N17
+  N17["Decor<br/>RateLimit(0.200000s)(telemetry_push)"]
+  N17 --> N18
+  N18((ACTION<br/>telemetry_push))
+```
+
+This diagram shows:
+- A **Selector** root that chooses between Engage, Patrol, or Telemetry
+- **Decorator chains** like `Failer(Gate(Timeout(engage)))` shown as nested decorators
+- **Composite nodes** (Sequence, Selector) with their children
+- **Leaf nodes** (Conditions, Actions) clearly marked
 
 ---
 
@@ -208,9 +257,9 @@ Paste the output into the Mermaid Live Editor.
 
 ## 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`.  
+- **Async‑first** — every node can be `async def`; scheduling is `asyncio`‑based.
+- **String‑free** — reference nodes directly by name (no magic strings).
+- **Composable** — split and recombine trees across modules with `subtree`.
 - **Fluent‑only** — decorator chains read naturally left→right.
 
 ---