mycorrhizal 0.1.0__tar.gz

mycorrhizal-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,70 @@
+# This workflow will upload a Python Package to PyPI when a release is created
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          # NOTE: put your own distribution build steps here.
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    # Dedicated environments with protections for publishing are strongly recommended.
+    # For more information, see: https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules
+    environment:
+      name: pypi
+      # OPTIONAL: uncomment and update to include your PyPI project URL in the deployment status:
+      # url: https://pypi.org/p/YOURPROJECT
+      #
+      # ALTERNATIVE: if your GitHub Release name is the PyPI project version string
+      # ALTERNATIVE: exactly, uncomment the following line instead:
+      # url: https://pypi.org/project/YOURPROJECT/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

mycorrhizal-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+
+**/__pycache__/
+*.claude_todo/
+*.pyc

mycorrhizal-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,188 @@
+# 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/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "mycorrhizal"
+version = "0.1.0"
+description = "Utilities and DSLs for modelling and implementing safe, performant, structured systems"
+readme = "README.md"
+authors = [{ name = "Jeff Ciesielski", email = "jeffciesielski@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "typeguard==4.4.4",
+    "pydantic>=2.11.7",
+]
+
+
+[tool.hatch.build]
+exclude = ["examples/*", "tests/*"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=4.0.0",
+    "pytest-timeout>=2.0.0",    
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--tb=short",
+    "--strict-markers",
+    "--cov=src/mycorrhizal",
+    "--cov-report=term",
+    "--cov-report=html"
+]
+markers = [
+    "slow: marks tests as slow",
+    "integration: marks tests as integration tests",
+    "performance: marks tests as performance tests",
+    "unit: marks tests as unit tests",
+]
+timeout = 30
+
+# Coverage configuration
+[tool.coverage.run]
+source = ["mycorrhizal"]
+omit = ["tests/*", "setup.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+]
+show_missing = false
+skip_covered = true
+precision = 2
+fail_under = 0

mycorrhizal-0.1.0/src/mycorrhizal/__init__.py

@@ -0,0 +1,3 @@
+
+
+

mycorrhizal-0.1.0/src/mycorrhizal/common/__init__.py

@@ -0,0 +1,68 @@
+"""
+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)
+"""
+
+# Import interfaces for easy access
+from mycorrhizal.common.interfaces import (
+    Readable,
+    Writable,
+    FieldAccessor,
+    BlackboardProtocol,
+    FieldMetadata,
+    InterfaceMetadata,
+    validate_implements,
+    get_interface_fields,
+    create_interface_from_model,
+)
+
+# Import wrappers for easy access
+from mycorrhizal.common.wrappers import (
+    AccessControlError,
+    ReadOnlyView,
+    WriteOnlyView,
+    ConstrainedView,
+    CompositeView,
+    create_readonly_view,
+    create_constrained_view,
+    create_view_from_protocol,
+    View,
+)
+
+# Import interface builder for easy access
+from mycorrhizal.common.interface_builder import (
+    blackboard_interface,
+    FieldSpec,
+)
+
+__all__ = [
+    # Interfaces
+    "Readable",
+    "Writable",
+    "FieldAccessor",
+    "BlackboardProtocol",
+    "FieldMetadata",
+    "InterfaceMetadata",
+    "validate_implements",
+    "get_interface_fields",
+    "create_interface_from_model",
+
+    # Wrappers
+    "AccessControlError",
+    "ReadOnlyView",
+    "WriteOnlyView",
+    "ConstrainedView",
+    "CompositeView",
+    "create_readonly_view",
+    "create_constrained_view",
+    "create_view_from_protocol",
+    "View",
+
+    # Interface Builder
+    "blackboard_interface",
+    "FieldSpec",
+]