zettcode-commands 0.4.2__py3-none-any.whl

zettcode/commands/plugin.py

@@ -0,0 +1,56 @@
+"""The plugin that offers the slash commands that act on the application.
+
+One plugin, not one per command group, so the order ``/help`` lists them in is the order they are registered here and
+does not depend on how the loader happens to sort entry-point names. It is found through the ``zettcode.plugin``
+entry point and is one the terminal requires: with no ``/help``, no ``/plugins`` and no ``/model`` there would be no
+way back to a working setup from inside the program.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from zettcode.plugin_api.plugin import TuiPlugin
+
+from .handlers import (
+    BashCommand,
+    CodeReview,
+    HelpCommand,
+    ModelCommands,
+    PluginCommand,
+    SessionCommands,
+    ShellControl,
+    SideQuestion,
+)
+from .hub import HubCommand
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zettcode.plugin_api import PluginContext
+
+
+class CommandsPlugin(TuiPlugin):
+    """``/help``, ``/plugins``, ``/resume``, ``/model``, ``/btw``, ``/review``, ``/bash``, ``/clear``…"""
+
+    name = "commands"
+    description = "The slash commands that act on the application"
+
+    def __init__(self) -> None:
+        #: The command groups, in the order ``/help`` lists them.
+        self.groups: tuple[TuiPlugin, ...] = (
+            HelpCommand(),
+            PluginCommand(),
+            SessionCommands(),
+            ModelCommands(),
+            SideQuestion(),
+            CodeReview(),
+            BashCommand(),
+            ShellControl(),
+            HubCommand(),
+        )
+
+    def activate(self, ctx: PluginContext) -> None:
+        """Register every group's commands, in order, on this plugin's own context."""
+        if ctx.tui is None:
+            return
+        for group in self.groups:
+            group.activate(ctx)

zettcode/commands/usage.py

@@ -0,0 +1,46 @@
+"""``/usage``: what this workspace's sessions have spent."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from zettcode.app.plugins.groups import require_tui
+from zettcode.plugin_api import USAGE_LEDGER
+from zettcode.plugin_api.commands import CommandContext, CommandResult
+from zettcode.plugin_api.plugin import TuiPlugin
+from zettcode.presenters import labels
+from zettcode.sdk.translation import ledger_from
+
+from .usage_page import UsagePage
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only
+    from zettcode.plugin_api import PluginContext
+
+
+class UsageCommand(TuiPlugin):
+    """``/usage``: what this workspace's sessions have spent, by model, session and day.
+
+    The numbers are read back from the stored conversations, so the page covers every
+    session of the workspace, not only the one open, and an hour from now it will still
+    agree with the files. It only reads, so it may run beside a request.
+    """
+
+    name = "usage"
+    description = "Token use by model, by session and by day"
+
+    def activate(self, ctx: PluginContext) -> None:
+        """Register ``/usage``; the store keeps one reader, so a second look re-reads only what changed."""
+        config = ctx.config
+        tui = require_tui(ctx)
+
+        async def show(context: CommandContext) -> CommandResult:
+            """Open the usage page, or say that nothing has been spent yet."""
+            service = ctx.agent.usage_ledger_service()
+            if service is None:
+                raise LookupError(f"No plugin provides the {USAGE_LEDGER!r} service")
+            usage = ledger_from(await service.ledger())
+            if usage.total.requests == 0:
+                return CommandResult(message="No model replies are recorded in this workspace yet.")
+            return CommandResult(widget=UsagePage(usage, workspace=labels.compact_path(config.workspace, limit=None)))
+
+        tui.register_command("usage", "Token use by model, by session and by day", show, when_busy="now")

zettcode/commands/usage_page.py

