holt-cli 0.1.0__py3-none-any.whl

holt/tui/events.py

@@ -0,0 +1,245 @@
+"""The trajectory event schema. Frozen.
+
+This module is the contract between the running pipeline and anything that
+watches it. It imports nothing from Textual and nothing from the TUI, so a
+future consumer — a log renderer, the eval harness, a test — can depend on it
+without dragging a terminal framework in.
+
+Two rules keep it stable:
+
+* **Events are added, never changed.** A stage that learns to emit a new kind of
+  finding adds a new event class. Existing classes keep their fields and their
+  meanings, so a renderer written today keeps working.
+* **Renderers dispatch on type through a registry, never a chain of isinstance
+  branches.** An event a renderer has never seen must degrade to a plain line
+  rather than raising; `describe()` below guarantees every event has one.
+
+The event stream is a *view* of the run. It is not how the run works, and
+nothing in `holt.agent` reads it. Deleting this package would leave the engine,
+the CLI and the eval harness untouched.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Union
+
+# ─── the stage vocabulary ───────────────────────────────────────────────────
+#
+# Mirrors the labels the pipeline passes to `ModelClient.complete`, plus the two
+# steps that run no model. Kept as data rather than an enum so that a stage
+# added to the engine shows up as itself instead of crashing the renderer.
+
+STAGE_TITLES: dict[str, str] = {
+    "classify": "classify",
+    "opportunity": "opportunity",
+    "outcomes": "outcomes",
+    "verify": "verify",
+    "verdict": "verdict",
+    "narrate": "narrate",
+    "pathfinder": "reading order",
+}
+
+#: Display order and gutter marks. Stages not listed here render after these,
+#: in arrival order, with a blank mark — new stages appear rather than vanish.
+STAGE_ORDER: tuple[tuple[str, str], ...] = (
+    ("classify", "A"),
+    ("opportunity", "B"),
+    ("outcomes", "C"),
+    ("verify", "D"),
+    ("verdict", " "),
+    ("narrate", "E"),
+    ("pathfinder", " "),
+)
+
+#: Stages that may legitimately not run — the reading order is skipped when a
+#: repository has no issue fixture. Their rows are mounted when they start
+#: rather than sitting at "—" after the run has finished, which would read as a
+#: stage that stalled rather than one that was never asked for.
+OPTIONAL_STAGES: frozenset[str] = frozenset({"pathfinder"})
+
+
+def stage_title(stage: str) -> str:
+    return STAGE_TITLES.get(stage, stage)
+
+
+def stage_mark(stage: str) -> str:
+    for name, mark in STAGE_ORDER:
+        if name == stage:
+            return mark
+    return " "
+
+
+# ─── events ─────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class RunStarted:
+    repo: str
+    replayed: bool
+
+
+@dataclass(frozen=True, slots=True)
+class EvidenceLoaded:
+    """The provider handed over its records. The size of what the agent may see.
+
+    `cutoff` is the boundary the provider *actually* applied, not the benchmark
+    constant. A live provider defaults it to today; only a fixture run or an
+    explicit `--as-of` is cut at T. A watcher that assumed T would report a
+    holdout the run never applied, so the run states its own.
+    """
+
+    count: int
+    window: str
+    #: Defaulted rather than required: events are added to, never changed, and
+    #: a caller written before this field existed still constructs a valid one.
+    cutoff: datetime | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class StageStarted:
+    stage: str
+    model: str
+
+
+@dataclass(frozen=True, slots=True)
+class StageFinished:
+    stage: str
+    seconds: float
+    summary: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class ToolResponse:
+    """A structured model response, as it came back, before a stage interprets it."""
+
+    stage: str
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class FindingEmitted:
+    """A claim a stage is making, with the ids it says support it.
+
+    Emitted *before* Stage D runs, so the live view can show a claim appear and
+    then be taken away again. `evidence_ids` here is what the model cited, not
+    what resolved.
+    """
+
+    stage: str
+    field: str
+    value: Any
+    evidence_ids: tuple[str, ...] = ()
+    note: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class EvidenceResolved:
+    """One lookup in Stage D. `resolved` false is the interesting case."""
+
+    evidence_id: str
+    resolved: bool
+
+
+@dataclass(frozen=True, slots=True)
+class FindingDropped:
+    """A claim was removed. The moment the whole pipeline exists to make.
+
+    Two reasons, and the difference matters to a reader watching: the cited
+    thread does not exist, or it exists and does not contain the quoted words.
+    Defaulted so an older producer of this event still describes itself.
+    """
+
+    field: str
+    value: Any
+    cited: tuple[str, ...] = ()
+    reason: str = "unresolved"
+
+
+@dataclass(frozen=True, slots=True)
+class UsageUpdated:
+    """Running total after a model call. Zero throughout a replay.
+
+    Added after the first version of this schema shipped, which is the case the
+    module was arranged for: a new class, no change to any existing one, and
+    screens that predate it keep working because they simply have no entry for
+    it in their dispatch table.
+    """
+
+    input_tokens: int
+    output_tokens: int
+    cost_usd: float
+
+
+@dataclass(frozen=True, slots=True)
+class Retry:
+    stage: str
+    attempt: int
+    reason: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class RunFailed:
+    error: str
+
+
+@dataclass(frozen=True, slots=True)
+class RunCancelled:
+    """The run was stopped on purpose, and is not a failure.
+
+    Kept distinct from `RunFailed` because the two need opposite treatment: a
+    failure is something to report and investigate, a stop is something the
+    reader asked for. Merging them would have the interface apologise for
+    obeying an instruction.
+    """
+
+    #: Stages that had already finished when the stop landed. A live run that
+    #: is stopped at stage D has spent real money, and saying so is the
+    #: difference between a stop and a loss.
+    completed_stages: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class RunFinished:
+    """Carries the finished `Assessment` and the pipeline's own `Trace`.
+
+    Typed as `Any` so this module stays importable without pulling in the rest
+    of the package; the attribute is always a `holt.report.Assessment`.
+    """
+
+    assessment: Any
+    trace: Any
+
+
+Event = Union[
+    RunStarted,
+    EvidenceLoaded,
+    StageStarted,
+    StageFinished,
+    ToolResponse,
+    FindingEmitted,
+    EvidenceResolved,
+    FindingDropped,
+    UsageUpdated,
+    Retry,
+    RunFailed,
+    RunCancelled,
+    RunFinished,
+]
+
+
+def describe(event: object) -> str:
+    """A one-line fallback for any event, including ones added after this file.
+
+    A renderer that has no specific handling for an event still has something
+    truthful to print. Nothing in the UI may raise on an unrecognised event.
+    """
+    name = type(event).__name__
+    fields = getattr(event, "__slots__", None) or ()
+    parts = []
+    for key in fields:
+        value = getattr(event, key, None)
+        text = str(value)
+        parts.append(f"{key}={text[:60]}")
+    return f"{name} " + " ".join(parts) if parts else name

holt/tui/mascot.py

@@ -0,0 +1,121 @@
+"""The cat, its moods, and the colour it wears today.
+
+One line, one kaomoji, no block art — so the mascot costs zero vertical space
+and can sit in a masthead or a status line without a layout of its own.
+
+**The face is not decoration, because it reports state.** Each mood below is
+tied to something the engine actually decided: a run in progress, a verdict, a
+claim Stage D removed. That is the whole justification for it being here — a
+mascot that only looked nice would be the one element in an interface built on
+"colour and shape carry meaning" that carried none.
+
+Animation works the same way. The cat blinks slowly at rest and looks about
+while a run is going, so motion means *something is happening* exactly as the
+stage spinner does. Nothing loops to be lively.
+
+The accent is chosen fresh each launch. That is deliberate and it is the only
+colour in the app allowed to be arbitrary: it identifies a *session*, not a
+state, so it is drawn from cool hues that cannot be mistaken for the verdict
+green, the clay of a negative verdict, the red of a dropped claim, or the teal
+of a resolvable evidence id. Those five keep their meanings whatever the cat is
+wearing today.
+"""
+
+from __future__ import annotations
+
+import os
+import random
+
+# ─── moods ──────────────────────────────────────────────────────────────────
+#
+# Frames are held by repetition: a frame listed eight times dwells eight ticks.
+# Reading the tuple tells you the rhythm without a second table of durations.
+
+TICK = 0.12
+
+IDLE = ("(=^･ω･^=)",) * 9 + ("(=^-ω-^=)",)
+WORKING = (
+    ("(=^･ω･^=)",) * 2
+    + ("(=^○ω○^=)",) * 2
+    + ("(=^･ω･^=)",) * 2
+    + ("(=^-ω-^=)",)
+)
+WORTH = ("(=^▽^=)",) * 11 + ("(=^-^=)",)
+NOT_WORTH = ("(=^￣ω￣^=)",) * 14 + ("(=^-ω-^=)",)
+NOT_ENOUGH = ("(=^¬_¬^=)",) * 13 + ("(=^-_-^=)",)
+DROPPED = ("(=^○ω○^=)",) * 6 + ("(=^･ω･^=)",) * 2 + ("(=^○ω○^=)",) * 4
+
+#: Mood name → frames. Anything not listed falls back to `idle`, so a state the
+#: engine grows later shows a calm cat rather than raising.
+MOODS: dict[str, tuple[str, ...]] = {
+    "idle": IDLE,
+    "working": WORKING,
+    "worth_time": WORTH,
+    "not_worth_time": NOT_WORTH,
+    "not_enough_evidence": NOT_ENOUGH,
+    "claim_dropped": DROPPED,
+}
+
+#: Verdict value → mood. Read through `.get`, never matched exhaustively:
+#: `holt.report.Verdict` owns the enum and may grow a fourth member.
+VERDICT_MOODS: dict[str, str] = {
+    "viable": "worth_time",
+    "not_viable": "not_worth_time",
+    "insufficient_evidence": "not_enough_evidence",
+}
+
+
+def frames(mood: str) -> tuple[str, ...]:
+    return MOODS.get(mood, IDLE)
+
+
+def still(mood: str) -> str:
+    """The resting frame, for when motion is off or the cat is not animated."""
+    return frames(mood)[0]
+
+
+def mood_for_verdict(value: str) -> str:
+    return VERDICT_MOODS.get(value, "idle")
+
+
+# ─── the accent of the day ──────────────────────────────────────────────────
+
+#: Cool hues only. Deliberately excludes green, clay, red and teal, which are
+#: the four colours that mean something elsewhere in the interface.
+ACCENTS: tuple[str, ...] = (
+    "#7e87c4",  # periwinkle
+    "#9a7fc4",  # violet
+    "#b07cb8",  # plum
+    "#6f8fd0",  # steel blue
+    "#8f7fd0",  # lilac
+    "#7fa0c9",  # dusty blue
+    "#a87fd0",  # amethyst
+    "#8ca0d8",  # cornflower
+)
+
+
+def pick_accent() -> str:
+    """A different colour each launch, unless one is pinned.
+
+    `HOLT_TUI_ACCENT` fixes it — for a screenshot that should not change under
+    you, and for the tests, which should not assert against a coin flip.
+    """
+    pinned = os.environ.get("HOLT_TUI_ACCENT", "").strip()
+    if pinned:
+        return pinned
+    return random.choice(ACCENTS)
+
+
+# ─── the words beside it ────────────────────────────────────────────────────
+
+#: From `holt.cli`'s own docstring. The tool's description of itself, not a
+#: second one written for the interface.
+TAGLINE = "is this repository worth your time?"
+
+#: The three things worth knowing before you type anything. Facts about how it
+#: behaves, not a feature list.
+FACTS: tuple[str, ...] = (
+    "read-only — never writes to GitHub, never opens a pull request",
+    "every claim carries an evidence id you can open and check",
+    "a claim whose evidence does not resolve is dropped, not softened",
+)