smartcomment 0.1.0__py3-none-any.whl

smartcomment/__init__.py

@@ -0,0 +1,49 @@
+"""smartcomment: A General-Purpose Execution Graph Tracing Package."""
+
+from .runtime import (
+    current_context,
+    current_graph,
+    current_op,
+    current_session,
+    comment_graph,
+    comment_op_scope,
+    comment_session,
+    disable_tracing,
+    enable_tracing,
+    is_tracing_enabled,
+    propagate_attributes,
+)
+from .api import (
+    comment_fn,
+    comment_link,
+    comment_mutation,
+    comment_op,
+    comment_variable,
+)
+from .identity import IdentityRegistry
+from .logging import logger, setup_logger
+from .debugging import draw_graph
+
+
+__all__ = [
+    "IdentityRegistry",
+    "logger",
+    "setup_logger",
+    "comment_graph",
+    "comment_op_scope",
+    "comment_session",
+    "current_context",
+    "current_graph",
+    "current_op",
+    "current_session",
+    "disable_tracing",
+    "draw_graph",
+    "enable_tracing",
+    "is_tracing_enabled",
+    "propagate_attributes",
+    "comment_fn",
+    "comment_link",
+    "comment_mutation",
+    "comment_op",
+    "comment_variable",
+]

smartcomment/analysis/__init__.py

@@ -0,0 +1 @@
+"""Analysis and visualization utilities."""

smartcomment/analysis/visualization/__init__.py

@@ -0,0 +1,43 @@
+"""Visualization backends for execution graphs.
+
+Standalone functions accept user-facing runtime types so callers
+can pass graph data without unwrapping internals.
+
+Optional dependencies: ``graphviz``, ``pyvis``, ``matplotlib``.
+Install with ``pip install smartcomment[viz]``.
+"""
+
+from collections import OrderedDict
+from ...runtime.operation import RuntimeEdge
+from ...runtime.variable import RuntimeVariable
+from .graphviz import render_static, to_dot
+from .pyvis import render_interactive
+from typing import Any, Protocol
+
+
+class GraphVisualizationBackend(Protocol):
+    """Graph visualization backend protocol."""
+
+    def __call__(
+        self,
+        nodes: list[RuntimeVariable[Any]],
+        edges: list[RuntimeEdge],
+        **kwargs: Any,
+    ) -> Any:
+        ...
+
+
+_VISUAL_BACKENDS: OrderedDict[str, GraphVisualizationBackend] = OrderedDict(
+    (
+        ("graphviz", render_static),
+        ("dot", to_dot),
+        ("pyvis", render_interactive),
+    )
+)
+
+
+__all__ = [
+    "render_interactive",
+    "render_static",
+    "to_dot",
+]

smartcomment/analysis/visualization/_utils.py

@@ -0,0 +1,103 @@
+"""Utility functions for visualization."""
+
+from __future__ import annotations
+import warnings
+from typing import TYPE_CHECKING, Iterable
+
+if TYPE_CHECKING:
+    from matplotlib.colors import Colormap
+
+
+def _truncate(val: str, max_len: int = 30) -> str:
+    """Truncate a string for graph labels (newlines collapsed to spaces).
+
+    Args:
+        val (`str`):
+            Text to truncate.
+        max_len (`int`, defaults to `30`):
+            Maximum length of the string.
+
+    Returns:
+        `str`:
+            Truncated string without newlines.
+    """
+    s = val.replace("\n", " ").replace("\r", "")
+    if len(s) > max_len:
+        return s[: max_len - 3] + "..."
+    return s
+
+
+def _escape_html(s: str) -> str:
+    """Escape string for HTML labels."""
+    return s.replace(
+        "&", 
+        "&"
+    ).replace(
+        "<", 
+        "&lt;"
+    ).replace(
+        ">", 
+        "&gt;"
+    ).replace(
+        '"', 
+        "&quot;"
+    )
+
+
+def _get_color_map(
+    categories: Iterable[str], 
+    cmap: str | Colormap | None = None, 
+    max_auto: int = 20
+) -> dict[str, str]:
+    """Generate a hex color mapping for a set of categories using Matplotlib.
+    
+    Args:
+        categories (`Iterable[str]`): 
+            Unique categories to colorize.
+        cmap (`str | Colormap | None`, optional): 
+            Matplotlib colormap name or a colormap object. 
+            If not provided, the default colormap will be used.
+        max_auto (`int`): 
+            If no color map is provided and categories exceed this, return no colors.
+        
+    Returns:
+        `dict[str, str]`:
+            Mapping from category string to hex color string.
+    """
+    if not categories:
+        raise ValueError("No categories are provided.")
+        
+    if cmap is None and len(categories) > max_auto:
+        return {}
+        
+    try:
+        import matplotlib.pyplot as plt
+        import matplotlib.colors as mcolors
+    except ImportError as e:
+        if cmap is not None:
+            raise ImportError(
+                "`matplotlib` is required for custom colormaps. "
+                "Install it via `pip install matplotlib`."
+            ) from e
+
+        # Graceful fallback to no colors if default behavior and no matplotlib. 
+        warnings.warn(
+            "`matplotlib` is required for custom colormaps, but it is not installed. "
+            "No colors will be assigned to categories."
+        )
+        return {}  
+
+    if cmap is None:
+        cmap_obj = plt.get_cmap("tab20")
+    elif isinstance(cmap, str):
+        cmap_obj = plt.get_cmap(cmap)
+    else:
+        cmap_obj = cmap
+
+    n = len(categories)
+    color_dict = {}
+    for i, cat in enumerate(sorted(categories)):
+        rgba = cmap_obj(i / max(1, n - 1))
+        color_dict[cat] = mcolors.to_hex(rgba)
+        
+    return color_dict

