bitfrost 0.1.0__py3-none-any.whl

bitfrost/__init__.py

@@ -0,0 +1,60 @@
+"""Bitfrost — drop-in OpenTelemetry observability for Python LLM apps.
+
+Made by `Voight <https://voight.xyz>`_. Licensed under MIT.
+
+Public API
+----------
+
+.. code-block:: python
+
+    from bitfrost import BitfrostOptions, EventPayload, PrivacyLevel
+
+Backends ship in :mod:`bitfrost.backends`:
+
+.. code-block:: python
+
+    from bitfrost.backends.console import ConsoleBackend
+    from bitfrost.backends.voight import VoightBackend
+    from bitfrost.backends.otlp import OTLPBackend
+    from bitfrost.backends.jsonl import JSONLBackend
+    from bitfrost.backends.sqlite import SQLiteBackend
+"""
+
+from __future__ import annotations
+
+from bitfrost.instrument import (
+    instrument_anthropic,
+    instrument_auto,
+    instrument_litellm,
+    instrument_openai,
+    instrument_smolagents,
+    quickstart,
+)
+from bitfrost.types import (
+    BitfrostOptions,
+    EventPayload,
+    EventType,
+    Outcome,
+    PrivacyLevel,
+    TokenBreakdown,
+    ToolCallRecord,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BitfrostOptions",
+    "EventPayload",
+    "EventType",
+    "Outcome",
+    "PrivacyLevel",
+    "TokenBreakdown",
+    "ToolCallRecord",
+    "__version__",
+    "instrument_anthropic",
+    "instrument_auto",
+    "instrument_litellm",
+    "instrument_openai",
+    "instrument_smolagents",
+    "quickstart",
+]

bitfrost/_brand.py

