semantic-state-machine-graphable 0.1.4__tar.gz

semantic_state_machine_graphable-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard West
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

semantic_state_machine_graphable-0.1.4/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: semantic-state-machine-graphable
+Version: 0.1.4
+Summary: A library for visualizing semantic-state-machine structures and AuditContext execution paths as graphs using graphable.
+Keywords: state-machine,graphable,visualization,audit,type-safety
+Author: Richard West
+Author-email: Richard West <dopplereffect.us@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Dist: graphable>=0.6.1
+Requires-Dist: semantic-state-machine>=0.1.0
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/TheTrueSCU/semantic-state-machine-graphable
+Project-URL: Repository, https://github.com/TheTrueSCU/semantic-state-machine-graphable
+Project-URL: Issues, https://github.com/TheTrueSCU/semantic-state-machine-graphable/issues
+Description-Content-Type: text/markdown
+
+# semantic-state-machine-graphable
+
+A library for visualizing `semantic-state-machine` structures and `AuditContext` execution paths as graphs using `graphable`.
+
+## Features
+- **StateMachineGraph**: Visualize the static structure of a `semantic-state-machine.StateMachine`.
+- **AuditContextGraph**: Visualize the execution history of an `AuditContext` as a graph, with edges annotated by transition indices.
+
+## Installation
+
+### For Development
+The project is managed with `uv`. To install dependencies:
+```bash
+uv sync
+```
+
+### From PyPI
+```bash
+pip install semantic-state-machine-graphable
+```
+
+## Testing
+The project uses `pytest` for testing. Run the test suite with coverage reporting:
+```bash
+PYTHONPATH=src uv run pytest --cov=semantic_state_machine_graphable --cov-report=term-missing
+```
+
+## Usage
+
+### State Machine Visualization
+```python
+from semantic_state_machine import StateMachine
+from semantic_state_machine_graphable.graph import StateMachineGraph
+
+sm = StateMachine(...)
+sm.add_transition(...)
+
+graph = StateMachineGraph(sm)
+# Now visualize or export the graph
+```
+
+### Execution Path Visualization
+```python
+from semantic_state_machine import AuditedStateMachine, AuditContext
+from semantic_state_machine_graphable.graph import AuditContextGraph
+
+sm = AuditedStateMachine(...)
+ctx = AuditContext(...)
+# ... execute transitions ...
+
+graph = AuditContextGraph(ctx, sm)
+# Now visualize or export the execution path graph
+```
+
+## License
+This project is licensed under the MIT License.

semantic_state_machine_graphable-0.1.4/README.md

@@ -0,0 +1,56 @@
+# semantic-state-machine-graphable
+
+A library for visualizing `semantic-state-machine` structures and `AuditContext` execution paths as graphs using `graphable`.
+
+## Features
+- **StateMachineGraph**: Visualize the static structure of a `semantic-state-machine.StateMachine`.
+- **AuditContextGraph**: Visualize the execution history of an `AuditContext` as a graph, with edges annotated by transition indices.
+
+## Installation
+
+### For Development
+The project is managed with `uv`. To install dependencies:
+```bash
+uv sync
+```
+
+### From PyPI
+```bash
+pip install semantic-state-machine-graphable
+```
+
+## Testing
+The project uses `pytest` for testing. Run the test suite with coverage reporting:
+```bash
+PYTHONPATH=src uv run pytest --cov=semantic_state_machine_graphable --cov-report=term-missing
+```
+
+## Usage
+
+### State Machine Visualization
+```python
+from semantic_state_machine import StateMachine
+from semantic_state_machine_graphable.graph import StateMachineGraph
+
+sm = StateMachine(...)
+sm.add_transition(...)
+
+graph = StateMachineGraph(sm)
+# Now visualize or export the graph
+```
+
+### Execution Path Visualization
+```python
+from semantic_state_machine import AuditedStateMachine, AuditContext
+from semantic_state_machine_graphable.graph import AuditContextGraph
+
+sm = AuditedStateMachine(...)
+ctx = AuditContext(...)
+# ... execute transitions ...
+
+graph = AuditContextGraph(ctx, sm)
+# Now visualize or export the execution path graph
+```
+
+## License
+This project is licensed under the MIT License.