@@ -0,0 +1,290 @@
+"""The page ``/usage`` opens: where the tokens went, by model, by session, and by day."""
+
+from __future__ import annotations
+
+import colorsys
+from collections.abc import Callable
+from datetime import date, timedelta
+
+from zettcode.presenters import usage_charts as charts
+from zettcode.sdk.types import WorkspaceUsage
+from zettcode.tui import SEPARATOR, KeyEvent, MouseAction, MouseEvent, Style, Theme, Widget
+from zettcode.tui.render import blend, parse_hex
+
+#: The tabs, in the order Tab walks through them.
+TABS = ("Models", "Sessions", "Calendar")
+
+#: Rows above the body: a blank, the title, the tabs, and the totals.
+HEAD_ROWS = 4
+
+#: How far a mouse-wheel notch moves the body.
+WHEEL_ROWS = 3
+
+#: Shade of each calendar level, as how far it sits from the page colour towards the busiest day's colour.
+#: The first level starts well clear of the empty cell, as GitHub's does: an active day must not read as
+#: a quiet one, on a dark page least of all, where a faint blend vanishes into the background. The steps
+#: still grow towards the top, so the busiest days pull away from the ones below them. They are wide at the
+#: bottom (a pale green was hard to tell from the level above it) and narrow at the top.
+HEAT = (0.0, 0.45, 0.65, 0.83, 1.0)
+
+#: How far the calendar's colour sits between the palette's warning yellow (0) and its orange, the write colour (1):
+#: an orange-gold that no other part of the page uses for data, and one every palette defines.
+HEAT_ORANGE = 0.5
+
+#: How the busiest day deepens the accent: more saturation and less lightness, so the top of
+#: the ramp reads as a deeper colour than the accent the rest of the page draws.
+DEEPER_SATURATION = 1.25
+DEEPER_LIGHTNESS = 0.88
+
+
+def deepened_accent(colour: str) -> str:
+    """Return ``colour`` deeper and more saturated: the shade of the busiest calendar day.
+
+    The ramp runs from the page towards this shade rather than towards the colour itself, so
+    the four levels spread over a wider range and the top one is deeper than anything else on
+    the page. A colour that cannot be parsed is returned unchanged, as :func:`blend` does.
+    """
+    rgb = parse_hex(colour)
+    if rgb is None:
+        return colour
+    hue, lightness, saturation = colorsys.rgb_to_hls(*(channel / 255 for channel in rgb))
+    deepened = colorsys.hls_to_rgb(hue, lightness * DEEPER_LIGHTNESS, min(1.0, saturation * DEEPER_SATURATION))
+    return "#" + "".join(f"{round(channel * 255):02x}" for channel in deepened)
+
+
+def heat_colour(theme: Theme) -> str:
+    """Return the colour of the busiest calendar day in a palette: a deepened orange-gold.
+
+    The calendar used to be shades of the accent, and the accent is a green made for text on a dark page; its four
+    levels sat close together and close to the empty cell. An orange-gold is told apart from the grey of an empty
+    day and from its own neighbours, and it takes nothing from the green the rest of the page draws.
+    """
+    return deepened_accent(blend(theme.warning, theme.tools.write, HEAT_ORANGE))
+
+
+class UsagePage(Widget):
+    """A full-screen page with three views of one workspace's usage.
+
+    Shape::
+
+        Usage  ~/projects/api                       <- title and workspace
+        Models  Sessions  Calendar                  <- tabs; the open one is filled
+        All models   1.2B tokens   in ...           <- totals, on every tab
+        <body>                                      <- scrolls
+        tab switch · ↑↓ scroll · esc back           <- footer
+
+    **Models** draws two bars for each model, **Sessions** one row for each session with its
+    input and output, and **Calendar** a grid of weeks like the one GitHub draws for
+    contributions: a column is a week, a square a day, and the shade is the day's tokens.
+    On the calendar the arrow keys choose a day and the line under the grid says what it
+    spent.
+
+    The page is the whole screen, and paints on every frame from the lines the chart module
+    describes, so a resize costs nothing but a repaint.
+    """
+
+    def __init__(
+        self,
+        ledger: WorkspaceUsage,
+        *,
+        workspace: str = "",
+        on_cancel: Callable[[], None] | None = None,
+        today: date | None = None,
+        tab: str = TABS[0],
+    ) -> None:
+        """Hold the ledger to draw and start on one tab.
+
+        Args:
+            ledger: What the workspace has spent.
+            workspace: Shown beside the title, so the page says whose usage it is.
+            on_cancel: Called on Escape instead of the page popping itself, for an owner that
+                keeps its own screen stack; most callers leave it out.
+            today: The last day the calendar draws; the real date when omitted.
+            tab: Which tab opens first.
+        """
+        super().__init__()
+        self.ledger = ledger
+        self.workspace = workspace
+        self.on_cancel = on_cancel
+        self.today = today or date.today()
+        self.tab = TABS.index(tab) if tab in TABS else 0
+        self.selected = self.today
+        self.offset = 0
+        self._body_rows = 0
+
+    @property
+    def focusable(self) -> bool:
+        """Take the keyboard when the page opens, so its keys work without a click."""
+        return True
+
+    @property
+    def tab_name(self) -> str:
+        """Return the name of the open tab."""
+        return TABS[self.tab]
+
+    # -- content ------------------------------------------------------------
+    def lines(self, width: int) -> tuple[list[charts.Line], list[charts.Line]]:
+        """Return the open tab's fixed heading lines and its scrolling body."""
+        if self.tab_name == "Models":
+            return charts.models_tab(self.ledger, width)
+        if self.tab_name == "Sessions":
+            return charts.sessions_tab(self.ledger, width)
+        head, body, _, _ = charts.calendar_tab(self.ledger, width, self.today, self.selected)
+        return head, body
+
+    # -- input --------------------------------------------------------------
+    def close(self) -> None:
+        """Leave the page: through the owner's callback when it gave one, else by popping itself."""
+        if self.on_cancel is not None:
+            self.on_cancel()
+        elif self.app is not None and self.app.screens.top.widget is self:
+            self.app.pop_screen()
+            self.app.request_layout()
+
+    def capture_event(self, event, host) -> bool:
+        """Close on Escape before anything else can take the key."""
+        if isinstance(event, KeyEvent) and event.key == "escape":
+            self.close()
+            return True
+        return False
+
+    def handle(self, event, host) -> bool:
+        """Switch tabs, scroll the body, or move the day chosen on the calendar."""
+        if isinstance(event, MouseEvent):
+            if event.action is MouseAction.SCROLL_UP:
+                self._scroll(-WHEEL_ROWS)
+            elif event.action is MouseAction.SCROLL_DOWN:
+                self._scroll(WHEEL_ROWS)
+            else:
+                return False
+            host.invalidate()
+            return True
+        key = self._key_of(event)
+        if key is None:
+            return False
+        if key in ("tab", "backtab"):
+            self._open((self.tab + (1 if key == "tab" else -1)) % len(TABS))
+        elif key in ("1", "2", "3"):
+            self._open(int(key) - 1)
+        elif self.tab_name == "Calendar" and key in ("left", "right", "up", "down", "home", "end"):
+            self._move_day(key)
+        elif key in ("left", "right"):
+            self._open((self.tab + (1 if key == "right" else -1)) % len(TABS))
+        elif key in ("up", "k"):
+            self._scroll(-1)
+        elif key in ("down", "j"):
+            self._scroll(1)
+        elif key == "page_up":
+            self._scroll(-max(1, self._body_rows - 1))
+        elif key == "page_down":
+            self._scroll(max(1, self._body_rows - 1))
+        elif key == "home":
+            self.offset = 0
+        elif key == "end":
+            self._scroll(10**9)
+        elif key == "q":
+            self.close()
+        else:
+            return False
+        host.invalidate()
+        return True
+
+    @staticmethod
+    def _key_of(event: object) -> str | None:
+        """Return the key an event names, whether it came as a key or as typed text."""
+        if isinstance(event, KeyEvent):
+            return None if event.alt or event.control else event.key
+        text = getattr(event, "text", None)
+        return text if isinstance(text, str) and len(text) == 1 else None
+
+    def _open(self, tab: int) -> None:
+        """Show another tab from its top."""
+        self.tab = tab
+        self.offset = 0
+
+    def _scroll(self, rows: int) -> None:
+        """Move the body, never past its first row or its last."""
+        _, body = self.lines(max(1, self.rect.width - 4))
+        furthest = max(0, len(body) - self._body_rows)
+        self.offset = min(max(0, self.offset + rows), furthest)
+
+    def _move_day(self, key: str) -> None:
+        """Move the chosen calendar day: a day for up and down, a week for left and right."""
+        step = {"left": -7, "right": 7, "up": -1, "down": 1}.get(key)
+        earliest = charts.first_day(self.today, charts.weeks_that_fit(max(1, self.rect.width - 4)))
+        if key == "home":
+            self.selected = earliest
+        elif key == "end":
+            self.selected = self.today
+        elif step is not None:
+            self.selected = min(self.today, max(earliest, self.selected + timedelta(days=step)))
+
+    # -- painting -----------------------------------------------------------
+    def style_of(self, role: str) -> Style:
+        """Return how a role is painted in the active theme."""
+        theme = self.theme
+        page = theme.surface_alt
+        if role.startswith("heat"):
+            chosen = role.endswith("*")
+            level = int(role.removeprefix("heat").removesuffix("*"))
+            if level == 0:
+                colour = blend(page, theme.text, 0.14)
+            else:
+                colour = blend(page, heat_colour(theme), HEAT[level])
+            # The day the arrow keys are on sits on a neutral lift of the page: the ramp's own colours are the data,
+            # and a tinted ground would pull the cell towards one of its neighbours.
+            ground = blend(page, theme.text, 0.2) if chosen else page
+            return Style(foreground=colour, background=ground, bold=chosen)
+        colours = {
+            "text": theme.text,
+            "heading": theme.text,
+            "muted": theme.muted,
+            "input": theme.accent,
+            "output": theme.warning,
+            "cached": theme.tools.subagent,
+            "track": blend(page, theme.text, 0.18),
+        }
+        return Style(foreground=colours.get(role, theme.text), background=page, bold=role == "heading")
+
+    def render(self, canvas) -> None:
+        """Fill the page, then draw the title, the tabs, the totals, the body, and the footer."""
+        if self.rect.empty:
+            return
+        theme = self.theme
+        rect = self.rect
+        page = Style(background=theme.surface_alt)
+        canvas.fill(rect.x, rect.y, rect.width, rect.height, page)
+        room = max(0, rect.width - 4)
+        canvas.draw_text(rect.x + 2, rect.y + 1, "Usage", self.style_of("heading"), max_width=room)
+        canvas.draw_text(rect.x + 9, rect.y + 1, self.workspace, self.style_of("muted"), max_width=max(0, room - 7))
+        column = rect.x + 2
+        for index, name in enumerate(TABS):
+            label = f" {name} "
+            style = (
+                Style(foreground=theme.surface_alt, background=theme.accent, bold=True)
+                if index == self.tab
+                else self.style_of("muted")
+            )
+            column += canvas.draw_text(column, rect.y + 2, label, style) + 1
+        head, body = self.lines(room)
+        for row, line in enumerate(head):
+            self._draw(canvas, rect.x + 2, rect.y + 3 + row, line, room)
+        top = rect.y + 3 + len(head) + 1
+        self._body_rows = max(0, rect.bottom - 2 - top)
+        self.offset = min(self.offset, max(0, len(body) - self._body_rows))
+        for row, line in enumerate(body[self.offset : self.offset + self._body_rows]):
+            self._draw(canvas, rect.x + 2, top + row, line, room)
+        if self.tab_name == "Calendar":
+            keys = "arrows choose a day"
+        else:
+            keys = "\u2191\u2193 scroll" if len(body) > self._body_rows else ""
+        hint = f" {SEPARATOR} ".join(part for part in ("tab switch", keys, "esc back") if part)
+        canvas.draw_text(rect.x + 2, rect.bottom - 1, hint, self.style_of("muted"), max_width=room)
+
+    def _draw(self, canvas, x: int, y: int, line: charts.Line, room: int) -> None:
+        """Draw one line of roles from ``x``, stopping at the edge of the page."""
+        used = 0
+        for text, role in line:
+            if used >= room:
+                break
+            used += canvas.draw_text(x + used, y, text, self.style_of(role), max_width=room - used)