@@ -0,0 +1,196 @@
+"""Shared brand identity for Bitfrost surfaces (CLI, TUI, web dashboard).
+
+One source of truth for the wordmark, the colour palette, and the
+welcome splash so the three surfaces read as the same product. The web
+frontend mirrors :data:`PALETTE` in its CSS (CSS can't import Python);
+keep them in sync.
+
+The name nods to the Bifrost — the rainbow bridge of Norse myth that
+links worlds — which is what an exporter does: bridge your LLM runtime
+to wherever you watch it. The splash leads with that bridge: a small
+iridescent arch (the only colourful element) beside a metallic wordmark.
+
+The arch + wordmark art below were pre-rendered once (PIL + pyfiglet) and
+embedded as plain strings — neither library is a runtime dependency. The
+gradients are applied at draw time with pure arithmetic via ``rich``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+# Palette — dark, platinum-forward, with a teal→violet "bridge" accent.
+# Mirrored in src/bitfrost/serve/static/styles.css (:root variables).
+PALETTE = {
+    "bg": "#0c0e0d",  # near-black canvas
+    "surface": "#14171a",  # card
+    "surface2": "#1a1e22",  # raised card / hover
+    "border": "#23282d",
+    "fg": "#e6e7ea",  # platinum text
+    "fg_muted": "#8b9197",
+    "accent": "#5eead4",  # teal — primary accent
+    "accent2": "#a78bfa",  # violet — bridge gradient end
+    "success": "#4ade80",
+    "failed": "#f87171",
+    "pending": "#fbbf24",
+}
+
+# Metallic platinum stops (logo's silver band) — for the wordmark, top→bottom.
+_METAL: list[tuple[int, int, int]] = [
+    (0xF6, 0xF6, 0xFB),
+    (0xC7, 0xC8, 0xD2),
+    (0xB9, 0xBA, 0xC6),
+    (0x9A, 0x9B, 0xA7),
+    (0x8A, 0x8B, 0x97),
+]
+# Iridescent stops (logo's rainbow inner line) — for the arch, left→right.
+_IRID: list[tuple[int, int, int]] = [
+    (0x8B, 0x7B, 0xF0),
+    (0x46, 0xC5, 0x85),
+    (0xEA, 0xBF, 0x4E),
+    (0xEF, 0x5A, 0x6A),
+]
+
+# The logo arch, rasterised to braille (pre-rendered). The ONLY colourful
+# element in the splash — coloured left→right with the iridescent stops.
+ARCH_BRAILLE: list[str] = [
+    "  ⢀⣠⣤⣶⠶⠾⠿⠿⠷⠶⣶⣦⣄⡀  ",
+    " ⣴⡿⠋⠁         ⠙⢿⣦ ",
+]
+
+# Wordmark (pyfiglet 'ansi_shadow', pre-rendered) — coloured top→bottom
+# with the metallic stops.
+WORDMARK: list[str] = [
+    "██████╗ ██╗████████╗███████╗██████╗  ██████╗ ███████╗████████╗",
+    "██╔══██╗██║╚══██╔══╝██╔════╝██╔══██╗██╔═══██╗██╔════╝╚══██╔══╝",
+    "██████╔╝██║   ██║   █████╗  ██████╔╝██║   ██║███████╗   ██║   ",
+    "██╔══██╗██║   ██║   ██╔══╝  ██╔══██╗██║   ██║╚════██║   ██║   ",
+    "██████╔╝██║   ██║   ██║     ██║  ██║╚██████╔╝███████║   ██║   ",
+    "╚═════╝ ╚═╝   ╚═╝   ╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝   ╚═╝   ",
+]
+
+# Plain-text fallback wordmark for when ``rich`` isn't installed.
+BANNER = r"""
+ ┌┐ ┬┌┬┐┌─┐┬─┐┌─┐┌─┐┌┬┐
+ ├┴┐│ │ ├┤ ├┬┘│ │└─┐ │
+ └─┘┴ ┴ └  ┴└─└─┘└─┘ ┴   by voight.xyz
+ ═══════════════════════ bridge your LLM telemetry
+""".strip("\n")
+
+
+def banner(tagline: str | None = None) -> str:
+    """Return the plain-text wordmark, optionally replacing the tagline."""
+
+    if tagline is None:
+        return BANNER
+    lines = BANNER.splitlines()
+    lines[-1] = "═" * 23 + " " + tagline
+    return "\n".join(lines)
+
+
+def _hex_at(fraction: float, stops: Sequence[tuple[int, int, int]]) -> str:
+    """Interpolate a multi-stop gradient and return a ``#rrggbb`` string."""
+
+    f = max(0.0, min(1.0, fraction))
+    seg = f * (len(stops) - 1)
+    i = int(seg)
+    if i >= len(stops) - 1:
+        r, g, b = stops[-1]
+        return f"#{r:02x}{g:02x}{b:02x}"
+    t = seg - i
+    a, c = stops[i], stops[i + 1]
+    r, g, b = (round(a[k] + (c[k] - a[k]) * t) for k in range(3))
+    return f"#{r:02x}{g:02x}{b:02x}"
+
+
+def render_splash(*, full: bool = True, console: object | None = None) -> None:
+    """Print the Bitfrost welcome splash to the terminal.
+
+    Shown only at startup — bare ``bitfrost`` (full), and ``watch`` /
+    ``serve`` (compact: lockup only, ``full=False``). Uses ``rich`` for
+    the gradient lockup + info panel; if ``rich`` isn't installed it falls
+    back to the plain :func:`banner`.
+
+    The arch is the only multi-coloured element; the wordmark is metallic
+    platinum and everything else uses the Voight palette.
+    """
+
+    try:
+        from rich.box import ROUNDED
+        from rich.console import Console
+        from rich.panel import Panel
+        from rich.table import Table
+        from rich.text import Text
+    except ImportError:  # pragma: no cover - exercised only without [rich]
+        print(banner())
+        return
+
+    con = console if isinstance(console, Console) else Console()
+
+    # Arch — iridescent, the only colourful element.
+    arch = Text()
+    for line in ARCH_BRAILLE:
+        width = max(1, len(line) - 1)
+        for i, ch in enumerate(line):
+            if ch == " ":
+                arch.append(" ")
+            else:
+                arch.append(ch, style=_hex_at(i / width, _IRID))
+        arch.append("\n")
+
+    # Wordmark — metallic platinum, top→bottom.
+    wm = Text()
+    rows = max(1, len(WORDMARK) - 1)
+    for i, line in enumerate(WORDMARK):
+        wm.append(line + "\n", style=_hex_at(i / rows, _METAL))
+
+    # Side-by-side lockup when the terminal is wide enough; otherwise stack
+    # the arch above the wordmark so neither wraps on an 80-column terminal.
+    needed = len(WORDMARK[0]) + len(ARCH_BRAILLE[0]) + 2
+    if con.size.width >= needed:
+        lockup = Table.grid(padding=(0, 2))
+        lockup.add_column()
+        lockup.add_column()
+        lockup.add_row(Text("\n") + arch, wm)
+        con.print(lockup)
+    else:
+        con.print(arch)
+        con.print(wm)
+
+    if not full:
+        return
+
+    try:
+        from bitfrost import __version__
+    except Exception:  # pragma: no cover - defensive
+        __version__ = "0.1.0"
+
+    con.print()
+    info = Text()
+    info.append("Drop-in OpenTelemetry observability for Python LLM apps.\n", style="#b4b4bd")
+    info.append(f"v{__version__} · MIT · Python 3.10-3.13\n\n", style="#5c5c66")
+
+    def _section(title: str, items: list[str]) -> None:
+        info.append(f"{title}\n", style=f"bold {PALETTE['accent']}")
+        info.append("  " + " · ".join(items) + "\n\n", style=PALETTE["fg"])
+
+    _section("Backends", ["console", "sqlite", "jsonl", "otlp", "voight", "tee"])
+    _section("Commands", ["watch", "replay", "query", "vacuum", "tui", "serve"])
+    _section("Instruments", ["openai", "anthropic", "litellm", "smolagents"])
+    info.append("run ", style="#5c5c66")
+    info.append("bitfrost --help", style=PALETTE["accent2"])
+
+    con.print(
+        Panel(
+            info,
+            title=f"[bold {PALETTE['fg']}]bitfrost[/]  [{PALETTE['fg_muted']}]by voight.xyz[/]",
+            title_align="left",
+            border_style=PALETTE["accent"],
+            box=ROUNDED,
+            padding=(1, 3),
+            width=84,
+        )
+    )
+
+
+__all__ = ["ARCH_BRAILLE", "BANNER", "PALETTE", "WORDMARK", "banner", "render_splash"]

