zettcode-plugin-api 0.4.0__py3-none-any.whl

zettcode/plugin_api/state.py

@@ -0,0 +1,251 @@
+"""The shell snapshot and segment types a plugin draws against.
+
+A segment builder is called once per paint with a :class:`ShellContext`: a
+snapshot of everything the shell's own rows read, grouped by what it describes
+(``session``, ``model``, ``activity``, ``display``) with the resolved ``config``
+beside them. The same module carries the segment types a plugin registers, so a
+builder and what it registers are described in one place.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, TypeAlias
+
+from zettcode._compat import StrEnum
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only, so the imports stay lazy
+    from pathlib import Path
+
+    from zettcode.config import ZettCodeConfig
+    from zettcode.sdk.types import ModelInfo, Usage
+    from zettcode.tui import TextLine, Theme
+
+    from .rows import Row
+
+
+#: Which row a plugin draws into: the header above the transcript, or the
+#: status line under the composer.
+UiRegion: TypeAlias = Literal["header", "status"]
+
+#: Which side of a row a segment gathers on. A plugin never chooses it: the
+#: registration method it calls, or the builtin segment it replaces, does.
+UiSide: TypeAlias = Literal["left", "right"]
+
+#: What one segment paints: a styled line, a plain string, a :class:`~zettcode.statusline.Row` of
+#: named parts the reader may switch off, or nothing. The alias quotes its members because
+#: :class:`TextLine` is imported only for the checker; an alias evaluates eagerly, so the names must stay strings.
+UiSegmentValue: TypeAlias = "TextLine | Row | str | None"
+
+#: What a builder returns: a value, or ``(value, override)`` when the segment
+#: wants its side to itself. With ``override`` the segments registered before it
+#: are dropped for that paint, so the side shows this segment (and anything
+#: registered after it) instead of what the builtins put there.
+UiBuilderResult: TypeAlias = "UiSegmentValue | tuple[UiSegmentValue, bool]"
+
+#: One plugin-drawn segment: the callable that paints it.
+UiBuilder: TypeAlias = Callable[["ShellContext"], UiBuilderResult]
+
+
+@dataclass(frozen=True, slots=True)
+class SessionState:
+    """Which conversation the shell is showing.
+
+    Attributes:
+        id: Active session identity.
+        title: Stored session title, or ``None`` before the first reply.
+        name: Title to show, falling back to ``"New session"``.
+        workspace: Workspace directory the agent runs in.
+        handle: The name other sessions address this one by with ``@``, or ``""`` when messaging is off or
+            the session is not registered yet.
+    """
+
+    id: str
+    title: str | None
+    name: str
+    workspace: Path
+    handle: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class ModelState:
+    """What the next request will ask for.
+
+    Attributes:
+        config: The active model, with its id, display name, context window, and
+            multimodal flag; ``None`` on a machine with no model configured yet,
+            where ``name`` is empty, ``efforts`` is empty, and anything that needs
+            a window has none to measure against.
+        name: Display name, the short form of ``config.name``.
+        effort: Reasoning effort as its string value.
+        efforts: Every reasoning level the runtime accepts, cheapest first.
+    """
+
+    config: ModelInfo | None
+    name: str
+    effort: str
+    efforts: tuple[str, ...]
+
+
+class Activity(StrEnum):
+    """What the shell is doing between requests, as the status line words it."""
+
+    READY = "ready"
+    RUNNING = "running"
+
+
+@dataclass(frozen=True, slots=True)
+class ActivityState:
+    """What the agent is doing right now, and what it has spent.
+
+    Attributes:
+        busy: Whether a turn or a command is in flight.
+        status: The shell's own state next to the activity glyph.
+        note: One-off text that takes the status word's place, such as the
+            running command's name or ``"copied 12 characters"``; ``None``
+            shows the status word itself.
+        auto_shell: Whether shell commands are approved for the rest of the run.
+            ``True`` exactly when ``permission`` is ``"full"``; kept for plugins
+            written before the other levels existed.
+        usage: Cumulative token counters for the active session.
+        tasks: The session's plan as ``(status, content)`` pairs, empty when the
+            model has not published one.
+        frame: Animation frame counter; it advances only while something is
+            busy, which is what a plugin animates against.
+        permission: How much of the shell may run unasked: ``"deny"``, ``"ask"``,
+            ``"safe"``, or ``"full"``.
+        self_compact: Whether the model may compact its own context in this session.
+    """
+
+    busy: bool
+    status: Activity
+    note: str | None
+    auto_shell: bool
+    usage: Usage
+    tasks: tuple[tuple[str, str], ...]
+    frame: int
+    permission: str = "ask"
+    self_compact: bool = False
+
+    @property
+    def label(self) -> str:
+        """Return the word the status line shows: the note, else the state."""
+        return self.note or self.status
+
+
+@dataclass(frozen=True, slots=True)
+class DisplayState:
+    """The terminal and the palette a shell row is drawn into.
+
+    Attributes:
+        theme: Active palette, so a plugin styles with the same colours as the
+            rest of the shell instead of hardcoding its own.
+        width: Current terminal width in columns.
+        height: Current terminal height in rows.
+        screen: Name of the topmost screen (``"main"``, ``"page"``, ``"toast"``),
+            so a plugin can tell an overlay from the composer.
+        scrolled_up: Whether the transcript is showing history rather than the
+            newest line, which is what the "back to bottom" badge tracks.
+    """
+
+    theme: Theme
+    width: int
+    height: int
+    screen: str
+    scrolled_up: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ShellContext:
+    """What a plugin reads when it draws one header or status row.
+
+    The state is rebuilt for every paint, so a builder always sees the current
+    session, model, counters, and terminal size; it is a snapshot, not a
+    subscription. It is deliberately everything the shell's own rows read —
+    a plugin should not have to guess at the shell's state to draw beside it —
+    grouped so a builder names the part it wants instead of one long field list.
+
+    Attributes:
+        config: Resolved settings the runtime was built from.
+        session: The conversation on screen.
+        model: What the next request will ask for.
+        activity: What the agent is doing and what it has spent.
+        display: The terminal, palette, and scroll position it draws into.
+    """
+
+    config: ZettCodeConfig
+    session: SessionState
+    model: ModelState
+    activity: ActivityState
+    display: DisplayState
+
+
+@dataclass(frozen=True, slots=True)
+class UiSegment:
+    """One named piece of a shell row.
+
+    Attributes:
+        name: Identity within its row. Registering a segment under a name that
+            already exists replaces that one in place, which is how a plugin
+            takes a slot over from the builtin rows.
+        builder: Called once per paint with the current :class:`ShellContext`.
+    """
+
+    name: str
+    builder: UiBuilder
+
+
+@dataclass(frozen=True, slots=True)
+class TurnContext:
+    """What a request came to, for the items of the line it ends on.
+
+    Attributes:
+        label: How the request ended, as the line's first word: ``Processed``, or ``Continued`` for a ``/continue``.
+        seconds: Wall time of the request.
+        clock: The time of day it ended, as ``HH:MM``.
+        usage: What the request spent: the session's usage after it, less before it.
+        tools: Tool calls the request made.
+        failed_tools: How many of them failed.
+    """
+
+    label: str
+    seconds: float
+    clock: str
+    usage: Usage
+    tools: int = 0
+    failed_tools: int = 0
+
+
+#: Called once when a request ends with its :class:`TurnContext`; returns the item's text, or nothing to leave it out.
+TurnBuilder: TypeAlias = Callable[[TurnContext], "str | None"]
+
+
+@dataclass(frozen=True, slots=True)
+class TurnSegment:
+    """One named item of the line a request ends on.
+
+    Attributes:
+        name: Identity, and the switch it has in ``[statusline]`` and ``/statusline``; it starts with ``turn-``.
+            Registering a segment under a name that exists replaces that one in place.
+        summary: One line saying what it shows, for the ``/statusline`` panel.
+        builder: Called once per request with a :class:`TurnContext`.
+    """
+
+    name: str
+    summary: str
+    builder: TurnBuilder
+
+
+@dataclass(frozen=True, slots=True)
+class UiRow:
+    """One shell row: its two sides, each painted left to right.
+
+    The sides are the shell's frame, not a plugin's choice; ``left`` is drawn at
+    the left edge and ``right`` flush to the right, with ``StatusBar`` settling
+    which one wins when the terminal is narrow.
+    """
+
+    region: UiRegion
+    left: tuple[UiSegment, ...] = ()
+    right: tuple[UiSegment, ...] = ()

zettcode/plugin_api/switch.py

@@ -0,0 +1,87 @@
+"""The switch the shell's panels draw: a short rail with a round knob, and the state of one row's switch.
+
+``/self-compact``, ``/statusline``, ``/config``'s one-model panel and ``/plugins`` all draw the same switch, so the thing
+a reader presses looks the same wherever they press it. It lives in a module of its own because more than one page
+draws it: a page importing another page's private helper was how it used to be spelled.
+"""
+
+from __future__ import annotations
+
+from zettcode.tui import Canvas, Theme
+from zettcode.tui.render import Style, blend
+
+#: Seconds a knob takes to travel to the option it was sent to.
+SLIDE_SECONDS = 0.28
+
+#: Columns of the rail: short enough to sit beside a name, long enough that the knob crosses nine columns in the slide
+#: instead of the four a five-column rail gives it, which is what made it jump.
+SWITCH_WIDTH = 10
+
+
+class Rail:
+    """One row's choices and the knob on them: where it is, where it is going, and how it gets there."""
+
+    def __init__(self, words: tuple[str, ...], current: int) -> None:
+        self.words = words
+        self.start = current
+        self.selected = current
+        self.origin = float(current)
+        self.set_off = 0.0
+        self.moving = False
+
+    def position(self, now: float) -> float:
+        """Return where the knob is, in options from the first: a fraction while it travels."""
+        if not self.moving:
+            return float(self.selected)
+        progress = (now - self.set_off) / SLIDE_SECONDS
+        if progress >= 1.0:
+            return float(self.selected)
+        eased = 1 - (1 - max(0.0, progress)) ** 3
+        return self.origin + (self.selected - self.origin) * eased
+
+    def choose(self, index: int, now: float, *, instant: bool) -> bool:
+        """Send the knob to an option; say whether it has somewhere to travel."""
+        index = max(0, min(len(self.words) - 1, index))
+        if index == self.selected:
+            return False
+        self.origin = self.position(now)
+        self.selected = index
+        self.set_off = now
+        self.moving = not instant
+        if instant:
+            self.origin = float(index)
+        return self.moving
+
+    def arrive(self, now: float) -> bool:
+        """Stop the knob if it has arrived; say whether this was its last frame."""
+        if self.moving and self.position(now) == float(self.selected):
+            self.moving = False
+            self.origin = float(self.selected)
+            return True
+        return False
+
+
+def draw_switch(canvas: Canvas, theme: Theme, y: int, x: int, position: float, groove: str) -> None:
+    """Draw a switch as a short thin rail: lit up to the knob when on, the knob at the start of a groove when off.
+
+    It is the rail every panel uses, drawn the same way, with its round knob. The position is the clock's, so a slow
+    terminal drops frames instead of slowing the knob.
+
+    Args:
+        canvas: Where to draw.
+        theme: The palette; the rail is drawn on its raised surface.
+        y: The row.
+        x: The column of the rail's first cell.
+        position: Where the knob is, from 0 (off) to 1 (on); a fraction while it travels.
+        groove: The colour of the empty stretch.
+    """
+    surface = theme.surface_alt
+    knob = round(max(0.0, min(1.0, position)) * (SWITCH_WIDTH - 1))
+    lit = blend(blend(theme.muted, surface, 0.25), theme.accent, position)
+    for cell in range(SWITCH_WIDTH):
+        if cell < knob:
+            canvas.draw_text(x + cell, y, "\u2501", Style(foreground=lit, background=surface))
+        elif cell > knob:
+            canvas.draw_text(x + cell, y, "\u2500", Style(foreground=groove, background=surface))
+    colour = blend(lit, theme.text, 0.35 * position)
+    canvas.draw_text(x + knob, y, "\u25cf", Style(foreground=colour, background=surface, bold=True))

