polyllmkit 0.1.0__py3-none-any.whl

llmkit/bridge/config.py

@@ -0,0 +1,277 @@
+"""Typed, extensible provider/profile config — the generic half of what
+zsh-ai's ``models.py`` used to do inline.
+
+The model has three tables, all generic:
+
+  ``[defaults]``         fields merged into every provider (a partial
+                         :class:`Provider`).
+  ``[providers.<name>]`` a named backend config: adapter (transport),
+                         model, endpoint, key, tuning. Resolve a usable
+                         one with :meth:`Config.resolve` (overlays defaults).
+  ``[profiles.<name>]``  a named map of *opaque* selector-key → provider
+                         name. The library never interprets the keys — a
+                         consumer (e.g. zsh-ai's "widgets": ask/modify/
+                         question/fim) gives them meaning via
+                         :meth:`Config.select`.
+
+Extending the schema is by *subclassing*, not by stuffing untyped values
+into a bag: parameterize :class:`ConfigParser` with a richer
+:class:`Provider` subclass and/or override :meth:`ConfigParser.build` to
+return a :class:`Config` subclass carrying extra typed sections. The
+parser's return type tracks your subclass — no ``Any``, no post-hoc
+mutation. The only escape hatch for genuinely-unknown *keys* is
+:attr:`Provider.extra`, typed as :data:`TomlValue` (TOML's closed value
+grammar), used purely for forward-compatible passthrough.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from datetime import date, datetime, time
+from typing import Generic, Mapping, Optional, Self, TypeAlias, TypeVar, cast
+
+# Exactly what ``tomllib.load`` can produce — a closed, recursive set.
+# Used for unknown passthrough keys and as the parser's input value type.
+TomlValue: TypeAlias = (
+    "str | int | float | bool | datetime | date | time "
+    "| list[TomlValue] | dict[str, TomlValue]"
+)
+
+# Known provider fields (anything else in a [providers.*] table → .extra).
+_PROVIDER_FIELDS = frozenset(
+    {
+        "model",
+        "adapter",
+        "endpoint",
+        "api_key",
+        "api_key_env",
+        "max_tokens",
+        "temperature",
+        "enable_thinking",
+        "stop",
+        "headers",
+    }
+)
+
+
+def _normalise_thinking(value: object) -> Optional[str]:
+    """Normalise an ``enable_thinking`` value to the bridge's tri-state
+    ``auto`` | ``true`` | ``false`` (or ``None`` if unspecified)."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    s = str(value).strip().lower()
+    if s in ("yes", "true", "1", "on"):
+        return "true"
+    if s in ("no", "false", "0", "off"):
+        return "false"
+    return "auto"
+
+
+def _as_stop(value: object) -> tuple[str, ...]:
+    """Coerce a ``stop`` field (scalar or list) into a tuple of strings."""
+    if value is None:
+        return ()
+    if isinstance(value, (list, tuple)):
+        return tuple(str(v) for v in value)
+    return (str(value),)
+
+
+def _as_table(value: object) -> dict[str, object]:
+    """A TOML table → dict, or {} for anything else (incl. missing)."""
+    return dict(value) if isinstance(value, Mapping) else {}
+
+
+def _header_item(key: object, value: object) -> tuple[str, str]:
+    """Normalise one header entry. Names are case-insensitive per RFC 9110
+    (and lowercase on the wire in HTTP/2), so lowercase them — that is also
+    what makes the per-key merge across ``[defaults]`` / provider / CLI
+    reliable. Whitespace is stripped from both halves (h11 rejects padded
+    values at request time). Non-string values are stringified via ``str()``
+    (so TOML ``true`` lands as ``'True'``, Python's casing)."""
+    return str(key).strip().lower(), str(value).strip()
+
+
+def _as_headers(value: object) -> dict[str, str]:
+    """Coerce a ``headers`` field into a str→str dict. Accepts a TOML table,
+    or a list of ``KEY=VALUE`` strings — the same shape the CLI ``--header``
+    flag and the zsh ``headers`` zstyle use, so either surface's idiom works.
+    Anything else (incl. missing) → ``{}``. Entries with an empty name are
+    dropped; see :func:`_header_item` for normalisation."""
+    if isinstance(value, (list, tuple)):
+        out: dict[str, str] = {}
+        for item in value:
+            key, _, val = str(item).partition("=")
+            key, val = _header_item(key, val)
+            if key:
+                out[key] = val
+        return out
+    return {
+        k: v
+        for k, v in (_header_item(kk, vv) for kk, vv in _as_table(value).items())
+        if k
+    }
+
+
+@dataclass(frozen=True)
+class Provider:
+    """A backend config. Every field is optional — ``None`` means
+    "unspecified", so partial providers (and ``[defaults]``) compose via
+    :meth:`merged`. Hard defaults (adapter, endpoint, …) are applied by
+    the bridge at use time, NOT here, so a ``Provider`` only ever holds
+    what was actually configured.
+    """
+
+    model: Optional[str] = None
+    # "openai-compatible" | "anthropic" | "google" | "claude_code"
+    adapter: Optional[str] = None
+    endpoint: Optional[str] = None
+    api_key: Optional[str] = None
+    api_key_env: Optional[str] = None
+    max_tokens: Optional[int] = None
+    temperature: Optional[float] = None
+    enable_thinking: Optional[str] = None  # auto|true|false
+    stop: tuple[str, ...] = ()
+    # Extra HTTP request headers, sent on every call by the openai/anthropic/
+    # google adapters (as the SDKs' ``default_headers`` / ``HttpOptions``). Used
+    # for gateway routing keys a gateway demands but the SDK won't set — e.g.
+    # OpenCode Zen's ``x-opencode-request``, which its qwen pool requires (absent
+    # it, zen 503s ``failover_exhausted``). Merges per-key over ``[defaults]``.
+    headers: Mapping[str, str] = field(default_factory=dict)
+    # Forward-compat passthrough for unknown [providers.*] keys.
+    extra: Mapping[str, "TomlValue"] = field(default_factory=dict)
+
+    @classmethod
+    def from_toml(cls, raw: Mapping[str, object]) -> Self:
+        """Build from a raw TOML table. Known keys are coerced into typed
+        fields; unrecognised keys are preserved verbatim in :attr:`extra`.
+        Subclasses that add fields override this to claim their own keys."""
+        extra = {k: v for k, v in raw.items() if k not in _PROVIDER_FIELDS}
+        return cls(
+            model=_opt_str(raw.get("model")),
+            adapter=_opt_str(raw.get("adapter")),
+            endpoint=_opt_str(raw.get("endpoint")),
+            api_key=_opt_str(raw.get("api_key")),
+            api_key_env=_opt_str(raw.get("api_key_env")),
+            max_tokens=_opt_int(raw.get("max_tokens")),
+            temperature=_opt_float(raw.get("temperature")),
+            enable_thinking=_normalise_thinking(raw.get("enable_thinking")),
+            stop=_as_stop(raw.get("stop")),
+            headers=_as_headers(raw.get("headers")),
+            extra=cast("Mapping[str, TomlValue]", extra),
+        )
+
+    def merged(self, base: Self) -> Self:
+        """Overlay ``self`` onto ``base`` (``self`` wins). Generic over
+        the concrete type — works field-by-field for any subclass, so a
+        richer provider's extra fields compose too. Mappings merge,
+        tuples fall back when empty, scalars pick non-``None``."""
+        out: dict[str, object] = {}
+        for f in dataclasses.fields(self):
+            out[f.name] = self._merge_field(
+                getattr(self, f.name), getattr(base, f.name)
+            )
+        return type(self)(**out)  # type: ignore[arg-type]  # preserves subclass type
+
+    @staticmethod
+    def _merge_field(self_val: object, base_val: object) -> object:
+        """Default per-field merge. Override in a subclass for fields that
+        need bespoke composition."""
+        if isinstance(self_val, Mapping) and isinstance(base_val, Mapping):
+            return {**base_val, **self_val}
+        if isinstance(self_val, tuple):
+            return self_val if self_val else base_val
+        return self_val if self_val is not None else base_val
+
+
+def _opt_str(v: object) -> Optional[str]:
+    return None if v is None else str(v)
+
+
+def _opt_int(v: object) -> Optional[int]:
+    return None if v is None else int(v)  # type: ignore[call-overload]
+
+
+def _opt_float(v: object) -> Optional[float]:
+    return None if v is None else float(v)  # type: ignore[arg-type]
+
+
+P = TypeVar("P", bound=Provider)
+
+
+@dataclass(frozen=True)
+class Config(Generic[P]):
+    """Parsed config. Parameterised by the provider type so subclasses can
+    carry a richer ``Provider`` (and add their own typed sections by
+    subclassing this and overriding :meth:`ConfigParser.build`)."""
+
+    defaults: P
+    providers: Mapping[str, P]
+    profiles: Mapping[str, Mapping[str, str]]  # name → (opaque key → provider)
+
+    def resolve(self, name: str) -> P:
+        """The named provider with ``[defaults]`` overlaid beneath it."""
+        return self.providers[name].merged(self.defaults)
+
+    def select(self, profile: str, key: str) -> Optional[str]:
+        """Provider name for ``key`` in ``profile`` (key opaque), or None."""
+        return self.profiles.get(profile, {}).get(key)
+
+
+class ConfigParser(Generic[P]):
+    """Parses the three known tables into a :class:`Config`. Extend by:
+
+      * setting :attr:`provider_cls` to a :class:`Provider` subclass, and/or
+      * overriding :meth:`build` to return a :class:`Config` subclass with
+        extra typed sections read from ``data``.
+
+    The base parser (``ConfigParser()``) yields ``Config[Provider]``.
+    """
+
+    provider_cls: type[P] = cast("type[P]", Provider)
+
+    def provider(self, raw: Mapping[str, object]) -> P:
+        return self.provider_cls.from_toml(raw)
+
+    def parse(self, data: Mapping[str, object]) -> Config[P]:
+        defaults = self.provider(_as_table(data.get("defaults")))
+        providers = {
+            name: self.provider(_as_table(v))
+            for name, v in _as_table(data.get("providers")).items()
+        }
+        profiles = {
+            name: {str(k): str(pv) for k, pv in _as_table(v).items()}
+            for name, v in _as_table(data.get("profiles")).items()
+        }
+        return self.build(defaults, providers, profiles, data)
+
+    def build(
+        self,
+        defaults: P,
+        providers: Mapping[str, P],
+        profiles: Mapping[str, Mapping[str, str]],
+        data: Mapping[str, object],
+    ) -> Config[P]:
+        """Assemble the final Config. Override to return a subclass that
+        reads extra tables from ``data`` (e.g. a typed ``widgets`` field)."""
+        return Config(defaults=defaults, providers=providers, profiles=profiles)
+
+
+def load(path: str) -> Config[Provider]:
+    """Convenience: parse a TOML file with the base parser."""
+    import tomllib
+
+    with open(path, "rb") as f:
+        data = tomllib.load(f)
+    return ConfigParser().parse(data)
+
+
+__all__ = [
+    "TomlValue",
+    "Provider",
+    "Config",
+    "ConfigParser",
+    "load",
+]

