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

mycorrhizal/_version.py

@@ -1 +1 @@
-version = "0.1.2"
+version = "0.2.1"

mycorrhizal/common/__init__.py

@@ -4,7 +4,7 @@ Common utilities and interfaces for Mycorrhizal.
 This module provides shared components used across all three DSL systems:
 - Hypha (Petri Nets)
 - Rhizomorph (Behavior Trees)
-- Enoki (State Machines)
+- Septum (State Machines)
 """
 
 # Import interfaces for easy access
@@ -15,7 +15,6 @@ from mycorrhizal.common.interfaces import (
     BlackboardProtocol,
     FieldMetadata,
     InterfaceMetadata,
-    validate_implements,
     get_interface_fields,
     create_interface_from_model,
 )
@@ -39,6 +38,14 @@ from mycorrhizal.common.interface_builder import (
     FieldSpec,
 )
 
+# Import mermaid formatting utilities for easy access
+from mycorrhizal.common.mermaid import (
+    format_state_node,
+    format_transition,
+    format_subgraph,
+    format_comment,
+)
+
 __all__ = [
     # Interfaces
     "Readable",
@@ -47,7 +54,6 @@ __all__ = [
     "BlackboardProtocol",
     "FieldMetadata",
     "InterfaceMetadata",
-    "validate_implements",
     "get_interface_fields",
     "create_interface_from_model",
 
@@ -65,4 +71,10 @@ __all__ = [
     # Interface Builder
     "blackboard_interface",
     "FieldSpec",
+
+    # Mermaid formatting
+    "format_state_node",
+    "format_transition",
+    "format_subgraph",
+    "format_comment",
 ]

mycorrhizal/common/cache.py

@@ -0,0 +1,114 @@
+"""
+Shared cache implementations for mycorrhizal runtimes.
+
+Provides LRU cache implementations for use across Hypha, Rhizomorph, and Septum.
+"""
+from collections import OrderedDict
+from typing import Any, Dict, Tuple, Type, Optional
+
+
+class InterfaceViewCache:
+    """
+    LRU cache for interface views bounded by maximum size.
+
+    This cache stores interface view objects keyed by (blackboard_id, interface_type, readonly_fields).
+    Uses OrderedDict for manual LRU tracking with bounded size.
+
+    Thread-safety: Safe for single reader/writer (async environments).
+    For multi-threaded environments, external synchronization is required.
+
+    Example:
+        cache = InterfaceViewCache(maxsize=256)
+        view = cache.get_or_create(bb_id, interface_type, readonly_fields, creator_func)
+        stats = cache.get_stats()
+    """
+
+    def __init__(self, maxsize: int = 256):
+        """
+        Initialize the LRU cache.
+
+        Args:
+            maxsize: Maximum number of entries to cache. Defaults to 256.
+        """
+        self._maxsize = maxsize
+        self._cache: OrderedDict[Tuple[int, Type, Tuple[str, ...]], Any] = OrderedDict()
+        self._hits = 0
+        self._misses = 0
+
+    def get_or_create(
+        self,
+        bb_id: int,
+        interface_type: Type,
+        readonly_fields: Optional[Tuple[str, ...]],
+        creator_func: callable
+    ) -> Any:
+        """
+        Get cached view or create using provided function.
+
+        Args:
+            bb_id: ID of blackboard (from id() builtin)
+            interface_type: The interface protocol class
+            readonly_fields: Tuple of readonly field names
+            creator_func: Function that creates the view if not cached
+
+        Returns:
+            The cached or newly created interface view
+        """
+        # Create cache key from hashable components
+        readonly_fields_tuple = tuple(sorted(readonly_fields)) if readonly_fields else ()
+        cache_key = (bb_id, interface_type, readonly_fields_tuple)
+
+        # Check cache
+        if cache_key in self._cache:
+            # Cache hit - move to end (most recently used)
+            self._cache.move_to_end(cache_key)
+            self._hits += 1
+            return self._cache[cache_key]
+
+        # Cache miss - create view and cache it
+        self._misses += 1
+        view = creator_func()
+
+        # Add to cache and move to end
+        self._cache[cache_key] = view
+        self._cache.move_to_end(cache_key)
+
+        # Evict oldest entry if over limit
+        if len(self._cache) > self._maxsize:
+            self._cache.popitem(last=False)
+
+        return view
+
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get cache statistics for monitoring and debugging.
+
+        Returns:
+            Dict with current cache size, maxsize, and hit/miss counts
+        """
+        return {
+            'cached_views': len(self._cache),
+            'maxsize': self._maxsize,
+            'hits': self._hits,
+            'misses': self._misses,
+        }
+
+    def clear(self) -> None:
+        """
+        Clear all cached entries and reset statistics.
+
+        Useful for testing and memory management.
+        """
+        self._cache.clear()
+        self._hits = 0
+        self._misses = 0
+
+    @property
+    def maxsize(self) -> int:
+        """Get maximum cache size."""
+        return self._maxsize
+
+    @property
+    def size(self) -> int:
+        """Get current cache size."""
+        return len(self._cache)

