shikiru-cli 0.2.0__py3-none-any.whl

shikiru/dashboard/timeline_section.py

@@ -0,0 +1,385 @@
+"""One task timeline: a category's rows, cursor stack, filters and follow state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, fields
+from typing import TYPE_CHECKING, ClassVar, cast
+
+from rich.text import Text
+from textual.binding import Binding
+from textual.containers import Vertical
+from textual.message import Message
+from textual.widgets import Static
+
+from shikiru.dashboard.row_list import RowList
+from shikiru.dashboard.section_rows import timeline_cells
+from shikiru.dashboard.timeline_filter import TimelineFilterBar
+from shikiru.errors import ShikiruError
+from shikiru.ui.screen import widget_is_current
+
+if TYPE_CHECKING:
+    import asyncio
+    from collections.abc import Callable
+
+    from rich.console import Console, ConsoleOptions, RenderResult
+    from textual.app import App, ComposeResult
+    from textual.binding import BindingType
+    from textual.widget import Widget
+
+    from shikiru.dashboard.contract import (
+        TaskTimelineCategory,
+        TaskTimelineEntryView,
+        TaskTimelinePageView,
+        WidgetContext,
+    )
+
+NO_TIMELINE_ROWS = "No recorded entries match."
+FOLLOWING_LABEL = "following"
+PAUSED_LABEL = "paused"
+REFRESH_FAILED = "Evidence timeline refresh failed"
+FILTER_KEY = "f"
+OPEN_FILTER_ACTION = "open_filter"
+SELECTED_MAX_LINES = 4
+ELLIPSIS = "\N{HORIZONTAL ELLIPSIS}"
+
+
+@dataclass(frozen=True)
+class TimelineIds:
+    """The widget ids of one timeline section, derived from a shared prefix."""
+
+    root: str
+    filters: str
+    list: str
+    selected: str
+
+    @classmethod
+    def with_prefix(cls, prefix: str) -> TimelineIds:
+        """Build the ids `<prefix>-<part>` for every part of a timeline section."""
+        return cls(*(f"{prefix}-{part.name}" for part in fields(cls)))
+
+
+@dataclass(frozen=True)
+class TimelineRequest:
+    """The page a timeline asks the views for."""
+
+    cursor: str | None
+    role: str | None
+    turn: str | None
+    category: str
+
+
+@dataclass(frozen=True)
+class TimelineHost:
+    """What a timeline needs from the panel that owns it."""
+
+    task_id: Callable[[], str | None]
+    lock: asyncio.Lock
+    report: Callable[[str], None]
+
+
+def screen_is_active(widget: Widget) -> bool:
+    """Whether the widget's screen is the current one in a running app."""
+    return widget_is_current(widget) and cast("App[None]", widget.app).is_running
+
+
+@dataclass(frozen=True)
+class _SelectedEntry:
+    text: Text
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        lines = self.text.wrap(console, options.max_width)
+        shown = lines[:SELECTED_MAX_LINES]
+        if len(lines) > SELECTED_MAX_LINES:
+            last = shown[-1]
+            last.rstrip()
+            last.truncate(max(options.max_width - 1, 1))
+            last.append(ELLIPSIS)
+        yield from shown
+
+
+class TimelineSection(Vertical):
+    """Own one timeline's rows, paging, filters and follow state; `shown` while open."""
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding(FILTER_KEY, OPEN_FILTER_ACTION, "Filter", show=False)
+    ]
+    DEFAULT_CSS = """
+    TimelineSection { height: auto; }
+    TimelineSection .timeline-selected {
+        height: auto; padding: 0 1; margin: 1 0 0 0;
+        color: $primary-text; background: $detail-surface; text-style: italic;
+    }
+    """
+
+    class StatusChanged(Message):
+        """The section's `following` or `paused` status, announced on mount and on every change."""
+
+        def __init__(self, section: TimelineSection, status: str) -> None:
+            super().__init__()
+            self.section = section
+            self.status = status
+
+    def __init__(
+        self,
+        context: WidgetContext,
+        host: TimelineHost,
+        *,
+        ids: TimelineIds,
+        category: TaskTimelineCategory,
+        filterable: bool,
+    ) -> None:
+        super().__init__(id=ids.root)
+        self.ids = ids
+        self._widget_context = context
+        self._host = host
+        self._category = category.value
+        self._filterable = filterable
+        self._page: TaskTimelinePageView | None = None
+        self._generation = 0
+        self.shown = False
+        self._reset_state()
+
+    def compose(self) -> ComposeResult:
+        yield RowList(widget_id=self.ids.list, edge_paging=True)
+        selected = Static("", id=self.ids.selected, classes="timeline-selected", markup=False)
+        selected.display = False
+        yield selected
+        if self._filterable:
+            yield TimelineFilterBar(widget_id=self.ids.filters)
+
+    def on_mount(self) -> None:
+        """Announce the initial status so its fold header shows it before it is ever opened."""
+        self._announce_status()
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        del parameters
+        return self._filterable if action == OPEN_FILTER_ACTION else True
+
+    def action_open_filter(self) -> None:
+        """Show the filter bar and move focus into it."""
+        bar = self.query_one(f"#{self.ids.filters}", TimelineFilterBar)
+        bar.display = True
+        bar.focus()
+
+    def close_filter(self) -> bool:
+        """Hide the focused filter bar and return focus to the list; False when it has none."""
+        if not self._filterable:
+            return False
+        bar = self.query_one(f"#{self.ids.filters}", TimelineFilterBar)
+        if not bar.has_focus:
+            return False
+        self.query_one(f"#{self.ids.list}", RowList).focus()
+        bar.display = bar.active
+        return True
+
+    @property
+    def request(self) -> TimelineRequest:
+        """The page the current cursor, filters and category ask for."""
+        return TimelineRequest(
+            None if self._following else self._cursors[-1],
+            self._role,
+            self._turn,
+            self._category,
+        )
+
+    @property
+    def generation(self) -> int:
+        """Bumped whenever the request changes, so older replies can be dropped."""
+        return self._generation
+
+    @property
+    def following(self) -> bool:
+        """Whether the section tracks the latest entries."""
+        return self._following
+
+    @property
+    def page(self) -> TaskTimelinePageView | None:
+        """The last page painted."""
+        return self._page
+
+    def reset(self) -> None:
+        """Forget the cursor, filters and rows, as for a newly selected task."""
+        self._reset_state()
+        self._page = None
+        self._generation += 1
+        if not self.is_mounted:
+            return
+        selected = self.query_one(f"#{self.ids.selected}", Static)
+        selected.update("")
+        selected.display = False
+        if self._filterable:
+            bar = self.query_one(f"#{self.ids.filters}", TimelineFilterBar)
+            bar.reset()
+            bar.display = False
+        self._announce_status()
+        self.query_one(f"#{self.ids.list}", RowList).set_rows(
+            (), selected=0, empty=NO_TIMELINE_ROWS
+        )
+
+    def show_page(self, page: TaskTimelinePageView | None) -> None:
+        """Paint a page of rows, keeping the selected entry when it is still listed."""
+        self._page = page
+        entries = page.entries if page is not None else ()
+        selected = (
+            len(entries) - 1
+            if self._select_last
+            else next(
+                (
+                    index
+                    for index, item in enumerate(entries)
+                    if item.identity == self._selected_identity
+                ),
+                0,
+            )
+        )
+        if self._select_last and selected > 0:
+            self._selected_identity = entries[selected].identity
+            self._following = False
+        self._select_last = False
+        self._remember_turns(entries)
+        self.query_one(f"#{self.ids.list}", RowList).set_rows(
+            [timeline_cells(item) for item in entries], selected=selected, empty=NO_TIMELINE_ROWS
+        )
+        self._announce_status()
+        self._paint_selection()
+
+    def pause_follow(self) -> None:
+        """Stop following the latest entries until the operator asks for them again."""
+        if not self._following:
+            return
+        self._following = False
+        self._generation += 1
+        if screen_is_active(self):
+            self._announce_status()
+
+    def restart(self) -> None:
+        """Return to the latest page and follow it."""
+        self._cursors = [None]
+        self._following = True
+        self._invalidate()
+
+    async def refresh_when_due(self) -> None:
+        """Fetch the latest page for the 1 Hz tick; only a shown, following section does."""
+        if self.shown and self._following:
+            await self.refresh_page()
+
+    async def refresh_page(self) -> None:
+        """Fetch this section's own page and paint it unless the request changed meanwhile."""
+        async with self._host.lock:
+            task_id = self._host.task_id()
+            if task_id is None or not screen_is_active(self):
+                return
+            generation = self._generation
+            request = self.request
+            try:
+                page = await self._widget_context.views.task_timeline(
+                    task_id,
+                    cursor=request.cursor,
+                    role=request.role,
+                    turn=request.turn,
+                    category=request.category,
+                )
+            except (ShikiruError, OSError, ValueError, TypeError) as error:
+                if screen_is_active(self) and generation == self._generation:
+                    self._host.report(f"{REFRESH_FAILED}: {error}")
+                return
+            if (
+                screen_is_active(self)
+                and task_id == self._host.task_id()
+                and generation == self._generation
+            ):
+                self.show_page(page)
+
+    def on_timeline_filter_bar_changed(self, message: TimelineFilterBar.Changed) -> None:
+        message.stop()
+        self._role, self._turn = message.role, message.turn
+        self.restart()
+
+    def on_timeline_filter_bar_closed(self, message: TimelineFilterBar.Closed) -> None:
+        message.stop()
+        self.close_filter()
+
+    def on_row_list_moved(self, message: RowList.Moved) -> None:
+        message.stop()
+        page = self._page
+        if page is None:
+            return
+        self._selected_identity = (
+            page.entries[message.index].identity if message.index > 0 else None
+        )
+        if message.index > 0:
+            self.pause_follow()
+        self._paint_selection()
+
+    def on_row_list_paged(self, message: RowList.Paged) -> None:
+        message.stop()
+        if message.older:
+            self._older_page()
+        else:
+            self._newer_page(select_last=message.by_arrow)
+
+    def on_row_list_scrolled(self, message: RowList.Scrolled) -> None:
+        message.stop()
+        self.pause_follow()
+
+    def on_row_list_latest(self, message: RowList.Latest) -> None:
+        message.stop()
+        self.restart()
+
+    def _reset_state(self) -> None:
+        self._cursors: list[str | None] = [None]
+        self._following = True
+        self._role: str | None = None
+        self._turn: str | None = None
+        self._selected_identity: str | None = None
+        self._select_last = False
+        self._known_turns: set[str] = set()
+
+    def _invalidate(self) -> None:
+        self._generation += 1
+        self._selected_identity = None
+        self.run_worker(self.refresh_page(), exclusive=False)
+
+    def _older_page(self) -> None:
+        page = self._page
+        if (
+            page is None
+            or not page.has_older
+            or page.older_cursor is None
+            or page.older_cursor == self._cursors[-1]
+        ):
+            return
+        self._cursors.append(page.older_cursor)
+        self._following = False
+        self._invalidate()
+
+    def _newer_page(self, *, select_last: bool) -> None:
+        if len(self._cursors) <= 1:
+            return
+        self._cursors.pop()
+        self._following = len(self._cursors) == 1
+        self._select_last = select_last
+        self._invalidate()
+
+    def _announce_status(self) -> None:
+        self.post_message(
+            self.StatusChanged(self, FOLLOWING_LABEL if self._following else PAUSED_LABEL)
+        )
+
+    def _remember_turns(self, entries: tuple[TaskTimelineEntryView, ...]) -> None:
+        if not self._filterable:
+            return
+        self._known_turns.update(item.turn for item in entries if item.turn)
+        self.query_one(f"#{self.ids.filters}", TimelineFilterBar).set_turns(
+            sorted(self._known_turns)
+        )
+
+    def _paint_selection(self) -> None:
+        page = self._page
+        entries = page.entries if page is not None else ()
+        chosen = self.query_one(f"#{self.ids.list}", RowList).selected
+        target = self.query_one(f"#{self.ids.selected}", Static)
+        selected = entries[chosen] if chosen < len(entries) else None
+        target.display = selected is not None
+        if selected is not None:
+            target.update(_SelectedEntry(Text(selected.phrase)))

