psystack 0.1.0__py3-none-any.whl

psystack/tui/widgets/causal_sequence.py

@@ -0,0 +1,73 @@
+"""Causal sequence — event chain timeline and factor attribution visualization."""
+
+from __future__ import annotations
+
+from rich.text import Text
+
+from textual.widgets import Static
+
+from psystack.models.event import Event
+from psystack.models.isolation import EffectEstimate
+
+_TYPE_SHORT = {
+    "first_signal_divergence": "sig div",
+    "first_action_divergence": "act div",
+    "first_risk_spike": "risk",
+    "first_boundary_collapse": "boundary",
+    "terminal": "terminal",
+    "max_metric_gap": "max gap",
+}
+
+_FACTOR_STYLES = {
+    "world_model": "bold magenta",
+    "planner": "bold cyan",
+    "env": "bold green",
+    "interaction": "bold yellow",
+    "unknown": "dim",
+}
+
+
+class CausalSequence(Static):
+    """Displays event chain as a causal arrow sequence, plus factor attribution chain."""
+
+    DEFAULT_CSS = """
+    CausalSequence {
+        height: auto;
+        padding: 1;
+    }
+    """
+
+    def set_events(self, events: list[Event]) -> None:
+        """Set the event chain (temporal causal sequence)."""
+        if not events:
+            self.update("No causal sequence available")
+            return
+        text = Text()
+        text.append("Event chain: ", style="bold")
+        for i, evt in enumerate(events):
+            if i > 0:
+                text.append(" -> ", style="dim")
+            label = _TYPE_SHORT.get(evt.type, evt.type)
+            text.append(f"[{evt.step}]", style="bold")
+            text.append(label)
+        self.update(text)
+
+    def set_factor_chain(self, main_effects: list[EffectEstimate]) -> None:
+        """Set the factor attribution chain from isolation results."""
+        if not main_effects:
+            return
+
+        # Sort by effect magnitude descending
+        sorted_effects = sorted(main_effects, key=lambda e: abs(e.effect), reverse=True)
+
+        text = Text()
+        text.append("\nFactor attribution: ", style="bold")
+        for i, eff in enumerate(sorted_effects):
+            if i > 0:
+                text.append(" > ", style="dim")
+            style = _FACTOR_STYLES.get(eff.factor, "")
+            conf_pct = f"{eff.confidence:.0%}" if eff.confidence else "?"
+            text.append(f"{eff.factor}", style=style)
+            text.append(f"({conf_pct})", style="dim")
+
+        self.update(text)

psystack/tui/widgets/comparability_summary.py