mycorrhizal/common/compilation.py

@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+"""
+Common Compilation Cache for DSL Systems
+
+This module provides a shared compilation cache for all Mycorrhizal DSL systems
+(Rhizomorph, Septum, Hypha) to eliminate redundant runtime type inspection overhead.
+
+The compilation cache stores pre-computed interface metadata for functions, including:
+- Interface type detection (Protocol-based)
+- Readonly and readwrite field extraction
+- Parameter type analysis
+
+This module uses type-based blackboard detection instead of parameter name matching,
+making it more robust and type-safe.
+"""
+
+from __future__ import annotations
+
+import inspect
+from dataclasses import dataclass
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Optional,
+    Set,
+    Type,
+    get_type_hints,
+)
+
+
+# ======================================================================================
+# Compiled Metadata
+# ======================================================================================
+
+
+@dataclass(frozen=True)
+class CompiledMetadata:
+    """
+    Pre-computed interface metadata for a function.
+
+    This dataclass stores the results of type inspection so that we don't need
+    to inspect function signatures at runtime. Metadata is compiled lazily on
+    first use and then cached globally.
+
+    Attributes:
+        has_interface: Whether the function has an interface type hint
+        interface_type: The interface Protocol type (if any)
+        readonly_fields: Set of readonly field names from the interface
+        readwrite_fields: Set of readwrite field names from the interface
+        bb_param_index: Index of the blackboard parameter in function signature
+    """
+    has_interface: bool
+    interface_type: Optional[Type]
+    readonly_fields: Optional[Set[str]] = None
+    readwrite_fields: Optional[Set[str]] = None
+    bb_param_index: int = 0
+
+
+# ======================================================================================
+# Global Compilation Cache
+# ======================================================================================
+
+_compilation_cache: Dict[int, CompiledMetadata] = {}
+
+
+def _clear_compilation_cache() -> None:
+    """Clear the global compilation cache. Useful for testing."""
+    global _compilation_cache
+    _compilation_cache.clear()
+
+
+def _get_compilation_cache_size() -> int:
+    """Get the current size of the compilation cache (for debugging)."""
+    return len(_compilation_cache)
+
+
+# ======================================================================================
+# Compilation Functions
+# ======================================================================================
+
+
+def _compile_function_metadata(
+    func: Callable,
+    bb_param_name: str = "bb",
+    ctx_param_name: str = "ctx",
+) -> CompiledMetadata:
+    """
+    Compile function metadata by inspecting type hints and extracting interface information.
+
+    This function performs the expensive type inspection operations once, so that
+    the compiled metadata can be cached and reused without repeated inspection.
+
+    The function uses type-based blackboard detection:
+    - Checks if the parameter type is a Protocol with interface metadata
+    - Does NOT rely on parameter names (more type-safe)
+
+    Args:
+        func: The function to inspect
+        bb_param_name: Expected blackboard parameter name (for Rhizomorph/Hypha)
+        ctx_param_name: Expected context parameter name (for Septum)
+
+    Returns:
+        CompiledMetadata with pre-extracted interface information
+
+    Raises:
+        TypeError: If the function is not callable
+        NameError: If type hints reference undefined types
+        AttributeError: If type hints reference undefined attributes
+    """
+    # Validate input
+    if not callable(func):
+        raise TypeError(f"Expected callable, got {type(func).__name__}")
+
+    # Get function name for error messages (handle callables without __name__)
+    func_name = getattr(func, '__name__', repr(func))
+
+    try:
+        sig = inspect.signature(func)
+
+        # Try to get type hints, but handle callable objects that don't support it
+        try:
+            hints = get_type_hints(func)
+        except TypeError:
+            # Callable objects (like TransitionRuntimeWrapper) may not support get_type_hints
+            # Return metadata without interface in this case
+            return CompiledMetadata(
+                has_interface=False,
+                interface_type=None,
+                readonly_fields=None,
+                readwrite_fields=None,
+                bb_param_index=0,
+            )
+
+        params = list(sig.parameters.values())
+
+        has_interface = False
+        interface_type = None
+        readonly_fields = None
+        readwrite_fields = None
+        bb_param_index = 0
+
+        # Find the blackboard/context parameter by TYPE, not by NAME
+        for idx, param in enumerate(params):
+            param_type = hints.get(param.name)
+
+            if param_type is None:
+                continue
+
+            # Check for Protocol with interface metadata
+            # This works for both direct Protocol types and generic types like SharedContext[Interface]
+            if _has_interface_metadata(param_type):
+                has_interface = True
+                interface_type = param_type
+                bb_param_index = idx
+
+                # Extract interface fields
+                # For generic types, extract the type argument
+                actual_type = _extract_generic_type_arg(param_type)
+                if actual_type and _has_interface_metadata(actual_type):
+                    # For generic types, use the extracted type for the interface
+                    interface_type = actual_type
+                    readonly_fields = getattr(actual_type, '_readonly_fields', set())
+                    readwrite_fields = getattr(actual_type, '_readwrite_fields', set())
+                else:
+                    # For direct Protocol types
+                    readonly_fields = getattr(param_type, '_readonly_fields', set())
+                    readwrite_fields = getattr(param_type, '_readwrite_fields', set())
+
+                break
+
+        return CompiledMetadata(
+            has_interface=has_interface,
+            interface_type=interface_type,
+            readonly_fields=readonly_fields,
+            readwrite_fields=readwrite_fields,
+            bb_param_index=bb_param_index,
+        )
+
+    except (TypeError, NameError, AttributeError) as e:
+        # Re-raise expected exceptions with better context
+        raise type(e)(
+            f"Failed to compile metadata for {func_name}: {e}"
+        ) from e
+
+
+def _has_interface_metadata(type_hint: Any) -> bool:
+    """
+    Check if a type hint has interface metadata (readonly/readwrite fields).
+
+    Args:
+        type_hint: A type hint from get_type_hints()
+
+    Returns:
+        True if the type has _readonly_fields attribute (interface metadata)
+    """
+    # For generic types (like SharedContext[Interface]), extract the type argument
+    actual_type = _extract_generic_type_arg(type_hint)
+    if actual_type:
+        return hasattr(actual_type, '_readonly_fields')
+
+    # For direct Protocol types
+    return hasattr(type_hint, '_readonly_fields')
+
+
+def _extract_generic_type_arg(type_hint: Any) -> Optional[Type]:
+    """
+    Extract the type argument from a generic type.
+
+    For example:
+    - SharedContext[MyInterface] -> MyInterface
+    - list[MyType] -> MyType
+    - dict[str, int] -> None (not a single-type generic)
+
+    Args:
+        type_hint: A type hint from get_type_hints()
+
+    Returns:
+        The extracted type argument, or None if not a single-type generic
+    """
+    # Check if type has __args__ (generic type)
+    if not hasattr(type_hint, '__args__'):
+        return None
+
+    args = type_hint.__args__
+    if not args or len(args) != 1:
+        return None
+
+    return args[0]
+
+
+def _get_compiled_metadata(func: Callable) -> CompiledMetadata:
+    """
+    Get compiled metadata for a function, using write-through cache with EAFP pattern.
+
+    This function checks the global compilation cache first using try/except
+    (EAFP - Easier to Ask for Forgiveness than Permission), which is faster
+    than inclusion checks in Python.
+
+    If the function's metadata hasn't been compiled yet, it compiles it and
+    writes it to the cache.
+
+    Args:
+        func: The function to get metadata for
+
+    Returns:
+        CompiledMetadata for the function
+
+    Raises:
+        TypeError: If func is not callable
+        ValueError: If type hints are malformed
+        AttributeError: If type hints reference undefined types
+    """
+    func_id = id(func)
+
+    # EAFP pattern: try to get from cache, handle miss
+    try:
+        return _compilation_cache[func_id]
+    except KeyError:
+        # Cache miss - compile and write through
+        metadata = _compile_function_metadata(func)
+        _compilation_cache[func_id] = metadata
+        return metadata