llmkit/bridge/sinks.py

@@ -0,0 +1,56 @@
+"""Output sinks for content / thinking streams.
+
+A "sink" is the destination for one of the two logical streams that
+:class:`llmkit.bridge.stream.StreamSplitter` produces. A caller picks each
+via a string spec (e.g. the ``--content`` / ``--thinking`` flags of the
+CLI); this module normalises that spec into something the splitter and the
+chat command can use.
+"""
+from __future__ import annotations
+
+import sys
+from typing import TextIO, Union
+
+# `Sink` is the resolved form. ``'inline'`` is a thinking-side sentinel
+# meaning "emit reasoning into the content sink, separated from real
+# content by a blank line". Renderers then render thinking as ordinary
+# prose; no wrapping tags or prefixes to confuse them.
+Sink = Union[None, str, TextIO]
+
+
+def open_target(spec: Union[str, TextIO]) -> Sink:
+    """Resolve a ``--content`` / ``--thinking`` spec to a sink.
+
+    Returns:
+      an already-open writable stream passed through as-is (in-process capture —
+        e.g. a ``StringIO`` from :func:`llmkit.bridge.chat_to_str`; the caller owns
+        it),
+      ``None`` for ``none`` (drop entirely),
+      the literal sentinel ``'inline'`` (the StreamSplitter interprets it),
+      ``sys.stdout`` for ``-``,
+      an open writable file for any other value (treated as a path).
+
+    Files are opened line-buffered so a downstream reader sees output
+    promptly.
+    """
+    if not isinstance(spec, str):   # already-open TextIO (caller-owned capture)
+        return spec
+    if spec == "none":
+        return None
+    if spec == "-":
+        return sys.stdout
+    if spec == "inline":
+        return "inline"
+    return open(spec, "w", buffering=1)
+
+
+def close_sink(sink: Sink) -> None:
+    """Close a sink if it owns its file handle."""
+    if sink is None or sink == "inline":
+        return
+    if sink in (sys.stdout, sys.stderr):
+        return
+    try:
+        sink.close()  # type: ignore[union-attr]
+    except Exception:
+        pass

