mycorrhizal 0.2.0__tar.gz → 0.2.2__tar.gz

{mycorrhizal-0.2.0 → mycorrhizal-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mycorrhizal
-Version: 0.2.0
+Version: 0.2.2
 Summary: Utilities and DSLs for modelling and implementing safe, performant, structured systems
 Author-email: Jeff Ciesielski <jeffciesielski@gmail.com>
 Requires-Python: >=3.10

{mycorrhizal-0.2.0 → mycorrhizal-0.2.2}/docs/rhizomorph/index.md

@@ -153,6 +153,46 @@ def my_parallel():
     yield task_c
 ```
 
+### Conditional Wrappers
+
+Control whether child nodes execute based on conditions:
+
+#### gate
+
+Execute child only when condition is true, otherwise return FAILURE:
+
+```python
+@bt.sequence
+def gated_sequence():
+    """Child must pass gate or sequence fails."""
+    yield bt.gate(has_battery)(engage_action)
+    yield next_step  # Only reached if gate passed
+```
+
+Use `gate` when a condition is **required** for execution.
+
+#### when
+
+Execute child only when condition is true, otherwise return SUCCESS (skip but continue):
+
+```python
+@bt.sequence
+def feature_flag_sequence():
+    """Optional action - sequence continues if feature is disabled."""
+    yield validate_input
+    yield bt.when(feature_enabled)(optional_action)
+    yield continue_processing  # Always reached
+```
+
+Use `when` for **optional** steps or feature flags.
+
+**When vs Gate:**
+
+| Wrapper | Condition True | Condition False | Use Case |
+|---------|---------------|-----------------|----------|
+| `gate(cond)(child)` | Execute child | Return FAILURE | Required precondition |
+| `when(cond)(child)` | Execute child | Return SUCCESS | Optional/feature flag |
+
 ### Root Node
 
 Every tree must have a root:

mycorrhizal-0.2.2/src/mycorrhizal/_version.py

@@ -0,0 +1 @@
+version = "0.2.2"

{mycorrhizal-0.2.0 → mycorrhizal-0.2.2}/src/mycorrhizal/hypha/core/runtime.py

@@ -285,51 +285,64 @@ class TransitionRuntime:
             if result is not None:
                 await self._process_yield(result)
 
-    def _resolve_place_ref(self, place_ref) -> Optional[Tuple[str, ...]]:
+    def _resolve_place_ref(self, place_ref) -> Tuple[str, ...]:
         """Resolve a PlaceRef to runtime place parts.
 
-        Attempts multiple resolution strategies in order:
+        Requires exact match or parent-relative mapping for subnet instances.
+
+        Resolution strategies in order:
         1. Exact match using PlaceRef.get_parts()
         2. Parent-relative mapping (for subnet instances)
-        3. Suffix fallback (match by local name)
 
         Returns:
-            Tuple of place parts if found, None otherwise
+            Tuple of place parts if found
+
+        Raises:
+            ValueError: If reference cannot be resolved
         """
+        # Extract local_name from place_ref (handles PlaceRef objects and strings)
+        if isinstance(place_ref, str):
+            local_name = place_ref
+        elif hasattr(place_ref, 'local_name'):
+            local_name = place_ref.local_name
+        else:
+            local_name = str(place_ref)
+
         # Try to get parts from the PlaceRef API
         try:
             parts = tuple(place_ref.get_parts())
         except Exception:
             parts = None
 
-        logger.debug("[resolve] place_ref=%r parts=%s", place_ref, parts)
+        logger.debug("[resolve] place_ref=%r parts=%s local_name=%s",
+                     place_ref, parts, local_name)
 
+        # Strategy 1: Exact match
         if parts:
             key = tuple(parts)
             if key in self.net.places:
                 logger.debug("[resolve] exact match parts=%s", parts)
                 return key
 
-        # Map relative to this transition's parent parts
+        # Strategy 2: Parent-relative mapping (for subnet instances)
         trans_parts = tuple(self.fqn.split('.'))
         if len(trans_parts) > 1:
             parent_prefix = trans_parts[:-1]
-            candidate = tuple(list(parent_prefix) + [place_ref.local_name])
+            candidate = tuple(list(parent_prefix) + [local_name])
             if candidate in self.net.places:
-                logger.debug("[resolve] mapped %s -> %s using parent_prefix", parts, candidate)
+                logger.debug("[resolve] mapped %s -> %s using parent_prefix",
+                           local_name, candidate)
                 return candidate
 
-        # Fallback: find any place whose last segment matches local_name
-        for p in self.net.places.keys():
-            if isinstance(p, tuple):
-                segs = list(p)
-            else:
-                segs = p.split('.')
-            if segs and segs[-1] == place_ref.local_name:
-                logger.debug("[resolve] suffix match %s -> %s", place_ref.local_name, p)
-                return tuple(segs)
-
-        return None
+        # No match found - raise helpful error
+        available_places = [p[-1] if isinstance(p, tuple) else p.split('.')[-1]
+                           for p in self.net.places.keys()]
+        raise ValueError(
+            f"Cannot resolve place reference '{local_name}' "
+            f"in transition '{self.fqn}'. Available places: {available_places}. "
+            f"Attempted resolution: {parts}. "
+            f"Use explicit place references (e.g., subnet.place)."
+        )
 
     def _normalize_to_parts(self, key) -> Tuple[str, ...]:
         """Normalize a place key to tuple of parts for runtime lookup.
@@ -387,9 +400,6 @@ class TransitionRuntime:
                 continue
 
             place_parts = self._resolve_place_ref(key)
-            if place_parts is None:
-                continue
-
             key_normalized = self._normalize_to_parts(place_parts)
             explicit_targets.add(key_normalized)
             await self._add_token_to_place(key_normalized, token)
@@ -420,10 +430,6 @@ class TransitionRuntime:
         """Process a single (place_ref, token) tuple yield."""
         place_ref, token = yielded
         place_parts = self._resolve_place_ref(place_ref)
-
-        if place_parts is None:
-            return
-
         key = self._normalize_to_parts(place_parts)
         await self._add_token_to_place(key, token)
     
@@ -521,6 +527,8 @@ class TransitionRuntime:
 
         except asyncio.CancelledError:
             pass
+        except ValueError:
+            raise
         except Exception:
             logger.exception("[%s] Transition error", self.fqn)
     
@@ -969,20 +977,24 @@ class NetRuntime:
 
 class Runner:
     """High-level runner for executing a Petri net"""
-    
+
     def __init__(self, net_func: Any, blackboard: Any):
         if not hasattr(net_func, '_spec'):
             raise ValueError(f"{net_func} is not a valid net")
-        
+
         self.spec = net_func._spec
         self.blackboard = blackboard
         self.timebase = None
         self.runtime: Optional[NetRuntime] = None
-    
+
     async def start(self, timebase: Any):
         """Start the net with given timebase"""
         self.timebase = timebase
-        self.runtime = NetRuntime(self.spec, self.blackboard, self.timebase)
+        self.runtime = NetRuntime(
+            self.spec,
+            self.blackboard,
+            self.timebase
+        )
         await self.runtime.start()
     
     async def stop(self, timeout: float = 5.0):

{mycorrhizal-0.2.0 → mycorrhizal-0.2.2}/src/mycorrhizal/rhizomorph/core.py

@@ -410,7 +410,7 @@ class Action(Node[BB]):
         # Log trace if enabled
         trace_logger = _trace_logger_ctx.get()
         if trace_logger is not None:
-            trace_logger.info(f"action: {self._fq_name} | {final_status.name}")
+            trace_logger.debug(f"action: {self._fq_name} | {final_status.name}")
 
         return await self._finish(bb, final_status, tb)
 
@@ -441,7 +441,7 @@ class Condition(Action[BB]):
         # Log trace if enabled
         trace_logger = _trace_logger_ctx.get()
         if trace_logger is not None:
-            trace_logger.info(f"condition: {self._fq_name} | {final_status.name}")
+            trace_logger.debug(f"condition: {self._fq_name} | {final_status.name}")
 
         return await self._finish(bb, final_status, tb)
 
@@ -452,7 +452,35 @@ class Condition(Action[BB]):
 
 
 class Sequence(Node[BB]):
-    """Sequence (AND): fail/err fast; RUNNING bubbles; all SUCCESS → SUCCESS."""
+    """Sequence (AND): fail/err fast; RUNNING bubbles; all SUCCESS → SUCCESS.
+
+    Memory Behavior:
+        When memory=True (default), the sequence remembers its position across ticks.
+        This allows the sequence to progress through its children incrementally.
+
+        When memory=False, the sequence restarts from the beginning on every tick.
+        This is useful for reactive sequences that should always start from the first child.
+
+    Important Note on do_while Loops:
+        If a sequence is used as the child of a do_while loop, it typically needs
+        memory=True to make progress. Without memory, the sequence will restart from
+        its first child on each tick, preventing it from completing all children.
+
+        Example:
+            @bt.sequence(memory=True)  # Required for progress
+            def image_samples():
+                yield bt.subtree(MoveToSample)
+                yield send_image_request
+                yield bt.subtree(IncrementSampleCounter)
+
+            @bt.sequence(memory=True)
+            def happy_path():
+                yield bt.do_while(samples_remain)(image_samples)
+                yield set_pod_to_grow
+
+        Without memory=True on image_samples, the do_while loop would never
+        progress past MoveToSample because the sequence would restart each tick.
+    """
 
     def __init__(
         self,
@@ -492,7 +520,20 @@ class Sequence(Node[BB]):
 
 
 class Selector(Node[BB]):
-    """Selector (Fallback): first SUCCESS wins; RUNNING bubbles; else FAILURE."""
+    """Selector (Fallback): first SUCCESS wins; RUNNING bubbles; else FAILURE.
+
+    Memory Behavior:
+        When memory=True (default), the selector remembers its position across ticks.
+        This allows the selector to continue trying children from where it left off.
+
+        When memory=False, the selector restarts from the beginning on every tick.
+        This is useful for reactive selectors that should always re-evaluate from the first child.
+
+    Important Note on do_while Loops:
+        Similar to Sequence, if a selector is used as the child of a do_while loop,
+        it typically needs memory=True to make progress. Without memory, the selector
+        will restart from its first child on each tick.
+    """
 
     def __init__(
         self,
@@ -849,20 +890,72 @@ class Gate(Node[BB]):
         return await self._finish(bb, st, tb)
 
 
+class When(Node[BB]):
+    """
+    Conditionally execute a child, returning SUCCESS if the condition fails.
+
+    Unlike gate(), when() does NOT fail the parent when the condition is false.
+    This is useful for optional steps or feature flags in sequences.
+
+    Behavior:
+      - If condition returns SUCCESS → execute child, return child's status
+      - If condition returns RUNNING → return RUNNING
+      - Otherwise → return SUCCESS (skip but don't fail parent)
+
+    Example:
+        yield bt.when(feature_enabled)(optional_action)
+        # If feature_enabled is false, returns SUCCESS and sequence continues
+    """
+
+    def __init__(
+        self,
+        condition: Node[BB],
+        child: Node[BB],
+        name: Optional[str] = None,
+        exception_policy: ExceptionPolicy = ExceptionPolicy.LOG_AND_CONTINUE,
+    ) -> None:
+        super().__init__(
+            name or f"When(cond={_name_of(condition)}, child={_name_of(child)})",
+            exception_policy=exception_policy,
+        )
+        self.condition = condition
+        self.child = child
+        self.condition.parent = self
+        self.child.parent = self
+
+    def reset(self) -> None:
+        super().reset()
+        self.condition.reset()
+        self.child.reset()
+
+    async def tick(self, bb: BB, tb: Timebase) -> Status:
+        await self._ensure_entered(bb, tb)
+        c = await self.condition.tick(bb, tb)
+        if c is Status.RUNNING:
+            return Status.RUNNING
+        if c is not Status.SUCCESS:
+            # Condition failed - return SUCCESS to skip but don't block parent
+            return await self._finish(bb, Status.SUCCESS, tb)
+        st = await self.child.tick(bb, tb)
+        if st is Status.RUNNING:
+            return Status.RUNNING
+        return await self._finish(bb, st, tb)
+
+
 class Match(Node[BB]):
     """
     Pattern-matching dispatch node.
-    
+
     Evaluates a key function against the blackboard, then checks each case
     in order. The first matching case's child is executed. If the child
     completes (SUCCESS or FAILURE), that status is returned immediately.
-    
+
     Cases can match by:
       - Type: isinstance(value, case_type)
       - Predicate: case_predicate(value) returns True
       - Value: value == case_value
       - Default: always matches (should be last)
-    
+
     If no case matches and there's no default, returns FAILURE.
     """
 
@@ -1003,6 +1096,68 @@ class DoWhile(Node[BB]):
         return await self._finish(bb, Status.FAILURE, tb)
 
 
+class TryCatch(Node[BB]):
+    """
+    Try-catch error handling node.
+
+    Executes the try block first. If it returns SUCCESS, that status is returned.
+    If the try block returns FAILURE, the catch block is executed instead.
+    Returns SUCCESS if either block succeeds, FAILURE if both fail.
+
+    This is semantically equivalent to a selector with two children, but provides
+    clearer intent and better visualization with labeled edges.
+    """
+
+    def __init__(
+        self,
+        try_block: Node[BB],
+        catch_block: Node[BB],
+        name: Optional[str] = None,
+        exception_policy: ExceptionPolicy = ExceptionPolicy.LOG_AND_CONTINUE,
+    ) -> None:
+        super().__init__(
+            name or f"TryCatch(try={_name_of(try_block)}, catch={_name_of(catch_block)})",
+            exception_policy=exception_policy,
+        )
+        self.try_block = try_block
+        self.catch_block = catch_block
+        self.try_block.parent = self
+        self.catch_block.parent = self
+        self._use_catch = False
+
+    def reset(self) -> None:
+        super().reset()
+        self.try_block.reset()
+        self.catch_block.reset()
+        self._use_catch = False
+
+    async def tick(self, bb: BB, tb: Timebase) -> Status:
+        await self._ensure_entered(bb, tb)
+
+        # If we're in catch mode, continue executing catch block
+        if self._use_catch:
+            st = await self.catch_block.tick(bb, tb)
+            if st is Status.RUNNING:
+                return Status.RUNNING
+            self._use_catch = False
+            return await self._finish(bb, st, tb)
+
+        # Try the try block
+        st = await self.try_block.tick(bb, tb)
+        if st is Status.RUNNING:
+            return Status.RUNNING
+        if st is Status.SUCCESS:
+            return await self._finish(bb, Status.SUCCESS, tb)
+
+        # Try block failed, switch to catch
+        self._use_catch = True
+        st = await self.catch_block.tick(bb, tb)
+        if st is Status.RUNNING:
+            return Status.RUNNING
+        self._use_catch = False
+        return await self._finish(bb, st, tb)
+
+
 # ======================================================================================
 # Authoring DSL (NodeSpec + bt namespace)
 # ======================================================================================
@@ -1018,6 +1173,7 @@ class NodeSpecKind(Enum):
     SUBTREE = "subtree"
     MATCH = "match"
     DO_WHILE = "do_while"
+    TRY_CATCH = "try_catch"
 
 
 class _DefaultCase:
@@ -1128,6 +1284,16 @@ class NodeSpec:
                     exception_policy=exception_policy,
                 )
 
+            case NodeSpecKind.TRY_CATCH:
+                try_spec = self.payload["try"]
+                catch_spec = self.payload["catch"]
+                return TryCatch(
+                    try_spec.to_node(exception_policy),
+                    catch_spec.to_node(exception_policy),
+                    name=self.name,
+                    exception_policy=exception_policy,
+                )
+
             case _:
                 raise ValueError(f"Unknown spec kind: {self.kind}")
 
@@ -1271,6 +1437,31 @@ class _WrapperChain:
             lambda ch: Gate(cond_spec.to_node(), ch),
         )
 
+    def when(
+        self, condition_spec_or_fn: Union["NodeSpec", Callable[[Any], Any]]
+    ) -> "_WrapperChain":
+        """
+        Add a conditional wrapper that executes the child only when condition is true.
+
+        Unlike gate(), when() returns SUCCESS (not FAILURE) when the condition fails.
+        This allows sequences to continue when optional steps are skipped.
+
+        Args:
+            condition_spec_or_fn: A node spec or callable that returns True/False
+
+        Returns:
+            The chain for further wrapping
+
+        Example:
+            yield bt.when(is_enabled)(optional_action)
+            # If is_enabled is False, returns SUCCESS and sequence continues
+        """
+        cond_spec = bt.as_spec(condition_spec_or_fn)
+        return self._append(
+            f"When(cond={_name_of(cond_spec)})",
+            lambda ch: When(cond_spec.to_node(), ch),
+        )
+
     def __call__(self, inner: Union["NodeSpec", Callable[[Any], Any]]) -> "NodeSpec":
         """
         Apply the chain to a child spec → nested decorator NodeSpecs.
@@ -1342,10 +1533,10 @@ class _MatchBuilder:
 
 class _DoWhileBuilder:
     """Builder for do_while loops."""
-    
+
     def __init__(self, condition_spec: NodeSpec) -> None:
         self._condition_spec = condition_spec
-    
+
     def __call__(self, child: Union["NodeSpec", Callable[[Any], Any]]) -> NodeSpec:
         child_spec = bt.as_spec(child)
         return NodeSpec(
@@ -1404,6 +1595,33 @@ class _BT:
 
             3. Direct call with child nodes:
                 bt.sequence(action1, action2, action3)
+
+        Memory Parameter:
+            The memory parameter controls whether the sequence remembers its position
+            across ticks:
+
+            - memory=None (default): Use the Runner's memory setting
+            - memory=True: Remember position, allowing incremental progress
+            - memory=False: Restart from beginning each tick (reactive behavior)
+
+            IMPORTANT: If a sequence is inside a do_while loop and needs to execute
+            all its children incrementally, use memory=True. Otherwise, the sequence
+            will restart from the first child on every tick and never complete.
+
+            Example:
+                # CORRECT - sequence progresses through children
+                @bt.sequence(memory=True)
+                def process_samples():
+                    yield move_to_sample
+                    yield capture_image
+                yield bt.do_while(samples_remain)(process_samples)
+
+                # WRONG - sequence restarts at move_to_sample every tick
+                @bt.sequence(memory=False)
+                def process_samples():
+                    yield move_to_sample
+                    yield capture_image  # Never reached!
+                yield bt.do_while(samples_remain)(process_samples)
         """
         # Case 3: Direct call with children - bt.sequence(node1, node2, ...)
         # This is detected when we have multiple args, or a single arg that's not a generator function
@@ -1488,6 +1706,9 @@ class _BT:
 
             3. Direct call with child nodes:
                 bt.selector(option1, option2, option3)
+
+        The memory parameter defaults to None, which means use the Runner's memory setting.
+        Explicitly set to True or False to override the Runner's setting.
         """
         # Case 3: Direct call with children - bt.selector(node1, node2, ...)
         # This is detected when we have multiple args, or a single arg that's not a generator function
@@ -1604,6 +1825,28 @@ class _BT:
         cond_spec = self.as_spec(condition)
         return _WrapperChain().gate(cond_spec)
 
+    def when(self, condition: Union[NodeSpec, Callable[[Any], Any]]) -> _WrapperChain:
+        """
+        Create a conditional wrapper that executes the child only when condition is true.
+
+        Unlike gate(), when() returns SUCCESS (not FAILURE) when the condition fails.
+        This is useful for optional steps or feature flags in sequences.
+
+        Args:
+            condition: A node spec or callable that returns True/False
+
+        Returns:
+            A wrapper chain that can be applied to a child node
+
+        Example:
+            @bt.sequence
+            def my_sequence():
+                yield bt.when(feature_enabled)(optional_feature)
+                yield next_step  # Always reached, even if flag is disabled
+        """
+        cond_spec = self.as_spec(condition)
+        return _WrapperChain().when(cond_spec)
+
     def match(
         self, key_fn: Callable[[Any], Any], name: Optional[str] = None
     ) -> "_MatchBuilder":
@@ -1685,6 +1928,62 @@ class _BT:
         cond_spec = self.as_spec(condition)
         return _DoWhileBuilder(cond_spec)
 
+    def try_catch(
+        self, try_block: Union[NodeSpec, Callable[[Any], Any]]
+    ) -> Callable[[Union[NodeSpec, Callable[[Any], Any]]], NodeSpec]:
+        """
+        Create a try-catch error handling pattern.
+
+        Usage:
+            # Define try and catch blocks with explicit memory settings
+            @bt.sequence(memory=True)
+            def try_block():
+                yield action1
+                yield action2
+
+            @bt.sequence(memory=True)
+            def catch_block():
+                yield cleanup
+
+            # Use in the tree
+            @bt.root
+            @bt.sequence
+            def root():
+                yield bt.try_catch(try_block)(catch_block)
+
+        Behavior:
+            1. Execute try block
+            2. If try block returns SUCCESS → return SUCCESS
+            3. If try block returns FAILURE → execute catch block
+            4. Return SUCCESS if either block succeeds, FAILURE if both fail
+
+        This is semantically equivalent to a selector with two children:
+            - First child (try) runs first
+            - Second child (catch) runs only if try fails
+            - Returns SUCCESS if either succeeds
+
+        Args:
+            try_block: The node to try first (pre-defined sequence/selector/etc with explicit memory settings)
+
+        Returns:
+            A callable that accepts a catch block (pre-defined sequence/selector/etc with explicit memory settings)
+        """
+        try_spec = self.as_spec(try_block)
+
+        def catcher(catch_block: Union[NodeSpec, Callable[[Any], Any]]) -> NodeSpec:
+            catch_spec = self.as_spec(catch_block)
+            return NodeSpec(
+                kind=NodeSpecKind.TRY_CATCH,
+                name=f"TryCatch(try={_name_of(try_spec)}, catch={_name_of(catch_spec)})",
+                payload={
+                    "try": try_spec,
+                    "catch": catch_spec,
+                },
+                children=[try_spec, catch_spec],
+            )
+
+        return catcher
+
     def subtree(self, tree: SimpleNamespace) -> NodeSpec:
         """
         Mount another tree's root spec as a subtree.
@@ -1813,6 +2112,8 @@ def _generate_mermaid(tree: SimpleNamespace) -> str:
                 return f"Match<br/>{spec.name}"
             case NodeSpecKind.DO_WHILE:
                 return f"DoWhile<br/>{spec.name}"
+            case NodeSpecKind.TRY_CATCH:
+                return f"TryCatch<br/>{spec.name}"
             case _:
                 return spec.name
 
@@ -1831,6 +2132,9 @@ def _generate_mermaid(tree: SimpleNamespace) -> str:
                 # Children already set (just the body), but we also want to show condition
                 cond_spec = spec.payload["condition"]
                 spec.children = [cond_spec] + spec.children
+            case NodeSpecKind.TRY_CATCH:
+                # Children already set in _TryCatchBuilder
+                pass
         return spec.children
 
     def walk(spec: NodeSpec) -> None:
@@ -1860,10 +2164,24 @@ def _generate_mermaid(tree: SimpleNamespace) -> str:
                 body_id = nid(children[1])
                 lines.append(f'  {this_id} -->|"body"| {body_id}')
                 walk(children[1])
+        elif spec.kind == NodeSpecKind.TRY_CATCH:
+            # First child is try, second is catch
+            try_id = nid(children[0])
+            lines.append(f'  {this_id} -->|"try"| {try_id}')
+            walk(children[0])
+            if len(children) > 1:
+                catch_id = nid(children[1])
+                lines.append(f'  {this_id} -->|"catch"| {catch_id}')
+                walk(children[1])
         else:
-            for child in children:
+            for i, child in enumerate(children, start=1):
                 child_id = nid(child)
-                lines.append(f"  {this_id} --> {child_id}")
+                if spec.kind == NodeSpecKind.PARALLEL:
+                    lines.append(f'  {this_id} -->|"P"| {child_id}')
+                elif spec.kind in (NodeSpecKind.SEQUENCE, NodeSpecKind.SELECTOR):
+                    lines.append(f'  {this_id} -->|"{i}"| {child_id}')
+                else:
+                    lines.append(f"  {this_id} --> {child_id}")
                 walk(child)
 
     walk(tree.root)