@@ -0,0 +1,48 @@
+"""Comparability summary widget — shows shared config + checkpoint comparison."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from textual.widgets import Static
+
+
+class ComparabilitySummary(Static):
+    """Displays shared config and checkpoint diff for the always-compare builder."""
+
+    DEFAULT_CSS = """
+    ComparabilitySummary {
+        height: auto;
+        padding: 1 2;
+        color: $text-muted;
+    }
+    """
+
+    def update_comparison(
+        self,
+        track: str,
+        episodes: int,
+        detail_a: str,
+        detail_b: str,
+        env_overrides: dict[str, Any] | None = None,
+        planner_diff: str | None = None,
+    ) -> None:
+        lines = []
+        lines.append(f"Shared: TRACK={track or '(none)'} | EPISODES={episodes}")
+
+        if env_overrides:
+            parts = [f"{k}={v}" for k, v in env_overrides.items()]
+            lines.append(f"Env: {', '.join(parts)}")
+
+        if detail_a != detail_b:
+            lines.append(f"Checkpoint: baseline={detail_a} vs candidate={detail_b}")
+        else:
+            lines.append("Checkpoint: (identical -- not a valid comparison)")
+
+        if planner_diff:
+            lines.append(f"Planner: {planner_diff}")
+
+        track_ok = bool(track)
+        lines.append(f"Checks: track {'OK' if track_ok else 'WARN: no track selected'}")
+
+        self.update("\n".join(lines))

psystack/tui/widgets/context_rail.py

@@ -0,0 +1,69 @@
+"""Context rail — left panel showing run cards and case summary."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.widgets import Static
+
+from psystack.models.case import Case
+
+
+class ContextRail(Vertical):
+    """Left rail showing run configuration and case context."""
+
+    DEFAULT_CSS = """
+    ContextRail {
+        width: 22;
+        border: solid $panel;
+        padding: 1;
+    }
+    ContextRail .cr-title {
+        text-style: bold;
+        padding-bottom: 1;
+    }
+    ContextRail .cr-section {
+        text-style: bold;
+        padding: 1 0 0 0;
+        color: $accent;
+    }
+    ContextRail .cr-field {
+        padding: 0;
+        color: $text-muted;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Static("Case Context", classes="cr-title")
+        yield Static("No case loaded", id="cr-content")
+
+    def set_case(self, case: Case) -> None:
+        content = self.query_one("#cr-content", Static)
+        lines = []
+
+        for label, run in [("[Run A]", case.run_a), ("[Run B]", case.run_b)]:
+            if run is None:
+                continue
+            lines.append(label)
+            lines.append(f"  wm: {_short(run.world_model_ref)}")
+            lines.append(f"  pln: {run.planner_ref or 'cem'}")
+            lines.append(f"  ep: {run.num_episodes}")
+            lines.append("")
+
+        lines.append("[Shared]")
+        lines.append(f"  track: {case.track_ref or '(none)'}")
+        lines.append(f"  episodes: {case.episode_count}")
+        seeds_str = ", ".join(str(s) for s in case.eval_seeds) if case.eval_seeds else "auto"
+        lines.append(f"  seeds: {seeds_str}")
+        lines.append(f"  align: {case.alignment_method}")
+
+        content.update("\n".join(lines))
+
+
+def _short(ref: str) -> str:
+    """Shorten a reference path for display."""
+    if not ref:
+        return "(none)"
+    # Show just filename
+    parts = ref.replace("\\", "/").split("/")
+    return parts[-1] if parts else ref

psystack/tui/widgets/effect_table.py

@@ -0,0 +1,32 @@
+"""Effect estimate table for attribution view."""
+
+from __future__ import annotations
+
+from textual.widgets import DataTable
+
+from psystack.models.isolation import EffectEstimate
+
+
+class EffectTable(DataTable):
+    DEFAULT_CSS = """
+    EffectTable {
+        height: auto;
+        max-height: 10;
+    }
+    """
+
+    def on_mount(self) -> None:
+        self.cursor_type = "row"
+        self.add_columns("Factor", "Effect", "Confidence", "Support tests")
+
+    def load_effects(self, effects: list[EffectEstimate]) -> None:
+        self.clear()
+        for e in effects:
+            conf_str = f"{e.confidence:.2f}" if e.confidence is not None else "—"
+            support_str = ", ".join(e.support_tests) if e.support_tests else "—"
+            self.add_row(
+                e.factor,
+                f"{e.effect:+.4f}",
+                conf_str,
+                support_str,
+            )

psystack/tui/widgets/event_navigator.py

@@ -0,0 +1,176 @@
+"""Event navigator — scrollable event list with severity-grouped sections."""
+
+from __future__ import annotations
+
+from rich.text import Text
+from textual.app import ComposeResult
+from textual.containers import VerticalScroll
+from textual.message import Message
+from textual.widgets import Static
+
+from psystack.models.event import Event
+
+_SEVERITY_STYLES = {
+    "critical": ("\u25cf", "bold red"),
+    "warning": ("\u25b2", "bold yellow"),
+    "info": ("\u25cb", "dim"),
+}
+
+_TYPE_SHORT = {
+    "first_signal_divergence": "sig_div",
+    "first_action_divergence": "act_div",
+    "first_risk_spike": "risk",
+    "first_boundary_collapse": "boundary",
+    "terminal": "terminal",
+    "max_metric_gap": "max_gap",
+    "first_divergence": "first_div",
+    "divergence_window": "div_window",
+    "risk_spike": "risk",
+    "off_track_terminal": "off_track",
+    "max_gap": "max_gap",
+}
+
+
+class EventNavigator(VerticalScroll):
+    """Right-rail event list — grouped by investigation relevance."""
+
+    _highlighted_idx: int = -1
+
+    class EventClicked(Message):
+        def __init__(self, event_idx: int, step: int) -> None:
+            self.event_idx = event_idx
+            self.step = step
+            super().__init__()
+
+    DEFAULT_CSS = """
+    EventNavigator {
+        width: 100%;
+        height: auto;
+        max-height: 50%;
+        min-height: 6;
+        border: round $panel;
+        padding: 0;
+    }
+    EventNavigator .en-item {
+        padding: 0 1;
+        height: 1;
+    }
+    EventNavigator .en-item-selected {
+        padding: 0 1;
+        height: 1;
+        background: $accent 15%;
+        border-left: wide $accent;
+    }
+    EventNavigator .en-section {
+        padding: 0 1;
+        height: 1;
+        color: $text-muted;
+        text-style: bold;
+    }
+    EventNavigator .en-empty {
+        padding: 1 2;
+        color: $text-muted;
+    }
+    """
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._events: list[Event] = []
+        # Direct widget references — index maps to Static widget, avoids ID collisions
+        self._item_widgets: list[Static] = []
+
+    def compose(self) -> ComposeResult:
+        self.border_title = "Divergences"
+        yield from ()
+
+    def set_events(self, events: list[Event]) -> None:
+        self._events = events
+        self._highlighted_idx = -1
+        self._item_widgets = []
+
+        # Remove all existing children synchronously via remove_children
+        self.remove_children()
+
+        if not events:
+            self.mount(Static("No divergences detected", classes="en-empty"))
+            self.border_title = "Divergences"
+            return
+
+        suggested = [(i, e) for i, e in enumerate(events) if e.severity in ("critical", "warning")]
+        other = [(i, e) for i, e in enumerate(events) if e.severity == "info"]
+
+        to_mount: list[Static] = []
+
+        if suggested:
+            to_mount.append(Static("Suggested Path", classes="en-section"))
+            for i, evt in suggested:
+                w = self._build_event_widget(i, evt, selected=False)
+                self._item_widgets.append((i, w))
+                to_mount.append(w)
+
+        if other:
+            to_mount.append(Static("Other Divergences", classes="en-section"))
+            for i, evt in other:
+                w = self._build_event_widget(i, evt, selected=False)
+                self._item_widgets.append((i, w))
+                to_mount.append(w)
+
+        if not suggested and not other:
+            for i, evt in enumerate(events):
+                w = self._build_event_widget(i, evt, selected=False)
+                self._item_widgets.append((i, w))
+                to_mount.append(w)
+
+        self.mount(*to_mount)
+        self.border_title = f"Divergences ({len(events)})"
+
+    def _build_event_widget(self, idx: int, evt: Event, selected: bool) -> Static:
+        line = self._build_line(idx, evt, selected)
+        cls = "en-item-selected" if selected else "en-item"
+        # No ID — we use _item_widgets list for direct reference
+        return Static(line, classes=cls)
+
+    def _build_line(self, idx: int, evt: Event, selected: bool) -> Text:
+        icon, icon_style = _SEVERITY_STYLES.get(evt.severity, ("?", ""))
+        label = _TYPE_SHORT.get(evt.type, evt.type.replace("_", " "))
+        line = Text()
+        line.append("> " if selected else "  ", style="bold" if selected else "")
+        line.append(icon, style=icon_style)
+        line.append(f" t={evt.step} ", style="bold")
+        line.append(label, style="")
+        return line
+
+    def highlight(self, idx: int | None) -> None:
+        """Highlight the event at idx."""
+        old = self._highlighted_idx
+        new = idx if idx is not None else -1
+        if old == new:
+            return
+        self._highlighted_idx = new
+
+        # Deselect old
+        for item_idx, widget in self._item_widgets:
+            if item_idx == old:
+                try:
+                    widget.set_classes("en-item")
+                    widget.update(self._build_line(item_idx, self._events[item_idx], selected=False))
+                except Exception:
+                    pass
+                break
+
+        # Select new
+        for item_idx, widget in self._item_widgets:
+            if item_idx == new:
+                try:
+                    widget.set_classes("en-item-selected")
+                    widget.update(self._build_line(item_idx, self._events[item_idx], selected=True))
+                    widget.scroll_visible()
+                except Exception:
+                    pass
+                break
+
+    def on_click(self, event) -> None:
+        for item_idx, widget in self._item_widgets:
+            if widget is event.widget:
+                self.post_message(self.EventClicked(item_idx, self._events[item_idx].step))
+                return

psystack/tui/widgets/explanation_card.py

@@ -0,0 +1,67 @@
+"""Explanation card — confidence bar, tier badge, and support basis."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.widgets import Static
+
+from psystack.models.explanation import Explanation
+
+_TIER_LABELS = {
+    "tier_0": "Tier 0: Correlational",
+    "tier_1": "Tier 1: Component-isolated",
+    "tier_2": "Tier 2: Counterfactual",
+    "tier_3": "Tier 3: Mechanistic",
+}
+
+
+def _confidence_bar(confidence: float, width: int = 20) -> str:
+    """Render a text-mode confidence bar."""
+    filled = int(confidence * width)
+    return "#" * filled + "-" * (width - filled)
+
+
+class ExplanationCard(Vertical):
+    """Displays an explanation with confidence visualization."""
+
+    DEFAULT_CSS = """
+    ExplanationCard {
+        height: auto;
+        border: solid $panel;
+        padding: 1;
+        margin: 0 0 1 0;
+    }
+    ExplanationCard .ec-label {
+        text-style: bold;
+    }
+    ExplanationCard .ec-tier {
+        color: $accent;
+    }
+    ExplanationCard .ec-confidence {
+        padding: 0;
+    }
+    ExplanationCard .ec-details {
+        color: $text-muted;
+    }
+    """
+
+    def __init__(self, explanation: Explanation, rank: int = 1, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._explanation = explanation
+        self._rank = rank
+
+    def compose(self) -> ComposeResult:
+        ex = self._explanation
+        yield Static(f"{self._rank}. {ex.label}", classes="ec-label")
+        yield Static(_TIER_LABELS.get(ex.tier, ex.tier), classes="ec-tier")
+        yield Static(
+            f"  confidence: {ex.confidence:.2f} [{_confidence_bar(ex.confidence)}]",
+            classes="ec-confidence",
+        )
+        if ex.support_basis:
+            yield Static(f"  basis: {' | '.join(ex.support_basis)}", classes="ec-details")
+        if ex.competing:
+            yield Static(f"  competing: {', '.join(ex.competing)}", classes="ec-details")
+        if ex.falsifiers:
+            yield Static(f"  falsifiers: {'; '.join(ex.falsifiers)}", classes="ec-details")

psystack/tui/widgets/falsifier_list.py

@@ -0,0 +1,73 @@
+"""Falsifier list — conditions that would disprove the explanation."""
+
+from __future__ import annotations
+
+from rich.text import Text
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.widgets import Static
+
+from psystack.models.isolation import EffectEstimate
+
+
+class FalsifierList(Vertical):
+    """Displays falsification conditions for the current explanation."""
+
+    DEFAULT_CSS = """
+    FalsifierList {
+        height: auto;
+        border: solid $panel;
+        padding: 1;
+    }
+    FalsifierList .fl-title {
+        text-style: bold;
+        padding-bottom: 1;
+    }
+    FalsifierList .fl-item {
+        color: $text-muted;
+        padding: 0 0 0 2;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Static("Falsifiers", classes="fl-title")
+        yield Static("No falsifiers defined", id="fl-content", classes="fl-item")
+
+    def set_falsifiers(self, falsifiers: list[str]) -> None:
+        """Set falsifier conditions from explanation model."""
+        content = self.query_one("#fl-content", Static)
+        if not falsifiers:
+            content.update("No falsifiers defined")
+            return
+        lines = [f"? {f}" for f in falsifiers]
+        content.update("\n".join(lines))
+
+    def set_interaction_effects(self, interactions: list[EffectEstimate]) -> None:
+        """Set falsifiers derived from interaction effects (contradictions)."""
+        content = self.query_one("#fl-content", Static)
+        if not interactions:
+            return
+
+        text = Text()
+        text.append("Interaction effects (potential contradictions):\n", style="bold")
+        for eff in interactions:
+            # An interaction effect suggests the main-effect attribution
+            # may be incomplete — the factors interact non-additively
+            severity = "HIGH" if abs(eff.effect) > 0.1 else "low"
+            style = "bold red" if severity == "HIGH" else "dim"
+            text.append(f"  [{severity}] ", style=style)
+            text.append(f"{eff.factor}: effect={eff.effect:.4f}")
+            if eff.confidence:
+                text.append(f" (conf={eff.confidence:.0%})")
+            text.append("\n")
+
+        # If main factors explain <80% of total, add a falsifier note
+        text.append("\nFalsification conditions:\n", style="bold")
+        for eff in interactions:
+            text.append(
+                f"  ? If {eff.factor} effect persists after controlling main factors, "
+                f"attribution is incomplete\n"
+            )
+
+        content.update(text)

psystack/tui/widgets/focus_signals_strip.py

@@ -0,0 +1,22 @@
+"""Compact single-line strip showing top signal deltas."""
+
+from __future__ import annotations
+
+from textual.widgets import Static
+
+
+class FocusSignalsStrip(Static):
+    """Single-line display of top signal deltas at the current step/event."""
+
+    DEFAULT_CSS = """
+    FocusSignalsStrip {
+        height: 1;
+        background: $boost;
+        padding: 0 1;
+    }
+    """
+
+    def set_signals(self, deltas: list[tuple[str, float]]) -> None:
+        """Show top signal deltas as compact line."""
+        parts = [f"{name} \u0394{val:+.3f}" for name, val in deltas[:5]]
+        self.update(" \u2502 ".join(parts) if parts else "")

psystack/tui/widgets/help_overlay.py

@@ -0,0 +1,85 @@
+"""HelpOverlay — toggleable command list popup."""
+
+from __future__ import annotations
+
+from textual.app import ComposeResult
+from textual.containers import Vertical
+from textual.widgets import Static
+
+
+# (key, description) pairs — grouped
+_COMMANDS: list[tuple[str, str]] = [
+    ("r", "Run evaluation"),
+    ("A", "Reanalyze"),
+    ("E", "Edit case"),
+    ("x", "Export report"),
+    ("e", "Evidence drawer"),
+    ("c", "Context drawer"),
+    ("a", "Attribution"),
+    ("b", "Builder"),
+    ("", ""),
+    ("j / ]", "Next event"),
+    ("k / [", "Prev event"),
+    (", / . / l", "Step back / forward"),
+    ("H / L", "Step back / forward 10"),
+    ("", ""),
+    ("n / N", "Next / prev episode"),
+    ("m", "Cycle signal"),
+    ("t", "Cycle timeline mode"),
+    ("w", "Cycle event window"),
+    ("v", "Cycle live view"),
+    ("", ""),
+    ("esc", "Back"),
+    ("h", "Close help"),
+]
+
+
+class HelpOverlay(Vertical):
+    """Floating command reference panel."""
+
+    DEFAULT_CSS = """
+    HelpOverlay {
+        display: none;
+        dock: bottom;
+        height: auto;
+        max-height: 70%;
+        background: $surface;
+        border-top: tall $accent;
+        padding: 1 2;
+    }
+    HelpOverlay.visible {
+        display: block;
+    }
+    HelpOverlay .help-title {
+        text-style: bold;
+        color: $accent;
+        padding: 0 0 1 0;
+    }
+    HelpOverlay .help-row {
+        height: 1;
+        padding: 0 1;
+    }
+    HelpOverlay .help-key {
+        width: 12;
+        text-style: bold;
+        color: $text;
+    }
+    HelpOverlay .help-sep {
+        height: 1;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Static("Commands", classes="help-title")
+        for key, desc in _COMMANDS:
+            if not key and not desc:
+                yield Static("", classes="help-sep")
+            else:
+                yield Static(f"  {key:<10} {desc}", classes="help-row")
+
+    def toggle(self) -> None:
+        self.toggle_class("visible")
+
+    @property
+    def is_visible(self) -> bool:
+        return self.has_class("visible")