scitex 2.7.0__py3-none-any.whl → 2.8.1__py3-none-any.whl

scitex/diagram/_schema.py

@@ -0,0 +1,182 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-15
+# Author: ywatanabe / Claude
+# File: scitex/diagram/_schema.py
+
+"""
+Schema definitions for SciTeX Diagram.
+
+The schema defines paper-specific constraints that Mermaid/Graphviz don't know:
+- Paper layout (single/double column, max width)
+- Reading direction preferences
+- Node emphasis for scientific communication
+- Semantic layer grouping
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Dict, Optional, Literal
+
+
+class DiagramType(Enum):
+    """Semantic type of diagram - affects layout strategy."""
+    WORKFLOW = "workflow"       # Sequential process, prefer LR/TB flow
+    DECISION = "decision"       # Decision tree, prefer TB with branches
+    PIPELINE = "pipeline"       # Data pipeline, strict LR with stages
+    HIERARCHY = "hierarchy"     # Tree structure, TB with levels
+    COMPARISON = "comparison"   # Side-by-side, two columns
+
+
+class ColumnLayout(Enum):
+    """Paper column layout."""
+    SINGLE = "single"   # Full width (~170mm)
+    DOUBLE = "double"   # Half width (~85mm)
+
+
+class SpacingLevel(Enum):
+    """Abstract spacing levels - mapped to backend-specific values."""
+    TIGHT = "tight"       # Publication: minimal whitespace
+    COMPACT = "compact"
+    MEDIUM = "medium"
+    LARGE = "large"
+
+
+class PaperMode(Enum):
+    """Paper mode affects layout density and edge visibility."""
+    DRAFT = "draft"           # Full arrows, visible bidirectional, medium spacing
+    PUBLICATION = "publication"  # Compact, return edges hidden/dotted
+
+
+@dataclass
+class PaperConstraints:
+    """Paper-specific constraints that affect layout."""
+    column: ColumnLayout = ColumnLayout.SINGLE
+    max_width_mm: int = 170
+    reading_direction: Literal["left_to_right", "top_to_bottom"] = "left_to_right"
+    mode: PaperMode = PaperMode.DRAFT  # draft: full details, publication: compact
+    emphasize: List[str] = field(default_factory=list)  # Node IDs to highlight
+
+    # Scientific communication hints
+    main_flow: List[str] = field(default_factory=list)  # Critical path nodes
+    secondary_flow: List[str] = field(default_factory=list)  # Supporting elements
+    return_edges: List[tuple] = field(default_factory=list)  # Edges to hide in publication
+
+
+@dataclass
+class LayoutHints:
+    """Abstract layout hints - compiled to backend directives."""
+    layers: List[List[str]] = field(default_factory=list)  # Nodes grouped by rank
+    alignment: Dict[str, str] = field(default_factory=dict)  # Node alignment hints
+    layer_gap: SpacingLevel = SpacingLevel.MEDIUM
+    node_gap: SpacingLevel = SpacingLevel.MEDIUM
+
+    # Subgraph organization
+    groups: Dict[str, List[str]] = field(default_factory=dict)  # Named groups
+
+
+@dataclass
+class NodeSpec:
+    """Specification for a single node."""
+    id: str
+    label: str
+    shape: Literal["box", "rounded", "diamond", "circle", "stadium"] = "box"
+    emphasis: Literal["normal", "primary", "success", "warning", "muted"] = "normal"
+
+    def short_label(self, max_chars: int = 20) -> str:
+        """Return truncated label for compact layouts."""
+        if len(self.label) <= max_chars:
+            return self.label
+        return self.label[:max_chars-3] + "..."
+
+
+@dataclass
+class EdgeSpec:
+    """Specification for an edge between nodes."""
+    source: str
+    target: str
+    label: Optional[str] = None
+    style: Literal["solid", "dashed", "dotted"] = "solid"
+    arrow: Literal["normal", "none", "open"] = "normal"
+
+
+@dataclass
+class DiagramSpec:
+    """Complete diagram specification - the semantic layer."""
+
+    # Metadata
+    type: DiagramType = DiagramType.WORKFLOW
+    title: str = ""
+
+    # Paper constraints
+    paper: PaperConstraints = field(default_factory=PaperConstraints)
+
+    # Layout hints
+    layout: LayoutHints = field(default_factory=LayoutHints)
+
+    # Content
+    nodes: List[NodeSpec] = field(default_factory=list)
+    edges: List[EdgeSpec] = field(default_factory=list)
+
+    # Theme
+    theme: Dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "DiagramSpec":
+        """Create DiagramSpec from dictionary (parsed YAML)."""
+        spec = cls()
+
+        # Parse type
+        if "type" in data:
+            spec.type = DiagramType(data["type"])
+
+        spec.title = data.get("title", "")
+
+        # Parse paper constraints
+        if "paper" in data:
+            p = data["paper"]
+            spec.paper = PaperConstraints(
+                column=ColumnLayout(p.get("column", "single")),
+                max_width_mm=p.get("max_width_mm", 170),
+                reading_direction=p.get("reading_direction", "left_to_right"),
+                mode=PaperMode(p.get("mode", "draft")),
+                emphasize=p.get("emphasize", []),
+                main_flow=p.get("main_flow", []),
+                secondary_flow=p.get("secondary_flow", []),
+                return_edges=[tuple(e) for e in p.get("return_edges", [])],
+            )
+
+        # Parse layout hints
+        if "layout" in data:
+            lt = data["layout"]
+            spec.layout = LayoutHints(
+                layers=lt.get("layers", []),
+                alignment=lt.get("alignment", {}),
+                layer_gap=SpacingLevel(lt.get("layer_gap", "medium")),
+                node_gap=SpacingLevel(lt.get("node_gap", "medium")),
+                groups=lt.get("groups", {}),
+            )
+
+        # Parse nodes
+        for n in data.get("nodes", []):
+            spec.nodes.append(NodeSpec(
+                id=n["id"],
+                label=n.get("label", n["id"]),
+                shape=n.get("shape", "box"),
+                emphasis=n.get("emphasis", "normal"),
+            ))
+
+        # Parse edges
+        for e in data.get("edges", []):
+            spec.edges.append(EdgeSpec(
+                source=e["from"] if "from" in e else e["source"],
+                target=e["to"] if "to" in e else e["target"],
+                label=e.get("label"),
+                style=e.get("style", "solid"),
+                arrow=e.get("arrow", "normal"),
+            ))
+
+        # Theme
+        spec.theme = data.get("theme", {})
+
+        return spec

scitex/diagram/_split.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# Timestamp: 2025-12-15
+# Author: ywatanabe / Claude
+# File: scitex/diagram/_split.py
+
+"""
+Auto-split large diagrams into multiple figures.
+
+Strategies:
+- by_groups: Split by existing layout.groups (deterministic, paper-friendly)
+- by_articulation: Split at hub nodes (graph-theoretic)
+
+The split preserves "ghost nodes" at boundaries for visual continuity.
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Set, Optional, Tuple
+from copy import deepcopy
+from enum import Enum
+
+from scitex.diagram._schema import DiagramSpec, NodeSpec, EdgeSpec
+
+
+class SplitStrategy(Enum):
+    BY_GROUPS = "by_groups"           # Split by layout.groups
+    BY_ARTICULATION = "by_articulation"  # Split at hub nodes
+
+
+@dataclass
+class SplitConfig:
+    """Configuration for auto-splitting."""
+    enabled: bool = False
+    max_nodes: int = 12               # Split if more nodes than this
+    strategy: SplitStrategy = SplitStrategy.BY_GROUPS
+    keep_hubs: bool = True            # Show hub nodes in both parts
+    ghost_style: str = "muted"        # Style for ghost nodes
+
+
+@dataclass
+class SplitResult:
+    """Result of splitting a diagram."""
+    figures: List[DiagramSpec]
+    labels: List[str]                  # Figure labels (A, B, C, ...)
+    cut_nodes: Set[str]               # Nodes that appear in multiple figures
+
+
+def split_diagram(
+    spec: DiagramSpec,
+    config: Optional[SplitConfig] = None,
+    group_assignments: Optional[List[List[str]]] = None,
+) -> SplitResult:
+    """
+    Split a diagram into multiple figures.
+
+    Parameters
+    ----------
+    spec : DiagramSpec
+        Original diagram specification.
+    config : SplitConfig, optional
+        Split configuration.
+    group_assignments : List[List[str]], optional
+        Manual group assignments for splitting.
+        If provided, overrides automatic detection.
+
+    Returns
+    -------
+    SplitResult
+        List of split diagram specifications.
+    """
+    if config is None:
+        config = SplitConfig(enabled=True)
+
+    # Check if split is needed
+    if not config.enabled or len(spec.nodes) <= config.max_nodes:
+        return SplitResult(figures=[spec], labels=[""], cut_nodes=set())
+
+    # Determine groups to split by
+    if group_assignments:
+        groups = group_assignments
+    elif config.strategy == SplitStrategy.BY_GROUPS:
+        groups = _split_by_groups(spec, max_nodes=config.max_nodes)
+    else:  # BY_ARTICULATION
+        groups = _split_by_articulation(spec)
+
+    # Create split figures
+    figures = []
+    labels = []
+    cut_nodes = set()
+
+    for i, group_nodes in enumerate(groups):
+        fig, cuts = _create_split_figure(spec, group_nodes, config)
+        figures.append(fig)
+        labels.append(chr(ord('A') + i))
+        cut_nodes.update(cuts)
+
+    return SplitResult(figures=figures, labels=labels, cut_nodes=cut_nodes)
+
+
+def _split_by_groups(spec: DiagramSpec, max_nodes: int = 12) -> List[List[str]]:
+    """
+    Split by existing layout.groups using greedy packing.
+
+    Packs groups into figures until max_nodes is exceeded,
+    then starts a new figure.
+
+    Returns list of node ID lists, one per split figure.
+    """
+    if not spec.layout.groups:
+        # No groups defined - try to split in half
+        node_ids = [n.id for n in spec.nodes]
+        mid = len(node_ids) // 2
+        return [node_ids[:mid], node_ids[mid:]]
+
+    # Group keys in order
+    group_names = list(spec.layout.groups.keys())
+
+    # Greedy packing: add groups until max_nodes exceeded
+    figures = []
+    current_figure = []
+    current_count = 0
+
+    for group_name in group_names:
+        group_nodes = spec.layout.groups[group_name]
+        group_size = len(group_nodes)
+
+        # If adding this group exceeds max and we have something, start new figure
+        if current_count + group_size > max_nodes and current_figure:
+            figures.append(current_figure)
+            current_figure = []
+            current_count = 0
+
+        # Add group to current figure
+        current_figure.extend(group_nodes)
+        current_count += group_size
+
+    # Don't forget the last figure
+    if current_figure:
+        figures.append(current_figure)
+
+    # Add ungrouped nodes to first figure
+    grouped = set()
+    for fig in figures:
+        grouped.update(fig)
+    for n in spec.nodes:
+        if n.id not in grouped:
+            if figures:
+                figures[0].append(n.id)
+            else:
+                figures.append([n.id])
+
+    # Ensure at least 2 figures if we have enough nodes
+    if len(figures) == 1 and len(figures[0]) > max_nodes:
+        # Force split in half
+        nodes = figures[0]
+        mid = len(nodes) // 2
+        figures = [nodes[:mid], nodes[mid:]]
+
+    return figures
+
+
+def _split_by_articulation(spec: DiagramSpec) -> List[List[str]]:
+    """
+    Split at articulation points (hub nodes).
+
+    This finds nodes that, if removed, would disconnect the graph.
+    These are natural split points for large diagrams.
+    """
+    # Build adjacency
+    adj: Dict[str, Set[str]] = {n.id: set() for n in spec.nodes}
+    for e in spec.edges:
+        adj[e.source].add(e.target)
+        adj[e.target].add(e.source)
+
+    # Find node with most connections (hub)
+    hub = max(adj.keys(), key=lambda x: len(adj[x]))
+
+    # BFS from first node, stopping at hub
+    visited = {hub}  # Block the hub
+    node_ids = [n.id for n in spec.nodes if n.id != hub]
+
+    if not node_ids:
+        return [[hub]]
+
+    # Find components when hub is removed
+    components = []
+    for start in node_ids:
+        if start in visited:
+            continue
+        component = []
+        queue = [start]
+        while queue:
+            curr = queue.pop(0)
+            if curr in visited:
+                continue
+            visited.add(curr)
+            component.append(curr)
+            for neighbor in adj[curr]:
+                if neighbor not in visited:
+                    queue.append(neighbor)
+        if component:
+            components.append(component)
+
+    # Add hub to each component (as ghost)
+    for comp in components:
+        comp.append(hub)
+
+    return components if components else [[n.id for n in spec.nodes]]
+
+
+def _create_split_figure(
+    spec: DiagramSpec,
+    node_ids: List[str],
+    config: SplitConfig,
+) -> Tuple[DiagramSpec, Set[str]]:
+    """
+    Create a split figure containing specified nodes.
+
+    Returns (figure_spec, ghost_node_ids).
+    """
+    node_id_set = set(node_ids)
+
+    # Find edges that cross the boundary
+    boundary_nodes = set()
+    for edge in spec.edges:
+        src_in = edge.source in node_id_set
+        tgt_in = edge.target in node_id_set
+        if src_in and not tgt_in:
+            if config.keep_hubs:
+                boundary_nodes.add(edge.target)
+        elif tgt_in and not src_in:
+            if config.keep_hubs:
+                boundary_nodes.add(edge.source)
+
+    # Create new spec
+    new_spec = DiagramSpec(
+        type=spec.type,
+        title=spec.title,
+        paper=deepcopy(spec.paper),
+        layout=deepcopy(spec.layout),
+        theme=dict(spec.theme),
+    )
+
+    # Filter nodes
+    node_map = {n.id: n for n in spec.nodes}
+    for node_id in node_ids:
+        if node_id in node_map:
+            new_spec.nodes.append(deepcopy(node_map[node_id]))
+
+    # Add ghost nodes (boundary nodes not in this split)
+    for ghost_id in boundary_nodes:
+        if ghost_id in node_map and ghost_id not in node_id_set:
+            ghost = deepcopy(node_map[ghost_id])
+            ghost.emphasis = config.ghost_style
+            ghost.label = f"→ {ghost.label}"  # Mark as continuation
+            new_spec.nodes.append(ghost)
+
+    # Filter edges
+    all_ids = node_id_set | boundary_nodes
+    for edge in spec.edges:
+        if edge.source in all_ids and edge.target in all_ids:
+            new_spec.edges.append(deepcopy(edge))
+
+    # Filter groups
+    new_spec.layout.groups = {}
+    for group_name, group_nodes in spec.layout.groups.items():
+        filtered = [n for n in group_nodes if n in all_ids]
+        if filtered:
+            new_spec.layout.groups[group_name] = filtered
+
+    # Filter layers
+    new_spec.layout.layers = []
+    for layer in spec.layout.layers:
+        filtered = [n for n in layer if n in all_ids]
+        if filtered:
+            new_spec.layout.layers.append(filtered)
+
+    return new_spec, boundary_nodes