smartcomment/analysis/visualization/graphviz.py

@@ -0,0 +1,201 @@
+"""Graphviz visualization backend."""
+
+from __future__ import annotations
+from ...runtime.operation import RuntimeEdge
+from ...runtime.variable import RuntimeVariable
+from ._utils import (
+    _get_color_map, 
+    _escape_html, 
+    _truncate,
+)
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from matplotlib.colors import Colormap
+    from graphviz import Source
+
+
+def to_dot(
+    nodes: list[RuntimeVariable[Any]],
+    edges: list[RuntimeEdge],
+    node_cmap: str | Colormap | None = None,
+    edge_cmap: str | Colormap | None = None,
+    max_str_len: int = 30,
+    **kwargs: Any,
+) -> str:
+    """Convert a node list and an edge list to a `graphviz` DOT string.
+
+    Args:
+        nodes (`list[RuntimeVariable]`):
+            Variable nodes to render.
+        edges (`list[RuntimeEdge]`):
+            Edges to render.
+        node_cmap (`str | Colormap | None`, optional):
+            Matplotlib colormap (name or object) for coloring nodes by category.
+        edge_cmap (`str | Colormap | None`, optional):
+            Matplotlib colormap (name or object) for coloring edges by category.
+        max_str_len (`int`, defaults to `30`):
+            Maximum string length for displayed fields before truncation.
+        **kwargs (`Any`):
+            These keyword arguments will be ignored.
+
+    Returns:
+        `str`:
+            DOT-format string.
+    """
+    lines = [
+        'digraph exec_graph {', 
+        '  rankdir=LR;',
+        '  node [shape=none, fontname="Helvetica"];',
+        '  edge [fontname="Helvetica"];'
+    ]
+
+    # Get unique categories for nodes and edges.
+    node_cats = {n.category for n in nodes}
+    edge_cats = {e.category for e in edges}
+
+
+    if node_cats:
+        node_colors = _get_color_map(node_cats, cmap=node_cmap)
+    else:
+        node_colors = {}
+    if edge_cats:
+        edge_colors = _get_color_map(edge_cats, cmap=edge_cmap)
+    else:
+        edge_colors = {}
+
+    for node in nodes:
+        cat = node.category
+        # Default white background. 
+        color_hex = node_colors.get(cat, "#FFFFFF")  
+        
+        node_id_str = _escape_html(
+            _truncate(
+                node.full_node_id, 
+                max_len=max_str_len
+            )
+        )
+        raw_val_str = _escape_html(
+            _truncate(
+                node.raw_value, 
+                max_len=max_str_len
+            )
+        )
+        cat_str = _escape_html(
+            _truncate(
+                node.category, 
+                max_len=max_str_len
+            )
+        )
+        tp_str = _escape_html(
+            _truncate(
+                node.trigger_point, 
+                max_len=max_str_len
+            )
+        )
+        comment_str = _escape_html(
+            _truncate(node.comment, max_len=max_str_len) if node.comment else ""
+        )
+
+        # Pad empty comments with a space to prevent the cell from collapsing. 
+        comment_display = comment_str if comment_str else " "
+
+        # Build HTML-like record with strict BALIGN="LEFT" and <BR ALIGN="LEFT"/>. 
+        label = (
+            f'<<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4" BGCOLOR="{color_hex}">\n'
+            f'  <TR><TD ALIGN="CENTER"><B>{node_id_str}</B></TD></TR>\n'
+            f'  <TR><TD ALIGN="LEFT" BALIGN="LEFT">'
+            f'{raw_val_str}<BR ALIGN="LEFT"/>'
+            f'category: {cat_str}<BR ALIGN="LEFT"/>'
+            f'trigger point: {tp_str}<BR ALIGN="LEFT"/>'
+            f'</TD></TR>\n'
+            f'  <TR><TD ALIGN="LEFT" BALIGN="LEFT">{comment_display}<BR ALIGN="LEFT"/></TD></TR>\n'
+            f'</TABLE>>'
+        )
+        
+        lines.append(f'  "{node.full_node_id}" [label={label}];')
+
+    for edge in edges:
+        cat = edge.category
+        # Default black for edges. 
+        color_hex = edge_colors.get(cat, "#000000")  
+        
+        label = _escape_html(
+            _truncate(
+                edge.category, 
+                max_len=max_str_len
+            )
+        )
+        if edge.comment:
+            label = _escape_html(
+                _truncate(
+                    edge.comment, 
+                    max_len=max_str_len
+                )
+            )
+            
+        lines.append(
+            f'  "{edge.source_full_node_id}" -> "{edge.target_full_node_id}" '
+            f'[label="{label}", color="{color_hex}", fontcolor="{color_hex}"];'
+        )
+
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def render_static(
+    nodes: list[RuntimeVariable[Any]],
+    edges: list[RuntimeEdge],
+    filename: str = "exec_graph",
+    format: str = "png",
+    node_cmap: str | Colormap | None = None,
+    edge_cmap: str | Colormap | None = None,
+    max_str_len: int = 30,
+    **kwargs: Any,
+) -> Source:
+    """Render a graph to a static image file via `graphviz`.
+
+    Args:
+        nodes (`list[RuntimeVariable]`):
+            Variable nodes to render.
+        edges (`list[RuntimeEdge]`):
+            Edges to render.
+        filename (`str`, defaults to `"exec_graph"`):
+            Output filename (without extension).
+        format (`str`, defaults to `"png"`):
+            Image format (``"png"``, ``"svg"``, ``"pdf"``).
+        node_cmap (`str | Colormap | None`, optional):
+            Matplotlib colormap (name or object) for coloring nodes by category.
+        edge_cmap (`str | Colormap | None`, optional):
+            Matplotlib colormap (name or object) for coloring edges by category.
+        max_str_len (`int`, defaults to `30`):
+            Maximum characters for text display.
+        **kwargs (`Any`):
+            Additional keyword arguments to be passed to ``graphviz.Source.render``.
+
+    Returns:
+        `Source`:
+            A `graphviz.Source` object.
+    """
+    try:
+        import graphviz as gv
+    except ImportError as e:
+        raise ImportError(
+            "`graphviz` Python package is required. "
+            "Install it via `pip install graphviz`."
+        ) from e
+
+    dot_str = to_dot(
+        nodes=nodes,
+        edges=edges,
+        node_cmap=node_cmap,
+        edge_cmap=edge_cmap,
+        max_str_len=max_str_len,
+    )
+    src = gv.Source(dot_str, format=format)
+    kwargs.setdefault("cleanup", True)
+    kwargs.setdefault("view", False)
+    src.render(filename=filename, **kwargs)
+
+    return src 