llmkit/bridge/stream.py

@@ -0,0 +1,161 @@
+"""Two-stream splitter for OpenAI-compatible chat responses.
+
+Unifies the two server conventions for "reasoning":
+
+  1. ``delta.reasoning_content`` — split-out API field (vLLM with
+     ``--reasoning-parser``, deepseek API, …)
+  2. ``<think>…</think>`` tags inside ``delta.content`` (llama.cpp
+     default, ollama, anything that passes raw model output through)
+
+Routes the unified streams to two sinks:
+
+  content   the final answer text
+  thinking  a writable (TextIO), ``None`` to drop, or the sentinel
+            ``"inline"`` — which merges reasoning into the content
+            sink, separated from real content by a blank line. No
+            tags, no prefixes; the markdown renderer treats it as
+            ordinary prose
+
+Robust to ``<think>`` tags straddling chunk boundaries — the open or
+close marker can be split across two ``feed_content_delta`` calls.
+"""
+from __future__ import annotations
+
+from typing import Optional, TextIO, cast
+
+from .sinks import Sink
+
+
+class StreamSplitter:
+    OPEN = "<think>"
+    CLOSE = "</think>"
+
+    def __init__(self, content_sink: Sink, thinking_sink: Sink) -> None:
+        self.content: Optional[TextIO] = (
+            None if content_sink in (None, "inline")
+            else cast(TextIO, content_sink)
+        )
+        self.inline = thinking_sink == "inline"
+        # Effective separate-sink thinking output: inline routes through
+        # content; None drops; otherwise a TextIO.
+        self._think_out: Optional[TextIO]
+        if self.inline:
+            self._think_out = self.content
+        elif thinking_sink is None:
+            self._think_out = None
+        else:
+            self._think_out = cast(TextIO, thinking_sink)
+
+        # Tag-parser state (case 2: <think> inside delta.content).
+        self._buf = ""
+        self._in_tag_think = False
+        # Inline-mode: True while we're emitting thinking text into the
+        # content sink, so transitions back to real content know to
+        # emit a blank-line separator.
+        self._inline_in_thinking = False
+
+    # ── public ──────────────────────────────────────────────────────────
+    def feed_content_delta(self, text: str) -> None:
+        if not text:
+            return
+        # API-field reasoning has ended — close the inline-thinking
+        # paragraph before content takes over.
+        self._end_inline_thinking()
+        self._buf += text
+        self._consume_buf()
+
+    def feed_reasoning_delta(self, text: str) -> None:
+        if not text:
+            return
+        self._begin_inline_thinking()
+        self._emit_thinking(text)
+
+    def finish(self) -> None:
+        if self._buf:
+            if self._in_tag_think:
+                self._emit_thinking(self._buf)
+            else:
+                self._emit_content(self._buf)
+            self._buf = ""
+        # Close any still-open inline-thinking paragraph.
+        self._end_inline_thinking()
+
+    # ── inline-mode helpers ─────────────────────────────────────────────
+    def _begin_inline_thinking(self) -> None:
+        """Inline mode only: emit a leading newline before the first
+        thinking chunk so the reasoning sits in its own paragraph."""
+        if self.inline and not self._inline_in_thinking:
+            self._emit_content("\n")
+            self._inline_in_thinking = True
+
+    def _end_inline_thinking(self) -> None:
+        """Inline mode only: terminate the thinking paragraph with a
+        blank line so subsequent content renders as a fresh paragraph."""
+        if self.inline and self._inline_in_thinking:
+            self._emit_content("\n\n")
+            self._inline_in_thinking = False
+
+    # ── low-level emitters ──────────────────────────────────────────────
+    def _emit_content(self, s: str) -> None:
+        if s and self.content is not None:
+            self.content.write(s)
+            self.content.flush()
+
+    def _emit_thinking(self, s: str) -> None:
+        """Inline mode routes through the content sink (separators are
+        bracketed by _begin/_end_inline_thinking). Otherwise writes to
+        the dedicated thinking sink."""
+        if not s:
+            return
+        if self.inline:
+            self._emit_content(s)
+        elif self._think_out is not None:
+            self._think_out.write(s)
+            self._think_out.flush()
+
+    # ── tag parser for <think>…</think> in delta.content ────────────────
+    def _consume_buf(self) -> None:
+        while self._buf:
+            if not self._in_tag_think:
+                idx = self._buf.find(self.OPEN)
+                if idx != -1:
+                    pre = self._buf[:idx]
+                    self._buf = self._buf[idx + len(self.OPEN):]
+                    self._emit_content(pre)
+                    self._in_tag_think = True
+                    self._begin_inline_thinking()
+                    continue
+                tail_keep = self._partial_tail(self.OPEN)
+                if tail_keep > 0:
+                    self._emit_content(self._buf[:-tail_keep])
+                    self._buf = self._buf[-tail_keep:]
+                else:
+                    self._emit_content(self._buf)
+                    self._buf = ""
+                return
+            else:
+                idx = self._buf.find(self.CLOSE)
+                if idx != -1:
+                    inner = self._buf[:idx]
+                    self._buf = self._buf[idx + len(self.CLOSE):]
+                    self._emit_thinking(inner)
+                    self._in_tag_think = False
+                    self._end_inline_thinking()
+                    continue
+                tail_keep = self._partial_tail(self.CLOSE)
+                if tail_keep > 0:
+                    self._emit_thinking(self._buf[:-tail_keep])
+                    self._buf = self._buf[-tail_keep:]
+                else:
+                    self._emit_thinking(self._buf)
+                    self._buf = ""
+                return
+
+    def _partial_tail(self, marker: str) -> int:
+        """Length of trailing buffer that could be the start of ``marker``."""
+        buf = self._buf
+        max_n = min(len(marker) - 1, len(buf))
+        for n in range(max_n, 0, -1):
+            if marker.startswith(buf[-n:]):
+                return n
+        return 0

llmkit/md/__init__.py

@@ -0,0 +1,13 @@
+"""llmkit.md — render markdown to a terminal.
+
+Two entry points, one rich/textual pipeline:
+
+  :mod:`llmkit.md.render`  one-shot or live-streaming render to stdout
+                           (``python -m llmkit.md.render``).
+  :mod:`llmkit.md.view`    scrollable, follow-tailing modal viewer
+                           (``python -m llmkit.md.view``).
+
+The streaming renderer (:class:`llmkit.md.render.stream.LiveMarkdownStream`)
+mirrors textual's ``Markdown.get_stream`` API, so callers can swap a rich
+Console for a textual widget without restructuring.
+"""

llmkit/md/render/__init__.py

@@ -0,0 +1 @@
+"""Markdown rendering: one-shot + live streaming (rich)."""

llmkit/md/render/__main__.py

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