mycorrhizal/common/interface_detection.py

@@ -0,0 +1,159 @@
+"""
+Automatic interface view creation for Mycorrhizal DSLs.
+
+This module provides utilities to automatically detect interface types
+in function signatures and create constrained views, ensuring type-safe
+access control without requiring manual view creation.
+"""
+from typing import Any, Callable, Type, TypeVar, get_type_hints
+from inspect import signature, Parameter
+from functools import lru_cache
+
+from mycorrhizal.common.wrappers import create_view_from_protocol
+
+
+# Cache for interface detection to avoid repeated introspection
+_interface_cache: dict[Type, bool] = {}
+
+
+def is_interface_type(t: Type) -> bool:
+    """
+    Check if a type is a blackboard interface.
+
+    Interfaces are marked by the presence of _readonly_fields and
+    _readwrite_fields attributes added by @blackboard_interface.
+
+    Args:
+        t: Type to check
+
+    Returns:
+        True if t is a blackboard interface, False otherwise
+    """
+    if t in _interface_cache:
+        return _interface_cache[t]
+
+    result = (
+        hasattr(t, '_readonly_fields') and
+        hasattr(t, '_readwrite_fields') and
+        callable(t)  # Interfaces are also protocols
+    )
+    _interface_cache[t] = result
+    return result
+
+
+def get_interface_parameters(func: Callable) -> dict[str, Type]:
+    """
+    Extract parameters with interface types from a function signature.
+
+    Args:
+        func: Function to inspect
+
+    Returns:
+        Dictionary mapping parameter names to their interface types
+    """
+    interface_params = {}
+
+    try:
+        type_hints = get_type_hints(func)
+        sig = signature(func)
+
+        for param_name, param in sig.parameters.items():
+            if param_name == 'bb':
+                # Skip the bb parameter itself (will be replaced)
+                continue
+
+            if param_name in type_hints:
+                param_type = type_hints[param_name]
+                if is_interface_type(param_type):
+                    interface_params[param_name] = param_type
+    except (ValueError, TypeError):
+        # get_type_hints can fail for some functions
+        pass
+
+    return interface_params
+
+
+def create_interface_views(
+    bb: Any,
+    func: Callable,
+    view_cache: dict[int, dict[Type, Any]] | None = None
+) -> dict[str, tuple[Any, Type]]:
+    """
+    Create interface views for a function based on its signature.
+
+    Inspects the function's type hints and automatically creates
+    constrained views for any parameters typed as interfaces.
+
+    Args:
+        bb: The blackboard to wrap
+        func: The function whose signature will be inspected
+        view_cache: Optional cache mapping (bb_id, interface_type) -> view
+
+    Returns:
+        Dictionary mapping parameter names to (view, interface_type) tuples
+    """
+    interface_views = {}
+
+    if view_cache is None:
+        view_cache = {}
+
+    bb_id = id(bb)
+
+    interface_params = get_interface_parameters(func)
+
+    for param_name, interface_type in interface_params.items():
+        # Check cache first
+        cache_key = (bb_id, interface_type)
+        if cache_key in view_cache:
+            view = view_cache[cache_key]
+        else:
+            # Create new view
+            readonly_fields = getattr(interface_type, '_readonly_fields', set())
+            view = create_view_from_protocol(
+                bb,
+                interface_type,
+                readonly_fields=readonly_fields
+            )
+            view_cache[cache_key] = view
+
+        interface_views[param_name] = (view, interface_type)
+
+    return interface_views
+
+
+def prepare_function_args(
+    bb: Any,
+    func: Callable,
+    view_cache: dict[int, dict[Type, Any]] | None = None
+) -> dict[str, Any]:
+    """
+    Prepare function arguments, creating interface views as needed.
+
+    This function:
+    1. Inspects the function signature for interface-typed parameters
+    2. Creates constrained views for those parameters
+    3. Returns a dict of arguments ready to pass to the function
+
+    Args:
+        bb: The blackboard
+        func: The function to call
+        view_cache: Optional cache for created views
+
+    Returns:
+        Dictionary of parameter names to values (views or original values)
+    """
+    interface_views = create_interface_views(bb, func, view_cache)
+    return {name: view for name, (view, _) in interface_views.items()}
+
+
+def should_wrap_with_interface(func: Callable) -> bool:
+    """
+    Check if a function has any interface-typed parameters.
+
+    Args:
+        func: Function to check
+
+    Returns:
+        True if function has interface parameters, False otherwise
+    """
+    return len(get_interface_parameters(func)) > 0