smartcomment/analysis/visualization/pyvis.py

@@ -0,0 +1,155 @@
+"""Pyvis visualization backend."""
+
+from __future__ import annotations
+from ...runtime.operation import RuntimeEdge
+from ...runtime.variable import RuntimeVariable
+from ._utils import _get_color_map, _truncate
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pyvis.network import Network
+    from matplotlib.colors import Colormap
+
+
+_DEFAULT_BARNES_HUT = {
+    "gravity": -12000,
+    "central_gravity": 0.12,
+    "spring_length": 400,
+    "spring_strength": 0.001,
+    "damping": 0.08,
+    "overlap": 1,
+}
+
+
+def render_interactive(
+    nodes: list[RuntimeVariable[Any]],
+    edges: list[RuntimeEdge],
+    filename: str = "exec_graph.html",
+    node_cmap: str | Colormap | None = None,
+    edge_cmap: str | Colormap | None = None,
+    max_str_len: int = 30,
+    smooth_type: str = "continuous",
+    barnes_hut_config: dict[str, float | int] | None = None,
+    **kwargs: Any,
+) -> Network:
+    """Render an interactive HTML graph via `pyvis`.
+
+    Args:
+        nodes (`list[RuntimeVariable]`):
+            Variable nodes to render.
+        edges (`list[RuntimeEdge]`):
+            Edges to render.
+        filename (`str`, defaults to `"exec_graph.html"`):
+            Output HTML file path.
+        node_cmap (`str | Colormap | None`, optional):
+            Matplotlib colormap (name or object) for coloring nodes by
+            category.
+        edge_cmap (`str | Colormap | None`, optional):
+            Matplotlib colormap (name or object) for coloring edges by
+            category.
+        max_str_len (`int`, defaults to `30`):
+            Maximum string length for node/edge labels before truncation.
+        smooth_type (`str`, defaults to `"continuous"`):
+            Edge smoothing algorithm.
+        barnes_hut_config (`dict[str, float | int] | None`, optional):
+            Override the default BarnesHut physics parameters.
+        **kwargs (`Any`):
+            Additional keyword arguments to be passed to ``pyvis.network.Network``.
+
+    Returns:
+        `Network`:
+            A `pyvis.network.Network` object.
+    """
+    try:
+        from pyvis.network import Network as PyvisNetwork
+    except ImportError as e:
+        raise ImportError(
+            "`pyvis` Python package is required. "
+            "Install it via `pip install pyvis`."
+        ) from e
+
+    net = PyvisNetwork(**kwargs)
+
+    node_cats = {n.category for n in nodes}
+    edge_cats = {e.category for e in edges}
+
+    if node_cats:
+        node_colors = _get_color_map(node_cats, cmap=node_cmap)
+    else:
+        node_colors = {}
+    if edge_cats:
+        edge_colors = _get_color_map(edge_cats, cmap=edge_cmap)
+    else:
+        edge_colors = {}
+
+    for node in nodes:
+        cat = node.category
+        # Pyvis default blueish. 
+        color_hex = node_colors.get(cat, "#97C2FC")
+
+        node_id_str = _truncate(node.full_node_id, max_len=max_str_len)
+        raw_val_str = _truncate(node.raw_value, max_len=max_str_len)
+        cat_str = _truncate(cat, max_len=max_str_len)
+        tp_str = _truncate(node.trigger_point, max_len=max_str_len)
+        comment_str = (
+            _truncate(node.comment, max_len=max_str_len) if node.comment else ""
+        )
+
+        separator = "-" * max(15, min(30, max_str_len))
+        label = (
+            f"{node_id_str}\n{separator}\n"
+            f"{raw_val_str}\ncategory: {cat_str}\n"
+            f"trigger point: {tp_str}"
+        )
+        if comment_str:
+            label += f"\n{separator}\n{comment_str}"
+
+        title = (
+            f"ID: {node.full_node_id}\nRaw Value: {node.raw_value}\n"
+            f"Category: {cat}\nTrigger Point: {node.trigger_point}"
+        )
+        if node.comment:
+            title += f"\nComment: {node.comment}"
+
+        # All fields are left aligned.
+        net.add_node(
+            node.full_node_id,
+            label=label,
+            title=title,
+            shape="box",
+            color=color_hex,
+            font={"align": "left"},
+        )
+
+    for edge in edges:
+        cat = edge.category
+        color_hex = edge_colors.get(cat, "#848484")
+        tp_str = _truncate(edge.trigger_point, max_len=max_str_len)
+
+        label_str = _truncate(edge.category, max_str_len)
+        if edge.comment:
+            label_str = _truncate(edge.comment, max_str_len)
+        label_str += f"\n({tp_str})"
+
+        title_str = f"Category: {cat}\nTrigger Point: {edge.trigger_point}"
+        if edge.comment:
+            title_str = (
+                f"Category: {cat}\nComment: {edge.comment}\n"
+                f"Trigger Point: {edge.trigger_point}"
+            )
+
+        net.add_edge(
+            edge.source_full_node_id,
+            edge.target_full_node_id,
+            label=label_str,
+            title=title_str,
+            color=color_hex,
+        )
+
+    net.set_edge_smooth(smooth_type)
+
+    bh = {**_DEFAULT_BARNES_HUT, **(barnes_hut_config or {})}
+    net.barnes_hut(**bh)
+    net.save_graph(filename)
+
+    return net

smartcomment/api/__init__.py

@@ -0,0 +1,18 @@
+"""Public APIs."""
+
+from .public import (
+    comment_fn,
+    comment_link,
+    comment_mutation,
+    comment_op,
+    comment_variable,
+)
+
+
+__all__ = [
+    "comment_fn",
+    "comment_link",
+    "comment_mutation",
+    "comment_op",
+    "comment_variable",
+]