zettcode-presenters 0.4.0__py3-none-any.whl

zettcode/presenters/pulse.py

@@ -0,0 +1,116 @@
+"""How the waiting row and the status bar's icon move: the pulse, the sweep, and the blink.
+
+Everything here is a function of one monotonic frame counter the application keeps, counted in animation
+steps rather than terminal ticks, so the pace of the sweep and of the running marker does not depend on how
+often the terminal happens to repaint: a period is a number of seconds, and a step is a share of it.
+"""
+
+from __future__ import annotations
+
+from zettcode.tui import RUNNING
+
+#: Animation steps per second: the rate the sweep, the running marker and the
+#: timers advance at, matching the frame loop's own ceiling. It used to be ten a
+#: second, which is a step the eye can see — the sweep moved in jumps — while the
+#: loop was repainting a hundred and twenty times a second to show the same
+#: picture twelve times over.
+ANIMATION_FPS = 120
+
+#: Wall-clock length of one animation step. ``Transcript.frame`` counts these
+#: steps rather than terminal ticks, so the pace of the sweep and the running
+#: marker does not depend on how often the terminal happens to repaint: a period
+#: is a number of seconds, and a step is a share of it.
+ANIMATION_SECONDS = 1 / ANIMATION_FPS
+
+#: The running marker's two states: the sparkle, then a dot of the same width so
+#: the label after it never shifts as the row pulses.
+RUNNING_GLYPHS = RUNNING
+
+#: Seconds one pulse of the waiting row takes: it moves for a second, then rests
+#: for a second before it moves again. The marker and the highlight share the
+#: period, so the row reads as one thing breathing instead of two effects on
+#: clocks of their own. The rest is deliberate: a row that never stops reads as
+#: busy-work, and the pause is what makes the sweep look like an event.
+MOVE_SECONDS = 1.0
+REST_SECONDS = 1.0
+
+#: Share of a pulse spent moving, and the frames one takes, counted in animation
+#: steps: the pace is a period rather than a speed, so a long wait row is crossed
+#: in the same time as a short one and the pulse does not depend on how often the
+#: terminal happens to repaint. The share is what the demo's pace keys scale, so
+#: changing the period keeps the two phases in proportion.
+MOVE_SHARE = MOVE_SECONDS / (MOVE_SECONDS + REST_SECONDS)
+PULSE_FRAMES = round((MOVE_SECONDS + REST_SECONDS) / ANIMATION_SECONDS)
+
+#: Seconds one blink of the status bar's icon takes. The icon is a small thing on
+#: a line of its own, so it turns over on a period of its own — no rest to sit
+#: through, unlike the waiting row it reports on.
+STATUS_BLINK_SECONDS = 1.5
+STATUS_BLINK_FRAMES = round(STATUS_BLINK_SECONDS / ANIMATION_SECONDS)
+
+
+def move_frames() -> int:
+    """Return the frames of one pulse the waiting row spends moving."""
+    return max(1, round(PULSE_FRAMES * MOVE_SHARE))
+
+
+def moving(frame: int) -> bool:
+    """Say whether the waiting row is in the moving part of its pulse."""
+    return frame % PULSE_FRAMES < move_frames()
+
+
+def sweep_column(frame: int, travel: int) -> int:
+    """Return the column the highlight has reached at one animation frame.
+
+    One pass takes the moving part of the pulse, so the highlight arrives at the
+    end of the label as the row rests and sets off again when it moves.
+
+    Args:
+        frame: Monotonic frame counter shared by the whole application.
+        travel: Columns one whole pass takes, ends included —
+            :attr:`~zettcode.tui.render.sweep.SweepSpan.travel`.
+    """
+    return frame % PULSE_FRAMES * max(1, travel) // move_frames()
+
+
+#: Columns of fade on each side of the waiting row's highlight. The presenter draws with it and
+#: :func:`wait_picture` counts with it, so the two cannot disagree about how far a pass travels.
+WAIT_RAMP = 3
+
+
+def wait_picture(frame: int, title_width: int) -> tuple[bool, int]:
+    """Return what the waiting row looks like at one frame, as a value.
+
+    Two frames give equal values exactly when the row is drawn the same way at both: the
+    highlight sits on a whole column, and its colours depend on nothing else, so this is
+    that column (``0`` while the row rests, which is drawn flat whatever the frame is).
+    The loop uses it to tell a frame that changes the screen from one that only repeats it.
+
+    Args:
+        frame: Monotonic frame counter shared by the whole application.
+        title_width: Display width of the word the highlight crosses.
+    """
+    if not moving(frame):
+        return (False, 0)
+    return (True, sweep_column(frame, title_width + 2 * WAIT_RAMP))
+
+
+def blink_state(frame: int) -> bool:
+    """Say which of its two states the status bar's icon is in at one frame."""
+    return frame % STATUS_BLINK_FRAMES < STATUS_BLINK_FRAMES // 2
+
+
+def activity_glyph(frame: int) -> str:
+    """Return the marker the status bar shows while work is in progress.
+
+    The marker keeps one column and holds each of its two states instead of
+    cycling through different symbols, which is what makes it read as an icon
+    rather than as a spinner. It alternates on a period of its own, with no rest
+    between blinks, because a small icon can turn over faster than the row it
+    reports on; both read the same frame counter, so neither depends on how often
+    the terminal repaints.
+
+    Args:
+        frame: Monotonic frame counter shared by the whole application.
+    """
+    return RUNNING_GLYPHS[0 if blink_state(frame) else 1]

