python-xli 0.2.0__py3-none-any.whl

xli/images.py

@@ -0,0 +1,90 @@
+"""Terminal image protocols — kitty / iTerm2 escapes, with a half-block fallback.
+
+Why this is simpler here than in a full-screen TUI: xli commits images to the normal
+scrollback (printed once), so we don't re-emit them every frame or juggle reserved rows
+in a redraw loop — we print the escape once and the terminal scrolls it like any output.
+
+Protocol detection is **env-only** (no terminal queries) so it can't interfere with the
+running prompt_toolkit app's input loop. Override with ``XLI_IMAGE_PROTOCOL`` =
+``kitty`` | ``iterm`` | ``halfblock``. Terminals without a graphics protocol (e.g. Windows
+Terminal) use the half-block renderer in :class:`xli.cells.ImageCell`, which is just text.
+
+kitty/iTerm output is best-effort and verified on capable terminals; the half-block path
+is the safe default everywhere.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import os
+
+# Approximate character-cell aspect (height / width). Used to pick a row count that
+# keeps the image from looking stretched.
+_CELL_ASPECT = 2.0
+_KITTY_CHUNK = 4096
+
+_protocol: str | None = None
+
+
+def detect_protocol() -> str:
+    """Best-effort env-based detection: 'kitty' | 'iterm' | 'halfblock'."""
+    term = os.environ.get("TERM", "")
+    if os.environ.get("KITTY_WINDOW_ID") or term == "xterm-kitty" or "ghostty" in term:
+        return "kitty"
+    if os.environ.get("TERM_PROGRAM", "") in ("iTerm.app", "WezTerm"):
+        return "iterm"
+    return "halfblock"
+
+
+def protocol() -> str:
+    """The active protocol (cached). ``XLI_IMAGE_PROTOCOL`` overrides detection."""
+    global _protocol
+    if _protocol is None:
+        _protocol = os.environ.get("XLI_IMAGE_PROTOCOL") or detect_protocol()
+    return _protocol
+
+
+def target_rows(width_px: int, height_px: int, cols: int) -> int:
+    return max(1, round(cols * (height_px / max(1, width_px)) / _CELL_ASPECT))
+
+
+def _png_b64(img) -> str:
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    return base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+def iterm_escape(img, cols: int, rows: int) -> str:
+    """iTerm2 inline image (OSC 1337). The image occupies the given cell box and the
+    terminal advances the cursor past it."""
+    data = _png_b64(img)
+    return (f"\033]1337;File=inline=1;width={cols};height={rows};"
+            f"preserveAspectRatio=1:{data}\a")
+
+
+def kitty_escape(img, cols: int, rows: int) -> str:
+    """kitty graphics protocol: transmit-and-display a PNG (f=100), scaled into a
+    ``cols``×``rows`` cell area, chunked at 4096 bytes per the spec."""
+    data = _png_b64(img)
+    chunks = [data[i:i + _KITTY_CHUNK] for i in range(0, len(data), _KITTY_CHUNK)] or [""]
+    out = []
+    for i, chunk in enumerate(chunks):
+        more = 1 if i < len(chunks) - 1 else 0
+        if i == 0:
+            ctrl = f"a=T,f=100,c={cols},r={rows},m={more}"
+        else:
+            ctrl = f"m={more}"
+        out.append(f"\033_G{ctrl};{chunk}\033\\")
+    return "".join(out)
+
+
+def graphics_escape(img, cols: int) -> str | None:
+    """Return the escape string for the active graphics protocol, or None for half-block."""
+    proto = protocol()
+    rows = target_rows(img.size[0], img.size[1], cols)
+    if proto == "iterm":
+        return iterm_escape(img, cols, rows)
+    if proto == "kitty":
+        return kitty_escape(img, cols, rows)
+    return None

xli/pets.py

@@ -0,0 +1,27 @@
+"""Ambient pets — a tiny animated companion in the status line's bottom-right.
+
+Opt-in (``xli.UI(pet="cat")``). Each pet is a list of one-line frames the engine cycles
+slowly; the animation is purely decorative and respects the light aesthetic (muted, no
+chrome). Pass a custom list of frames for your own creature.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+PETS: dict[str, list[str]] = {
+    # mostly-open frames with an occasional blink/wiggle so it idles gently
+    "cat": ["(=^･ω･^=)", "(=^･ω･^=)", "(=^･ω･^=)", "(=˘ω˘=)"],
+    "dog": ["( •ᴥ• )", "( •ᴥ• )", "( •ᴥ• )", "( ◕ᴥ◕ )"],
+    "fox": ["(^≖ᆺ≖^)", "(^≖ᆺ≖^)", "(^-ᆺ-^)"],
+    "owl": ["{ʘᴥʘ}", "{ʘᴥʘ}", "{-ᴥ-}"],
+}
+
+
+def frames(pet: str | Sequence[str] | None) -> list[str] | None:
+    """Resolve a pet name or explicit frame list to frames (None disables)."""
+    if pet is None:
+        return None
+    if isinstance(pet, str):
+        return PETS.get(pet, PETS["cat"])
+    return list(pet)

