matchlab 0.1.0.dev1__py3-none-any.whl

matchlab/eval/tui/widgets/assignment.py

@@ -0,0 +1,72 @@
+"""AssignmentBar widget for displaying column assignments in the evaluation UI."""
+
+from typing import Any, NamedTuple
+
+from textual.widgets import Static
+
+
+class GroupSelect(NamedTuple):
+    """A letter and colour combination representing a group assignment."""
+
+    letter: str
+    colour: str
+
+
+class AssignmentBar(Static):
+    """A status bar widget showing column assignments as a visual bar.
+
+    Each position represents a column in the comparison table. Positions can be:
+
+        - None (unassigned): displayed as dim •
+        - GroupSelect: displayed as letter (first occurrence) or • (subsequent blocks)
+
+    Consecutive positions with the same group assignment are rendered in that
+    group's colour, showing the letter only at the first position.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        """Initialise an empty AssignmentBar."""
+        super().__init__(**kwargs)
+        self.positions: list[GroupSelect | None] = []
+        self._render_bar()
+
+    def reset(self, num_positions: int) -> None:
+        """Reset the bar with a new number of positions.
+
+        Args:
+            num_positions: The number of columns to represent.
+        """
+        self.positions = [None] * num_positions
+        self._render_bar()
+
+    def set_position(self, index: int, letter: str, colour: str) -> None:
+        """Set a position to a letter and colour.
+
+        Args:
+            index: The position index to set.
+            letter: The group letter (a-z).
+            colour: The colour name for the group.
+        """
+        if 0 <= index < len(self.positions):
+            self.positions[index] = GroupSelect(letter, colour)
+            self._render_bar()
+
+    def _render_bar(self) -> None:
+        """Generate the Rich markup for the assignment bar."""
+        if not self.positions:
+            self.update("")
+            return
+
+        parts = []
+        for i, pos in enumerate(self.positions):
+            colour = "dim" if pos is None else pos.colour
+
+            # Show the letter only where a block starts, otherwise •
+            if pos is None or (i > 0 and self.positions[i - 1] == pos):
+                char = "•"
+            else:
+                char = pos.letter
+
+            parts.append(f"[{colour}]{char}[/{colour}]")
+
+        self.update("".join(parts))

matchlab/eval/tui/widgets/styling.py

@@ -0,0 +1,75 @@
+"""Styling utilities for entity resolution evaluation UI."""
+
+GROUP_STYLES = {
+    # Row: q w e r t y u i o p
+    "q": ("■", "#e53935"),  # red
+    "w": ("●", "#43a047"),  # green
+    "e": ("▲", "#1e88e5"),  # blue
+    "r": ("◆", "#fdd835"),  # yellow
+    "t": ("★", "#d81b60"),  # magenta
+    "y": ("⬢", "#00acc1"),  # cyan
+    "u": ("♦", "#fb8c00"),  # orange
+    "i": ("▼", "#00897b"),  # teal
+    "o": ("○", "#8e24aa"),  # purple
+    "p": ("△", "#6d4c41"),  # brown
+    # Row: a s d f g h j k l
+    "a": ("◇", "#d81b60"),  # magenta
+    "s": ("☆", "#00acc1"),  # cyan
+    "d": ("⬡", "#e53935"),  # red
+    "f": ("✦", "#43a047"),  # green
+    "g": ("✧", "#1e88e5"),  # blue
+    "h": ("⟐", "#fdd835"),  # yellow
+    "j": ("✚", "#d81b60"),  # magenta
+    "k": ("✖", "#3949ab"),  # indigo (keeps distance from teal above-left)
+    "l": ("□", "#e53935"),  # red
+    # Row: z x c v b n m
+    "z": ("▽", "#fb8c00"),  # orange
+    "x": ("◯", "#8e24aa"),  # purple (far from cyan/red above)
+    "c": ("◻", "#fdd835"),  # yellow
+    "v": ("◼", "#6d4c41"),  # brown
+    "b": ("⬤", "#e53935"),  # red
+    "n": ("☑", "#43a047"),  # green
+    "m": ("✤", "#1e88e5"),  # blue
+}
+
+
+def get_group_style(group: str) -> tuple[str, str]:
+    """Get symbol and colour for a group letter.
+
+    Args:
+        group: Single letter group identifier (a-z)
+
+    Returns:
+        Tuple of (symbol, colour)
+    """
+    return GROUP_STYLES.get(group.lower(), ("■", "white"))
+
+
+def get_display_text(group: str, count: int) -> tuple[str, str]:
+    """Get formatted display text with colour and symbol.
+
+    Args:
+        group: Single letter group identifier (a-z) or "unassigned"
+        count: Number of items in this group
+
+    Returns:
+        Tuple of (formatted_text, colour)
+    """
+    if group == "unassigned":
+        return f"UNASSIGNED ({count})", "dim"
+
+    symbol, colour = get_group_style(group)
+    text = f"{symbol} {group.upper()} ({count})"
+    return text, colour
+
+
+def generate_css_classes() -> str:
+    """Generate CSS classes for all groups.
+
+    Returns:
+        CSS string with all group styling classes
+    """
+    lines = []
+    for group, (_symbol, colour) in GROUP_STYLES.items():
+        lines.append(f"ComparisonTable .group-{group} {{ background: {colour}; }}")
+    return "\n".join(lines)

matchlab/eval/tui/widgets/table.py

@@ -0,0 +1,285 @@
+"""Comparison display table for entity resolution evaluation."""
+
+from typing import Any
+
+import polars as pl
+from rich.text import Text
+from textual import events
+from textual.binding import Binding
+from textual.message import Message
+from textual.reactive import reactive
+from textual.widgets import DataTable
+from textual.widgets.data_table import ColumnKey
+
+from matchlab.eval.samples import EvaluationItem
+from matchlab.eval.tui.widgets.styling import get_group_style
+
+
+class ComparisonDisplayTable(DataTable):
+    """DataTable for comparing records with keyboard-driven assignment.
+
+    The DataTable's own cursor column is the anchor for the visible "1"-"9" labels,
+    even though the cursor itself is hidden:
+
+    - The cursor column is labelled "1", the next column "2", and so on.
+    - Paging right or left moves the cursor by 9 columns, and forces a scroll so the
+      anchor column sits at the left edge, keeping the labels visible.
+    """
+
+    current_item: reactive[EvaluationItem | None] = reactive(None)
+    current_assignments: reactive[dict[int, str]] = reactive({}, init=False)
+    current_group: reactive[str] = reactive("")
+    table_ready: reactive[bool] = reactive(False)
+
+    # DataTable overrides
+    BINDINGS = [
+        Binding("up", "page_up", "Page up", show=False),
+        Binding("down", "page_down", "Page down", show=False),
+        Binding("right", "page_right", "Page right", show=False),
+        Binding("left", "page_left", "Page left", show=False),
+    ]
+
+    def __init__(
+        self, scroll_debounce_delay: float | None = 0.3, **kwargs: Any
+    ) -> None:
+        """Initialise the comparison display table."""
+        super().__init__(**kwargs)
+        self.zebra_stripes = True
+        # The cursor tracks columns, for the anchor logic below, but stays hidden.
+        self.cursor_type = "column"
+        self.show_cursor = False
+        self.fixed_columns = 1
+
+        self._scroll_debounce_delay: float | None = scroll_debounce_delay
+
+    def watch_current_item(self, item: EvaluationItem | None) -> None:
+        """Rebuild the table when the item changes (Textual reactive pattern)."""
+        self.table_ready = False
+
+        # Reset the cursor to the start (column 1, skipping the fixed 'Field' column)
+        self.move_cursor(row=0, column=1, animate=False)
+        self.scroll_x = 0
+
+        if not item:
+            self.clear(columns=True)
+            return
+
+        unique_groups = item.get_unique_record_groups()
+
+        self.clear(columns=True)
+        self.add_column("Field", key="field")
+
+        for i, _ in enumerate(unique_groups):
+            # Headers will be populated by _update_headers shortly
+            self.add_column("", key=f"col_{i}")
+
+        for field in item.fields:
+            row_values = [Text(field.display_name)]
+            for group in unique_groups:
+                record_idx = group[0]  # Representative record from group
+                row_data = item.records.filter(pl.col("leaf") == record_idx).row(
+                    0, named=True
+                )
+                # Take first non-empty value from source columns
+                value = next(
+                    (
+                        str(row_data.get(col, "")).strip()
+                        for col in field.source_columns
+                        if row_data.get(col)
+                    ),
+                    "",
+                )
+                row_values.append(Text(value))
+            self.add_row(*row_values, key=field.display_name)
+
+        self.table_ready = True
+        # Force header update now that columns exist
+        self._update_headers()
+
+    def watch_cursor_coordinate(self, old_value: float, new_value: float) -> None:
+        """Update headers whenever the cursor moves (manual scroll or paging)."""
+        self._update_headers()
+
+    def watch_current_assignments(
+        self, old_assignments: dict[int, str], new_assignments: dict[int, str]
+    ) -> None:
+        """Update column headers and cells when assignments change."""
+        # Find which columns changed
+        all_group_indices = set(old_assignments.keys()) | set(new_assignments.keys())
+
+        for group_idx in all_group_indices:
+            old_val = old_assignments.get(group_idx)
+            new_val = new_assignments.get(group_idx)
+
+            if old_val != new_val:
+                self._paint_column(group_idx, new_val)
+
+        # Refresh headers (to update status symbols)
+        self._update_headers()
+
+    def on_key(self, event: events.Key) -> None:
+        """Handle keyboard shortcuts for assignment."""
+        if event.key in "abcdefghijklmnopqrstuvwxyz":
+            self.current_group = event.key
+            self.post_message(self.CurrentGroupChanged(event.key))
+            event.stop()
+
+        elif event.key in "123456789":
+            if not self.current_item or not self.current_group:
+                return
+
+            key_num = int(event.key)
+
+            # Group index is relative to the anchor (cursor column). Key '1' is the
+            # anchor itself, and the fixed field column (index 0) does not count.
+            anchor_col = max(1, self.cursor_column)
+            group_idx = (anchor_col - 1) + (key_num - 1)
+
+            unique_groups = self.current_item.get_unique_record_groups()
+            if 0 <= group_idx < len(unique_groups):
+                self.post_message(self.AssignmentMade(group_idx, self.current_group))
+
+            event.stop()
+
+    def action_page_right(self) -> None:
+        """Move the anchor (cursor) right by 9 columns and force scroll."""
+        if not self.current_item:
+            return
+
+        unique_groups = self.current_item.get_unique_record_groups()
+        total_cols = len(unique_groups) + self.fixed_columns
+
+        current_col = self.cursor_column
+
+        # The last page should be full (9 columns) where possible, so the anchor never
+        # goes past total_cols - 9. Example: 20 columns gives max anchor 11, showing
+        # columns 11-19.
+        max_anchor = max(self.fixed_columns, total_cols - 9)
+
+        target_col = min(current_col + 9, max_anchor)
+
+        # Snapping back to max_anchor also recovers from manual scrolling that put the
+        # anchor past it.
+        if target_col != current_col:
+            # Move the cursor without scrolling, then scroll explicitly so the anchor
+            # column lands at the left edge rather than wherever Textual defaults to.
+            self.move_cursor(column=target_col, animate=False, scroll=False)
+            self._scroll_column_to_left(target_col)
+
+    def action_page_left(self) -> None:
+        """Move the anchor (cursor) left by 9 columns and force scroll."""
+        current_col = self.cursor_column
+
+        # Move left by 9 columns, clamped to the first data column.
+        target_col = max(self.fixed_columns, current_col - 9)
+
+        if target_col != current_col:
+            self.move_cursor(column=target_col, animate=False, scroll=False)
+            self._scroll_column_to_left(target_col)
+
+    def _scroll_column_to_left(self, column_index: int) -> None:
+        """Scroll so the target column is at the left edge of the viewport."""
+        region = self._get_column_region(column_index)
+        target_x = region.x
+
+        # Fixed columns obscure the left of the viewport, so subtract their width to
+        # land the target column just past them, not at absolute x=0.
+        fixed_offset = self._get_fixed_offset()
+        scroll_target = target_x - fixed_offset.left
+
+        self.scroll_to(
+            x=scroll_target,
+            animate=bool(self._scroll_debounce_delay),
+            duration=self._scroll_debounce_delay,
+        )
+
+    def _update_headers(self) -> None:
+        """Update column headers based on current cursor position."""
+        if not self.current_item or not self.table_ready:
+            return
+
+        unique_groups = self.current_item.get_unique_record_groups()
+
+        # The anchor is the cursor column, clamped so it never indexes the fixed
+        # 'Field' column.
+        anchor_col = max(1, self.cursor_column)
+
+        # Calculate the data index offset (cursor column 1 maps to data index 0)
+        data_offset = anchor_col - 1
+
+        for i, group in enumerate(unique_groups):
+            # Visual position 1-9 relative to the anchor
+            # i is the data index. Visual position is (i - data_offset) + 1
+            visual_pos_idx = i - data_offset + 1
+
+            visual_pos = None
+            if 1 <= visual_pos_idx <= 9:
+                visual_pos = visual_pos_idx
+
+            assignment = self.current_assignments.get(i)
+            new_header = self._build_header(visual_pos, group, assignment)
+
+            # Update DataTable column label (+1 for fixed field column)
+            self.ordered_columns[i + 1].label = new_header
+
+        # DataTable caches rendered labels, so the new ones need this to show.
+        self._clear_caches()
+        self.refresh()
+
+    def _paint_column(self, group_idx: int, assignment: str | None) -> None:
+        """Paint or unpaint a column with colour and symbol."""
+        if not self.current_item:
+            return
+
+        unique_groups = self.current_item.get_unique_record_groups()
+        if group_idx >= len(unique_groups):
+            return
+
+        col_key: ColumnKey = f"col_{group_idx}"
+        colour = get_group_style(assignment)[1] if assignment else None
+
+        for row_key in self.rows:
+            cell_value = str(self.get_cell(row_key, col_key))
+            text_obj = Text(cell_value)
+            if colour:
+                text_obj.stylize(colour)
+            self.update_cell(row_key, col_key, text_obj)
+
+    def _build_header(
+        self, visual_pos: int | None, group: list[int], assignment: str | None = None
+    ) -> Text:
+        """Build header with position, count, and optional assignment."""
+        dup_count = len(group)
+        count_text = f" (×{dup_count})" if dup_count > 1 else ""
+
+        header = Text()
+
+        if assignment:
+            symbol, colour = get_group_style(assignment)
+            pos_text = f" {visual_pos}" if visual_pos is not None else ""
+            header.append(f"{symbol}{pos_text}{count_text}")
+            header.stylize(colour)
+        else:
+            if visual_pos is not None:
+                header.append(f"{visual_pos}{count_text}", style="dim")
+            else:
+                header.append(count_text.strip(), style="dim")
+
+        return header
+
+    class AssignmentMade(Message):
+        """Posted when a single column assignment is made."""
+
+        def __init__(self, column_idx: int, group: str) -> None:
+            """Initialise assignment made message."""
+            super().__init__()
+            self.column_idx = column_idx
+            self.group = group
+
+    class CurrentGroupChanged(Message):
+        """Posted when current group selection changes."""
+
+        def __init__(self, group: str) -> None:
+            """Initialise current group changed message."""
+            super().__init__()
+            self.group = group

matchlab/lineage.py

@@ -0,0 +1,239 @@
+"""Lineage algorithms over a plan tree.
+
+Steps hold references to their *inputs* only (`step.upstream`). There is no registry
+and no downstream pointer. "The DAG" is therefore
+whatever is reachable upstream from the node you are holding, and every graph
+operation is a pure function of a root node.
+
+Nodes are deduplicated by **object identity**, not by name or config. A node feeding
+two branches is one object and is visited once (structural sharing), while two
+structurally identical but distinct nodes are two plan entries.
+
+`draw` also owns the vocabulary for *how a step is doing*, meaning `StepStatus` and
+`StepState`, because the tree is where that vocabulary is read. `matchlab.progress`
+drives it during a collection. Nothing here executes anything.
+"""
+
+from collections.abc import Mapping
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict
+
+if TYPE_CHECKING:
+    # `matchlab.steps` imports this module
+    from matchlab.steps import Step
+
+
+class StepStatus(StrEnum):
+    """Where a step has got to in a collection.
+
+    `CACHED` and `DONE` both mean the artifact is available. They differ in whether
+    this collection paid for it. That distinction is the whole point of showing
+    progress for a content-addressed plan. It is how you see what your edit
+    invalidated.
+    """
+
+    PENDING = "pending"
+    RUNNING = "running"
+    DONE = "done"
+    CACHED = "cached"
+    FAILED = "failed"
+
+    @property
+    def marker(self) -> str:
+        """A single-width glyph for this status.
+
+        Deliberately geometric rather than emoji: emoji are double-width in some
+        terminals and single in others, which knocks a tree's guide lines out of
+        alignment line by line.
+        """
+        return _MARKERS[self]
+
+    @property
+    def style(self) -> str:
+        """A Rich style for this status, used when drawing with markup."""
+        return _STYLES[self]
+
+
+_MARKERS: dict[StepStatus, str] = {
+    StepStatus.PENDING: "○",
+    StepStatus.RUNNING: "◐",
+    StepStatus.DONE: "●",
+    StepStatus.CACHED: "◍",
+    StepStatus.FAILED: "✗",
+}
+
+_STYLES: dict[StepStatus, str] = {
+    StepStatus.PENDING: "dim",
+    StepStatus.RUNNING: "bold yellow",
+    StepStatus.DONE: "bold green",
+    StepStatus.CACHED: "cyan",
+    StepStatus.FAILED: "bold red",
+}
+
+
+# Statuses where an elapsed time is worth showing, the ones that spent any.
+_TIMED = (StepStatus.RUNNING, StepStatus.DONE, StepStatus.FAILED)
+
+
+class StepState(BaseModel):
+    """A step's status, and how long it has been in it."""
+
+    model_config = ConfigDict(frozen=True)
+
+    status: StepStatus
+    elapsed: float | None = None
+
+    def annotation(self) -> str:
+        """The trailing detail shown after a step in a drawing, possibly empty.
+
+        A time is shown only where it was spent. A cached step reads `cached` alone,
+        because `0.0s` next to it says nothing.
+        """
+        parts: list[str] = []
+        if self.status not in (StepStatus.PENDING, StepStatus.DONE):
+            parts.append(self.status.value)
+        if self.elapsed is not None and self.status in _TIMED:
+            parts.append(f"{self.elapsed:.1f}s")
+        return " ".join(parts)
+
+
+def walk(root: "Step") -> list["Step"]:
+    """Return `root` and every transitive input, in topological order.
+
+    Upstream steps always precede the steps that consume them, so executing the
+    returned list in order satisfies every dependency. Implemented as an iterative
+    depth-first post-order over the upstream references.
+    """
+    ordered: list[Step] = []
+    seen: set[int] = set()
+    # (step, expanded). `expanded` marks the second visit, when the node's inputs
+    # have already been pushed and it is safe to emit.
+    stack: list[tuple[Step, bool]] = [(root, False)]
+
+    while stack:
+        step, expanded = stack.pop()
+        if expanded:
+            ordered.append(step)
+            continue
+        if id(step) in seen:
+            continue
+        seen.add(id(step))
+        stack.append((step, True))
+        for parent in step.upstream:
+            if id(parent) not in seen:
+                stack.append((parent, False))
+
+    return ordered
+
+
+def number(root: "Step") -> dict[int, int]:
+    """Map each step in `root`'s plan to the position it is known by.
+
+    A step is referred to by position, in logs, in `draw()`, and in a document.
+    The position belongs to the walk rather than to the step: the
+    same node numbers differently in `walk(deduped)` and `walk(companies)`, so nothing
+    is written back onto the steps. Callers that need one hold this mapping, as
+    `draw` does and as `matchlab.progress.Progress` does for the walk `collect` gave it.
+
+    Returns:
+        Step identity to position, in walk order.
+    """
+    return {id(step): position for position, step in enumerate(walk(root))}
+
+
+def draw(
+    root: "Step",
+    state: Mapping[int, StepState] | None = None,
+    *,
+    markup: bool = False,
+) -> str:
+    """`root`'s sub-plan as an indented tree. See `render`, which this joins up."""
+    return "\n".join(render(root, state, markup=markup)[0])
+
+
+def render(
+    root: "Step",
+    state: Mapping[int, StepState] | None = None,
+    *,
+    markup: bool = False,
+) -> tuple[list[str], dict[int, int]]:
+    """Render `root`'s sub-plan as an indented tree, inputs nested beneath consumers.
+
+    Each node carries its **position**, the index `collect` runs it at, and the index
+    it occupies in this plan's document. The index is the cross-reference, where
+    `step 7` is the node drawn as `[7]`. Positions come from `walk`, not from the order
+    these lines happen to be printed in, since a tree nests consumers above their
+    inputs while a walk lists inputs first.
+
+    Args:
+        root: The step to draw, along with everything upstream of it.
+        state: Per-step status, keyed by `id(step)` as `number` is. Steps missing from
+            the mapping are drawn as `PENDING`. When omitted, each step is drawn from
+            its own `is_collected` flag instead, a static view of a plan you hold.
+        markup: Emit Rich markup, styling each marker and annotation by status. Off by
+            default, so the return value stays printable anywhere.
+
+    Returns:
+        The lines, one per node plus one per repeat reference, and the row each step
+        is first drawn on, keyed by `id(step)` as `number` is. The rows are what let a
+        caller show part of a tree and still know where it is: `matchlab.progress`
+        windows a plan too tall for the terminal around the row that is running.
+
+    A node feeding several branches is expanded where it is first met and marked `↑`
+    everywhere after, rather than having its whole subtree redrawn each time. Positions
+    are what make that readable. `↑ [12]` names the node you already have, and without
+    it the drawing contradicts the structural sharing it is meant to show. The
+    24-step plan in `examples/companies` draws 187 lines expanded, and 39 like this.
+    """
+    position = number(root)
+    lines: list[str] = []
+    expanded: set[int] = set()
+    # Where each step is drawn. A repeat reference is a pointer to the expansion, not
+    # another copy of it, so the first row is the one worth looking at.
+    rows: dict[int, int] = {}
+
+    def draw_step(step: "Step", prefix: str, connector: str) -> None:
+        if state is None:
+            marker = "●" if step.is_collected else "○"
+            style, annotation = "", ""
+        else:
+            step_state = state.get(id(step), StepState(status=StepStatus.PENDING))
+            marker = step_state.status.marker
+            style = step_state.status.style
+            annotation = step_state.annotation()
+
+        repeat = id(step) in expanded
+        expanded.add(id(step))
+
+        label = f"[{position[id(step)]}] {step}"
+        if annotation:
+            label = f"{label} {annotation}"
+        if repeat:
+            label = f"{label} ↑"
+
+        # Escape the whole label, not just the step. `[7]` would itself parse as a
+        # style tag.
+        row = (
+            f"[{style}]{marker}[/] {_escape(label)}" if markup else f"{marker} {label}"
+        )
+
+        rows.setdefault(id(step), len(lines))
+        lines.append(f"{prefix}{connector}{row}")
+        if repeat:  # already drawn in full above, the reference is the whole line
+            return
+
+        child_prefix = prefix + ("    " if connector in ("└── ", "") else "│   ")
+        parents = step.upstream
+        for index, parent in enumerate(parents):
+            last = index == len(parents) - 1
+            draw_step(parent, child_prefix, "└── " if last else "├── ")
+
+    draw_step(root, "", "")
+    return lines, rows
+
+
+def _escape(text: str) -> str:
+    """Escape Rich markup, so a `[7]` isn't read as a style tag."""
+    return text.replace("[", r"\[")