mycorrhizal 0.1.0__py3-none-any.whl

mycorrhizal/spores/models.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""
+Spores Data Models
+
+OCEL-compatible data models for event and object logging.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Dict, Optional, Union, Any
+from enum import Enum
+
+
+# ============================================================================
+# OCEL Data Models
+# ============================================================================
+
+@dataclass(frozen=True)
+class Relationship:
+    """
+    A relationship from an event to an object.
+
+    Attributes:
+        object_id: The ID of the related object
+        qualifier: How the object relates to the event (e.g., "input", "output", "actor")
+    """
+    object_id: str
+    qualifier: str
+
+
+@dataclass(frozen=True)
+class EventAttributeValue:
+    """
+    An attribute value for an event.
+
+    OCEL attributes include timestamps for versioning.
+
+    Attributes:
+        name: The attribute name
+        value: The string representation of the value
+        time: When this attribute value was set
+    """
+    name: str
+    value: str
+    time: datetime
+
+
+@dataclass(frozen=True)
+class ObjectAttributeValue:
+    """
+    An attribute value for an object.
+
+    OCEL attributes include timestamps for versioning.
+
+    Attributes:
+        name: The attribute name
+        value: The string representation of the value
+        time: When this attribute value was set
+    """
+    name: str
+    value: str
+    time: datetime
+
+
+@dataclass
+class Event:
+    """
+    An OCEL event representing something that happened.
+
+    Attributes:
+        id: Unique event identifier
+        type: Event type/category
+        time: When the event occurred
+        attributes: Event attributes (name -> EventAttributeValue)
+        relationships: Objects related to this event (qualifier -> Relationship)
+    """
+    id: str
+    type: str
+    time: datetime
+    attributes: Dict[str, EventAttributeValue] = field(default_factory=dict)
+    relationships: Dict[str, Relationship] = field(default_factory=dict)
+
+
+@dataclass
+class Object:
+    """
+    An OCEL object representing an entity in the system.
+
+    Attributes:
+        id: Unique object identifier
+        type: Object type/category
+        attributes: Object attributes (name -> ObjectAttributeValue)
+        relationships: Other objects related to this object (qualifier -> Relationship)
+    """
+    id: str
+    type: str
+    attributes: Dict[str, ObjectAttributeValue] = field(default_factory=dict)
+    relationships: Dict[str, Relationship] = field(default_factory=dict)
+
+
+@dataclass
+class LogRecord:
+    """
+    A log record containing either an event or an object (not both).
+
+    This is the union type used for streaming to OCEL consumers.
+
+    Attributes:
+        event: An event record (if logging an event)
+        object: An object record (if logging an object)
+
+    Note:
+        Exactly one of event or object must be set.
+    """
+    event: Optional[Event] = None
+    object: Optional[Object] = None
+
+    def __post_init__(self):
+        """Validate that exactly one of event or object is set."""
+        if self.event is None and self.object is None:
+            raise ValueError("LogRecord must have either event or object set")
+        if self.event is not None and self.object is not None:
+            raise ValueError("LogRecord cannot have both event and object set")
+
+
+# ============================================================================
+# Spores-Specific Metadata
+# ============================================================================
+
+class ObjectScope(Enum):
+    """Scope for object associations with events."""
+    GLOBAL = "global"  # Included in every event
+    EVENT = "event"    # Only when explicitly requested
+    AUTO = "auto"      # Automatically detected from context
+
+
+@dataclass(frozen=True)
+class ObjectRef:
+    """
+    Metadata annotation for object references in blackboard interfaces.
+
+    Used with typing.Annotated to mark fields as OCEL objects:
+
+        robot: Annotated[Robot, ObjectRef(qualifier="actor", scope=ObjectScope.GLOBAL)]
+
+    Attributes:
+        qualifier: How the object relates to events ("input", "output", "actor", etc.)
+        scope: When to include this object in events
+    """
+    qualifier: str
+    scope: Union[ObjectScope, str] = ObjectScope.EVENT
+
+    def __post_init__(self):
+        """Convert string scope to ObjectScope enum if needed."""
+        if isinstance(self.scope, str):
+            object.__setattr__(self, 'scope', ObjectScope(self.scope))
+
+
+@dataclass(frozen=True)
+class EventAttr:
+    """
+    Metadata annotation for event attributes in blackboard interfaces.
+
+    Used with typing.Annotated to mark fields that should be logged as event attributes:
+
+        mission_id: Annotated[str, EventAttr]
+        battery_level: Annotated[int, EventAttr]
+
+    Attributes:
+        name: Optional custom name for the attribute (defaults to field name)
+    """
+    name: Optional[str] = None
+
+
+# ============================================================================
+# Attribute Value Conversion
+# ============================================================================
+
+def attribute_value_from_python(value: Any, time: datetime) -> EventAttributeValue:
+    """
+    Convert a Python value to an OCEL EventAttributeValue.
+
+    All values are converted to strings per OCEL specification.
+
+    Args:
+        value: The Python value to convert
+        time: The timestamp for this attribute value
+
+    Returns:
+        An EventAttributeValue with string representation
+    """
+    # Handle None
+    if value is None:
+        str_value = "null"
+
+    # Handle enums (use name)
+    elif isinstance(value, Enum):
+        str_value = value.name
+
+    # Handle datetime (ISO format)
+    elif isinstance(value, datetime):
+        str_value = value.isoformat()
+
+    # Handle bool (lowercase true/false)
+    elif isinstance(value, bool):
+        str_value = "true" if value else "false"
+
+    # Handle primitives
+    elif isinstance(value, (str, int, float)):
+        str_value = str(value)
+
+    # Everything else: convert to string
+    else:
+        str_value = str(value)
+
+    return EventAttributeValue(
+        name="",  # Name set by caller
+        value=str_value,
+        time=time
+    )
+
+
+def object_attribute_from_python(value: Any, time: datetime) -> ObjectAttributeValue:
+    """
+    Convert a Python value to an OCEL ObjectAttributeValue.
+
+    Same conversion rules as attribute_value_from_python but for objects.
+
+    Args:
+        value: The Python value to convert
+        time: The timestamp for this attribute value
+
+    Returns:
+        An ObjectAttributeValue with string representation
+    """
+    # Use same conversion logic
+    event_attr = attribute_value_from_python(value, time)
+
+    return ObjectAttributeValue(
+        name=event_attr.name,
+        value=event_attr.value,
+        time=event_attr.time
+    )
+
+
+# ============================================================================
+# Event ID Generation
+# ============================================================================
+
+def generate_event_id() -> str:
+    """
+    Generate a unique event ID.
+
+    Simple implementation using counter. Could be enhanced with UUIDs
+    or more sophisticated schemes.
+
+    Returns:
+        A unique event identifier
+    """
+    import uuid
+    return f"evt-{uuid.uuid4()}"
+
+
+def generate_object_id(obj: Any) -> str:
+    """
+    Generate an object ID from an object.
+
+    Tries to use obj.id if available, otherwise generates a UUID.
+
+    Args:
+        obj: The object to generate an ID for
+
+    Returns:
+        A unique object identifier
+    """
+    # Try to get id attribute
+    if hasattr(obj, 'id'):
+        return str(obj.id)
+
+    # Try Pydantic model's field
+    if hasattr(obj, '__dict__') and 'id' in obj.__dict__:
+        return str(obj.__dict__['id'])
+
+    # Generate UUID-based ID
+    import uuid
+    return f"obj-{uuid.uuid4()}"