semantic_state_machine_graphable-0.1.4/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "semantic-state-machine-graphable"
+version = "0.1.4"
+description = "A library for visualizing semantic-state-machine structures and AuditContext execution paths as graphs using graphable."
+readme = "README.md"
+authors = [
+    { name = "Richard West", email = "dopplereffect.us@gmail.com" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["state-machine", "graphable", "visualization", "audit", "type-safety"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+requires-python = ">=3.13"
+dependencies = [
+    "graphable>=0.6.1",
+    "semantic-state-machine>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/TheTrueSCU/semantic-state-machine-graphable"
+Repository = "https://github.com/TheTrueSCU/semantic-state-machine-graphable"
+Issues = "https://github.com/TheTrueSCU/semantic-state-machine-graphable/issues"
+
+[build-system]
+requires = ["uv-build>=0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "pytest-gitignore>=1.3",
+    "pytest-html-plus>=0.5.2",
+    "pytest-isort>=4.0.0",
+    "pytest-randomly>=4.0.1",
+    "pytest-timeout>=2.4.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.15.10",
+    "ty>=0.0.29",
+]

semantic_state_machine_graphable-0.1.4/src/semantic_state_machine_graphable/graph.py

@@ -0,0 +1,134 @@
+from enum import Enum
+from typing import TypeVar
+from semantic_state_machine import StateMachine, AuditContext
+from graphable import Graph, Graphable
+
+S = TypeVar("S", bound=Enum)
+E = TypeVar("E", bound=Enum)
+C = TypeVar("C")
+
+
+class StateNode[S: Enum](Graphable[S]):
+    """A node in the graph representing a state.
+
+    Args:
+        state: The Enum value representing the state.
+    """
+
+    def __init__(self, state: S):
+        super().__init__(state)
+
+
+class StateMachineGraph[S: Enum, E: Enum, C](Graph[StateNode[S]]):
+    """A graph representation of a StateMachine's structure.
+
+    Args:
+        sm: The StateMachine instance to visualize.
+
+    Notes:
+        Architectural Intent: Provides a static view of all possible
+        transitions defined in the state machine.
+    """
+
+    def __init__(self, sm: StateMachine[S, E, C]):
+        super().__init__()
+        self._sm = sm
+        self._sync()
+
+    def _get_or_create_node(self, state: S) -> StateNode[S]:
+        """Retrieves an existing node for a state or creates a new one."""
+        try:
+            return self[state]
+        except KeyError:
+            node = StateNode(state)
+            self.add_node(node)
+            return node
+
+    def _sync(self):
+        """Builds the Graph from the StateMachine's transitions."""
+        for (from_state, event), (to_state, _) in self._sm._transitions.items():
+            u = self._get_or_create_node(from_state)
+            v = self._get_or_create_node(to_state)
+
+            if v in u.dependents:
+                attrs = u.edge_attributes(v)
+                events = attrs.get("events", [])
+                if event not in events:
+                    events.append(event)
+                u.set_edge_attribute(v, "events", events)
+                u.set_edge_attribute(v, "label", ", ".join(e.name for e in events))
+            else:
+                u.add_dependent(v, events=[event], label=event.name)
+
+
+class AuditContextGraph[S: Enum, E: Enum, C](Graph[StateNode[S]]):
+    """A graph representation of the execution path recorded in an AuditContext.
+
+    Args:
+        ctx: The AuditContext instance to visualize.
+        sm: Optional StateMachine instance to resolve target states.
+            If not provided, target states are inferred from the next entry
+            in the audit log, meaning the final transition's target state
+            cannot be determined.
+
+    Notes:
+        Architectural Intent: Visualizes the actual sequence of states
+        visited. Edges are annotated with the sequence of 1-based indices
+        from the audit log.
+    """
+
+    def __init__(
+        self, ctx: AuditContext[S, E], sm: StateMachine[S, E, C] | None = None
+    ):
+        super().__init__()
+        self._ctx = ctx
+        self._sm = sm
+        self._sync()
+
+    def _get_or_create_node(self, state: S) -> StateNode[S]:
+        """Retrieves an existing node for a state or creates a new one."""
+        try:
+            return self[state]
+        except KeyError:
+            node = StateNode(state)
+            self.add_node(node)
+            return node
+
+    def _sync(self):
+        """Builds the Graph from the AuditContext's history."""
+        audit_data = self._ctx._audit
+        for i in range(len(audit_data)):
+            from_state, event = audit_data[i]
+
+            to_state = None
+            if self._sm:
+                # Use StateMachine to find to_state
+                try:
+                    to_state, _ = self._sm._next_transition(from_state, event)
+                except Exception:
+                    # If SM doesn't have it, try fallback to inference
+                    pass
+
+            if to_state is None and i + 1 < len(audit_data):
+                # Fallback to inference from next state
+                to_state = audit_data[i + 1][0]
+
+            if to_state is None:
+                continue
+
+            u = self._get_or_create_node(from_state)
+            v = self._get_or_create_node(to_state)
+
+            # The user requested "index (plus one)" which matches 1-based indexing.
+            index = i + 1
+
+            if v in u.dependents:
+                attrs = u.edge_attributes(v)
+                indices = attrs.get("indices", [])
+                indices.append(index)
+                u.set_edge_attribute(v, "indices", indices)
+                u.set_edge_attribute(
+                    v, "label", f"{event.name} ({', '.join(map(str, indices))})"
+                )
+            else:
+                u.add_dependent(v, indices=[index], label=f"{event.name} ({index})")