zettcode_plugin_api-0.4.0.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: zettcode-plugin-api
+Version: 0.4.0
+Summary: The one package a ZettCode plugin depends on: the plugin surface, re-exported
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: api,plugin,zettcode
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: zettcode-engine
+Requires-Dist: zettcode-tui
+Provides-Extra: types
+Requires-Dist: zettcode-sdk; extra == 'types'

zettcode_plugin_api-0.4.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+zettcode/plugin_api/__init__.py,sha256=2kP0ceBF5fzi0AB5aXwHlbo_i4uXCVHNEj2ZuUc_brw,9644
+zettcode/plugin_api/commands.py,sha256=Ku0aHPOVQjp79W8p8FMFhKjbmMUmgB9TMCQIOIyyTlE,17956
+zettcode/plugin_api/entries.py,sha256=taGQFPzwj-UBchOBLrDGpRjUHGIj8qSma1UH6A_FV24,14761
+zettcode/plugin_api/host.py,sha256=LT38RB4ipgn05SiupkoBol9B9J57RCSXW1vqK5sahQE,1476
+zettcode/plugin_api/mixins.py,sha256=v1tdhi9I8rLwQJrj--3DUDWVQmInS87EA9QQ13yrf-8,3083
+zettcode/plugin_api/panels.py,sha256=rtcu27JhfLSKlw5PDik-Gm1FIVRca25ecxqHEsvE41o,1729
+zettcode/plugin_api/pets.py,sha256=q2opVI1psQqphjU0pSdAxhPmGwIHpDw_zgSZGFZVH9A,9858
+zettcode/plugin_api/plugin.py,sha256=rF6BLQkEszdK6sD72a2qfDF7g4986nreIgoLMfJF_RU,4150
+zettcode/plugin_api/presenters.py,sha256=EeNlDVjqUaQW4VtwEy1FVA8sWTwDwKoddYr5yK7iIJ4,13686
+zettcode/plugin_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zettcode/plugin_api/rows.py,sha256=d4EgXCNX17fS3UoUOC3n2rv_hDdel36o71iS_Xstr-o,3574
+zettcode/plugin_api/state.py,sha256=FvhkdTvI_Kza0tqkFycSe8teHCD_-fpOT6HopXnlHZM,9183
+zettcode/plugin_api/switch.py,sha256=r2ayyIY2E6a8lns3Dy6uwR7HL-6P9jmRIPEBpsrv_p4,3819
+zettcode_plugin_api-0.4.0.dist-info/METADATA,sha256=gzqPlvor0Iv4-psRfLG-Znuc4Wi-drzcfufmLlnL5KQ,832
+zettcode_plugin_api-0.4.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+zettcode_plugin_api-0.4.0.dist-info/RECORD,,

zettcode_plugin_api-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any