mycorrhizal/spores/transport/__init__.py

@@ -0,0 +1,10 @@
+#!/usr/bin/env python3
+"""
+Spores Transports
+
+Transports for sending OCEL LogRecords to various destinations.
+"""
+
+from .base import Transport
+
+__all__ = ['Transport']

mycorrhizal/spores/transport/base.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""
+Spores Transport Interface
+
+Abstract base class for transporting encoded LogRecords.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Protocol, Callable, Optional
+
+
+class Transport(Protocol):
+    """
+    Protocol for transports that send encoded LogRecords.
+
+    Transports handle the actual delivery of log records to consumers
+    (e.g., HTTP POST, files, message queues, etc.).
+    """
+
+    async def send(self, data: bytes, content_type: str) -> None:
+        """
+        Send encoded data to the transport destination.
+
+        Args:
+            data: The encoded log record data
+            content_type: MIME content type (e.g., "application/json")
+        """
+        ...
+
+    def is_async(self) -> bool:
+        """
+        Return True if this transport is async (non-blocking).
+
+        Async transports don't block the caller when sending data.
+        They typically use background threads, queues, or async I/O.
+
+        Returns:
+            True if transport is async, False if synchronous
+        """
+        ...
+
+    def close(self) -> None:
+        """Close the transport and release resources."""
+        ...