xli/render/__init__.py

@@ -0,0 +1,21 @@
+"""Renderers — pure functions from data → Rich renderables.
+
+Each module returns a ``rich.console.RenderableType``. The :class:`xli.UI`
+prints these into the transcript. They're pure so they can be tested
+without a terminal and reused outside the UI loop.
+"""
+
+from .diff import render_diff
+from .message import render_message, render_streaming_message
+from .plan import render_plan
+from .reasoning import render_reasoning
+from .tool import render_tool
+
+__all__ = [
+    "render_diff",
+    "render_message",
+    "render_plan",
+    "render_reasoning",
+    "render_streaming_message",
+    "render_tool",
+]

xli/render/diff.py

@@ -0,0 +1,37 @@
+"""Render unified diffs with sane colors and an optional path header."""
+
+from __future__ import annotations
+
+from rich.console import Group, RenderableType
+from rich.text import Text
+
+from ..theme import Theme
+
+
+def render_diff(
+    diff: str,
+    *,
+    path: str | None = None,
+    theme: Theme,
+) -> RenderableType:
+    """Colorize a unified-diff string. Path header is muted+bold above the diff."""
+
+    body = Text(no_wrap=False)
+    for i, line in enumerate(diff.splitlines()):
+        if i > 0:
+            body.append("\n")
+        if line.startswith("+++") or line.startswith("---"):
+            body.append(line, style="bold")
+        elif line.startswith("@@"):
+            body.append(line, style=theme.diff_hunk_color)
+        elif line.startswith("+"):
+            body.append(line, style=theme.diff_add_color)
+        elif line.startswith("-"):
+            body.append(line, style=theme.diff_del_color)
+        else:
+            body.append(line)
+
+    if path is None:
+        return body
+    header = Text(f"diff  {path}", style=f"bold {theme.muted_color}")
+    return Group(header, body)

xli/render/message.py

