preview.py

"""Preview: render a sample run as a diff for human/Claude review.

A `Preview` is what `Session.sample()` returns. It is **read-only** for the
viewer; mutations happen via `Session.review()` (which feeds actions back
into normalize rules + accepted/rejected sets).

Phase 0: data class + the JSON shape Skill tools will return. Real
construction happens in Phase 1 (#3) when sample() lands.
"""
from __future__ import annotations

from dataclasses import asdict, dataclass, field
from typing import Any, Literal


NodeStatus = Literal["new", "duplicate_of", "low_confidence", "schema_violation"]


@dataclass
class PreviewNode:
    id: str
    label: str
    type: str | None = None
    status: NodeStatus = "new"
    duplicate_of: str | None = None
    confidence: str = "EXTRACTED"
    evidence_span: str | None = None
    rationale: str | None = None
    source_file: str | None = None
    source_location: str | None = None


@dataclass
class PreviewEdge:
    source: str
    target: str
    relation: str
    confidence: str = "EXTRACTED"
    evidence_span: str | None = None
    rationale: str | None = None
    source_file: str | None = None


@dataclass
class Preview:
    """One sample-run's worth of preview material."""

    schema_version: int
    inputs: list[str]
    nodes: list[PreviewNode] = field(default_factory=list)
    edges: list[PreviewEdge] = field(default_factory=list)
    suggested_merges: list[dict[str, Any]] = field(default_factory=list)
    suggested_rules: list[dict[str, Any]] = field(default_factory=list)
    cost_estimate_full: dict[str, Any] | None = None
    notes: list[str] = field(default_factory=list)

    def to_dict(self) -> dict[str, Any]:
        return asdict(self)