polyllmkit 0.1.0__py3-none-any.whl

llmkit/md/render/cli.py

@@ -0,0 +1,231 @@
+"""mdrender — render markdown from a file or stdin through rich to stdout.
+
+A standalone CLI over the same rich pipeline as the modal viewer
+(:mod:`llmkit.md.view`). Two roles:
+
+  1. Validation tool: see exactly how the rich pipeline renders a
+     markdown stream, headlessly, without any modal UI.
+  2. Drop-in formatter for a streaming producer — a single-process
+     replacement for mdansi / glow / mdcat with live re-render.
+
+Two modes:
+
+  --no-stream (default): consume all stdin, render once at EOF, emit
+                         to stdout. Best for piped one-shot use.
+  --stream             : re-render incrementally as stdin arrives
+                         (rich.live.Live + Markdown). Best for live
+                         use with a streaming producer such as the
+                         bridge. Re-render is debounced so frequent
+                         small chunks don't thrash the terminal.
+                         Note: Live repaints in place, so very long
+                         documents may overflow visible area — use
+                         bin/mdview (alt-screen + scroll) for
+                         documents larger than one screenful.
+
+Theming: ``--theme-file`` points at an INI theme (see themes/*.ini).
+Rich has no global theme config, so the file is loaded explicitly here
+and applied to this Console only. Without it, Rich's stock markdown
+styling is used.
+"""
+
+from __future__ import annotations
+
+import argparse
+import configparser
+import os
+import select
+import sys
+from typing import List, Optional, Tuple, cast
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.style import Style
+from rich.text import Text
+from rich.theme import Theme
+
+from .stream import LiveMarkdownStream, Mode
+
+# Rich's default Pygments style for fenced code blocks.
+_DEFAULT_CODE_THEME = "monokai"
+
+
+def _load_theme(path: Optional[str]) -> Tuple[Optional[Theme], str]:
+    """Load a markdown Theme + Pygments code-theme name from an INI file.
+
+    The INI has a ``[styles]`` section (Rich style names → style specs,
+    layered onto Rich's defaults via ``inherit=True``) and an optional
+    ``[code]`` section with ``theme = <pygments style>`` for fenced code
+    blocks. Returns ``(None, "monokai")`` — Rich's stock look — when
+    *path* is falsy or the file can't be read.
+    """
+    if not path:
+        return None, _DEFAULT_CODE_THEME
+    cfg = configparser.ConfigParser()
+    if not cfg.read(path):
+        return None, _DEFAULT_CODE_THEME
+    theme: Optional[Theme] = None
+    if cfg.has_section("styles"):
+        styles = {name: Style.parse(value) for name, value in cfg.items("styles")}
+        if styles:
+            theme = Theme(styles, inherit=True)
+    code_theme = cfg.get("code", "theme", fallback=_DEFAULT_CODE_THEME)
+    return theme, code_theme
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(
+        prog="mdrender",
+        description="Render markdown from a file or stdin through rich to stdout.",
+    )
+    p.add_argument(
+        "--render",
+        choices=["markdown", "raw"],
+        default="markdown",
+        help="Render mode (default: markdown). raw = ANSI passthrough.",
+    )
+    p.add_argument(
+        "--stream",
+        action="store_true",
+        help="Re-render incrementally as stdin arrives (uses rich.live). "
+        "Default: consume all stdin, render once at EOF.",
+    )
+    p.add_argument(
+        "--debounce",
+        type=float,
+        default=0.1,
+        help="Min seconds between re-renders in --stream mode (default 0.1).",
+    )
+    p.add_argument(
+        "--color",
+        choices=["always", "auto", "never"],
+        default="auto",
+        help="When to emit ANSI color (default: auto — colorized only "
+        "if stdout is a tty). Use 'always' when piping to a pager "
+        "or capturing to a file you'll view later.",
+    )
+    p.add_argument(
+        "--theme-file",
+        default=None,
+        help="Path to an INI theme file (see themes/*.ini). Without it, "
+        "Rich's default markdown styling is used.",
+    )
+    p.add_argument(
+        "--pager",
+        action="store_true",
+        help="Pipe output through $PAGER (or `less -R` if unset). "
+        "Implies --color always. Incompatible with --stream.",
+    )
+    p.add_argument(
+        "file",
+        nargs="?",
+        default=None,
+        help="Markdown source file. If omitted (or '-'), read from stdin.",
+    )
+    args = p.parse_args(argv)
+
+    if args.pager and args.stream:
+        print("mdrender: --pager and --stream are incompatible", file=sys.stderr)
+        return 2
+
+    theme, code_theme = _load_theme(args.theme_file)
+
+    # Color resolution. rich's Console respects:
+    #   force_terminal=True       — emit colors regardless of stdout tty
+    #   no_color=True             — strip colors regardless of tty
+    #   neither set               — auto-detect via isatty()
+    force_terminal: Optional[bool] = None
+    no_color: Optional[bool] = None
+    if args.color == "always" or args.pager:
+        force_terminal = True
+    elif args.color == "never":
+        no_color = True
+    console = Console(force_terminal=force_terminal, no_color=no_color, theme=theme)
+
+    # "-" is the conventional stdin sentinel; treat it like no file.
+    source: Optional[str] = args.file if args.file not in (None, "-") else None
+
+    try:
+        mode = cast(Mode, args.render)
+        if args.pager:
+            # console.pager(styles=True) spawns $PAGER (or `less -RFX`)
+            # and pipes our captured output through it on context exit.
+            # styles=True ensures ANSI is preserved through the pipe.
+            with console.pager(styles=True):
+                return _run_oneshot(console, mode, code_theme, source)
+        if args.stream:
+            return _run_stream(console, mode, args.debounce, theme, code_theme, source)
+        return _run_oneshot(console, mode, code_theme, source)
+    except KeyboardInterrupt:
+        return 130
+    except BrokenPipeError:
+        return 0
+    except OSError as e:
+        print(f"mdrender: {e}", file=sys.stderr)
+        return 1
+
+
+def _run_oneshot(
+    console: Console, mode: str, code_theme: str, source: Optional[str]
+) -> int:
+    if source is None:
+        text = sys.stdin.read()
+    else:
+        with open(source, encoding="utf-8", errors="replace") as f:
+            text = f.read()
+    if mode == "markdown":
+        console.print(Markdown(text, code_theme=code_theme))
+    else:
+        console.print(Text.from_ansi(text), end="")
+    return 0
+
+
+def _run_stream(
+    console: Console,
+    mode: Mode,
+    debounce: float,
+    theme: Optional[Theme],
+    code_theme: str,
+    source: Optional[str],
+) -> int:
+    """Read the source (stdin or a file) as a byte stream, feeding chunks
+    to LiveMarkdownStream.
+
+    Interface parallels textual's:
+
+        stream = Markdown.get_stream(widget)
+        for chunk in source: await stream.write(chunk)
+        await stream.stop()
+
+    We poll the raw fd with select() + non-blocking os.read() — using
+    ``for line in sys.stdin`` would buffer ~4 KB at a pipe before
+    yielding, killing the live-update feel through slow producers. A
+    file (or fifo) path is opened directly; the same loop drains it.
+    """
+    if source is None:
+        fd = sys.stdin.fileno()
+        close_fd = False
+    else:
+        fd = os.open(source, os.O_RDONLY)
+        close_fd = True
+    stream = LiveMarkdownStream.get_stream(
+        console, mode=mode, debounce=debounce, theme=theme, code_theme=code_theme
+    )
+    try:
+        while True:
+            select.select([fd], [], [], debounce)
+            try:
+                chunk = os.read(fd, 4096)
+            except OSError:
+                break
+            if not chunk:
+                break
+            stream.write(chunk.decode("utf-8", errors="replace"))
+    finally:
+        stream.stop()
+        if close_fd:
+            os.close(fd)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