@@ -0,0 +1,115 @@
+"""Render user / assistant / system messages.
+
+Each message is a small Rich renderable group: an optional role label
+followed by the body. The body is markdown for assistant messages, plain
+for user/system. Borders / left-rails are governed by the theme.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from rich import box as _box
+from rich.console import Group, RenderableType
+from rich.markdown import Markdown
+from rich.padding import Padding
+from rich.panel import Panel
+from rich.text import Text
+
+from ..theme import Theme
+
+Role = Literal["user", "assistant", "system"]
+
+
+def _box_for(name: str):
+    """Map a theme box name (e.g. 'rounded') to a rich Box, defaulting to ROUNDED."""
+    return getattr(_box, name.upper(), _box.ROUNDED)
+
+
+def render_message(
+    text: str,
+    *,
+    role: Role,
+    theme: Theme,
+    markdown: bool | None = None,
+    label: bool = True,
+) -> RenderableType:
+    """Static message render (the streaming case sees ``render_streaming_message``).
+
+    ``label=False`` suppresses the role label — used for streamed continuation chunks
+    that commit under an already-labelled first chunk (so the label isn't repeated).
+    """
+
+    # System messages are compact by design: ``· text`` on as few lines as
+    # possible. They're meta-info, not part of the conversation flow.
+    if role == "system":
+        return _render_system(text, theme=theme)
+
+    use_md = markdown if markdown is not None else (role == "assistant")
+    body: RenderableType
+    if use_md and text.strip():
+        body = Markdown(
+            text,
+            code_theme=theme.code_theme,
+            inline_code_theme=theme.code_theme,
+        )
+    else:
+        body = Text(text or "", no_wrap=False)
+
+    if theme.use_borders:
+        return Panel(
+            body,
+            title=_role_label_text(role, theme) if label else None,
+            title_align="left",
+            border_style=_role_color(role, theme),
+            box=_box_for(theme.panel_border),
+        )
+
+    parts: list[RenderableType] = []
+    if label and theme.show_role_labels:
+        parts.append(_role_label_text(role, theme))
+    parts.append(Padding(body, (0, 0, 0, 2)))
+    return Group(*parts)
+
+
+def _render_system(text: str, *, theme: Theme) -> RenderableType:
+    """``· first line``, additional lines indented to align with the body."""
+
+    lines = (text or "").splitlines() or [""]
+    out = Text()
+    for i, line in enumerate(lines):
+        if i > 0:
+            out.append("\n")
+        if i == 0:
+            out.append("· ", style=theme.muted_color)
+        else:
+            out.append("  ")
+        out.append(line, style=theme.muted_color)
+    return out
+
+
+def render_streaming_message(
+    text: str, *, role: Role, theme: Theme, markdown: bool | None = None
+) -> RenderableType:
+    """Renderable suitable for repeated update inside Rich's ``Live`` context.
+
+    Same shape as :func:`render_message` but tolerant of partial markdown
+    (we don't try to "complete" it — Rich handles partial blocks fine).
+    """
+    return render_message(text or " ", role=role, theme=theme, markdown=markdown)
+
+
+def _role_label_text(role: Role, theme: Theme) -> Text:
+    if role == "user":
+        return Text(theme.user_label, style=f"bold {theme.user_color}")
+    if role == "assistant":
+        return Text(theme.assistant_label, style=f"bold {theme.assistant_color}")
+    return Text(theme.system_label, style=f"bold {theme.system_color}")
+
+
+def _role_color(role: Role, theme: Theme) -> str:
+    if role == "user":
+        return theme.user_color
+    if role == "assistant":
+        return theme.assistant_color
+    return theme.system_color

xli/render/plan.py

@@ -0,0 +1,70 @@
+"""Render a plan: list of (title, status) steps as a checklist.
+
+Status values: ``"pending"`` (default), ``"in_progress"``, ``"completed"``.
+Anything else is treated as ``"pending"`` (forward-compat).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from rich.console import RenderableType
+from rich.text import Text
+
+from ..theme import Theme
+
+
+def render_plan(
+    steps: Iterable[Any],
+    *,
+    theme: Theme,
+    title: str | None = None,
+) -> RenderableType:
+    out = Text()
+    if title:
+        out.append(title, style=f"bold {theme.plan_color}")
+        out.append("\n")
+    rows = list(_iter_steps(steps))
+    for i, (step_title, status, notes) in enumerate(rows):
+        glyph = _glyph(status, theme)
+        out.append(f"  {glyph}  ", style=theme.plan_color)
+        out.append(step_title)
+        if notes:
+            out.append(f"   ({notes})", style=theme.muted_color)
+        if i != len(rows) - 1:
+            out.append("\n")
+    return out
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+
+def _glyph(status: str, theme: Theme) -> str:
+    if status == "completed":
+        return theme.plan_completed_glyph
+    if status == "in_progress":
+        return theme.plan_in_progress_glyph
+    return theme.plan_pending_glyph
+
+
+def _iter_steps(steps: Iterable[Any]) -> Iterable[tuple[str, str, str | None]]:
+    """Accept any of: dicts, dataclasses, (title, status[, notes]) tuples, bare strings."""
+    for s in steps:
+        if isinstance(s, dict):
+            yield (str(s.get("title", "")), str(s.get("status", "pending")), s.get("notes"))
+        elif isinstance(s, str):
+            yield (s, "pending", None)
+        elif isinstance(s, tuple):
+            if len(s) == 2:
+                yield (str(s[0]), str(s[1]), None)
+            else:
+                yield (str(s[0]), str(s[1]), str(s[2]) if s[2] else None)
+        else:
+            yield (
+                str(getattr(s, "title", s)),
+                str(getattr(s, "status", "pending")),
+                getattr(s, "notes", None),
+            )

xli/render/reasoning.py

@@ -0,0 +1,20 @@
+"""Render reasoning summaries — muted, lightly-railed."""
+
+from __future__ import annotations
+
+from rich.console import RenderableType
+from rich.text import Text
+
+from ..theme import Theme
+
+
+def render_reasoning(summary: str, *, theme: Theme) -> RenderableType:
+    text = Text()
+    rail = theme.reasoning_glyph
+    style = theme.reasoning_color
+    for i, line in enumerate(summary.strip().splitlines() or [""]):
+        if i > 0:
+            text.append("\n")
+        text.append(f"{rail} ", style=style)
+        text.append(line, style=style)
+    return text

xli/render/tool.py

@@ -0,0 +1,128 @@
+"""Render tool calls.
+
+Each tool call is a compact card:
+
+    ▸ shell  ls -la
+      total 48
+      drwxr-xr-x 8 ...
+
+Title line uses the tool glyph + name + a short summary; the output is
+indented. When output is missing or empty, just the title shows.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from rich.console import Group, RenderableType
+from rich.padding import Padding
+from rich.text import Text
+
+from ..theme import Theme
+
+_MAX_TITLE_DETAIL = 100
+_MAX_OUTPUT_INLINE = 8000
+
+
+def render_tool(
+    name: str,
+    *,
+    args: dict[str, Any] | None = None,
+    output: Any = None,
+    error: str | None = None,
+    status: str | None = None,
+    theme: Theme,
+) -> RenderableType:
+    args = args or {}
+    title = _title_for(name, args, theme=theme, errored=error is not None, status=status)
+    if output is None and error is None:
+        return title
+    body_text = _body_for(output, error)
+    if not body_text:
+        return title
+    body = Padding(
+        Text(body_text, style=theme.muted_color, no_wrap=False),
+        (0, 0, 0, theme.tool_output_indent),
+    )
+    return Group(title, body)
+
+
+def _title_for(
+    name: str, args: dict[str, Any], *, theme: Theme, errored: bool, status: str | None = None
+) -> Text:
+    # Status drives the gutter glyph + accent so a card reads at a glance as it
+    # moves running -> done. When no status is given we keep the plain tool glyph
+    # (back-compat with one-shot ``ui.tool(...)`` cards).
+    if errored or status == "error":
+        color, glyph = theme.error_color, theme.tool_error_glyph
+    elif status == "cancelled":
+        color, glyph = theme.error_color, theme.tool_cancelled_glyph
+    elif status == "done":
+        color, glyph = theme.success_color, theme.tool_done_glyph
+    else:  # running / None
+        color, glyph = theme.tool_color, theme.tool_glyph
+    summary = _summary_for(name, args)
+    title = Text()
+    title.append(f"{glyph} ", style=color)
+    title.append(name, style=f"bold {color}")
+    if summary:
+        title.append("  ")
+        title.append(summary, style=theme.muted_color)
+    return title
+
+
+def _summary_for(name: str, args: dict[str, Any]) -> str:
+    if name == "shell":
+        return _truncate(" ".join(args.get("command", []) or args.get("argv", [])), _MAX_TITLE_DETAIL)
+    if name == "apply_patch":
+        patch = args.get("patch", "")
+        n = (
+            patch.count("*** Add File:")
+            + patch.count("*** Update File:")
+            + patch.count("*** Delete File:")
+        ) or 1
+        return f"({n} change{'s' if n != 1 else ''})"
+    if name == "view_image":
+        return str(args.get("path", ""))
+    if name == "save_artifact":
+        return str(args.get("path", ""))
+    if name == "read_artifact":
+        return str(args.get("path", ""))
+    if name == "web_search":
+        return str(args.get("query", ""))
+    if name == "update_plan":
+        steps = args.get("steps") or []
+        return f"({len(steps)} step{'s' if len(steps) != 1 else ''})"
+    if name == "remember":
+        return _truncate(str(args.get("content", "")), _MAX_TITLE_DETAIL)
+    if name == "task":
+        sub = args.get("subagent_type", "")
+        desc = args.get("description", "")
+        return _truncate(f"[{sub}] {desc}".strip(), _MAX_TITLE_DETAIL) if (sub or desc) else ""
+    # generic fallback
+    if args:
+        return _truncate(json.dumps(args, default=str, separators=(",", ":")), _MAX_TITLE_DETAIL)
+    return ""
+
+
+def _body_for(output: Any, error: str | None) -> str:
+    if error:
+        return f"error: {error}"
+    if output is None:
+        return ""
+    if isinstance(output, str):
+        return _truncate(output, _MAX_OUTPUT_INLINE)
+    if isinstance(output, (bytes, bytearray)):
+        return f"<{len(output)} bytes>"
+    try:
+        return _truncate(json.dumps(output, default=str, indent=2), _MAX_OUTPUT_INLINE)
+    except Exception:  # pragma: no cover
+        return _truncate(repr(output), _MAX_OUTPUT_INLINE)
+
+
+def _truncate(text: str, limit: int) -> str:
+    text = str(text)
+    if len(text) <= limit:
+        return text
+    return text[: limit - 1] + "…"

xli/render_bridge.py

@@ -0,0 +1,36 @@
+"""The render bridge — Rich renderables → ANSI lines for the prompt_toolkit engine.
+
+The engine draws its live region (and commits to scrollback) as plain ANSI text.
+Rich does all the actual rendering — markdown, syntax highlighting, tables, diffs,
+half-block images — and this module turns a renderable into a list of ANSI strings
+at a given width. prompt_toolkit then displays each line via ``ANSI(...)``.
+
+Kept tiny and pure so it's trivially testable and cache-friendly.
+"""
+
+from __future__ import annotations
+
+import io
+
+from rich.console import Console, RenderableType
+
+
+def render_to_ansi(renderable: RenderableType, width: int) -> list[str]:
+    """Render ``renderable`` to a list of ANSI lines at ``width`` columns.
+
+    Truecolor is forced (degrade is the terminal's job via its own palette); a
+    trailing empty line from Rich's newline is stripped so callers control spacing.
+    """
+    buf = io.StringIO()
+    Console(
+        file=buf,
+        width=max(1, width),
+        force_terminal=True,
+        color_system="truecolor",
+        highlight=False,
+        soft_wrap=False,
+    ).print(renderable, end="")
+    lines = buf.getvalue().split("\n")
+    if lines and lines[-1] == "":
+        lines.pop()
+    return lines