scitex 2.13.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

scitex/diagram/_compile.py

@@ -1,312 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-# Timestamp: 2025-12-15
-# Author: ywatanabe / Claude
-# File: scitex/diagram/_compile.py
-
-"""
-Compilers from DiagramSpec to backend formats (Mermaid, Graphviz).
-
-The compiler applies paper constraints to generate backend-specific
-layout directives. This is where domain knowledge about "good paper figures"
-gets encoded.
-"""
-
-import json
-from typing import Optional
-from scitex.diagram._schema import (
-    DiagramSpec, DiagramType, ColumnLayout, SpacingLevel, PaperMode
-)
-from scitex.diagram._presets import get_preset, DiagramPreset
-
-
-def compile_to_mermaid(
-    spec: DiagramSpec,
-    preset: Optional[DiagramPreset] = None
-) -> str:
-    """
-    Compile DiagramSpec to Mermaid format with paper-optimized settings.
-
-    Parameters
-    ----------
-    spec : DiagramSpec
-        The semantic diagram specification.
-    preset : DiagramPreset, optional
-        Override preset (default: inferred from spec.type).
-
-    Returns
-    -------
-    str
-        Mermaid diagram source code.
-    """
-    if preset is None:
-        preset = get_preset(spec.type.value)
-
-    lines = []
-
-    # Theme initialization
-    theme_vars = {**preset.mermaid_theme, **spec.theme}
-    theme_json = json.dumps({"theme": "base", "themeVariables": theme_vars})
-    lines.append(f"%%{{init: {theme_json}}}%%")
-
-    # Determine direction based on paper constraints
-    direction = preset.mermaid_direction
-    if spec.paper.reading_direction == "top_to_bottom":
-        direction = "TB"
-    elif spec.paper.column == ColumnLayout.DOUBLE:
-        # Double column prefers vertical to save horizontal space
-        direction = "TB"
-
-    lines.append(f"graph {direction}")
-
-    # Build node ID to spec mapping
-    node_map = {n.id: n for n in spec.nodes}
-
-    # Generate subgraphs for groups
-    indent = "    "
-    for group_name, group_nodes in spec.layout.groups.items():
-        lines.append(f'{indent}subgraph {_sanitize_id(group_name)}["{group_name}"]')
-        for node_id in group_nodes:
-            if node_id in node_map:
-                node = node_map[node_id]
-                lines.append(f"{indent}{indent}{_mermaid_node(node, preset)}")
-        lines.append(f"{indent}end")
-
-    # Generate standalone nodes (not in any group)
-    grouped_nodes = set()
-    for group_nodes in spec.layout.groups.values():
-        grouped_nodes.update(group_nodes)
-
-    for node in spec.nodes:
-        if node.id not in grouped_nodes:
-            lines.append(f"{indent}{_mermaid_node(node, preset)}")
-
-    # Generate edges
-    for edge in spec.edges:
-        edge_str = _mermaid_edge(edge)
-        lines.append(f"{indent}{edge_str}")
-
-    # Generate styles for emphasized nodes
-    for node in spec.nodes:
-        if node.emphasis != "normal" or node.id in spec.paper.emphasize:
-            emphasis = "primary" if node.id in spec.paper.emphasize else node.emphasis
-            style = preset.emphasis_styles.get(emphasis, {})
-            if style:
-                style_parts = [f"{k}:{v}" for k, v in style.items()]
-                lines.append(f"{indent}style {_sanitize_id(node.id)} {','.join(style_parts)}")
-
-    return "\n".join(lines)
-
-
-def compile_to_graphviz(
-    spec: DiagramSpec,
-    preset: Optional[DiagramPreset] = None
-) -> str:
-    """
-    Compile DiagramSpec to Graphviz DOT format.
-
-    Parameters
-    ----------
-    spec : DiagramSpec
-        The semantic diagram specification.
-    preset : DiagramPreset, optional
-        Override preset.
-
-    Returns
-    -------
-    str
-        Graphviz DOT source code.
-    """
-    if preset is None:
-        preset = get_preset(spec.type.value)
-
-    is_publication = spec.paper.mode == PaperMode.PUBLICATION
-    lines = []
-
-    # Determine direction
-    rankdir = preset.graphviz_rankdir
-    if spec.paper.reading_direction == "top_to_bottom":
-        rankdir = "TB"
-    elif spec.paper.column == ColumnLayout.DOUBLE:
-        rankdir = "TB"
-
-    # Get spacing - publication mode uses tight spacing
-    if is_publication:
-        spacing = preset.spacing_map.get("tight", {})
-    else:
-        spacing = preset.spacing_map.get(spec.layout.layer_gap.value, {})
-    ranksep = spacing.get("ranksep", preset.graphviz_ranksep)
-    nodesep = spacing.get("nodesep", preset.graphviz_nodesep)
-
-    lines.append("digraph G {")
-    lines.append(f"    rankdir={rankdir};")
-    lines.append(f"    ranksep={ranksep};")
-    lines.append(f"    nodesep={nodesep};")
-    lines.append("    splines=ortho;")  # Orthogonal edges for cleaner look
-    lines.append('    node [fontname="Helvetica", fontsize=10];')
-    lines.append('    edge [fontname="Helvetica", fontsize=9];')
-    lines.append("")
-
-    # Node map
-    node_map = {n.id: n for n in spec.nodes}
-
-    # Build return edges set for publication mode
-    return_edge_set = set()
-    for e in spec.paper.return_edges:
-        if len(e) >= 2:
-            return_edge_set.add((e[0], e[1]))
-
-    # Generate subgraphs (without clusters for tighter layout in publication)
-    if is_publication and spec.layout.layers:
-        # In publication mode with layers, skip clusters - use rank=same instead
-        for node in spec.nodes:
-            lines.append(f"    {_graphviz_node(node, preset, spec.paper.emphasize)}")
-    else:
-        # Draft mode: use clusters for visual grouping
-        cluster_idx = 0
-        for group_name, group_nodes in spec.layout.groups.items():
-            lines.append(f'    subgraph cluster_{cluster_idx} {{')
-            lines.append(f'        label="{group_name}";')
-            for node_id in group_nodes:
-                if node_id in node_map:
-                    node = node_map[node_id]
-                    lines.append(f"        {_graphviz_node(node, preset, spec.paper.emphasize)}")
-            lines.append("    }")
-            cluster_idx += 1
-
-        # Standalone nodes
-        grouped_nodes = set()
-        for group_nodes in spec.layout.groups.values():
-            grouped_nodes.update(group_nodes)
-
-        for node in spec.nodes:
-            if node.id not in grouped_nodes:
-                lines.append(f"    {_graphviz_node(node, preset, spec.paper.emphasize)}")
-
-    lines.append("")
-
-    # Rank constraints from layers (CRITICAL for minimizing whitespace)
-    for layer in spec.layout.layers:
-        if layer:
-            node_ids = "; ".join(_sanitize_id(n) for n in layer)
-            lines.append(f"    {{ rank=same; {node_ids}; }}")
-
-    lines.append("")
-
-    # Edges - handle return edges in publication mode
-    for edge in spec.edges:
-        edge_key = (edge.source, edge.target)
-        if is_publication and edge_key in return_edge_set:
-            # Make return edges invisible in publication mode
-            lines.append(f"    {_graphviz_edge_with_style(edge, invisible=True)}")
-        else:
-            lines.append(f"    {_graphviz_edge(edge)}")
-
-    lines.append("}")
-
-    return "\n".join(lines)
-
-
-def _sanitize_id(s: str) -> str:
-    """Make string safe for use as node ID."""
-    import re
-    # Remove or replace problematic characters for Mermaid/Graphviz
-    s = re.sub(r'[^\w]', '_', s)  # Replace non-word chars with _
-    s = re.sub(r'_+', '_', s)      # Collapse multiple underscores
-    s = s.strip('_')               # Remove leading/trailing underscores
-    return s or "node"
-
-
-def _mermaid_node(node, preset: DiagramPreset) -> str:
-    """Generate Mermaid node definition."""
-    shape_template = preset.mermaid_shapes.get(node.shape, '["__LABEL__"]')
-    shape_str = shape_template.replace("__LABEL__", node.label)
-    return f"{_sanitize_id(node.id)}{shape_str}"
-
-
-def _mermaid_edge(edge) -> str:
-    """Generate Mermaid edge definition."""
-    arrow = "-->" if edge.arrow == "normal" else "---"
-    if edge.style == "dashed":
-        arrow = "-.->" if edge.arrow == "normal" else "-.-"
-    elif edge.style == "dotted":
-        arrow = "..>" if edge.arrow == "normal" else "..."
-
-    src = _sanitize_id(edge.source)
-    tgt = _sanitize_id(edge.target)
-
-    if edge.label:
-        return f'{src} {arrow}|"{edge.label}"| {tgt}'
-    return f"{src} {arrow} {tgt}"
-
-
-def _graphviz_node(node, preset: DiagramPreset, emphasize: list) -> str:
-    """Generate Graphviz node definition."""
-    shape = preset.graphviz_shapes.get(node.shape, "box")
-
-    # Get emphasis style
-    emphasis_key = "primary" if node.id in emphasize else node.emphasis
-    style = preset.emphasis_styles.get(emphasis_key, {})
-
-    attrs = [f'label="{node.label}"', f'shape={shape}']
-
-    # Collect style values (filled, rounded, etc.) - combine with comma
-    styles = []
-    if style.get("fill"):
-        attrs.append(f'fillcolor="{style["fill"]}"')
-        styles.append("filled")
-    if style.get("stroke"):
-        attrs.append(f'color="{style["stroke"]}"')
-    if node.shape == "rounded":
-        styles.append("rounded")
-
-    # Output style once with comma-separated values
-    if styles:
-        attrs.append(f'style="{",".join(styles)}"')
-
-    return f'{_sanitize_id(node.id)} [{", ".join(attrs)}];'
-
-
-def _graphviz_edge(edge) -> str:
-    """Generate Graphviz edge definition."""
-    src = _sanitize_id(edge.source)
-    tgt = _sanitize_id(edge.target)
-
-    attrs = []
-    if edge.label:
-        attrs.append(f'label="{edge.label}"')
-    if edge.style == "dashed":
-        attrs.append("style=dashed")
-    elif edge.style == "dotted":
-        attrs.append("style=dotted")
-    if edge.arrow == "none":
-        attrs.append("arrowhead=none")
-
-    if attrs:
-        return f'{src} -> {tgt} [{", ".join(attrs)}];'
-    return f"{src} -> {tgt};"
-
-
-def _graphviz_edge_with_style(edge, invisible: bool = False) -> str:
-    """Generate Graphviz edge with optional invisible style."""
-    src = _sanitize_id(edge.source)
-    tgt = _sanitize_id(edge.target)
-
-    attrs = []
-    if invisible:
-        attrs.append("style=invis")
-        # Invisible edges still constrain layout
-        attrs.append("constraint=true")
-    else:
-        if edge.label:
-            attrs.append(f'label="{edge.label}"')
-        if edge.style == "dashed":
-            attrs.append("style=dashed")
-        elif edge.style == "dotted":
-            attrs.append("style=dotted")
-        if edge.arrow == "none":
-            attrs.append("arrowhead=none")
-
-    if attrs:
-        return f'{src} -> {tgt} [{", ".join(attrs)}];'
-    return f"{src} -> {tgt};"