mycorrhizal/common/interfaces.py

@@ -2,7 +2,7 @@
 Blackboard Interface System
 
 This module provides Protocol-based interfaces for type-safe, constrained access
-to blackboard state across Mycorrhizal's three DSL systems (Hypha, Rhizomorph, Enoki).
+to blackboard state across Mycorrhizal's three DSL systems (Hypha, Rhizomorph, Septum).
 
 Key concepts:
 - Protocols: Structural subtyping for interface definitions
@@ -10,6 +10,7 @@ Key concepts:
 - Composition: Combine multiple interfaces into larger ones
 """
 
+import typing
 from typing import Protocol, TypeVar, Generic, Any, runtime_checkable, runtime_checkable
 from typing import Optional, get_type_hints, Union
 from dataclasses import dataclass, field
@@ -254,56 +255,9 @@ def _extract_interface_metadata(
 
 
 # ============================================================================
-# Protocol Helper Functions
+# Interface Field Extraction
 # ============================================================================
 
-def validate_implements(cls: type, protocol: type) -> bool:
-    """
-    Validate that a class implements a protocol.
-
-    Uses structural subtyping to check if the class has all required
-    methods and attributes defined by the protocol.
-
-    Args:
-        cls: The class to check
-        protocol: The protocol to check against
-
-    Returns:
-        True if cls implements protocol, False otherwise
-
-    Example:
-        >>> class MyBlackboard:
-        ...     def validate(self) -> bool:
-        ...         return True
-        ...     def to_dict(self) -> dict:
-        ...         return {}
-        >>> validate_implements(MyBlackboard, BlackboardProtocol)
-        True
-        >>> validate_implements(str, BlackboardProtocol)
-        False
-    """
-    if not isinstance(protocol, type) or not hasattr(protocol, '__protocol_attrs__'):
-        # Not a protocol, try anyway with isinstance
-        try:
-            return issubclass(cls, protocol) if isinstance(cls, type) else isinstance(cls, protocol)
-        except TypeError:
-            return False
-
-    # Check if protocol is runtime_checkable
-    if not hasattr(protocol, '__is_protocol__'):
-        return False
-
-    # Use isinstance if we have an instance, otherwise check structure
-    try:
-        # For protocols, we need to check if the class has all protocol attributes
-        for attr in getattr(protocol, '__protocol_attrs__', []):
-            if not hasattr(cls, attr):
-                return False
-        return True
-    except Exception:
-        return False
-
-
 def get_interface_fields(interface: type) -> dict[str, type]:
     """
     Extract field type annotations from an interface.
@@ -405,7 +359,6 @@ __all__ = [
     "InterfaceMetadata",
 
     # Helper Functions
-    "validate_implements",
     "get_interface_fields",
     "create_interface_from_model",
     "_extract_interface_metadata",