zettcode_commands-0.4.2.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.5
+Name: zettcode-commands
+Version: 0.4.2
+Summary: The slash commands that act on ZettCode's terminal application, offered to it as a plugin
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: commands,terminal,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-app
+Requires-Dist: zettcode-engine
+Requires-Dist: zettcode-plugin-api
+Requires-Dist: zettcode-presenters
+Requires-Dist: zettcode-sdk
+Requires-Dist: zettcode-tui

zettcode_commands-0.4.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+zettcode/commands/__init__.py,sha256=8s-idpD7K8ar5mfvXqYXPGd2012ZKbTabVM7v-jQXik,113
+zettcode/commands/context.py,sha256=TP7uue6cmbXbTFd29gL4y83-eKYWX7Vsv78_aXmkxsc,4024
+zettcode/commands/context_charts.py,sha256=n6NjNOXIkuSfN-8t_qQkfyiKQ1LE-EfmGy1HuhcqVuw,13127
+zettcode/commands/context_page.py,sha256=zBWpZSbMetgj1rJvMmG3D3XQu-3eqgzXupt15QEyShg,19306
+zettcode/commands/handlers.py,sha256=1PTpkQCr3NrEwqtgrbELcNmDuR5bY2ctYfH7x7ssICY,31737
+zettcode/commands/hub.py,sha256=nDOYwgeih9FCbq7QI2BmjP3dt6n4HMUVP6PXwRymLEs,52567
+zettcode/commands/hub_graph.py,sha256=QQ9D5X12WaEJWQc7iU_deer8Pr9MGgerJsgR7a5oLGY,30889
+zettcode/commands/plugin.py,sha256=MsN7v_xsfQZMvYZWCbVQKjxkj9QouD2lRi8s8OQcL7g,1801
+zettcode/commands/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zettcode/commands/usage.py,sha256=NTSPUDc_-JBayqQiirOlC7Zvq3DhPgXgOXopfPazdNc,2004
+zettcode/commands/usage_page.py,sha256=BbJepFlJhlR6PhlYS3Af5cGsoAu8EhJrwbnuIuHZefs,13020
+zettcode_commands-0.4.2.dist-info/METADATA,sha256=Fmx1za6dA0-5prHTDG88ejBoXZe2giNGBVrekHL5vVY,907
+zettcode_commands-0.4.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+zettcode_commands-0.4.2.dist-info/entry_points.txt,sha256=sNgTapffS02eE0nLmeKamISYGIy5GmD5rb1QBspKiNo,168
+zettcode_commands-0.4.2.dist-info/RECORD,,

zettcode_commands-0.4.2.dist-info/WHEEL

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

zettcode_commands-0.4.2.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[zettcode.plugin]
+commands = zettcode.commands.plugin:CommandsPlugin
+context = zettcode.commands.context:ContextPagePlugin
+usage = zettcode.commands.usage:UsageCommand