shikiru/dashboard/usage_body.py

@@ -0,0 +1,269 @@
+"""Body of the Usage fold: a totals line, one aligned line per session, one note."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from decimal import ROUND_HALF_UP, Decimal
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from rich.cells import cell_len
+from rich.console import Group
+from rich.text import Text
+
+from shikiru.agents.contracts import BILLING_MODE_SUBSCRIPTION, BILLING_MODE_UNKNOWN
+from shikiru.dashboard.briefing_view import counted, total_cost_text
+from shikiru.domain.levels import UsageLevel, displayed_pct
+from shikiru.ui.compact import (
+    COUNT_SHORT_MILLION,
+    COUNT_SHORT_SCALE,
+    ROLE_LABELS,
+    compact_count,
+)
+from shikiru.ui.section import BOLD_STEEL, GROUP_SEPARATOR, grey
+from shikiru.ui.tokens import AMBER, SECONDARY_TEXT_COLOR, USAGE_LEVEL_COLORS
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from rich.console import Console, ConsoleOptions, RenderableType, RenderResult
+
+    from shikiru.dashboard.contract import TaskDetailView, TaskSessionView
+
+NO_VALUE = "\N{EM DASH}"
+NO_USAGE = "No usage is recorded yet."
+COVERAGE_UNAVAILABLE = "Task usage coverage unavailable"
+OLD_TAG = "old"
+TOKENS_WORD = " tokens"
+NOTE_LEAD = "! "
+LEAD = "  "
+GAP = "  "
+ELLIPSIS = "\N{HORIZONTAL ELLIPSIS}"
+MODEL_MIN_WIDTH = 8
+SIGNIFICANT_DIGITS = 3
+PAIR_SEPARATOR = " / "
+PAIR_LABEL = "r/w"
+_NOUN_SESSION = "session"
+_NOUN_GAP = "model-history gap"
+_VERB_NO_USAGE = "reported no usage"
+_PHRASE_BILLING_UNKNOWN = "billing unknown for"
+
+
+class Column(StrEnum):
+    """The session table columns, in display order, named as their header shows them."""
+
+    ROLE = "Role"
+    MODEL = "Model"
+    TOKENS = "Tokens r/w"
+    COST = "Cost"
+    CONTEXT = "Ctx"
+
+
+_LEFT_ALIGNED = (Column.ROLE, Column.MODEL)
+_DROP_ORDER = (Column.MODEL, Column.CONTEXT, Column.COST)
+
+
+@dataclass(frozen=True)
+class UsageRow:
+    """One session's cell texts, its context level and whether it is an older session."""
+
+    cells: dict[Column, str]
+    level: UsageLevel | None
+    old: bool
+
+
+@dataclass(frozen=True)
+class UsageTable:
+    """The columns that fit the width, their widths, the rows and whether they stack."""
+
+    columns: tuple[Column, ...]
+    widths: dict[Column, int]
+    rows: tuple[UsageRow, ...]
+    stacked: bool
+
+
+def usage_rows(sessions: Sequence[TaskSessionView], width: int) -> UsageTable:
+    """Derive the session table for `width`: shrink the model, drop it, then drop Ctx and Cost."""
+    ordered = sorted(sessions, key=lambda session: not session.current_lineage)
+    rows = tuple(_row(session) for session in ordered)
+    columns = list(Column)
+    widths = {
+        column: max(cell_len(column.value), *(cell_len(row.cells[column]) for row in rows))
+        for column in columns
+    }
+    old_room = (len(GAP) + len(OLD_TAG)) if any(row.old for row in rows) else 0
+
+    def total() -> int:
+        gaps = len(GAP) * (len(columns) - 1)
+        return len(LEAD) + sum(widths[c] for c in columns) + gaps + old_room
+
+    overflow = total() - width
+    if overflow > 0:
+        widths[Column.MODEL] = max(MODEL_MIN_WIDTH, widths[Column.MODEL] - overflow)
+    for column in _DROP_ORDER:
+        if total() > width:
+            columns.remove(column)
+    return UsageTable(tuple(columns), widths, rows, stacked=total() > width)
+
+
+def _row(session: TaskSessionView) -> UsageRow:
+    return UsageRow(
+        {
+            Column.ROLE: ROLE_LABELS.get(session.role, session.role.title()),
+            Column.MODEL: session.model,
+            Column.TOKENS: _tokens(session),
+            Column.COST: _cost(session),
+            Column.CONTEXT: _context(session),
+        },
+        session.context_level,
+        not session.current_lineage,
+    )
+
+
+def _tokens_known(session: TaskSessionView) -> bool:
+    return session.usage_reported is True or session.legacy_token_totals
+
+
+def _session_tokens(session: TaskSessionView) -> int:
+    return session.input_tokens + session.output_tokens
+
+
+def _tokens(session: TaskSessionView) -> str:
+    if not _tokens_known(session):
+        return NO_VALUE
+    return PAIR_SEPARATOR.join(
+        (_abbreviated(session.input_tokens), _abbreviated(session.output_tokens))
+    )
+
+
+def _abbreviated(count: int) -> str:
+    if count < COUNT_SHORT_SCALE:
+        return str(count)
+    thousands = _significant(Decimal(count) / COUNT_SHORT_SCALE)
+    if thousands < COUNT_SHORT_SCALE:
+        return f"{_plain(thousands)}k"
+    return f"{_plain(_significant(Decimal(count) / COUNT_SHORT_MILLION))}M"
+
+
+def _significant(value: Decimal) -> Decimal:
+    exponent = value.adjusted() - (SIGNIFICANT_DIGITS - 1)
+    return value.quantize(Decimal(1).scaleb(exponent), rounding=ROUND_HALF_UP)
+
+
+def _plain(value: Decimal) -> str:
+    return format(value.normalize(), "f")
+
+
+def _cost(session: TaskSessionView) -> str:
+    if session.cost_usd is None or session.billing_mode == BILLING_MODE_SUBSCRIPTION:
+        return NO_VALUE
+    return f"${session.cost_usd:.2f}"
+
+
+def _context(session: TaskSessionView) -> str:
+    if session.usage_reported is False or session.context_used_pct is None:
+        return NO_VALUE
+    return f"{displayed_pct(session.context_used_pct)}%"
+
+
+def _fit(text: str, width: int) -> str:
+    if cell_len(text) <= width:
+        return text
+    return text[: width - len(ELLIPSIS)] + ELLIPSIS
+
+
+def _padded(text: str, width: int, *, left: bool) -> str:
+    fitted = _fit(text, width)
+    padding = " " * (width - cell_len(fitted))
+    return fitted + padding if left else padding + fitted
+
+
+def _line(table: UsageTable, cells: dict[Column, str], style: str) -> Text:
+    return Text(
+        LEAD
+        + GAP.join(
+            _padded(cells[column], table.widths[column], left=column in _LEFT_ALIGNED)
+            for column in table.columns
+        ),
+        style=style,
+    )
+
+
+def _row_text(table: UsageTable, row: UsageRow) -> Text:
+    line = _line(table, row.cells, "")
+    if row.level is not None and row.level is not UsageLevel.OK and Column.CONTEXT in table.columns:
+        context_width = table.widths[Column.CONTEXT]
+        line.stylize(USAGE_LEVEL_COLORS[row.level], len(line) - context_width, len(line))
+    return _old_tagged(line, row)
+
+
+def _old_tagged(line: Text, row: UsageRow) -> Text:
+    if row.old:
+        line.append(f"{GAP}{OLD_TAG}", style=SECONDARY_TEXT_COLOR)
+    return line
+
+
+def _table_lines(table: UsageTable) -> list[Text]:
+    if table.stacked:
+        return [line for row in table.rows for line in _stacked_row(row)]
+    header = _line(table, {column: column.value for column in Column}, SECONDARY_TEXT_COLOR)
+    return [header, *(_row_text(table, row) for row in table.rows)]
+
+
+def _stacked_row(row: UsageRow) -> list[Text]:
+    role = _old_tagged(Text(LEAD + row.cells[Column.ROLE]), row)
+    pair = Text.assemble(LEAD, GAP, grey(PAIR_LABEL), GAP, row.cells[Column.TOKENS])
+    return [role, pair]
+
+
+def _heading(sessions: Sequence[TaskSessionView]) -> Text | None:
+    parts: list[Text] = []
+    cost = total_cost_text(sessions)
+    if cost is not None:
+        parts.append(Text(cost))
+    known = [_session_tokens(session) for session in sessions if _tokens_known(session)]
+    if known:
+        parts.append(Text.assemble((compact_count(sum(known)), BOLD_STEEL), grey(TOKENS_WORD)))
+    return Text(GROUP_SEPARATOR).join(parts) if parts else None
+
+
+def _note(sessions: Sequence[TaskSessionView]) -> Text | None:
+    silent = sum(session.usage_reported is False for session in sessions)
+    gaps = sum(len(session.history_gaps) for session in sessions)
+    unknown = sum(session.billing_mode == BILLING_MODE_UNKNOWN for session in sessions)
+    parts: list[str] = []
+    if silent:
+        parts.append(f"{counted(silent, _NOUN_SESSION)} {_VERB_NO_USAGE}")
+    if gaps:
+        parts.append(counted(gaps, _NOUN_GAP))
+    if unknown:
+        parts.append(f"{_PHRASE_BILLING_UNKNOWN} {counted(unknown, _NOUN_SESSION)}")
+    return Text(NOTE_LEAD + GROUP_SEPARATOR.join(parts), style=AMBER) if parts else None
+
+
+@dataclass(frozen=True)
+class UsageBody:
+    """Render the Usage fold of a task at the width it is drawn at."""
+
+    view: TaskDetailView
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        """Yield the heading, the session table and the note."""
+        del console
+        view = self.view
+        if view.usage is None:
+            yield grey(COVERAGE_UNAVAILABLE)
+        if not view.sessions:
+            if view.usage is not None:
+                yield grey(NO_USAGE)
+            return
+        table = usage_rows(view.sessions, options.max_width)
+        heading = _heading(view.sessions)
+        blocks: list[RenderableType] = [
+            *([heading] if heading is not None else []),
+            *_table_lines(table),
+        ]
+        note = _note(view.sessions)
+        if note is not None:
+            blocks.extend([Text(), note])
+        yield Group(*blocks)