scitex/diagram/_diagram.py

@@ -1,355 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-# Timestamp: 2025-12-15
-# Author: ywatanabe / Claude
-# File: scitex/diagram/_diagram.py
-
-"""
-Main Diagram class - the user-facing API.
-"""
-
-from pathlib import Path
-from typing import Optional, Union, List
-import yaml
-import re
-
-from scitex.diagram._schema import DiagramSpec, DiagramType, NodeSpec, EdgeSpec, PaperMode
-from scitex.diagram._compile import compile_to_mermaid, compile_to_graphviz
-from scitex.diagram._presets import get_preset
-from scitex.diagram._split import split_diagram, SplitConfig, SplitStrategy, SplitResult
-
-
-class Diagram:
-    """
-    Paper-optimized diagram with semantic specification.
-
-    This class provides the main interface for creating diagrams
-    that compile to Mermaid or Graphviz with paper-appropriate
-    layout constraints.
-
-    Examples
-    --------
-    >>> # From YAML spec
-    >>> d = Diagram.from_yaml("workflow.diagram.yaml")
-    >>> d.to_mermaid("workflow.mmd")
-
-    >>> # From existing Mermaid (parse and enhance)
-    >>> d = Diagram.from_mermaid("existing.mmd", diagram_type="workflow")
-    >>> d.spec.paper.column = "double"
-    >>> d.to_mermaid("enhanced.mmd")
-
-    >>> # Programmatic creation
-    >>> d = Diagram(type="pipeline")
-    >>> d.add_node("input", "Raw Data")
-    >>> d.add_node("process", "Transform", emphasis="primary")
-    >>> d.add_node("output", "Results")
-    >>> d.add_edge("input", "process")
-    >>> d.add_edge("process", "output")
-    >>> print(d.to_mermaid())
-    """
-
-    def __init__(
-        self,
-        type: str = "workflow",
-        title: str = "",
-        column: str = "single",
-    ):
-        """
-        Initialize a new diagram.
-
-        Parameters
-        ----------
-        type : str
-            Diagram type: workflow, decision, pipeline, hierarchy.
-        title : str
-            Diagram title.
-        column : str
-            Paper column: single or double.
-        """
-        self.spec = DiagramSpec(
-            type=DiagramType(type),
-            title=title,
-        )
-        self.spec.paper.column = column
-
-    @classmethod
-    def from_yaml(cls, path: Union[str, Path]) -> "Diagram":
-        """
-        Load diagram from YAML specification file.
-
-        Parameters
-        ----------
-        path : str or Path
-            Path to YAML file.
-
-        Returns
-        -------
-        Diagram
-            Loaded diagram.
-        """
-        path = Path(path)
-        with open(path, "r", encoding="utf-8") as f:
-            data = yaml.safe_load(f)
-
-        diagram = cls.__new__(cls)
-        diagram.spec = DiagramSpec.from_dict(data)
-        return diagram
-
-    @classmethod
-    def from_mermaid(
-        cls,
-        path: Union[str, Path],
-        diagram_type: str = "workflow",
-    ) -> "Diagram":
-        """
-        Parse existing Mermaid file and create enhanced Diagram.
-
-        This allows upgrading existing Mermaid files with SciTeX
-        paper constraints while preserving the original structure.
-
-        Parameters
-        ----------
-        path : str or Path
-            Path to .mmd file.
-        diagram_type : str
-            Inferred diagram type.
-
-        Returns
-        -------
-        Diagram
-            Parsed diagram (can be enhanced and re-exported).
-        """
-        path = Path(path)
-        with open(path, "r", encoding="utf-8") as f:
-            content = f.read()
-
-        diagram = cls(type=diagram_type)
-        diagram._parse_mermaid(content)
-        return diagram
-
-    def _parse_mermaid(self, content: str):
-        """Parse Mermaid content to extract structure."""
-        # Extract nodes
-        # Pattern: ID["Label"] or ID("Label") etc.
-        node_pattern = r'(\w+)\s*[\[\(\{<][\"\']?([^"\'\]\)\}>]+)[\"\']?[\]\)\}>]'
-
-        for match in re.finditer(node_pattern, content):
-            node_id = match.group(1)
-            label = match.group(2).strip()
-            # Skip if it looks like a subgraph name
-            if node_id.lower() not in ["subgraph", "end", "style", "graph", "direction"]:
-                # Check for duplicates
-                existing = [n for n in self.spec.nodes if n.id == node_id]
-                if not existing:
-                    self.spec.nodes.append(NodeSpec(id=node_id, label=label))
-
-        # Extract edges
-        # Pattern: A --> B or A -->|label| B
-        edge_pattern = r'(\w+)\s*(-->|-.->|-----|---)\s*(?:\|["\']?([^|"\']+)["\']?\|)?\s*(\w+)'
-
-        for match in re.finditer(edge_pattern, content):
-            source = match.group(1)
-            arrow = match.group(2)
-            label = match.group(3)
-            target = match.group(4)
-
-            style = "solid"
-            if "-.->" in arrow or "-.." in arrow:
-                style = "dashed"
-
-            self.spec.edges.append(EdgeSpec(
-                source=source,
-                target=target,
-                label=label.strip() if label else None,
-                style=style,
-            ))
-
-        # Extract subgraphs as groups
-        subgraph_pattern = r'subgraph\s+(\w+)\s*\[?"?([^"\]]*)"?\]?'
-        for match in re.finditer(subgraph_pattern, content):
-            group_id = match.group(1)
-            group_name = match.group(2) or group_id
-            self.spec.layout.groups[group_name] = []
-
-    def add_node(
-        self,
-        id: str,
-        label: str,
-        shape: str = "box",
-        emphasis: str = "normal",
-    ):
-        """Add a node to the diagram."""
-        self.spec.nodes.append(NodeSpec(
-            id=id,
-            label=label,
-            shape=shape,
-            emphasis=emphasis,
-        ))
-
-    def add_edge(
-        self,
-        source: str,
-        target: str,
-        label: Optional[str] = None,
-        style: str = "solid",
-    ):
-        """Add an edge between nodes."""
-        self.spec.edges.append(EdgeSpec(
-            source=source,
-            target=target,
-            label=label,
-            style=style,
-        ))
-
-    def set_group(self, group_name: str, node_ids: list):
-        """Define a group of nodes (rendered as subgraph)."""
-        self.spec.layout.groups[group_name] = node_ids
-
-    def emphasize(self, *node_ids: str):
-        """Mark nodes as emphasized (primary styling)."""
-        self.spec.paper.emphasize.extend(node_ids)
-
-    def to_mermaid(self, path: Optional[Union[str, Path]] = None) -> str:
-        """
-        Compile to Mermaid format.
-
-        Parameters
-        ----------
-        path : str or Path, optional
-            If provided, write to file.
-
-        Returns
-        -------
-        str
-            Mermaid source code.
-        """
-        result = compile_to_mermaid(self.spec)
-
-        if path:
-            path = Path(path)
-            with open(path, "w", encoding="utf-8") as f:
-                f.write(result)
-
-        return result
-
-    def to_graphviz(self, path: Optional[Union[str, Path]] = None) -> str:
-        """
-        Compile to Graphviz DOT format.
-
-        Parameters
-        ----------
-        path : str or Path, optional
-            If provided, write to file.
-
-        Returns
-        -------
-        str
-            Graphviz DOT source code.
-        """
-        result = compile_to_graphviz(self.spec)
-
-        if path:
-            path = Path(path)
-            with open(path, "w", encoding="utf-8") as f:
-                f.write(result)
-
-        return result
-
-    def to_yaml(self, path: Optional[Union[str, Path]] = None) -> str:
-        """
-        Export specification as YAML.
-
-        Parameters
-        ----------
-        path : str or Path, optional
-            If provided, write to file.
-
-        Returns
-        -------
-        str
-            YAML specification.
-        """
-        data = {
-            "type": self.spec.type.value,
-            "title": self.spec.title,
-            "paper": {
-                "column": self.spec.paper.column.value if hasattr(self.spec.paper.column, 'value') else self.spec.paper.column,
-                "max_width_mm": self.spec.paper.max_width_mm,
-                "reading_direction": self.spec.paper.reading_direction,
-                "mode": self.spec.paper.mode.value if hasattr(self.spec.paper.mode, 'value') else self.spec.paper.mode,
-                "emphasize": self.spec.paper.emphasize,
-            },
-            "layout": {
-                "groups": self.spec.layout.groups,
-                "layers": self.spec.layout.layers,
-                "layer_gap": self.spec.layout.layer_gap.value,
-                "node_gap": self.spec.layout.node_gap.value,
-            },
-            "nodes": [
-                {"id": n.id, "label": n.label, "shape": n.shape, "emphasis": n.emphasis}
-                for n in self.spec.nodes
-            ],
-            "edges": [
-                {"from": e.source, "to": e.target, "label": e.label, "style": e.style}
-                for e in self.spec.edges
-            ],
-        }
-
-        result = yaml.dump(data, default_flow_style=False, allow_unicode=True)
-
-        if path:
-            path = Path(path)
-            with open(path, "w", encoding="utf-8") as f:
-                f.write(result)
-
-        return result
-
-    def split(
-        self,
-        max_nodes: int = 12,
-        strategy: str = "by_groups",
-        keep_hubs: bool = True,
-    ) -> List["Diagram"]:
-        """
-        Split diagram into multiple figures if too large.
-
-        Parameters
-        ----------
-        max_nodes : int
-            Maximum nodes per figure before splitting.
-        strategy : str
-            Split strategy: "by_groups" or "by_articulation".
-        keep_hubs : bool
-            Show hub nodes as ghosts in both parts.
-
-        Returns
-        -------
-        List[Diagram]
-            List of split diagrams (or single diagram if no split needed).
-
-        Examples
-        --------
-        >>> d = Diagram.from_yaml("large_workflow.yaml")
-        >>> parts = d.split(max_nodes=8)
-        >>> for i, part in enumerate(parts):
-        ...     part.to_mermaid(f"workflow_part_{i+1}.mmd")
-        """
-        config = SplitConfig(
-            enabled=True,
-            max_nodes=max_nodes,
-            strategy=SplitStrategy(strategy),
-            keep_hubs=keep_hubs,
-        )
-
-        result = split_diagram(self.spec, config)
-
-        # Wrap each spec in a Diagram object
-        diagrams = []
-        for fig_spec, label in zip(result.figures, result.labels):
-            d = Diagram.__new__(Diagram)
-            d.spec = fig_spec
-            if label:
-                d.spec.title = f"{self.spec.title} ({label})" if self.spec.title else f"Part {label}"
-            diagrams.append(d)
-
-        return diagrams