zettcode-engine 0.3.4__py3-none-any.whl

zettcode/engine/agent/context.py

@@ -0,0 +1,166 @@
+"""What the next request carries: its size, its breakdown, and shrinking it.
+
+Counting a request and summarizing one are the same subject seen from two ends — one says
+how full the window is, the other makes room in it — and both are answered from what the
+runtime assembled or, before it has assembled one, from what the store holds.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from zett_agent.agent import AgentRunConfig
+from zett_agent.extensions.events import CompactionEvent
+from zett_agent.messages import AnyMessage, SystemMessage
+from zett_agent.model import ToolDefinition
+
+from zettcode.engine.core import build_system_prompt
+from zettcode.engine.extensions.context import ContextReport
+from zettcode.engine.extensions.usage import UsageSnapshot
+from zettcode.engine.storage import Session
+
+from .base import AgentBase
+
+
+class ContextMixin(AgentBase):
+    """Report the request the next turn would send, and compact the conversation behind it."""
+
+    @property
+    def usage(self) -> UsageSnapshot:
+        """Return the active session's cumulative token counters.
+
+        The numbers come from the usage extension's in-memory totals, so the
+        status line can read them every frame; a session replayed from the store
+        is seeded before this is asked.
+        """
+        return self.runtime.usage.snapshot(self.session_id)
+
+    async def context_report(self) -> ContextReport | None:
+        """Return what the next request carries by source, or None before the first call.
+
+        The shares come from the tokenizer, which is prepared first: it prefers
+        tiktoken and falls back to a character estimate when that vocabulary
+        cannot be opened, which the report names so the numbers are not mistaken
+        for exact ones. The total comes from the provider when it counted this
+        very request — it counts what it bills — and from the tokenizer when the
+        request was primed from the store, whose stored figure belongs to a call
+        the dialogue may have outgrown.
+        """
+        tokenizer = self.runtime.tokenizer
+        await tokenizer.prepare()
+        model = self.runtime.active_model
+        # No model configured means no window to measure against. Nothing is reported either way: a request is
+        # refused before one is assembled, so the report is None and no share is ever computed from this 0.
+        window = 0 if model is None else model.context_window
+        counted = self.runtime.usage.snapshot(self.session_id).context_tokens
+        # The provider's own count of this conversation is the total: what it
+        # billed for the request this process assembled, or — for a session
+        # rebuilt from the store, which has no call of its own yet — what it
+        # billed for the last call that session made. Locally counting a rebuilt
+        # request is not a substitute: on this machine's own session the rebuilt
+        # list measured 1.65 M tokens against a provider's 326 k, because a
+        # rebuilt list holds messages the live request no longer carries.
+        #
+        # A count that reaches the window is refused instead: a request cannot
+        # carry more than the window it is measured against, so a figure that does
+        # is about something else, and a share pinned at a hundred is worse than
+        # the measurement.
+        reported = counted if 0 < counted < window else None
+        return self.runtime.context.report(
+            self.session_id,
+            window=window,
+            tokenizer=tokenizer,
+            reported=reported,
+        )
+
+    async def ensure_compactable(self) -> None:
+        """Refuse a compaction that would do nothing, before a row is put up for it.
+
+        The command opens a working row before it starts; checking the
+        checkpoint first keeps a refusal from leaving that row behind with no
+        work and no text.
+
+        Raises:
+            SessionLocked: Another process has this session open.
+            ValueError: The newest checkpoint already covers the branch.
+        """
+        self.require_session()
+        if await self._compacted_at_the_head():
+            raise ValueError("Already compacted; send a message before compacting again")
+
+    async def compact(self) -> CompactionEvent | None:
+        """Summarize the conversation now, without adding a turn to it.
+
+        zett-agent runs one pass over the restored session and dispatches every
+        event it emits, so the transcript animates the same ``Compacting`` row an
+        automatic compaction shows. Nothing is appended to the conversation and
+        no primary model call is made: the only work is the summary itself.
+
+        Returns:
+            The checkpoint that was stored, or ``None`` when there was nothing
+            worth replacing.
+
+        Raises:
+            SessionLocked: Another process has this session open, and a checkpoint is a write.
+            ValueError: When the newest checkpoint already covers the branch —
+                a second pass would summarize nothing but the checkpoint.
+        """
+        await self.ensure_compactable()
+        return await self._compact_pass()
+
+    async def _compact_pass(self) -> CompactionEvent | None:
+        """Run the pass after the caller has checked that there is something to compact."""
+        await self.runtime.start()
+        return await self.runtime.started.compact(
+            config=AgentRunConfig(session_id=self.session_id),
+            model=self.runtime.provider,
+        )
+
+    async def _compacted_at_the_head(self) -> bool:
+        """Return whether nothing has been appended since the newest checkpoint.
+
+        Messages and checkpoints both carry ``created_at``, so the last message
+        being older than the last checkpoint is what says the branch has not
+        moved since it was summarized — no matter which session is active or
+        whether the transcript in this process ever showed that compaction.
+        Reading the file is file work, so it runs on a worker: it must not hold
+        the loop while a frame is waiting to be drawn.
+        """
+        try:
+            session = await asyncio.to_thread(self.runtime.persistence.read, self.session_id)
+        except ValueError:
+            # A runtime without a store to read: no checkpoint can cover it.
+            return False
+        latest = session.latest_compaction
+        if latest is None or session.head_id is None:
+            return False
+        head = session.message(session.head_id)
+        return head is not None and head.created_at <= latest.created_at
+
+    def _context_request(self, session: Session) -> tuple[tuple[AnyMessage, ...], tuple[ToolDefinition, ...]]:
+        """Return the messages and tools the next turn would send.
+
+        The request this process assembled is the honest answer; before one has
+        run — a session restored into a fresh process — the instructions and the
+        active branch stand in for it, which is all that can be known there.
+        """
+        assembled = self.runtime.context.assembled(self.session_id)
+        if assembled is not None:
+            messages, tools = assembled
+            return tuple(messages), tuple(tools)
+        return self._stored_request(session), self.runtime.context.tools
+
+    def _stored_request(self, session: Session) -> tuple[AnyMessage, ...]:
+        """Return the messages a request for ``session`` would carry, from what is stored.
+
+        This depends on the session it is given and on nothing that changes with the
+        active one, so it can be run later — a restore hands it over unrun, and the
+        reader may have moved to another session by the time it is wanted.
+        """
+        instructions = self.runtime.context.instructions or (
+            SystemMessage(content=build_system_prompt(self.runtime.config)),
+        )
+        checkpoint, tail = session.active()
+        stored: list[AnyMessage] = [checkpoint.message[0]] if checkpoint is not None else []
+        stored.extend(line.message[0] for line in tail if line.message[0].include_in_messages)
+        return (*instructions, *stored)

zettcode/engine/agent/exports.py

@@ -0,0 +1,73 @@
+"""Writing a session out as a page a reader can open."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import datetime
+from pathlib import Path
+
+from zettcode.engine.export import build_trace, render_html, write_export
+from zettcode.engine.storage import Session
+
+from .context import ContextMixin
+from .sessions import SessionsMixin
+from .settings import SettingsMixin
+
+
+class ExportsMixin(SessionsMixin, SettingsMixin, ContextMixin):
+    """Export the active session together with the request the next turn would send."""
+
+    async def export_session(self, path: str | Path | None = None) -> Path:
+        """Write the active session, and the context it now carries, to HTML.
+
+        The conversation is rendered with the same presenters the shell paints,
+        and the request the next turn would send is included beside it, so a
+        reader sees both the history and what the model is down to.
+
+        Args:
+            path: File to write; ``None`` puts ``zettcode-<id8>.html`` in the
+                workspace. A relative path is taken from the working directory.
+
+        Returns:
+            The absolute path that was written.
+
+        Raises:
+            ValueError: When the session has no stored header, so there is
+                nothing to export yet.
+        """
+        session = self.runtime.persistence.read(self.session_id)
+        if session.header is None:
+            raise ValueError("Nothing to export: this session has not been stored yet")
+        report = await self.context_report()
+        messages, tools = self._context_request(session)
+        trace = build_trace(
+            session,
+            title=self.session_name,
+            subtitle=f"Session {self.session_id} · {self.workspace}",
+            meta=self._export_meta(session),
+            tags=(self._export_model(), self.effort),
+            context_messages=messages,
+            tools=tuple(tool.name for tool in tools),
+            report=report,
+        )
+        trace = replace(trace, exported_at=datetime.now().astimezone().strftime("%Y-%m-%d %H:%M"))
+        target = path if path is not None else self.workspace / f"zettcode-{self.session_id[:8]}.html"
+        return write_export(target, render_html(trace))
+
+    def _export_model(self) -> str:
+        """Return the name a page is tagged with; a machine with no model says so rather than naming one."""
+        model = self.runtime.active_model
+        return "no model" if model is None else model.shown_name
+
+    def _export_meta(self, session: Session) -> tuple[tuple[str, str], ...]:
+        """Return the label/value pairs the exported page's sidebar carries."""
+        model = self.runtime.active_model
+        in_use = "none configured" if model is None else f"{model.shown_name} ({model.model})"
+        return (
+            ("Workspace", str(self.workspace)),
+            ("Model", in_use),
+            ("Effort", self.effort),
+            ("Created", session.created_at.astimezone().strftime("%Y-%m-%d %H:%M")),
+            ("Updated", session.updated_at.astimezone().strftime("%Y-%m-%d %H:%M")),
+            ("Messages", f"{session.message_count}"),
+        )