bitfrost/_readers.py

@@ -0,0 +1,260 @@
+"""Readers that turn a captured log (JSONL file or SQLite DB) back into events.
+
+The CLI commands (``watch``, ``replay``, ``query``) all need to pull events
+out of a file the user captured earlier. Two storage formats ship in v0.1:
+
+- **JSONL** (:class:`~bitfrost.backends.jsonl.JSONLBackend`) — one JSON
+  object per line, each line a full :class:`~bitfrost.types.EventPayload`.
+- **SQLite** (:class:`~bitfrost.backends.sqlite.SQLiteBackend`) — flat
+  columns plus a ``metadata`` JSON column.
+
+Both readers expose the same surface:
+
+- ``read_all()`` → every event as a payload dict, in capture order.
+- ``tail(marker)`` → ``(new_events, new_marker)`` since the last poll, so
+  ``bitfrost watch`` can incrementally stream new events without re-reading
+  the whole file. The marker is opaque to callers: a byte offset for
+  JSONL, a rowid for SQLite. Start a watch loop with ``marker=0``.
+
+:class:`SQLiteReader` additionally exposes ``query(sql)`` — a **read-only**
+SQL passthrough for ``bitfrost query`` — opened with SQLite's ``mode=ro``
+URI so a fat-fingered ``DROP TABLE`` can't damage the user's capture.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+
+class JSONLReader:
+    """Read events from a ``.jsonl`` capture file."""
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+
+    def read_all(self) -> list[dict[str, Any]]:
+        """Return every well-formed event in the file, in order.
+
+        Blank lines and malformed JSON are skipped silently — a partially
+        written final line (the writer crashed mid-append) shouldn't make
+        the whole replay unreadable.
+        """
+
+        events: list[dict[str, Any]] = []
+        if not self._path.exists():
+            return events
+        with self._path.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                event = _parse_line(line)
+                if event is not None:
+                    events.append(event)
+        return events
+
+    def tail(self, marker: int = 0) -> tuple[list[dict[str, Any]], int]:
+        """Return events appended since byte offset ``marker``.
+
+        Reads only complete lines: if the file currently ends mid-line
+        (a write in progress), the partial trailing line is left for the
+        next poll by rewinding the returned marker to the start of it.
+        """
+
+        if not self._path.exists():
+            return [], marker
+        events: list[dict[str, Any]] = []
+        with self._path.open("rb") as fh:
+            fh.seek(marker)
+            data = fh.read()
+            new_marker = fh.tell()
+        if not data:
+            return [], marker
+        text = data.decode("utf-8", "replace")
+        # If the chunk doesn't end on a newline, hold back the partial
+        # last line so we re-read it whole next time.
+        if not text.endswith("\n"):
+            last_nl = text.rfind("\n")
+            if last_nl == -1:
+                # No complete line yet — wait for more.
+                return [], marker
+            consumed = last_nl + 1
+            new_marker = marker + len(text[:consumed].encode("utf-8"))
+            text = text[:consumed]
+        for line in text.splitlines():
+            event = _parse_line(line)
+            if event is not None:
+                events.append(event)
+        return events, new_marker
+
+
+class SQLiteReader:
+    """Read events from a SQLite capture DB written by ``SQLiteBackend``."""
+
+    def __init__(self, path: str | Path) -> None:
+        self._path = Path(path)
+
+    def read_all(self) -> list[dict[str, Any]]:
+        """Return every event reconstructed into payload-dict shape, in order."""
+
+        if not self._path.exists():
+            return []
+        conn = self._connect_ro()
+        try:
+            cursor = conn.execute(
+                "SELECT rowid, agent_id, session_id, timestamp, event_type, "
+                "model, duration_ms, outcome, tool_executed, input, metadata "
+                "FROM events ORDER BY rowid"
+            )
+            return [_row_to_event(row) for row in cursor.fetchall()]
+        finally:
+            conn.close()
+
+    def tail(self, marker: int = 0) -> tuple[list[dict[str, Any]], int]:
+        """Return events with ``rowid > marker``; new marker is the max rowid.
+
+        rowid is SQLite's monotonic insertion counter, so it gives a stable
+        "everything since last poll" cursor even when two events share a
+        millisecond timestamp.
+        """
+
+        if not self._path.exists():
+            return [], marker
+        conn = self._connect_ro()
+        try:
+            cursor = conn.execute(
+                "SELECT rowid, agent_id, session_id, timestamp, event_type, "
+                "model, duration_ms, outcome, tool_executed, input, metadata "
+                "FROM events WHERE rowid > ? ORDER BY rowid",
+                (marker,),
+            )
+            rows = cursor.fetchall()
+        finally:
+            conn.close()
+        if not rows:
+            return [], marker
+        events = [_row_to_event(row) for row in rows]
+        new_marker = max(int(row[0]) for row in rows)
+        return events, new_marker
+
+    def query(self, sql: str) -> tuple[list[str], list[tuple[Any, ...]]]:
+        """Run a read-only SQL query, returning ``(column_names, rows)``.
+
+        The connection is opened ``mode=ro`` so any mutation (INSERT,
+        UPDATE, DELETE, DROP, …) raises ``sqlite3.OperationalError`` rather
+        than touching the user's capture. ``bitfrost query`` surfaces that
+        as a friendly error.
+        """
+
+        conn = self._connect_ro()
+        try:
+            cursor = conn.execute(sql)
+            columns = [d[0] for d in cursor.description] if cursor.description else []
+            rows = cursor.fetchall()
+            return columns, rows
+        finally:
+            conn.close()
+
+    def _connect_ro(self) -> sqlite3.Connection:
+        """Open a read-only connection via the ``file:…?mode=ro`` URI."""
+
+        uri = f"file:{self._path}?mode=ro"
+        return sqlite3.connect(uri, uri=True)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_line(line: str) -> dict[str, Any] | None:
+    """Parse one JSONL line into an event dict, or ``None`` if not usable."""
+
+    stripped = line.strip()
+    if not stripped:
+        return None
+    try:
+        parsed = json.loads(stripped)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _row_to_event(row: tuple[Any, ...]) -> dict[str, Any]:
+    """Reconstruct a render-ready event dict from a SQLite row.
+
+    Column order matches the SELECT in :meth:`SQLiteReader.read_all`:
+    ``(rowid, agent_id, session_id, timestamp, event_type, model,
+    duration_ms, outcome, tool_executed, input, metadata)``.
+
+    ``metadata`` already carries ``tokens`` / ``provider`` / ``sessionId``
+    and ``input`` carries the (privacy-filtered) prompt, so the
+    reconstructed dict renders identically to a live event.
+    """
+
+    (
+        _rowid,
+        agent_id,
+        _session_id,
+        timestamp,
+        event_type,
+        model,
+        duration_ms,
+        outcome,
+        tool_executed,
+        input_raw,
+        metadata_raw,
+    ) = row
+    try:
+        metadata = json.loads(metadata_raw) if metadata_raw else {}
+    except (json.JSONDecodeError, ValueError, TypeError):
+        metadata = {}
+    if not isinstance(metadata, dict):
+        metadata = {}
+
+    event: dict[str, Any] = {
+        "agentId": agent_id,
+        "type": event_type,
+        "model": model,
+        "durationMs": duration_ms,
+        "outcome": outcome,
+        "timestamp": timestamp,
+        "metadata": metadata,
+    }
+    if tool_executed:
+        event["toolExecuted"] = tool_executed
+    if input_raw:
+        with contextlib.suppress(json.JSONDecodeError, ValueError, TypeError):
+            event["input"] = json.loads(input_raw)
+    return event
+
+
+def make_reader(path: str | Path, fmt: str | None = None) -> JSONLReader | SQLiteReader:
+    """Return the right reader for ``path``, auto-detecting by extension.
+
+    ``fmt`` overrides detection: ``"jsonl"`` or ``"sqlite"`` / ``"db"``.
+    Detection falls back to SQLite for ``.db`` / ``.sqlite`` / ``.sqlite3``
+    and JSONL for ``.jsonl`` / ``.ndjson``; anything else raises so the CLI
+    can tell the user to pass an explicit flag.
+    """
+
+    if fmt is not None:
+        fmt_l = fmt.lower()
+        if fmt_l == "jsonl":
+            return JSONLReader(path)
+        if fmt_l in ("sqlite", "db"):
+            return SQLiteReader(path)
+        msg = f"unknown reader format: {fmt!r} (expected 'jsonl' or 'sqlite')"
+        raise ValueError(msg)
+
+    suffix = Path(path).suffix.lower()
+    if suffix in (".db", ".sqlite", ".sqlite3"):
+        return SQLiteReader(path)
+    if suffix in (".jsonl", ".ndjson"):
+        return JSONLReader(path)
+    msg = f"cannot infer format from extension {suffix!r}; pass --db or --jsonl explicitly"
+    raise ValueError(msg)
+
+
+__all__ = ["JSONLReader", "SQLiteReader", "make_reader"]