llmkit/md/render/stream.py

@@ -0,0 +1,244 @@
+"""Reusable streaming-Markdown renderer that mirrors textual's API.
+
+Interface parallels textual's ``Markdown.get_stream()`` so callers can
+swap the target (rich Console vs textual Markdown widget) without
+restructuring their code:
+
+    # textual side
+    stream = Markdown.get_stream(markdown_widget)
+    try:
+        async for chunk in source: await stream.write(chunk)
+    finally:
+        await stream.stop()
+
+    # rich side (this module)
+    stream = LiveMarkdownStream.get_stream(Console())
+    try:
+        for chunk in source: stream.write(chunk)
+    finally:
+        stream.stop()
+
+The append mechanism mirrors textual too. From reading
+``textual.widgets._markdown.Markdown.append``:
+
+  1. Track ``_last_parsed_line`` — the source line up to which we've
+     committed rendered output that won't change.
+  2. On write: parse ONLY the new source (from _last_parsed_line on)
+     with markdown-it-py, not the whole document.
+  3. Advance _last_parsed_line to the START of the LAST top-level
+     token. Everything before that is "complete" and gets frozen.
+     The trailing block is potentially incomplete (more chunks may
+     extend it) so it stays mutable.
+  4. Render the newly-frozen prefix once, append to a cached ANSI
+     string. The mutable trailing block is re-rendered each tick
+     into ``Text.from_ansi(frozen + fresh_trailing)``.
+
+Cost per write: parse only new source (typically a few lines).
+Cost per render: re-render only the trailing block (small).
+Cost per stop: one final commit + render.
+
+This is the same shape as textual's mount-new-blocks pattern adapted
+for rich's flat ANSI-string output instead of a widget tree.
+"""
+
+from __future__ import annotations
+
+import io
+import time
+from types import TracebackType
+from typing import Literal, Optional, Type
+
+from markdown_it import MarkdownIt
+from rich.console import Console, RenderableType
+from rich.live import Live
+from rich.markdown import Markdown
+from rich.text import Text
+from rich.theme import Theme
+
+Mode = Literal["markdown", "raw"]
+
+
+class LiveMarkdownStream:
+    """Streaming Markdown writer backed by ``rich.live.Live``.
+
+    Don't instantiate directly — use :meth:`get_stream`, which mirrors
+    ``textual.widgets.Markdown.get_stream(widget)``.
+
+    Caveats:
+      Live repaints in place. Documents that grow past the visible
+      terminal area will overflow / scroll oddly — for long content
+      use a scrollable widget (textual MarkdownViewer) instead.
+    """
+
+    # ── factory (mirrors textual's Markdown.get_stream) ─────────────────
+    @classmethod
+    def get_stream(
+        cls,
+        console: Console,
+        *,
+        mode: Mode = "markdown",
+        debounce: float = 0.1,
+        theme: Optional[Theme] = None,
+        code_theme: str = "monokai",
+    ) -> "LiveMarkdownStream":
+        """Create a started stream against ``console``. Caller is
+        responsible for ``stop()`` (or use the returned object as a
+        context manager)."""
+        stream = cls(
+            console=console,
+            mode=mode,
+            debounce=debounce,
+            theme=theme,
+            code_theme=code_theme,
+        )
+        stream.start()
+        return stream
+
+    def __init__(
+        self,
+        console: Console,
+        mode: Mode = "markdown",
+        debounce: float = 0.1,
+        theme: Optional[Theme] = None,
+        code_theme: str = "monokai",
+    ) -> None:
+        self.console = console
+        self.mode: Mode = mode
+        self.debounce = debounce
+        self._theme = theme
+        self._code_theme = code_theme
+        self._buf = ""
+        self._last_render = 0.0
+        self._live: Optional[Live] = None
+        self._stopped = False
+        # ── incremental-parse state (markdown mode only) ────────────────
+        # _last_parsed_line: line index in _buf up to which we've
+        #   committed rendered output (won't change on further appends).
+        # _committed_ansi: rendered ANSI for lines [0 : _last_parsed_line].
+        # _parser: shared MarkdownIt instance — re-using across writes
+        #   is fine since parse() is stateless.
+        self._last_parsed_line = 0
+        self._committed_ansi = ""
+        self._parser = MarkdownIt("gfm-like") if mode == "markdown" else None
+
+    # ── public API (mirrors textual's MarkdownStream) ───────────────────
+    def start(self) -> None:
+        """Open the underlying Live context."""
+        if self._live is not None:
+            return
+        self._live = Live(
+            self._build_renderable(),
+            console=self.console,
+            auto_refresh=False,
+            transient=False,
+        )
+        self._live.__enter__()
+
+    def write(self, chunk: str) -> None:
+        """Append a markdown fragment. Commits any newly-complete
+        blocks to the cached prefix; re-renders the live view if
+        the debounce window has elapsed. Empty chunks are no-ops."""
+        if self._stopped:
+            raise RuntimeError("Can't write to the stream after it has stopped.")
+        if not chunk:
+            return
+        self._buf += chunk
+        self._commit_complete_blocks()
+        now = time.monotonic()
+        if now - self._last_render >= self.debounce:
+            self._refresh()
+            self._last_render = now
+
+    def stop(self) -> None:
+        """Final commit + render + close the Live context."""
+        if self._stopped:
+            return
+        self._stopped = True
+        if self._live is not None:
+            try:
+                self._commit_complete_blocks()
+                self._refresh()
+            finally:
+                self._live.__exit__(None, None, None)
+                self._live = None
+
+    @property
+    def buffer(self) -> str:
+        """The accumulated text seen so far."""
+        return self._buf
+
+    # ── context-manager sugar ───────────────────────────────────────────
+    def __enter__(self) -> "LiveMarkdownStream":
+        self.start()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        self.stop()
+
+    # ── incremental-parse internals ─────────────────────────────────────
+    def _commit_complete_blocks(self) -> None:
+        """Mirrors textual's Markdown.append's commit logic. Parses only
+        the source from ``_last_parsed_line`` onward, finds the start
+        of the LAST top-level token, and freezes everything before it
+        into ``_committed_ansi``. The trailing block remains mutable —
+        future writes may extend it."""
+        if self._parser is None:  # raw mode: nothing to commit
+            return
+        lines = self._buf.splitlines(keepends=True)
+        if self._last_parsed_line >= len(lines):
+            return
+        new_source = "".join(lines[self._last_parsed_line :])
+        if not new_source:
+            return
+        tokens = self._parser.parse(new_source)
+        # Find the start line of the last top-level token. That's the
+        # boundary: everything before is "complete enough" to commit.
+        last_block_start: Optional[int] = None
+        for token in reversed(tokens):
+            if token.map is not None and token.level == 0:
+                last_block_start = token.map[0]
+                break
+        if last_block_start is None or last_block_start == 0:
+            # No fully-completed blocks since the last commit.
+            return
+        committed_source = "".join(
+            lines[self._last_parsed_line : self._last_parsed_line + last_block_start]
+        )
+        if committed_source:
+            self._committed_ansi += self._render_to_ansi(committed_source)
+        self._last_parsed_line += last_block_start
+
+    def _refresh(self) -> None:
+        if self._live is not None:
+            self._live.update(self._build_renderable(), refresh=True)
+
+    def _build_renderable(self) -> RenderableType:
+        """Compose the current frame: cached committed-ANSI prefix +
+        freshly-rendered trailing (incomplete) block."""
+        if self.mode == "raw":
+            return Text.from_ansi(self._buf)
+        # markdown mode: prefix + trailing render
+        lines = self._buf.splitlines(keepends=True)
+        trailing_source = "".join(lines[self._last_parsed_line :])
+        trailing_ansi = self._render_to_ansi(trailing_source) if trailing_source else ""
+        return Text.from_ansi(self._committed_ansi + trailing_ansi)
+
+    def _render_to_ansi(self, markdown_source: str) -> str:
+        """Render a markdown fragment to a captured ANSI string at the
+        Console's current width. Used for both the frozen-prefix cache
+        and the trailing-block per-tick render."""
+        sink = io.StringIO()
+        Console(
+            file=sink,
+            force_terminal=True,
+            color_system="truecolor",
+            width=self.console.size.width,
+            legacy_windows=False,
+            theme=self._theme,
+        ).print(Markdown(markdown_source, code_theme=self._code_theme), end="")
+        return sink.getvalue()

llmkit/md/view/__init__.py

@@ -0,0 +1 @@
+"""Scrollable modal markdown viewer (textual)."""

llmkit/md/view/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m llmkit.md.view`` → :func:`.cli.main`."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())