mycorrhizal-0.1.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: mycorrhizal
+Version: 0.1.0
+Summary: Utilities and DSLs for modelling and implementing safe, performant, structured systems
+Author-email: Jeff Ciesielski <jeffciesielski@gmail.com>
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: typeguard==4.4.4
+Description-Content-Type: text/markdown
+
+# Mycorrhizal
+
+A Python library for building safe, structured, concurrent, event-driven systems.
+
+## Overview
+
+Mycorrhizal provides four domain-specific languages (DSLs) for modeling and implementing different aspects of complex systems:
+
+* **Hypha** - Colored Petri nets for workflow modeling and orchestration
+* **Rhizomorph** - Behavior trees for decision-making and control logic
+* **Enoki** - Finite state machines for stateful components
+* **Spores** - Event and object logging for observability and process mining
+
+Each DSL can be used independently or combined to build sophisticated systems. All modules share common infrastructure for state management (blackboards) and time abstraction, enabling seamless composition.
+
+## Installation
+
+```bash
+pip install mycorrhizal
+```
+
+Requires Python 3.10 or later.
+
+## Quick Start
+
+### Behavior Tree (Rhizomorph)
+
+Define behavior trees using a decorator-based DSL:
+
+```python
+from mycorrhizal.rhizomorph.core import bt, Runner, Status
+
+@bt.tree
+def ThreatResponse():
+    @bt.action
+    async def assess_threat(bb) -> Status:
+        # Analyze threat level
+        return Status.SUCCESS if bb.threat_level > 5 else Status.FAILURE
+
+    @bt.action
+    async def engage_countermeasures(bb) -> Status:
+        # Respond to threat
+        return Status.SUCCESS
+
+    @bt.root
+    @bt.sequence
+    def root():
+        yield assess_threat
+        yield engage_countermeasures
+
+# Run the behavior tree
+runner = Runner(ThreatResponse, bb=blackboard)
+await runner.tick_until_complete()
+```
+
+### Petri Net (Hypha)
+
+Model workflows with colored Petri nets:
+
+```python
+from mycorrhizal.hypha.core import pn, Runner, PlaceType
+
+@pn.net
+def ProcessingNet(builder):
+    # Define places
+    pending = builder.place("pending", type=PlaceType.QUEUE)
+    processed = builder.place("processed", type=PlaceType.QUEUE)
+
+    # Define transitions
+    @builder.transition()
+    async def process(consumed, bb, timebase):
+        for token in consumed:
+            result = await handle(token)
+            yield {processed: result}
+
+    # Wire the net
+    builder.arc(pending, process).arc(processed)
+
+# Run the Petri net
+runner = Runner(ProcessingNet, bb=blackboard)
+await runner.start(timebase)
+```
+
+### Finite State Machine (Enoki)
+
+Build stateful components with FSMs:
+
+```python
+from mycorrhizal.enoki.core import enoki, StateMachine, LabeledTransition
+
+@enoki.state()
+def IdleState():
+    @enoki.on_state
+    async def on_state(ctx):
+        if ctx.msg == "start":
+            return Events.START
+        return None
+
+    @enoki.transitions
+    def transitions():
+        return [
+            LabeledTransition(Events.START, ProcessingState),
+        ]
+
+# Create and run the FSM
+fsm = StateMachine(initial_state=IdleState, common_data={})
+await fsm.initialize()
+fsm.send_message("start")
+await fsm.tick()
+```
+
+## Key Features
+
+### Shared Infrastructure
+
+All DSLs use common building blocks:
+
+* **Blackboards** - Typed shared state using Pydantic models
+* **Interfaces** - Decorator-based access control for blackboard fields
+* **Timebase** - Abstract time for simulation and testing
+
+### Composition
+
+Combine DSLs to model complex systems:
+
+* Embed behavior trees in Petri net transitions
+* Run state machines within behavior tree actions
+* Use Petri nets to orchestrate FSM-based components
+
+### Observability
+
+The Spores module provides OCEL-compliant logging:
+
+* Automatic event extraction from DSL execution
+* Object lifecycle tracking
+* Transport layer for custom backends
+
+## Examples
+
+The repository contains comprehensive examples:
+
+* `examples/hypha/` - Petri net patterns
+* `examples/rhizomorph/` - Behavior tree patterns
+* `examples/enoki/` - State machine patterns
+* `examples/spores/` - Event logging integration
+* `examples/interfaces/` - Type-safe blackboard access
+
+Run examples with:
+
+```bash
+uv run python examples/hypha/minimal_hypha_demo.py
+```
+
+See [examples/README.md](examples/README.md) for a complete guide.
+
+## Documentation
+
+Full API documentation is available at [docs link here].
+
+## Development
+
+```bash
+# Install dependencies
+uv pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=src/mycorrhizal --cov-report=html
+```
+
+## Project Status
+
+This is a 0.1.0 release. The core APIs are stable and well-tested, but some features are still in development:
+
+* Current: Four DSLs with decorator-based syntax
+* Current: Comprehensive examples and tests
+* Planned: Cross-DSL interoperability layer
+* Planned: Enhanced composition patterns
+
+## License
+
+MIT
+
+## Author
+
+Jeff Ciesielski

