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

mycorrhizal/{enoki → septum}/testing_utils.py

@@ -1,8 +1,8 @@
 #!/usr/bin/env python3
 """
-Enoki Testing Utilities
+Septum Testing Utilities
 
-Testing infrastructure for the class-method-based Enoki architecture.
+Testing infrastructure for the class-method-based Septum architecture.
 """
 
 import unittest
@@ -13,8 +13,8 @@ import gevent
 from gevent import sleep
 import traceback
 
-# Import the Enoki modules
-from mycorrhizal.enoki import (
+# Import the Septum modules
+from mycorrhizal.septum import (
     State,
     StateMachine,
     StateConfiguration,
@@ -151,8 +151,8 @@ def simulate_state_lifecycle(
     return results
 
 
-class EnokiTestCase(unittest.TestCase):
-    """Base test case class with assertion methods for Enoki FSM testing."""
+class SeptumTestCase(unittest.TestCase):
+    """Base test case class with assertion methods for Septum FSM testing."""
 
     def assertStateTransition(
         self, state_class, expected_transition, context=None, **context_kwargs
@@ -328,7 +328,7 @@ class EnokiTestCase(unittest.TestCase):
         self.assertIsNotNone(timeout_result, "on_timeout should return a transition")
 
 
-class StateMachineTestCase(EnokiTestCase):
+class StateMachineTestCase(SeptumTestCase):
     """Extended test case for testing full StateMachine behavior."""
 
     def assertFSMTransition(

mycorrhizal/{enoki → septum}/util.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 """
-Enoki State Machine Utilities
+Septum State Machine Utilities
 
 Utility functions for FSM operations like Mermaid diagram generation.
 """
@@ -16,6 +16,24 @@ class _TransitionInfo:
     transition_type: str  # "normal", "push", "pop", "again", "retry", etc.
 
 
+def _short_state_name(state_name: str) -> str:
+    """
+    Extract short state name from full qualified name.
+
+    Converts 'examples.septum.network_protocol_fsm.IdleState' to 'IdleState'.
+    Handles edge cases like '<string>.IdleState' gracefully.
+
+    Args:
+        state_name: Full state name with module path
+
+    Returns:
+        Short state name (just the class name)
+    """
+    if "." in state_name:
+        return state_name.rsplit(".", 1)[-1]
+    return state_name
+
+
 def to_mermaid(fsm) -> str:
     """
     Generate Mermaid diagram from a StateMachine instance.
@@ -24,15 +42,15 @@ def to_mermaid(fsm) -> str:
     including special handling for Push/Pop transitions.
 
     Args:
-        fsm: A StateMachine instance (from mycorrhizal.enoki.core)
+        fsm: A StateMachine instance (from mycorrhizal.septum.core)
 
     Returns:
         Mermaid diagram as a string
 
     Example:
         ```python
-        from mycorrhizal.enoki.core import StateMachine
-        from mycorrhizal.enoki.util import to_mermaid
+        from mycorrhizal.septum.core import StateMachine
+        from mycorrhizal.septum.util import to_mermaid
 
         fsm = StateMachine(initial_state=MyState)
         await fsm.initialize()
@@ -43,7 +61,7 @@ def to_mermaid(fsm) -> str:
         ```
     """
     # Import here to avoid circular imports
-    from mycorrhizal.enoki.core import (
+    from mycorrhizal.septum.core import (
         StateSpec,
         StateRef,
         LabeledTransition,
@@ -77,12 +95,12 @@ def to_mermaid(fsm) -> str:
 
     # Add initial state marker
     initial_name = fsm.initial_state.name if isinstance(fsm.initial_state, StateSpec) else str(fsm.initial_state)
-    lines.append(f"    start((start)) --> {nid(initial_name)}")
+    lines.append(f'    start((start)) --> {nid(initial_name)}')
 
     # Add error state if exists
     if fsm.error_state:
         error_name = fsm.error_state.name if isinstance(fsm.error_state, StateSpec) else str(fsm.error_state)
-        lines.append(f"    {nid(error_name)}(((ERROR)))")
+        lines.append(f'    {nid(error_name)}{{"ERROR"}}')
 
     # Collect all transitions
     transitions: Dict[str, List[_TransitionInfo]] = {}
@@ -135,8 +153,9 @@ def to_mermaid(fsm) -> str:
                             # Push transitions - show all states being pushed
                             for push_state in p.push_states:
                                 push_name = push_state.name if isinstance(push_state, StateSpec) else str(push_state)
+                                # Use -> instead of unicode arrow for better compatibility
                                 transitions[state_name].append(
-                                    _TransitionInfo(f"{label.name} → push", push_name, "push")
+                                    _TransitionInfo(f"{label.name}->push", push_name, "push")
                                 )
                         case StateSpec() as target_state:
                             transitions[state_name].append(
@@ -182,39 +201,43 @@ def to_mermaid(fsm) -> str:
             continue
 
         state_id = nid(state_name)
+        short_name = _short_state_name(state_name)
 
         # Determine node shape based on state properties
+        # All nodes use quotes to handle special characters
         if state.config.terminal:
-            shape = f'[{state_name} (**terminal**)]'
+            # Terminal state: use double parentheses and note terminal status
+            lines.append(f'    {state_id}[["{short_name}<br/>terminal"]]')
         elif state_name == initial_name:
-            shape = f'[{state_name}]'
+            # Initial state: normal shape
+            lines.append(f'    {state_id}["{short_name}"]')
         elif fsm.error_state and state_name == (fsm.error_state.name if isinstance(fsm.error_state, StateSpec) else str(fsm.error_state)):
-            shape = f'[{state_name}]'
+            # Error state: use rhombus shape
+            lines.append(f'    {state_id}{{"{short_name}"}}')
         else:
-            shape = f'[{state_name}]'
-
-        lines.append(f"    {state_id}{shape}")
+            # Normal state
+            lines.append(f'    {state_id}["{short_name}"]')
 
         # Add transitions
         for trans in transitions.get(state_name, []):
             if trans.transition_type in ("again", "retry", "repeat", "restart", "unhandled"):
-                # Self-loop
-                label = f'"{trans.transition_type}"' if trans.transition_type else ""
-                lines.append(f"    {state_id} -->|{label}| {state_id}")
+                # Self-loop with transition type
+                lines.append(f'    {state_id} -->|"{trans.transition_type}"| {state_id}')
             elif trans.transition_type == "pop":
                 # Pop goes to a special pop node
-                lines.append(f"    {state_id} -->|\"{trans.label or 'pop'}\"| pop((pop))")
+                label = trans.label if trans.label else "pop"
+                lines.append(f'    {state_id} -->|"{label}"| pop((pop))')
             elif trans.transition_type == "push":
                 # Push transition
                 target_id = nid(trans.target)
-                lines.append(f"    {state_id} -->|\"{trans.label}\"| {target_id}")
+                lines.append(f'    {state_id} -->|"{trans.label}"| {target_id}')
             else:
                 # Normal transition
                 target_id = nid(trans.target)
-                lines.append(f"    {state_id} -->|\"{trans.label}\"| {target_id}")
+                lines.append(f'    {state_id} -->|"{trans.label}"| {target_id}')
 
     # Add pop node if any pop transitions exist
     if any(t.transition_type == "pop" for transs in transitions.values() for t in transs):
-        lines.append("    pop((pop))")
+        lines.append('    pop((pop))')
 
     return "\n".join(lines)

mycorrhizal/spores/__init__.py

@@ -6,22 +6,53 @@ OCEL (Object-Centric Event Log) compatible logging system for tracking events
 and objects in Mycorrhizal systems. Provides automatic extraction of events
 and objects from DSL execution.
 
-Usage:
-    from mycorrhizal.spores import configure, spore, EventAttr, ObjectRef
-
-    # Configure logging
-    configure(
-        enabled=True,
-        object_cache_size=100,
-        transport=FileTransport("logs/ocel.jsonl"),
+Usage (Standalone Event and Object Logging):
+    from mycorrhizal.spores import configure, get_spore_sync, get_spore_async
+    from mycorrhizal.spores.transport import SyncFileTransport, AsyncFileTransport
+    from mycorrhizal.spores.models import SporesAttr
+    from pydantic import BaseModel
+    from typing import Annotated
+
+    # Mark domain model fields for object attribute logging
+    class Order(BaseModel):
+        id: str
+        status: Annotated[str, SporesAttr]
+        total: Annotated[float, SporesAttr]
+
+    # Sync code
+    configure(transport=SyncFileTransport("logs/ocel.jsonl"))
+    spore = get_spore_sync(__name__)
+
+    @spore.log_event(
+        event_type="OrderCreated",
+        relationships={"order": ("return", "Order")},
+    )
+    def create_order(customer: Customer, items: list) -> Order:
+        return Order(...)
+
+    # Async code
+    configure(transport=AsyncFileTransport("logs/ocel.jsonl"))
+    aspore = get_spore_async(__name__)
+
+    @aspore.log_event(
+        event_type="OrderCreated",
+        relationships={"order": ("return", "Order")},
     )
+    async def create_order_async(customer: Customer, items: list) -> Order:
+        return Order(...)
+
+Usage (DSL Adapters):
+    from mycorrhizal.spores import configure, spore
+    from mycorrhizal.spores.models import EventAttr, ObjectRef, ObjectScope
+    from pydantic import BaseModel
+    from typing import Annotated
 
-    # Mark model fields for automatic extraction
+    # Mark blackboard fields for event attribute extraction
     class MissionContext(BaseModel):
         mission_id: Annotated[str, EventAttr]
         robot: Annotated[Robot, ObjectRef(qualifier="actor", scope=ObjectScope.GLOBAL)]
 
-    # Mark object types
+    # Mark object types for logging
     @spore.object(object_type="Robot")
     class Robot(BaseModel):
         id: str
@@ -30,14 +61,17 @@ Usage:
 DSL Adapters:
     HyphaAdapter - Log Petri net transitions with token relationships
     RhizomorphAdapter - Log behavior tree node execution with status
-    EnokiAdapter - Log state machine execution and lifecycle events
+    SeptumAdapter - Log state machine execution and lifecycle events
+
+Annotation Types:
+    EventAttr - Mark blackboard fields for automatic event attribute extraction (DSL adapters)
+    SporesAttr - Mark domain model fields for automatic object attribute logging (log_event)
+    ObjectRef - Mark blackboard fields as object references with scope
 
 Key Concepts:
     Event - Something that happens at a point in time with attributes
     Object - An entity with a type and attributes
     Relationship - Link between events and objects (e.g., "actor", "target")
-    EventAttr - Mark blackboard fields for automatic event attribute extraction
-    ObjectRef - Mark blackboard fields as object references with scope
 
 Object Scopes:
     EVENT - Object exists only for this event (default)
@@ -48,8 +82,13 @@ from .core import (
     configure,
     get_config,
     get_object_cache,
+    get_spore_sync,
+    get_spore_async,
     spore,
     SporesConfig,
+    EventLogger,
+    AsyncEventLogger,
+    SyncEventLogger,
 )
 
 from .models import (
@@ -62,6 +101,7 @@ from .models import (
     ObjectRef,
     ObjectScope,
     EventAttr,
+    SporesAttr,
     generate_event_id,
     generate_object_id,
     attribute_value_from_python,
@@ -71,17 +111,20 @@ from .models import (
 from .cache import ObjectLRUCache
 
 from .encoder import Encoder, JSONEncoder
-from .transport import Transport
+from .transport import SyncTransport, AsyncTransport, Transport, SyncFileTransport, AsyncFileTransport
 
 # DSL adapters
 from .dsl import (
     HyphaAdapter,
     RhizomorphAdapter,
-    EnokiAdapter,
+    SeptumAdapter,
 )
 
 
-__version__ = "0.1.0"
+try:
+    from mycorrhizal._version import version as __version__
+except ImportError:
+    __version__ = "0.0.0+dev"
 
 
 __all__ = [
@@ -89,7 +132,12 @@ __all__ = [
     'configure',
     'get_config',
     'get_object_cache',
-    'spore',
+    'get_spore_sync',
+    'get_spore_async',
+    'EventLogger',
+    'AsyncEventLogger',
+    'SyncEventLogger',
+    'spore',  # For DSL adapters and @spore.object() decorator
     'SporesConfig',
 
     # Models
@@ -102,6 +150,7 @@ __all__ = [
     'ObjectRef',
     'ObjectScope',
     'EventAttr',
+    'SporesAttr',
     'generate_event_id',
     'generate_object_id',
     'attribute_value_from_python',
@@ -115,10 +164,14 @@ __all__ = [
     'JSONEncoder',
 
     # Transport
-    'Transport',
+    'SyncTransport',
+    'AsyncTransport',
+    'Transport',  # Alias for AsyncTransport (backward compatibility)
+    'SyncFileTransport',
+    'AsyncFileTransport',
 
     # DSL Adapters
     'HyphaAdapter',
     'RhizomorphAdapter',
-    'EnokiAdapter',
+    'SeptumAdapter',
 ]