zettcode-app 0.4.2__py3-none-any.whl

zettcode/app/agent/conversation/transcript/__init__.py

@@ -0,0 +1,80 @@
+"""The conversation model: an ordered list of entries, and what the agent does to it.
+
+The projector writes into this model and the UI reads it, so it lives on the agent
+side of the application and never imports the shell. The entries are plain data
+(``entries.py``); how one is drawn is its presenter's business (``presenters.py``);
+the scrollable view over the list is ``app.ui.widgets.transcript``.
+
+What is left is the list and the verbs on it, which this package splits by what each
+is responsible for, the way the shell splits its own: a shared state class, and a
+mixin for each kind of thing done to it.
+
+==============  ==========================================================
+``log``         :class:`EntryLog` — the list: where an entry goes, how many
+                are kept, what changed since the view last looked
+``turn``        :class:`TurnMixin` — a request's life: the reader's message,
+                the pinned wait row, the clock, closing what was left open
+``stream``      :class:`StreamMixin` — what the model produces as it arrives:
+                reasoning, a compaction, the answer, tool calls
+``oneoff``      :class:`OneOffMixin` — rows written once and left alone:
+                a banner, a notice, an error, an announcement, Markdown
+``fold``        :class:`FoldMixin` — opening and closing reasoning and tools
+==============  ==========================================================
+
+A mixin inherits :class:`EntryLog` only to be type-checked against the surface it
+shares with the rest. :class:`Transcript` is the composition, and the one place
+that holds what no single part owns: the clock, the renderers that phrase tool rows,
+and the presenters the view draws with.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from time import monotonic
+
+from zettcode.config import DEFAULT_TRANSCRIPT_MAX_ENTRIES
+from zettcode.plugin_api.commands import CommandTranscript
+from zettcode.presenters.presenters import DEFAULT_PRESENTERS, Presenters
+
+from ..rendering import DEFAULT_RENDERERS, Renderers
+from ..tips import TipDeck
+from .fold import FoldMixin
+from .log import EntryLog
+from .oneoff import OneOffMixin
+from .stream import StreamMixin
+
+__all__ = ["EntryLog", "Transcript"]
+
+
+# The contract is last on purpose: the mixins above implement its methods and must be found first.
+class Transcript(OneOffMixin, FoldMixin, StreamMixin, EntryLog, CommandTranscript):
+    """The conversation: entries in order, and the verbs the agent's events map onto."""
+
+    def __init__(
+        self,
+        *,
+        clock: Callable[[], float] = monotonic,
+        renderers: Renderers = DEFAULT_RENDERERS,
+        presenters: Presenters = DEFAULT_PRESENTERS,
+        max_entries: int = DEFAULT_TRANSCRIPT_MAX_ENTRIES,
+    ) -> None:
+        """Start an empty transcript whose elapsed times come from ``clock``.
+
+        Args:
+            clock: Time source for row durations, injectable for tests.
+            renderers: Chain that phrases tool rows; tests can pass their own to
+                pin the wording a row would show.
+            presenters: How each row is drawn; the view reads this so a
+                transcript given other presenters is drawn with them.
+            max_entries: Conversation entries kept for display; older ones are
+                dropped, while the session file keeps the whole tree. Must be
+                positive.
+        """
+        super().__init__(max_entries=max_entries)
+        self.clock = clock
+        self.renderers = renderers
+        self.presenters = presenters
+        self.frame = 0
+        #: Where the tips under the waiting row come from; ``None`` shows none.
+        self.tip_deck: TipDeck | None = None
+        self._picture_drawn = None

zettcode/app/agent/conversation/transcript/fold.py

@@ -0,0 +1,57 @@
+"""Opening and closing the rows that can be opened: reasoning and tool output.
+
+This is the one thing the reader does to the transcript rather than the agent. It
+changes how a row looks without changing what happened, so it only edits an entry
+in place and tells the log it did.
+"""
+
+from __future__ import annotations
+
+from zettcode.plugin_api.entries import ThinkingEntry, ToolEntry
+
+from .log import EntryLog
+
+
+class FoldMixin(EntryLog):
+    """Expand and collapse the reasoning and tool rows."""
+
+    def toggle(self, entry_id: int) -> bool:
+        """Expand or collapse one collapsible entry and report whether it changed.
+
+        Args:
+            entry_id: Id from the click or key that triggered the toggle; a
+                running tool row, or one with no body, refuses to expand.
+        """
+        entry = self.entry(entry_id)
+        if not isinstance(entry, (ThinkingEntry, ToolEntry)):
+            return False
+        if isinstance(entry, ToolEntry) and not entry.foldable:
+            return False
+        entry.expanded = not entry.expanded
+        self._changed(entry)
+        return True
+
+    def toggle_latest_thinking(self) -> bool:
+        """Expand or collapse the newest thinking block."""
+        entry = self._last(ThinkingEntry)
+        if entry is None:
+            return False
+        entry.expanded = not entry.expanded
+        self._changed(entry)
+        return True
+
+    def collapse_thinking_except(self, entry_id: int | None) -> bool:
+        """Collapse every expanded thinking block except the one to keep open.
+
+        Args:
+            entry_id: Block to leave expanded, or ``None`` to collapse them all.
+        """
+        changed = False
+        for index, entry in enumerate(self.entries):
+            if isinstance(entry, ThinkingEntry) and entry.expanded and entry.id != entry_id:
+                entry.expanded = False
+                self._touch(index)
+                changed = True
+        if changed:
+            self.version += 1
+        return changed