mycorrhizal-0.1.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+mycorrhizal/__init__.py,sha256=ajz1GSNU9xYVrFEDSz6Xwg7amWQ_yvW75tQa1ZvRIWc,3
+mycorrhizal/common/__init__.py,sha256=vAL2NZFFVcoGoPlIREKRG0mrgx1prVTGTlWBopJ76Sw,1450
+mycorrhizal/common/interface_builder.py,sha256=rBJzduqZ6EjD9MNGO669BcjkM9mYvsnMG0F1kd1wWaQ,6895
+mycorrhizal/common/interfaces.py,sha256=fWw6bm2ejFmKUnl2pSTiSEwTP0Id8Kowg827_Mqir-s,12261
+mycorrhizal/common/timebase.py,sha256=h8OymApwr_EvpRsfRJb6E5YosHg3jfqToOGAfMlL-Qw,2229
+mycorrhizal/common/wrappers.py,sha256=hdj_1OgWe9RNqGlEkcklQ2j0FFn-AE9h5A55udYTr4o,17794
+mycorrhizal/enoki/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mycorrhizal/enoki/core.py,sha256=17oV8AGTI5aY299nAm3Jtc5iarImT2WPbMIwYE5LRsA,53697
+mycorrhizal/enoki/testing_utils.py,sha256=S19p0nZ0UTfQm-hPHFAWqN9LAdfjL9uQKMFx_gaices,17307
+mycorrhizal/enoki/util.py,sha256=oJ9vmHrbUdX99Rkh7bBeUHFzM5sS3yrtXOTQDA1524I,8434
+mycorrhizal/hypha/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mycorrhizal/hypha/util.py,sha256=tpvjWXTdGhtVUycQElcQg4usOy-tSEqwE9KEni8R30s,906
+mycorrhizal/hypha/core/__init__.py,sha256=o6BE3fhRKjVfyIWwtNTO64kPt0udlZGyXr-ZuN_ZzF8,2518
+mycorrhizal/hypha/core/builder.py,sha256=3oXG235bllLql8v2IiIa9K7ska_e4cHc8tvGGWwWZzA,15210
+mycorrhizal/hypha/core/runtime.py,sha256=K7EDxPTYu9lyHoolBGrrOTws7f1xmbnU2SBVVLnoD3g,34848
+mycorrhizal/hypha/core/specs.py,sha256=-MH4-ast3uxIWns3VpYV9vC_vqfjLCbvj61nbAOImn8,7882
+mycorrhizal/rhizomorph/README.md,sha256=g-G8d00VgMOPriggsNveH7HqLhnJ9HlvoIzrwmUEy_M,8134
+mycorrhizal/rhizomorph/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mycorrhizal/rhizomorph/core.py,sha256=BmgTbnzF2fzYhjQK4iAuO85LHCsN9-dKGok6U8bDv-g,58668
+mycorrhizal/rhizomorph/util.py,sha256=dUgKAWX5RNtzFK01mGkz10tJyeTMCqyyfnZ8Mi97LkY,1280
+mycorrhizal/spores/__init__.py,sha256=y-KPzgUMVXJKjClgQXmsykdWNe2g_U42pWRvdmmCqbg,2836
+mycorrhizal/spores/cache.py,sha256=0FuWHKudgyC7vlrlcJ_kmRKr7OAJuC2gxRURReMlqF4,6119
+mycorrhizal/spores/core.py,sha256=mfo1dQtDeyyYedIiaQ16YPhcBpIe-4wgzWXiMCjIj1I,12310
+mycorrhizal/spores/extraction.py,sha256=YnUGABcVgZVSDCXyOQewWG62NAkdievJrXPIA_eJkxg,14918
+mycorrhizal/spores/models.py,sha256=P5hlBaKmK6pCyLxBwGgPB4U9ef29_9fEoNEbYXJLV6g,7964
+mycorrhizal/spores/dsl/__init__.py,sha256=bkxHTkaPrDWUlU1pjYlGJOM-772M5_k7R4aZ8HaxMNM,1153
+mycorrhizal/spores/dsl/enoki.py,sha256=eVYNBp3ESZ7lK91vE8H5JWkXX14pOtf6cdAWSLiqAsE,15506
+mycorrhizal/spores/dsl/hypha.py,sha256=vcJimWbZT2MmGhj8Lbn3izF1PO9HVJe1YQi5P3EiZ6o,11959
+mycorrhizal/spores/dsl/rhizomorph.py,sha256=ChG2fRQD9DR90dLKLYSQR72asC-7eLccvBwZtz8C8kw,9898
+mycorrhizal/spores/encoder/__init__.py,sha256=hpp1W4xwQUG1N1zdrea0coBPtMf-WYSE77Q780TinP8,204
+mycorrhizal/spores/encoder/base.py,sha256=xFKk-f5_W_HNrOgNXyquUwhcrcz28LmeT5Y5enDVrwU,870
+mycorrhizal/spores/encoder/json.py,sha256=dyQSTXfG0VQPSNt9ed8VEgMwxFUPnLtV6u_bSRuEnNY,4747
+mycorrhizal/spores/transport/__init__.py,sha256=-QYmAwqaTbhrgEXr16qSYWx2f6J22d0SklPlm_Y8RWo,168
+mycorrhizal/spores/transport/base.py,sha256=lJ2sLlXd-ZDeMn3ujSoYTneUB3Zwlz0mpWh5yxKK6Lw,1201
+mycorrhizal-0.1.0.dist-info/METADATA,sha256=fKifHtnUMVeIKv13_kukZ6rtotKusA3m20VSXRr9qK0,4895
+mycorrhizal-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mycorrhizal-0.1.0.dist-info/RECORD,,

mycorrhizal-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any