zettcode/engine/agent/interaction.py

@@ -0,0 +1,54 @@
+"""Answering what the model asked for: a shell approval, or a question for the reader.
+
+The agent is suspended inside a tool call while it waits, so the answer is an external
+event routed to the session and the call the request came from.
+"""
+
+from __future__ import annotations
+
+from zett_agent.agent import AgentRunConfig
+from zett_agent.extensions.external import ExternalEvent
+from zett_agent.extensions.shell_approval import SHELL_APPROVAL_RESPONSE_EVENT_NAME
+
+from zettcode.engine.dialogue.ask import ASK_USER_RESPONSE_EVENT_NAME, AskUserQuestion, answer_payload, decline_payload
+
+from .base import AgentBase
+
+
+class InteractionMixin(AgentBase):
+    """Send the reader's answer to an approval request or a question back to the running agent."""
+
+    def respond_approval(self, session_id: str, call_id: str, decision: str, remember: bool) -> None:
+        """Answer a pending shell approval for the originating session."""
+        self.runtime.started.agent.emit_external_event(
+            ExternalEvent(
+                name=SHELL_APPROVAL_RESPONSE_EVENT_NAME,
+                payload={"tool_call_id": call_id, "decision": decision, "remember": remember},
+            ),
+            config=AgentRunConfig(session_id=session_id),
+        )
+
+    def answer_ask(self, question: AskUserQuestion, answer: str) -> None:
+        """Answer the model's question; the suspended tool call resumes with it.
+
+        Args:
+            question: The question being answered, which carries the session and
+                the tool call the runtime routes the reply on.
+            answer: What the reader typed, exactly as it should reach the model.
+        """
+        self._respond_to_ask(question, answer_payload(question, answer))
+
+    def decline_ask(self, question: AskUserQuestion) -> None:
+        """Tell the model the reader cancelled, rather than leaving it waiting.
+
+        ``ask_user`` has no rejection channel in the runtime, so the tool result
+        says the question was declined and why; the model carries on from that.
+        """
+        self._respond_to_ask(question, decline_payload(question))
+
+    def _respond_to_ask(self, question: AskUserQuestion, payload: dict[str, object]) -> None:
+        """Emit one ``ask_user_response`` for the session the question came from."""
+        self.runtime.started.agent.emit_external_event(
+            ExternalEvent(name=ASK_USER_RESPONSE_EVENT_NAME, payload=dict(payload)),
+            config=AgentRunConfig(session_id=question.session_id),
+        )