zettcode/presenters/text.py

@@ -0,0 +1,304 @@
+"""The words and bounds of a transcript row: its margin, its labels, how long output is allowed to be.
+
+What a row says and how much of it is kept live here rather than with the conversation model: the left margin,
+the bounding of tool output, the text of an elapsed time, the wording of the waiting row's remarks, and the
+path the header shortens. The model imports these to build entries and the renderer imports them to paint, and
+this module imports neither — which is what keeps the two apart. How a row *moves* is :mod:`.pulse`, and the
+two animations of the effort setting are :mod:`.effort_gauge` and :mod:`.shimmer`.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from zettcode.tui import ELLIPSIS
+from zettcode.tui.glyphs import ARROW_DOWN, ARROW_UP, SEPARATOR
+from zettcode.tui.render import count_wrapped_rows, display_width, truncate, wrap_columns
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only; the wording reads figures, it does not need the SDK
+    from zettcode.sdk.types import Usage
+
+#: Left margin of every transcript row: the width of the composer's ``\u203a ``
+#: prompt, so text lines up under what the user types and never starts left of
+#: the caret in an empty composer.
+
+#: Label of the row that shows a reasoning span while it streams.
+
+#: Label of the row that shows the summarizer working: the same kind of row, so
+#: it carries the same marker and timer as reasoning does.
+COMPACTING_LABEL = "Compacting"
+
+MAX_TOOL_OUTPUT = 64_000
+TOOL_PREVIEW_ROWS = 5
+TOOL_EXPANDED_ROWS = 40
+
+#: Label of a row shown while the model is working and has not answered yet.
+#: One request can show it more than once: every tool batch is followed by
+#: another model call, and until that call produces something there is nothing
+#: else on screen to say work is still going on.
+PROCESSING = "Processing"
+
+#: What the reader can press to stop the request, shown beside its clock. The
+#: status row builds its own hint from this, so the two cannot drift apart, and
+#: both keys are named because both work: Escape stops a turn while one is in
+#: flight, and a reader should not have to remember which of the two the shell
+#: reserved for it.
+STOP_HINT = "^C/Esc to interrupt"
+
+#: What the row of a question the reader cancelled says under its title.
+DECLINED_NOTE = "You declined; the model was told and carries on."
+
+# Matches both escape families a tool can smuggle into its output: CSI
+# (``ESC [`` parameters and a final byte) and OSC (``ESC ]`` up to BEL or ST).
+# Stripping them keeps a coloured compiler message from repainting the canvas.
+_ANSI = re.compile(r"\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\))")
+
+
+def terminal_safe(value: str) -> str:
+    """Strip escape sequences and replace characters the canvas cannot paint.
+
+    Args:
+        value: Raw tool output; newlines survive, a tab advances to the next
+            four-column stop, and anything else non-printable becomes the
+            replacement character so a tool cannot smuggle control codes into
+            the canvas.
+
+    Line endings are normalised first. Output printed with CRLF — a tool that
+    shells out to ``curl -i`` or to a Windows program — would otherwise leave a
+    replacement glyph at the end of every line, because a carriage return stops
+    being a line break the moment it is replaced.
+    """
+    cleaned = _ANSI.sub("", value).replace("\r\n", "\n").replace("\r", "\n").expandtabs(4)
+    if cleaned.replace("\n", "").isprintable():
+        # Nothing to replace, which is the usual output: say so in one pass instead
+        # of looking at every character of what may be tens of kilobytes.
+        return cleaned
+    return "".join(
+        character if character in "\n" else character if character.isprintable() else "\ufffd" for character in cleaned
+    )
+
+
+def bounded_rows(value: str, width: int, limit: int) -> tuple[list[str], int]:
+    """Wrap tool output and return a bounded viewport plus omitted rows.
+
+    Args:
+        value: Raw tool output.
+        width: Wrap width in cells.
+        limit: Most rows to return; the remainder is reported as omitted.
+    """
+    rows: list[str] = []
+    hidden = 0
+    for source in terminal_safe(value).splitlines() or [""]:
+        if len(rows) < limit:
+            rows.extend(wrap_columns(source, width))
+        else:
+            # Past the rows that are shown only the count is wanted, and counting
+            # a line's rows does not need the rows: a 900-line test log is wrapped
+            # for five of them.
+            hidden += count_wrapped_rows(source, width)
+    omitted = max(0, len(rows) - limit) + hidden
+    return rows[:limit], omitted
+
+
+def limit_output(value: str) -> str:
+    """Bound stored tool output while keeping both ends useful.
+
+    Args:
+        value: Raw tool output; anything past ``MAX_TOOL_OUTPUT`` keeps its head
+            and tail with a marker in between, so a huge result cannot dominate
+            memory while still showing how it started and ended.
+    """
+    if len(value) <= MAX_TOOL_OUTPUT:
+        return value
+    half = MAX_TOOL_OUTPUT // 2
+    omitted = len(value) - half * 2
+    return f"{value[:half]}\n{ELLIPSIS} {omitted:,} characters omitted {ELLIPSIS}\n{value[-half:]}"
+
+
+def duration_text(seconds: float | None) -> str:
+    """Format an elapsed time for a row header, in the unit a reader wants.
+
+    Args:
+        seconds: Elapsed time, or ``None`` for a row that has already finished
+            without a recorded duration.
+
+    Under a minute the time is shown to the tenth of a second, because that is
+    what makes a live row look alive and milliseconds would change the column's
+    width on every repaint. Past a minute the tenth is noise — ``134.5 s`` is a
+    number a reader has to divide before it means anything — so the row switches
+    to minutes and seconds, and to hours and minutes past an hour. That column
+    changes width as the units change: it narrows at each boundary — ``1m 0s``
+    is a column narrower than ``59.9 s``, ``1h 0m`` two narrower than
+    ``59m 59s`` — and widens as the count climbs inside one, so a running tool
+    row's title is truncated again whenever it does. A whole request's wall time
+    is a different question, so it goes through :func:`elapsed_text` instead.
+    """
+    if seconds is None:
+        return "done"
+    total = max(0.0, seconds)
+    if round(total, 1) < 60:
+        return f"{total:.1f} s"
+    minutes, remainder = divmod(round(total), 60)
+    if minutes < 60:
+        return f"{minutes}m {remainder}s"
+    hours, minutes = divmod(minutes, 60)
+    return f"{hours}h {minutes}m"
+
+
+#: Seconds the model may say nothing before the waiting row says so. A first token after ten seconds is a
+#: slow model and after twenty is something a reader is already wondering about; a reasoning model that
+#: streams nothing for longer is also why this only *says* it and never gives up on the request.
+QUIET_SECONDS = 20.0
+
+
+#: Seconds a request has to run before a tip is put under its waiting row: one that is answered at once is not
+#: worth a line, and a tip that flashes by is not read.
+#: Whole seconds, like :data:`TIP_EVERY`: the waiting row's clock counts whole seconds and the picture the loop compares
+#: holds that count, so a tip appears and changes on a second the loop already draws.
+TIP_AFTER = 5.0
+
+#: Seconds each tip stays before the next takes its place, long enough to read and not so long that a request of
+#: several minutes shows one.
+TIP_EVERY = 15.0
+
+
+def tip_text(tips: tuple[str, ...], seconds: float | None) -> str | None:
+    """Return the tip a request that has run for ``seconds`` shows, or ``None`` while it is too soon or there are none."""
+    if not tips or seconds is None or seconds < TIP_AFTER:
+        return None
+    return tips[int((seconds - TIP_AFTER) // TIP_EVERY) % len(tips)]
+
+
+def quiet_text(seconds: float) -> str | None:
+    """Return what the waiting row says about a silence of ``seconds``, or ``None`` while it is too short to mention."""
+    if seconds < QUIET_SECONDS:
+        return None
+    return f"nothing from the model for {elapsed_text(seconds)}"
+
+
+def elapsed_text(seconds: float) -> str:
+    """Show every nonzero time unit in a finished request's wall time.
+
+    Args:
+        seconds: Wall time of the request, negative values clamped to zero.
+    """
+    total = max(0, round(seconds))
+    hours, remainder = divmod(total, 3600)
+    minutes, seconds = divmod(remainder, 60)
+    if hours:
+        return f"{hours}h {minutes}m {seconds}s"
+    if minutes:
+        return f"{minutes}m {seconds}s"
+    return f"{seconds}s"
+
+
+def clock_text(moment: datetime | None = None) -> str:
+    """Format a wall-clock reading as local ``HH:MM``.
+
+    Args:
+        moment: Time to show; ``None`` reads the clock, and tests inject a value
+            so a rendered footer stays deterministic.
+    """
+    return (moment or datetime.now()).strftime("%H:%M")
+
+
+def pack_segments(segments: list[str], room: int) -> list[str]:
+    """Join segments with `` · `` into rows no wider than ``room``, breaking between segments and never inside one.
+
+    A single segment wider than the room gets a row of its own and is cut to fit, so no row is ever too wide.
+    """
+    joint = f" {SEPARATOR} "
+    rows: list[str] = []
+    current = ""
+    for segment in segments:
+        if current and display_width(current) + display_width(joint) + display_width(segment) <= room:
+            current += joint + segment
+            continue
+        if current:
+            rows.append(current)
+        current = segment
+    if current:
+        rows.append(current)
+    return [row if display_width(row) <= room else truncate(row, room, ellipsis=ELLIPSIS) for row in rows]
+
+
+def tokens_text(usage: Usage) -> str | None:
+    """Say the tokens a request sent and received, or nothing before the model has answered."""
+    if not usage.requests:
+        return None
+    return f"{ARROW_UP}{compact_tokens(usage.input_tokens)} {ARROW_DOWN}{compact_tokens(usage.output_tokens)}"
+
+
+def cache_text(usage: Usage) -> str | None:
+    """Say the share of the input the provider served from its cache, or nothing when it served none."""
+    if usage.requests and usage.cache_read_tokens > 0 and usage.input_tokens > 0:
+        return f"{usage.cache_read_tokens / usage.input_tokens * 100:.1f}% cached"
+    return None
+
+
+def calls_text(usage: Usage) -> str | None:
+    """Say how many times the model was asked, when it was asked more than once."""
+    return f"{usage.requests} model calls" if usage.requests > 1 else None
+
+
+def speed_text(usage: Usage) -> str | None:
+    """Say how fast the model generated, when it can be told and is at least one token a second.
+
+    Reads :attr:`Usage.output_rate` — the provider's whole count over the time from the first token to the end of the
+    reply — so this line and the status line a reader sees above it never disagree.
+    """
+    rate = usage.output_rate
+    if usage.requests and rate is not None and rate >= 1:
+        return f"{rate:.1f} tok/s" if rate < 10 else f"{rate:.0f} tok/s"
+    return None
+
+
+def tools_text(tools: int, failed_tools: int = 0) -> str | None:
+    """Say how many tool calls a request made and how many failed; the failures stay in the same segment."""
+    if not tools:
+        return None
+    said = f"{tools} tool call{'' if tools == 1 else 's'}"
+    return f"{said}, {failed_tools} failed" if failed_tools else said
+
+
+def compact_path(path: Path, *, limit: int | None = 38) -> str:
+    """Shorten a workspace path for the header.
+
+    Args:
+        path: Absolute path to display.
+        limit: Most columns to keep; the home directory collapses to ``~``, and
+            anything longer keeps a leading ellipsis plus its tail. ``None``
+            keeps the whole path and collapses only the home directory, for a
+            line that has the room to show it.
+    """
+    value = str(path)
+    home = str(Path.home())
+    if value == home or value.startswith(home + "/"):
+        value = "~" + value[len(home) :]
+    if limit is None:
+        return value
+    width = display_width(value)
+    if width <= limit:
+        return value
+    # Count the tail from the end so a wide glyph is dropped whole rather than
+    # overhanging the budget, which the ellipsis also has to fit inside.
+    budget = limit - 1
+    tail = ""
+    for character in reversed(value):
+        if display_width(character) > budget:
+            break
+        tail = character + tail
+        budget -= display_width(character)
+    return ELLIPSIS + tail
+
+
+def compact_tokens(count: int) -> str:
+    """Shorten a token count for the status line: ``912``, ``12.3k``, ``1.2M``."""
+    if count < 1_000:
+        return str(count)
+    if count < 999_950:
+        return f"{count / 1_000:.1f}k"
+    return f"{count / 1_000_000:.1f}M"

zettcode_presenters-0.4.0.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.5
+Name: zettcode-presenters
+Version: 0.4.0
+Summary: The conversation's rows and how ZettCode's terminal draws them
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Author: Chang-LeHung
+License-Expression: MIT
+Keywords: presenters,transcript,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-plugin-api
+Requires-Dist: zettcode-tui
+Provides-Extra: types
+Requires-Dist: zettcode-sdk; extra == 'types'

zettcode_presenters-0.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+zettcode/presenters/__init__.py,sha256=CVzMjwmPMFoBmIyLwvOnrdsfJv9Gtpt4ONm83O_MMAY,1115
+zettcode/presenters/brand.py,sha256=Ebq97gOYCHXBWqTBii-iPmj0b53238WxRbjPtOWnol0,1256
+zettcode/presenters/plugin.py,sha256=2Z7hZwaqi0wWJGwMxej_TpC34BxJV_TZPVbjI2ZLf2I,1529
+zettcode/presenters/presenters.py,sha256=1bB832-GPi5MEtc-GISG3OSKBHnvqrIsgTIKv105XCw,35996
+zettcode/presenters/pulse.py,sha256=62HnCyaw3CEIC1TUaJ8RcuudNpYI-BAkdrWI2Rhe6Qg,5337
+zettcode/presenters/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+zettcode/presenters/text.py,sha256=vr2Vi5j2qxxGUgPITs2EIJFFiYgGAcjlhSDDSc7MRnY,12913
+zettcode_presenters-0.4.0.dist-info/METADATA,sha256=H3H6KBfTp92VGr60o9tun8nMfvA50F5PwgPoI05Ao1o,832
+zettcode_presenters-0.4.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+zettcode_presenters-0.4.0.dist-info/entry_points.txt,sha256=V-yGLKSy_I7OZRZpAdAO4NU2E8TCnMkgslI33U24hJE,77
+zettcode_presenters-0.4.0.dist-info/RECORD,,

zettcode_presenters-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

zettcode_presenters-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[zettcode.terminal]
+presenters = zettcode.presenters.plugin:PresentersPlugin