mycorrhizal 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

mycorrhizal/rhizomorph/core.py

@@ -52,11 +52,13 @@ Multi-file Composition:
 from __future__ import annotations
 
 import asyncio
+import contextvars
 import inspect
 import logging
 import traceback
 from dataclasses import dataclass, field
 from enum import Enum
+from types import ModuleType, SimpleNamespace
 from typing import (
     Any,
     Callable,
@@ -64,60 +66,99 @@ from typing import (
     Generator,
     Generic,
     List,
+    Literal,
     Optional,
     Tuple,
+    Type,
     TypeVar,
     Union,
     Set,
     Protocol,
+    overload,
+    get_type_hints,
+    Sequence as SequenceT,
 )
-from typing import Sequence as SequenceT
-from types import SimpleNamespace
 
+from mycorrhizal.common.wrappers import create_view_from_protocol
+from mycorrhizal.common.compilation import (
+    _get_compiled_metadata,
+    _clear_compilation_cache,
+    CompiledMetadata,
+)
 from mycorrhizal.common.timebase import *
 
 logger = logging.getLogger(__name__)
 
+# Context variable for trace logger
+_trace_logger_ctx: contextvars.ContextVar[Optional[logging.Logger]] = contextvars.ContextVar(
+    "_trace_logger_ctx", default=None
+)
+
 BB = TypeVar("BB")
+F = TypeVar("F", bound=Callable[..., Any])
 
 
 # ======================================================================================
-# Interface Integration Helper
+# Interface View Caching
 # ======================================================================================
 
+# Cache for interface views to avoid repeated creation
+_interface_view_cache: Dict[Tuple[int, Type], Any] = {}
+
+
+def _clear_interface_view_cache() -> None:
+    """Clear the interface view cache. Useful for testing."""
+    global _interface_view_cache
+    _interface_view_cache.clear()
+    # Also clear the compilation cache from common module
+    _clear_compilation_cache()
+
 
 def _create_interface_view_if_needed(bb: Any, func: Callable) -> Any:
     """
     Create a constrained view if the function has an interface type hint on its
-    first parameter (typically named 'bb').
+    blackboard parameter.
 
     This enables type-safe, constrained access to blackboard state based on
     interface definitions created with @blackboard_interface.
 
+    The function signature can use an interface type:
+        async def my_action(bb: MyInterface) -> Status:
+            # bb is automatically a constrained view
+            return Status.SUCCESS
+
     Args:
         bb: The blackboard instance
         func: The function to check for interface type hints
 
     Returns:
         Either the original blackboard or a constrained view based on interface metadata
-    """
-    from typing import get_type_hints
-
-    try:
-        sig = inspect.signature(func)
-        params = list(sig.parameters.values())
 
-        # Check first parameter (usually 'bb')
-        if params and params[0].name == 'bb':
-            bb_type = get_type_hints(func).get('bb')
+    Raises:
+        TypeError: If func is not callable or type hints are malformed
+        AttributeError: If type hints reference undefined types
+    """
+    # Get compiled metadata (uses EAFP pattern internally)
+    # Raises specific exceptions if compilation fails
+    metadata = _get_compiled_metadata(func)
+
+    # If handler has interface type hint, create constrained view
+    if metadata.has_interface and metadata.interface_type:
+        # EAFP: Try to get view from cache, create if not present
+        cache_key = (id(bb), metadata.interface_type)
+        try:
+            return _interface_view_cache[cache_key]
+        except KeyError:
+            # Create view with pre-extracted interface metadata
+            view = create_view_from_protocol(
+                bb,
+                metadata.interface_type,
+                readonly_fields=metadata.readonly_fields
+            )
 
-            # If type hint exists and has interface metadata
-            if bb_type and hasattr(bb_type, '_readonly_fields'):
-                from mycorrhizal.common.wrappers import create_view_from_protocol
-                return create_view_from_protocol(bb, bb_type)
-    except Exception:
-        # If anything goes wrong with type inspection, fall back to original bb
-        pass
+            # Cache for reuse
+            _interface_view_cache[cache_key] = view
+            return view
 
     return bb
 
@@ -136,17 +177,23 @@ def _supports_timebase(func: Callable) -> bool:
         return False
 
 
-async def _call_node_function(func: Callable, bb: Any, tb: Timebase) -> Any:
+async def _call_node_function(func: Callable, bb: Any, tb: Timebase, supports_timebase: bool) -> Any:
     """
     Call a node function with appropriate parameters based on its signature.
 
     If the function has an interface type hint on its 'bb' parameter, a
     constrained view will be created automatically to enforce access control.
+
+    Args:
+        func: The function to call
+        bb: The blackboard
+        tb: The timebase
+        supports_timebase: Cached flag indicating if func accepts 'tb' parameter
     """
     # Create interface view if function has interface type hint
     bb_to_pass = _create_interface_view_if_needed(bb, func)
 
-    if _supports_timebase(func):
+    if supports_timebase:
         if inspect.iscoroutinefunction(func):
             return await func(bb=bb_to_pass, tb=tb)
         else:
@@ -202,6 +249,24 @@ def _name_of(obj: Any) -> str:
     return f"{obj.__class__.__name__}@{id(obj):x}"
 
 
+def _fully_qualified_name(func: Callable[..., Any]) -> str:
+    """
+    Get the fully qualified name of a function.
+
+    Returns module.function_name if the function has a module,
+    otherwise returns just the function name.
+    """
+    name = func.__name__
+    module = getattr(func, "__module__", None)
+    if module:
+        # Handle nested functions by trying to get qualname
+        qualname = getattr(func, "__qualname__", None)
+        if qualname and qualname != name:
+            return f"{module}.{qualname}"
+        return f"{module}.{name}"
+    return name
+
+
 # ======================================================================================
 # Recursion Detection
 # ======================================================================================
@@ -315,11 +380,15 @@ class Action(Node[BB]):
     ) -> None:
         super().__init__(name=_name_of(func), exception_policy=exception_policy)
         self._func = func
+        # Cache whether function supports timebase parameter (checked during construction)
+        self._supports_timebase = _supports_timebase(func)
+        # Cache fully qualified name for tracing
+        self._fq_name = _fully_qualified_name(func)
 
     async def tick(self, bb: BB, tb: Timebase) -> Status:
         await self._ensure_entered(bb, tb)
         try:
-            result = await _call_node_function(self._func, bb, tb)
+            result = await _call_node_function(self._func, bb, tb, self._supports_timebase)
         except asyncio.CancelledError:
             return await self._finish(bb, Status.CANCELLED, tb)
         except Exception as e:
@@ -330,13 +399,20 @@ class Action(Node[BB]):
                 raise
             return await self._finish(bb, Status.ERROR, tb)
 
+        # Determine final status
         if isinstance(result, Status):
-            return await self._finish(bb, result, tb)
-        if isinstance(result, bool):
-            return await self._finish(
-                bb, Status.SUCCESS if result else Status.FAILURE, tb
-            )
-        return await self._finish(bb, Status.SUCCESS, tb)
+            final_status = result
+        elif isinstance(result, bool):
+            final_status = Status.SUCCESS if result else Status.FAILURE
+        else:
+            final_status = Status.SUCCESS
+
+        # 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}")
+
+        return await self._finish(bb, final_status, tb)
 
 
 class Condition(Action[BB]):
@@ -345,7 +421,7 @@ class Condition(Action[BB]):
     async def tick(self, bb: BB, tb: Timebase) -> Status:
         await self._ensure_entered(bb, tb)
         try:
-            result = await _call_node_function(self._func, bb, tb)
+            result = await _call_node_function(self._func, bb, tb, self._supports_timebase)
         except asyncio.CancelledError:
             return await self._finish(bb, Status.CANCELLED, tb)
         except Exception as e:
@@ -356,11 +432,18 @@ class Condition(Action[BB]):
                 raise
             return await self._finish(bb, Status.ERROR, tb)
 
+        # Determine final status
         if isinstance(result, Status):
-            return await self._finish(bb, result, tb)
-        return await self._finish(
-            bb, Status.SUCCESS if bool(result) else Status.FAILURE, tb
-        )
+            final_status = result
+        else:
+            final_status = Status.SUCCESS if bool(result) else Status.FAILURE
+
+        # 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}")
+
+        return await self._finish(bb, final_status, tb)
 
 
 # ======================================================================================
@@ -799,6 +882,8 @@ class Match(Node[BB]):
         for _, child in self._cases:
             child.parent = self
         self._matched_idx: Optional[int] = None
+        # Cache whether key_fn supports timebase parameter
+        self._key_fn_supports_timebase = _supports_timebase(key_fn)
 
     def reset(self) -> None:
         super().reset()
@@ -818,7 +903,7 @@ class Match(Node[BB]):
 
     async def tick(self, bb: BB, tb: Timebase) -> Status:
         await self._ensure_entered(bb, tb)
-        
+
         if self._matched_idx is not None:
             _, child = self._cases[self._matched_idx]
             st = await child.tick(bb, tb)
@@ -826,9 +911,9 @@ class Match(Node[BB]):
                 return Status.RUNNING
             self._matched_idx = None
             return await self._finish(bb, st, tb)
-        
-        value = await _call_node_function(self._key_fn, bb, tb)
-        
+
+        value = await _call_node_function(self._key_fn, bb, tb, self._key_fn_supports_timebase)
+
         for i, (matcher, child) in enumerate(self._cases):
             if self._matches(matcher, value):
                 st = await child.tick(bb, tb)
@@ -836,7 +921,7 @@ class Match(Node[BB]):
                     self._matched_idx = i
                     return Status.RUNNING
                 return await self._finish(bb, st, tb)
-        
+
         return await self._finish(bb, Status.FAILURE, tb)
 
 
@@ -971,7 +1056,6 @@ class NodeSpec:
 
     def to_node(
         self,
-        owner: Optional[Any] = None,
         exception_policy: ExceptionPolicy = ExceptionPolicy.LOG_AND_CONTINUE,
     ) -> Node[Any]:
         match self.kind:
@@ -980,12 +1064,11 @@ class NodeSpec:
             case NodeSpecKind.CONDITION:
                 return Condition(self.payload, exception_policy=exception_policy)
             case NodeSpecKind.SEQUENCE | NodeSpecKind.SELECTOR | NodeSpecKind.PARALLEL:
-                owner_effective = getattr(self, "owner", None) or owner
                 factory = self.payload["factory"]
-                expanded = _bt_expand_children(factory, owner_effective)
+                expanded = _bt_expand_children(factory)
                 self.children = expanded
                 built = [
-                    ch.to_node(owner_effective, exception_policy) for ch in expanded
+                    ch.to_node(exception_policy) for ch in expanded
                 ]
                 match self.kind:
                     case NodeSpecKind.SEQUENCE:
@@ -1013,7 +1096,7 @@ class NodeSpec:
 
             case NodeSpecKind.DECORATOR:
                 assert len(self.children) == 1, "Decorator must wrap exactly one child"
-                child_node = self.children[0].to_node(owner, exception_policy)
+                child_node = self.children[0].to_node(exception_policy)
                 builder = self.payload
                 return builder(child_node)
 
@@ -1025,7 +1108,7 @@ class NodeSpec:
                 key_fn = self.payload["key_fn"]
                 case_specs: List[CaseSpec] = self.payload["cases"]
                 cases = [
-                    (cs.matcher, cs.child.to_node(owner, exception_policy))
+                    (cs.matcher, cs.child.to_node(exception_policy))
                     for cs in case_specs
                 ]
                 return Match(
@@ -1039,8 +1122,8 @@ class NodeSpec:
                 cond_spec = self.payload["condition"]
                 child_spec = self.children[0]
                 return DoWhile(
-                    cond_spec.to_node(owner, exception_policy),
-                    child_spec.to_node(owner, exception_policy),
+                    cond_spec.to_node(exception_policy),
+                    child_spec.to_node(exception_policy),
                     name=self.name,
                     exception_policy=exception_policy,
                 )
@@ -1051,7 +1134,6 @@ class NodeSpec:
 
 def _bt_expand_children(
     factory: Callable[..., Generator[Any, None, None]],
-    owner: Optional[Any],
     expansion_stack: Optional[Set[str]] = None,
 ) -> List[NodeSpec]:
     """
@@ -1059,7 +1141,6 @@ def _bt_expand_children(
 
     Args:
         factory: The generator function that yields child specs
-        owner: The namespace object for resolving N references
         expansion_stack: Stack of factory names to detect recursion
     """
     if expansion_stack is None:
@@ -1080,10 +1161,7 @@ def _bt_expand_children(
     expansion_stack = expansion_stack.copy()
     expansion_stack.add(factory_name)
 
-    try:
-        gen = factory(owner)
-    except TypeError:
-        gen = factory()
+    gen = factory()
 
     if not inspect.isgenerator(gen):
         raise TypeError(
@@ -1119,8 +1197,7 @@ def _bt_expand_children(
             NodeSpecKind.PARALLEL,
         ) and hasattr(spec, "_expansion_stack"):
             child_factory = spec.payload["factory"]
-            child_owner = getattr(spec, "owner", None) or owner
-            _bt_expand_children(child_factory, child_owner, spec._expansion_stack)  # type: ignore
+            _bt_expand_children(child_factory, spec._expansion_stack)  # type: ignore
 
     return out
 
@@ -1309,12 +1386,78 @@ class _BT:
             self._tracking_stack[-1].append((fn.__name__, fn))
         return fn
 
-    def sequence(self, *, memory: bool = True):
-        """Decorator to mark a generator function as a sequence composite."""
+    def sequence(
+        self, *args: Union[F, NodeSpec, Callable[[Any], Any]], memory: bool = True
+    ) -> Union[F, Callable[[F], F], NodeSpec]:
+        """Decorator to mark a generator function as a sequence composite.
+
+        Can be used in three ways:
+            1. Decorator without parentheses:
+                @bt.sequence
+                def root():
+                    ...
+
+            2. Decorator with parameters:
+                @bt.sequence(memory=False)
+                def root():
+                    ...
+
+            3. Direct call with child nodes:
+                bt.sequence(action1, action2, action3)
+        """
+        # 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
+        if len(args) == 0:
+            # Case 2a: bt.sequence() with no arguments - return decorator
+            return self._sequence_impl(memory=memory)
+
+        if len(args) > 1:
+            # Multiple children - create sequence directly
+            return self._sequence_from_children(args, memory)
+
+        # Single argument - check if it's a generator function (decorator case) or a node (direct call)
+        single_arg = args[0]
+
+        # Check if it's a generator function (decorator form)
+        if inspect.isfunction(single_arg) and inspect.isgeneratorfunction(single_arg):
+            # Case 1: @bt.sequence def root(): ...
+            spec = NodeSpec(
+                kind=NodeSpecKind.SEQUENCE,
+                name=_name_of(single_arg),
+                payload={"factory": single_arg, "memory": memory},
+            )
+            single_arg.node_spec = spec  # type: ignore
+            if self._tracking_stack:
+                self._tracking_stack[-1].append((single_arg.__name__, single_arg))
+            return single_arg
+
+        # Case 3b: Single child node - bt.sequence(action1)
+        return self._sequence_from_children(args, memory)
+
+    def _sequence_from_children(self, children: Tuple[Any, ...], memory: bool) -> NodeSpec:
+        """Create a sequence NodeSpec from child nodes."""
+        # Create a uniquely named factory to avoid false recursion detection
+        child_names = ', '.join(_name_of(c) for c in children)
+
+        def _sequence_factory_direct() -> Generator[Any, None, None]:
+            for child in children:
+                yield child
+
+        # Set a unique name for the factory function
+        _sequence_factory_direct.__name__ = f"_sequence_factory_direct_{id(children)}"
+        _sequence_factory_direct.__qualname__ = f"_sequence_factory_direct_{id(children)}"
 
-        def deco(
-            factory: Callable[..., Generator[Any, None, None]],
-        ) -> Callable[..., Generator[Any, None, None]]:
+        name = f"Sequence({child_names})" if children else "Sequence"
+
+        return NodeSpec(
+            kind=NodeSpecKind.SEQUENCE,
+            name=name,
+            payload={"factory": _sequence_factory_direct, "memory": memory},
+        )
+
+    def _sequence_impl(self, memory: bool) -> Callable[[F], F]:
+        """Implementation of sequence decorator."""
+        def deco(factory: F) -> F:
             spec = NodeSpec(
                 kind=NodeSpecKind.SEQUENCE,
                 name=_name_of(factory),
@@ -1327,16 +1470,82 @@ class _BT:
 
         return deco
 
-    def selector(self, *, memory: bool = True, reactive: bool = False):
-        """Decorator to mark a generator function as a selector composite."""
+    def selector(
+        self, *args: Union[F, NodeSpec, Callable[[Any], Any]], memory: bool = True
+    ) -> Union[F, Callable[[F], F], NodeSpec]:
+        """Decorator to mark a generator function as a selector composite.
+
+        Can be used in three ways:
+            1. Decorator without parentheses:
+                @bt.selector
+                def root():
+                    ...
+
+            2. Decorator with parameters:
+                @bt.selector(memory=False)
+                def root():
+                    ...
+
+            3. Direct call with child nodes:
+                bt.selector(option1, option2, option3)
+        """
+        # 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
+        if len(args) == 0:
+            # Case 2a: bt.selector() with no arguments - return decorator
+            return self._selector_impl(memory=memory)
+
+        if len(args) > 1:
+            # Multiple children - create selector directly
+            return self._selector_from_children(args, memory)
+
+        # Single argument - check if it's a generator function (decorator case) or a node (direct call)
+        single_arg = args[0]
+
+        # Check if it's a generator function (decorator form)
+        if inspect.isfunction(single_arg) and inspect.isgeneratorfunction(single_arg):
+            # Case 1: @bt.selector def root(): ...
+            spec = NodeSpec(
+                kind=NodeSpecKind.SELECTOR,
+                name=_name_of(single_arg),
+                payload={"factory": single_arg, "memory": memory},
+            )
+            single_arg.node_spec = spec  # type: ignore
+            if self._tracking_stack:
+                self._tracking_stack[-1].append((single_arg.__name__, single_arg))
+            return single_arg
+
+        # Case 3b: Single child node - bt.selector(action1)
+        return self._selector_from_children(args, memory)
+
+    def _selector_from_children(self, children: Tuple[Any, ...], memory: bool) -> NodeSpec:
+        """Create a selector NodeSpec from child nodes."""
+        # Create a uniquely named factory to avoid false recursion detection
+        child_names = ', '.join(_name_of(c) for c in children)
+
+        def _selector_factory_direct() -> Generator[Any, None, None]:
+            for child in children:
+                yield child
+
+        # Set a unique name for the factory function
+        _selector_factory_direct.__name__ = f"_selector_factory_direct_{id(children)}"
+        _selector_factory_direct.__qualname__ = f"_selector_factory_direct_{id(children)}"
+
+        name = f"Selector({child_names})" if children else "Selector"
+
+        return NodeSpec(
+            kind=NodeSpecKind.SELECTOR,
+            name=name,
+            payload={"factory": _selector_factory_direct, "memory": memory},
+        )
 
-        def deco(
-            factory: Callable[..., Generator[Any, None, None]],
-        ) -> Callable[..., Generator[Any, None, None]]:
+    def _selector_impl(self, memory: bool) -> Callable[[F], F]:
+        """Implementation of selector decorator."""
+        def deco(factory: F) -> F:
             spec = NodeSpec(
                 kind=NodeSpecKind.SELECTOR,
                 name=_name_of(factory),
-                payload={"factory": factory, "memory": memory, "reactive": reactive},
+                payload={"factory": factory, "memory": memory},
             )
             factory.node_spec = spec  # type: ignore
             if self._tracking_stack:
@@ -1347,12 +1556,10 @@ class _BT:
 
     def parallel(
         self, *, success_threshold: int, failure_threshold: Optional[int] = None
-    ):
+    ) -> Callable[[F], F]:
         """Decorator to mark a generator function as a parallel composite."""
 
-        def deco(
-            factory: Callable[..., Generator[Any, None, None]],
-        ) -> Callable[..., Generator[Any, None, None]]:
+        def deco(factory: F) -> F:
             spec = NodeSpec(
                 kind=NodeSpecKind.PARALLEL,
                 name=_name_of(factory),
@@ -1511,8 +1718,8 @@ class _BT:
                     ...
 
                 @bt.sequence()
-                def root(N):
-                    yield N.my_action
+                def root():
+                    yield my_action
         """
         created_nodes = []
         self._tracking_stack.append(created_nodes)
@@ -1526,7 +1733,7 @@ class _BT:
             name: node for name, node in created_nodes if hasattr(node, "node_spec")
         }
         namespace = SimpleNamespace(**nodes)
-        
+
         # Store the tree's name for use in subtree references
         namespace._tree_name = fn.__name__
 
@@ -1542,10 +1749,13 @@ class _BT:
 
         return namespace
 
-    def root(
-        self, fn: Callable[..., Generator[Any, None, None]]
-    ) -> Callable[..., Generator[Any, None, None]]:
+    def root(self, fn: F) -> F:
         """Mark a composite as the root of the tree."""
+        if not hasattr(fn, "node_spec"):
+            raise TypeError(
+                f"@bt.root can only be used on composites (sequences, selectors, etc.), "
+                f"got {fn!r}"
+            )
         fn.node_spec.is_root = True  # type: ignore
         return fn
 
@@ -1609,9 +1819,8 @@ def _generate_mermaid(tree: SimpleNamespace) -> str:
     def ensure_children(spec: NodeSpec) -> List[NodeSpec]:
         match spec.kind:
             case NodeSpecKind.SEQUENCE | NodeSpecKind.SELECTOR | NodeSpecKind.PARALLEL:
-                owner = getattr(spec, "owner", None) or tree
                 factory = spec.payload["factory"]
-                spec.children = _bt_expand_children(factory, owner)
+                spec.children = _bt_expand_children(factory)
             case NodeSpecKind.SUBTREE:
                 subtree_root = spec.payload["root"]
                 spec.children = [subtree_root]
@@ -1677,6 +1886,7 @@ class Runner(Generic[BB]):
         bb: Blackboard containing shared state
         tb: Optional timebase for time management (defaults to MonotonicClock)
         exception_policy: How to handle exceptions during tree execution
+        trace: Optional logger instance for tracing action/condition execution
 
     Methods:
         tick(): Execute one tick of the behavior tree
@@ -1693,6 +1903,14 @@ class Runner(Generic[BB]):
 
         runner = Runner(MyTree, bb=blackboard)
         result = await runner.tick_until_complete()
+
+    Tracing:
+        import logging
+        trace_logger = logging.getLogger("bt.trace")
+        runner = Runner(MyTree, bb=blackboard, trace=trace_logger)
+        result = await runner.tick_until_complete()
+        # Logs: "action: module.do_work | SUCCESS"
+        #       "condition: module.check_condition | SUCCESS"
     """
     def __init__(
         self,
@@ -1700,23 +1918,31 @@ class Runner(Generic[BB]):
         bb: BB,
         tb: Optional[Timebase] = None,
         exception_policy: ExceptionPolicy = ExceptionPolicy.LOG_AND_CONTINUE,
+        trace: Optional[logging.Logger] = None,
     ) -> None:
         self.tree = tree
         self.bb: BB = bb
         self.tb = tb or MonotonicClock()
         self.exception_policy = exception_policy
+        self.trace = trace
 
         if not hasattr(tree, "root"):
             raise ValueError("Tree namespace must have a 'root' attribute")
 
         self.root: Node[BB] = tree.root.to_node(
-            owner=tree, exception_policy=exception_policy
+            exception_policy=exception_policy
         )
 
     async def tick(self) -> Status:
-        result = await self.root.tick(self.bb, self.tb)
-        self.tb.advance()
-        return result
+        # Set trace logger in context for this tick
+        token = _trace_logger_ctx.set(self.trace)
+        try:
+            result = await self.root.tick(self.bb, self.tb)
+            self.tb.advance()
+            return result
+        finally:
+            # Clear the context variable
+            _trace_logger_ctx.reset(token)
 
     async def tick_until_complete(self, timeout: Optional[float] = None) -> Status:
         start = self.tb.now()