zettcode/app/agent/conversation/transcript/log.py

@@ -0,0 +1,182 @@
+"""The ordered list of entries, and the bookkeeping every verb on it shares.
+
+Whatever the transcript does to the conversation comes down to four things: put an
+entry in, change one, drop the old ones, and tell the view what moved. This is the
+part that is the same for all of them, and nothing here knows what a tool call or an
+answer is — the verbs that do are the mixins in this package, each of which inherits
+:class:`EntryLog` to be type-checked against the surface it shares with the rest.
+
+It holds exactly one rule about order, because the list cannot be kept without it:
+while a request runs, its wait row is the last entry, and everything new lands above.
+"""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+from zettcode.plugin_api.entries import Entry, WaitEntry
+
+#: The entry subtype an add/look-up call works with, pinned by the caller.
+E = TypeVar("E", bound=Entry)
+
+#: Smallest batch a trim drops, so the list shift and the view rebuild that
+#: follow a trim are paid once per several appends instead of per append. The
+#: real batch is a share of the cap, so a large cap trims off more at a time.
+MIN_TRIM_SLACK = 8
+
+#: Share of the cap the list may grow past before a trim: 1/32 of it. Small caps
+#: keep a proportionally small overrun, large caps trim fewer times.
+TRIM_SLACK_SHARE = 32
+
+
+class EntryLog:
+    """An ordered list of entries that knows what changed in it since it was last read.
+
+    Attributes:
+        entries: The conversation, oldest first.
+        version: Moves whenever anything in the list changed, which is what a view
+            compares to know it has to look again.
+        max_entries: How many entries are kept for display.
+    """
+
+    def __init__(self, *, max_entries: int) -> None:
+        """Start an empty list that keeps at most ``max_entries`` entries on display.
+
+        Args:
+            max_entries: Conversation entries kept for display; older ones are
+                dropped, while the session file keeps the whole tree. Must be
+                positive.
+        """
+        if max_entries < 1:
+            raise ValueError("max_entries must be positive")
+        self.entries: list[Entry] = []
+        self.max_entries = max_entries
+        self._trim_threshold = max_entries + max(MIN_TRIM_SLACK, max_entries // TRIM_SLACK_SHARE)
+        self.version = 0
+        self._next_id = 1
+        # Where the current request's own rows begin: the wait row is opened
+        # against the content already there, and everything above it until the
+        # next request is this request's work. The animation walks this range
+        # and no further, so a step's cost follows the request, not the session.
+        self._turn_from = 0
+        # Earliest entry touched since the view last took the mark, so it can
+        # re-measure only the changed suffix instead of the whole transcript.
+        self._dirty_from: int | None = None
+
+    # -- telling the view what moved ------------------------------------------
+    def take_dirty(self) -> int | None:
+        """Return the earliest changed entry index and reset the mark.
+
+        A view calls this once per version and rebuilds its line boundaries
+        from that index on; everything before it is unchanged and can be kept.
+        The mark is consumed rather than merely read so a later append starts
+        from the new tail instead of the oldest edit ever made. ``None`` means
+        no precise mark is available and the caller should rebuild in full.
+        """
+        dirty = self._dirty_from
+        self._dirty_from = None
+        return dirty
+
+    def _touch(self, index: int) -> None:
+        """Record that the entry at ``index`` changed, keeping the earliest one."""
+        self._dirty_from = index if self._dirty_from is None else min(self._dirty_from, index)
+
+    def _touch_entry(self, entry: Entry) -> None:
+        """Mark one entry changed, checking the tail before searching the list."""
+        last = len(self.entries) - 1
+        if last >= 0 and self.entries[last] is entry:
+            self._touch(last)
+            return
+        index = next((index for index, item in enumerate(self.entries) if item is entry), None)
+        if index is not None:
+            self._touch(index)
+
+    def _changed(self, entry: Entry) -> None:
+        """Say that an entry was edited in place: mark it, and move the version.
+
+        Every verb that changes a row ends here, so the mark and the version cannot
+        be updated one without the other.
+        """
+        self._touch_entry(entry)
+        self.version += 1
+
+    # -- where an entry goes --------------------------------------------------
+    def _open_wait(self) -> WaitEntry | None:
+        """Return the wait row while it is open, which is what keeps it pinned.
+
+        The row is the last entry for as long as the request runs, so "open"
+        and "at the tail" are the same thing: anything that lands below it would
+        be something the reader is still waiting for.
+        """
+        last = self.entries[-1] if self.entries else None
+        if isinstance(last, WaitEntry) and last.running:
+            return last
+        return None
+
+    def _add_index(self) -> int:
+        """Return where a new entry belongs: above the pinned wait row, or at the end.
+
+        The one place the pin is written down as an index, so the add path and
+        the answer path cannot disagree about where the row sits.
+        """
+        return len(self.entries) - 1 if self._open_wait() is not None else len(self.entries)
+
+    def _add(self, entry: E) -> E:
+        """Add a typed entry above the wait row, or append it when none is open.
+
+        The wait row is pinned to the bottom of the transcript while the request
+        runs: reasoning, tool calls, and the answer all land above it, so the one
+        line that says work is going on stays where the reader is already
+        looking instead of scrolling off with the reply that replaced it.
+        """
+        self._next_id += 1
+        index = self._add_index()
+        self._touch(index)
+        self.entries.insert(index, entry)
+        self._trim()
+        self.version += 1
+        return entry
+
+    def _trim(self) -> None:
+        """Drop the oldest entries once the display cap is well past.
+
+        Trimming from the front shifts every remaining index, so the render
+        view is told to rebuild its boundaries from zero. That rebuild is cheap
+        at an unchanged width — cached blocks only re-key — and it happens once
+        per trim batch, so the amortized cost per new entry stays flat. The
+        store keeps the full conversation; this bounds what is shown.
+        """
+        if len(self.entries) <= self._trim_threshold:
+            return
+        dropped = len(self.entries) - self.max_entries
+        del self.entries[:dropped]
+        # Every index the transcript is holding on to moves with the list.
+        self._turn_from = max(0, self._turn_from - dropped)
+        self._dirty_from = 0
+
+    # -- finding and replacing ------------------------------------------------
+    def _last(self, entry_type: type[E]) -> E | None:
+        """Return the newest entry of one type, or None when there is none."""
+        return next((entry for entry in reversed(self.entries) if isinstance(entry, entry_type)), None)
+
+    def entry(self, entry_id: int) -> Entry | None:
+        """Return the entry with this id, or None when it has been cleared."""
+        return next((item for item in self.entries if item.id == entry_id), None)
+
+    def clear(self) -> None:
+        """Drop every entry, for instance when starting a new session."""
+        self.entries.clear()
+        self._turn_from = 0
+        self._dirty_from = 0
+        self.version += 1
+
+    def replace(self, entries: list[Entry]) -> None:
+        """Replace visible entries with the chosen session's rebuilt history."""
+        self.entries[:] = entries
+        self._next_id = max((entry.id for entry in entries), default=0) + 1
+        # A rebuilt history is all in the past: no request is open in it, so the
+        # animation has no range of its own to walk.
+        self._turn_from = len(self.entries)
+        self._trim()
+        self._dirty_from = 0
+        self.version += 1

zettcode/app/agent/conversation/transcript/oneoff.py

@@ -0,0 +1,55 @@
+"""One-off rows: a banner, a notice, an error, an announcement, a block of Markdown.
+
+None of these is part of a request. They are written once, land where the log puts
+them, and never change — so they need nothing from the wait row or the clock, only
+the log's ``_add``.
+"""
+
+from __future__ import annotations
+
+from zettcode.plugin_api.entries import EntryKind, MarkdownEntry, NoticeLevel, TextEntry
+
+from .log import EntryLog
+
+
+class OneOffMixin(EntryLog):
+    """Append the rows that say one thing and stay as they are."""
+
+    def welcome(self, text: str) -> None:
+        """Append the banner shown once at startup."""
+        self._add(TextEntry(id=self._next_id, kind=EntryKind.WELCOME, text=text))
+
+    def notice(self, text: str) -> None:
+        """Append a muted one-off status line."""
+        self._add(TextEntry(id=self._next_id, kind=EntryKind.NOTICE, text=text))
+
+    def error(self, text: str) -> None:
+        """Append a one-off failure line, painted as an error."""
+        self._add(TextEntry(id=self._next_id, kind=EntryKind.NOTICE, text=text, level=NoticeLevel.ERROR))
+
+    def announce(self, text: str) -> None:
+        """Announce a change as one centered line between horizontal rules."""
+        self._add(TextEntry(id=self._next_id, kind=EntryKind.ANNOUNCEMENT, text=text))
+
+    def model_changed(self, previous: str, current: str) -> None:
+        """Announce a model change in the conversation; an empty previous is the first model there has been."""
+        self.announce(f"Model changed from {previous} to {current}." if previous else f"Model set to {current}.")
+
+    def permission_changed(self, previous: str, current: str) -> None:
+        """Announce a shell-permission change the way a model change is shown."""
+        self.announce(f"Shell permission changed from {previous} to {current}.")
+
+    def effort_changed(self, previous: str, current: str) -> None:
+        """Announce a reasoning-effort change the way a model change is shown."""
+        self.announce(f"Reasoning effort changed from {previous} to {current}.")
+
+    def markdown(self, text: str) -> None:
+        """Append a Markdown block, parsed and rendered like an answer.
+
+        Use it for command output, which is usually a list or a table; a notice
+        is the terse alternative for one-line status such as ``stopped``.
+        """
+        entry = MarkdownEntry(id=self._next_id, kind=EntryKind.MESSAGE)
+        entry.markdown.append(text)
+        entry.text = text
+        self._add(entry)

zettcode/app/agent/conversation/transcript/stream.py

@@ -0,0 +1,187 @@
+"""What the model produces as it arrives: reasoning, a compaction, an answer, tool calls.
+
+Each of these is a row that grows while a request runs, or opens when the agent starts
+something and closes when it reports back. They land above the wait row (the log's
+rule), and a tool's result ends by telling the reader that work continues, which is
+why this builds on :class:`~.turn.TurnMixin` rather than on the log alone.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+
+from zettcode.plugin_api.entries import EntryKind, EntryStatus, MarkdownEntry, ThinkingEntry, ToolEntry
+from zettcode.presenters.text import COMPACTING_LABEL, limit_output
+
+from ..rendering import ANSWER, THINKING, Renderers
+from .turn import TurnMixin
+
+
+class StreamMixin(TurnMixin):
+    """Open, grow, and close the rows that carry the agent's output."""
+
+    #: Chain that phrases tool rows and shapes streamed text; set by :class:`~.Transcript`.
+    renderers: Renderers
+    clock: Callable[[], float]
+
+    # -- reasoning ------------------------------------------------------------
+    def restore_thinking(self, text: str, duration_ns: int | None) -> None:
+        """Append completed reasoning from one stored assistant response."""
+        duration = duration_ns / 1_000_000_000 if duration_ns is not None else None
+        self._add(
+            ThinkingEntry(
+                id=self._next_id,
+                text=self.renderers.text(THINKING, text, opening=True),
+                status=EntryStatus.COMPLETED,
+                duration=duration,
+            )
+        )
+
+    def start_thinking(self) -> ThinkingEntry:
+        """Open a reasoning row, which lands above the wait row below it.
+
+        The wait row is not turned into this one: it stays where it is, saying
+        that a model call is still running, and the reasoning grows above it.
+        """
+        current = self._last(ThinkingEntry)
+        if current is not None and current.running:
+            return current
+        return self._add(ThinkingEntry(id=self._next_id, started_at=self.clock()))
+
+    def append_thinking(self, delta: str) -> None:
+        """Append a reasoning delta to the running thinking block."""
+        entry = self.start_thinking()
+        entry.text += self.renderers.text(THINKING, delta, opening=not entry.text)
+        self._changed(entry)
+
+    def complete_thinking(self) -> None:
+        """Close the running thinking block and stamp its elapsed time."""
+        entry = self._last(ThinkingEntry)
+        if entry is None or not entry.running:
+            return
+        entry.finish(EntryStatus.COMPLETED, self.clock())
+        self._changed(entry)
+
+    # -- compaction -----------------------------------------------------------
+    def start_compaction(self) -> ThinkingEntry:
+        """Open the row that shows the summarizer working.
+
+        A compaction is a model call streamed back like any other, so it gets
+        the same row as reasoning — marker, and timer included — under its own
+        label. The two never borrow each other's row: a compaction that happens
+        between reasoning spans keeps its text out of the thinking one.
+        """
+        current = self._last(ThinkingEntry)
+        if current is not None and current.running and current.title == COMPACTING_LABEL:
+            return current
+        return self._add(
+            ThinkingEntry(
+                id=self._next_id,
+                title=COMPACTING_LABEL,
+                started_at=self.clock(),
+            )
+        )
+
+    def append_compaction(self, delta: str) -> None:
+        """Append one summary fragment to the running compaction row."""
+        row = self.start_compaction()
+        row.text += delta
+        self._changed(row)
+
+    def complete_compaction(self, text: str = "") -> None:
+        """Close the running compaction row and stamp its elapsed time.
+
+        Args:
+            text: What to leave in place of the streamed summary, when the pass
+                ended before writing one — a stop, for example. The row is
+                expanded so the note is on its face rather than in a fold.
+        """
+        row = self._last(ThinkingEntry)
+        if row is None or row.title != COMPACTING_LABEL or not row.running:
+            return
+        if text:
+            row.text = text
+            row.expanded = True
+        row.finish(EntryStatus.COMPLETED, self.clock())
+        self._changed(row)
+
+    # -- the answer -----------------------------------------------------------
+    def append_answer(self, delta: str) -> None:
+        """Stream a delta into the answer block, opening one if needed.
+
+        The wait row stays open below it: the answer is being written, not
+        finished, and the pinned row is how that still reads while it streams.
+        """
+        # The answer is the entry the reply is writing into: the tail, or the
+        # one the pinned wait row sits under.
+        index = self._add_index() - 1
+        current = self.entries[index] if index >= 0 else None
+        if not isinstance(current, MarkdownEntry) or current.kind is not EntryKind.ANSWER:
+            current = MarkdownEntry(id=self._next_id, kind=EntryKind.ANSWER)
+            self._add(current)
+        delta = self.renderers.text(ANSWER, delta, opening=not current.text)
+        current.markdown.append(delta)
+        current.text += delta
+        self._changed(current)
+
+    # -- tools ----------------------------------------------------------------
+    def start_tool(self, call_id: str, name: str, arguments: Mapping[str, object]) -> None:
+        """Open a tool row, closing the reasoning span it interrupts.
+
+        Args:
+            call_id: Identifier the matching result will carry.
+            name: Tool name; the renderer chain turns it into the row's words.
+            arguments: Arguments the chain reads to phrase the call.
+        """
+        self.complete_thinking()
+        # The tool's own handler decides which entry the call is, so what a row carries is its
+        # tool's business and this opens every one the same way.
+        self._add(self.renderers.open_tool(name, arguments, id=self._next_id, call_id=call_id, started_at=self.clock()))
+
+    def restate_tool(self, call_id: str, arguments: Mapping[str, object]) -> None:
+        """Phrase a row again with arguments that arrived after it opened.
+
+        A hosted tool's input may stream in fragments after the call started, so the row opens knowing only the tool's
+        name. This is where the query it really ran appears, before the row is closed.
+
+        Args:
+            call_id: Identifier the matching result will carry.
+            arguments: What the call turned out to be, which the chain phrases.
+        """
+        entry = next(
+            (item for item in reversed(self.entries) if isinstance(item, ToolEntry) and item.call_id == call_id), None
+        )
+        if entry is None:
+            return
+        entry.title = self.renderers.describe(entry.tool, arguments).title
+        self._changed(entry)
+
+    def complete_tool(
+        self, call_id: str, output: str, *, status: EntryStatus = EntryStatus.COMPLETED, wait: bool = True
+    ) -> None:
+        """Attach a tool result to its row, ignoring calls that are no longer on screen.
+
+        Args:
+            call_id: Identifier from the matching ``start_tool`` call.
+            output: Raw output; bounded before it is stored.
+            status: Final status, normally ``completed``, ``failed``, or
+                ``skipped``.
+        """
+        entry = next(
+            (item for item in reversed(self.entries) if isinstance(item, ToolEntry) and item.call_id == call_id), None
+        )
+        if entry is None:
+            return
+        # An unknown status is refused before the row is touched at all.
+        outcome = EntryStatus(status)
+        body = self.renderers.body(entry.tool, output)
+        entry.text = limit_output(body)
+        # The result, unbounded: a count is of what came back, not of the preview the row keeps, and what it says about
+        # the body depends on whether the call worked.
+        self.renderers.finished(entry, body, outcome)
+        entry.finish(outcome, self.clock())
+        self._changed(entry)
+        # The loop calls the model again once the batch has produced its
+        # results, so the reader is told that work continues.
+        if wait:
+            self.wait_for_model()