zettcode/engine/agent/sessions.py

@@ -0,0 +1,218 @@
+"""Sessions: which one is active, switching and forking, and the title that names it.
+
+Resuming is two steps on purpose. :meth:`SessionsMixin.load_session` reads and replays a
+stored session into a value and touches nothing the shell is reading, so the shell can run
+it on a worker thread; :meth:`SessionsMixin.install_session` only assigns, so it runs where
+the rest of the shell does.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from zett_agent.messages import AssistantMessage, UserMessage
+from zett_agent.model import ReasoningEffort
+
+from zettcode.engine.dialogue.title import summarize_title
+from zettcode.engine.extensions.usage import UsageSnapshot, session_usage
+from zettcode.engine.storage import Session, SessionInfo, SessionStats
+from zettcode.wording import UNTITLED_SESSION
+
+from .context import ContextMixin
+
+
+@dataclass(frozen=True, slots=True)
+class StoredSession:
+    """A session read from the store, not yet made active.
+
+    Attributes:
+        session_id: The session that was read.
+        session: Its parsed file.
+        usage: Totals accumulated from the usage every stored reply recorded.
+        title: Its stored display title, if it has one: read here because folding
+            the metadata log is the other thing resuming used to do on the loop.
+        model: The model the session last used, by the name the model picker shows, if one
+            was recorded; read here for the same reason as the title.
+    """
+
+    session_id: str
+    session: Session
+    usage: UsageSnapshot
+    title: str | None
+    model: str | None = None
+
+
+class SessionsMixin(ContextMixin):
+    """Switch, resume, fork, list, and name the conversation the next turn belongs to."""
+
+    @property
+    def session_title(self) -> str | None:
+        """Return the active session's stored display title, if it has one.
+
+        Reading the store folds the whole metadata log, so callers that paint
+        often should cache the result instead of asking once per frame.
+        """
+        return self.runtime.persistence.session_title(self.session_id)
+
+    def session_path(self) -> Path:
+        """Return the file this session is stored in, under the store root.
+
+        The whole conversation, on disk: what ``/context`` shows beside the token
+        breakdown, and what a reader opens when they want the raw records rather
+        than a rendered transcript.
+        """
+        return self.runtime.persistence.session_path(self.session_id)
+
+    @property
+    def session_name(self) -> str:
+        """Return the name to show for the active session.
+
+        A session is named after its first reply; until then the store has no
+        title, and a status line or list row that shows nothing at all reads
+        like a bug rather than like a fresh session.
+        """
+        return self.session_title or UNTITLED_SESSION
+
+    def new_session(self) -> str:
+        """Start a new conversation."""
+        return self.runtime.new_session()
+
+    def use_session(self, session_id: str) -> None:
+        """Switch future turns to a session."""
+        self.runtime.use_session(session_id)
+
+    def fork_session(self) -> str:
+        """Copy this conversation's context into a new session, and return its id.
+
+        What is carried over is what a request would send — the newest checkpoint's
+        summary and the messages after it — not the whole stored history: the fork
+        starts from the conversation the model is actually working with. The shell
+        installs the result the way a resume does, so the reader lands in the fork
+        with the same conversation in front of them.
+
+        Synchronous file work on purpose, so the shell can run it on a thread.
+        """
+        return self.runtime.persistence.fork(self.session_id)
+
+    def load_session(self, session_id: str) -> StoredSession:
+        """Read a stored session, changing nothing.
+
+        This is the expensive half of resuming — parsing the file and adding up its usage — and it touches no
+        state anyone is reading, so a caller may run it on a worker thread and hand the result to
+        :meth:`install_session` on the loop. What a front end shows of the session it builds from
+        ``stored.session`` itself.
+
+        Raises:
+            ValueError: The store holds no such session, or its file is corrupt.
+        """
+        persistence = self.runtime.persistence
+        session = persistence.read(session_id)
+        if session.header is None:
+            raise ValueError(f"Unknown session: {session_id}")
+        return StoredSession(
+            session_id=session_id,
+            session=session,
+            usage=session_usage(session.branch()),
+            title=persistence.session_title(session_id),
+            model=persistence.session_model(session_id),
+        )
+
+    def install_session(self, stored: StoredSession) -> None:
+        """Make a loaded session the active one: its totals, its id, its model.
+
+        The cheap half, and the one that changes state; everything it does is assignment.
+        """
+        session_id, session = stored.session_id, stored.session
+        self.runtime.usage.seed(session_id, stored.usage)
+        self.use_session(session_id)
+        # Pick up where the session left off: the model it last used, when this configuration
+        # still has it. A session that never recorded one, or whose model is gone, keeps whatever
+        # is selected now — the shell says so in the second case.
+        model = self.runtime.find_model(stored.model) if stored.model else None
+        if model is not None and model is not self.runtime.active_model:
+            self.runtime.use_model(model)
+        # Prime the report with what the next turn would send, not with what the
+        # transcript shows: the display keeps every message a compaction folded
+        # away, and measuring those claims a request several times the size of the
+        # real one — 2.9 M tokens against a context of 290 k, which is a share
+        # pinned at a hundred. `_context_request` is the one definition of that
+        # request; the environment and tool notes only exist inside a real one,
+        # which the report admits.
+        #
+        # It is handed over as a function, not built here: the request holds every
+        # message since the last checkpoint, decoding them is most of what a long
+        # resume would cost, and nothing reads the list until `/context` does.
+        self.runtime.context.remember(session_id, lambda: self._stored_request(session))
+
+    def restore_session(self, session_id: str) -> None:
+        """Load the stored branch and make it the active one."""
+        self.install_session(self.load_session(session_id))
+
+    async def list_sessions(self, *, limit: int = 20) -> list[SessionInfo]:
+        """List persisted session metadata by recent activity."""
+        return await self.runtime.persistence.list_sessions(limit=limit)
+
+    async def session_stats(self, sessions: Sequence[SessionInfo]) -> dict[str, SessionStats]:
+        """Return the entry count and token totals of listed sessions, keyed by session id.
+
+        A session missing from the answer has no totals to show.
+        """
+        return await self.runtime.persistence.session_stats([session.session_id for session in sessions])
+
+    async def rename_session(self, title: str) -> str:
+        """Store a display title for the active session and return it cleaned.
+
+        A title the user typed wins over the one the background summarizer would
+        have written: ``title_session`` never renames a session that already has
+        a title, so naming by hand also stops the model call.
+
+        Args:
+            title: Name to store; surrounding space is trimmed, and a blank or
+                over-long name is rejected by the store.
+
+        Raises:
+            SessionLocked: Another process has this session open.
+        """
+        self.require_session()
+        await self.runtime.persistence.set_title(self.session_id, title)
+        return title.strip()
+
+    async def title_session(self, session_id: str) -> str | None:
+        """Name a session from its first exchange, unless it already has a title.
+
+        The call is a background nicety: it reads the stored branch, asks the
+        active model for a short title, and appends that title to the session.
+
+        Args:
+            session_id: Session to name.
+
+        Returns:
+            The stored title, or ``None`` when the session was already named, has
+            no first exchange yet, or the model replied with nothing usable.
+        """
+        if self.runtime.persistence.session_title(session_id) is not None:
+            return None
+        if session_id == self.session_id and self.session_locked:
+            return None  # a nicety, and not one that is worth writing into a session that is not ours
+        session = self.runtime.persistence.read(session_id)
+        branch = session.branch()
+        question = next(
+            (line.message[0].text for line in branch if isinstance(line.message[0], UserMessage)),
+            None,
+        )
+        answer = next(
+            (line.message[0].content for line in reversed(branch) if isinstance(line.message[0], AssistantMessage)),
+            None,
+        )
+        if not question or not answer:
+            return None
+        await self.runtime.start()
+        # A level the model takes, so naming the session cannot be what fails on an endpoint that lacks `low`.
+        effort = self.runtime.required_model.accepted_effort(ReasoningEffort.LOW)
+        title = await summarize_title(self.runtime.provider, question=question, answer=answer, effort=effort)
+        if title is None:
+            return None
+        await self.runtime.persistence.set_title(session_id, title)
+        return title