ctxlineage 0.1.0__py3-none-any.whl

ctxlineage/__init__.py

@@ -0,0 +1,5 @@
+from ctxlineage._span import span
+from ctxlineage._state import init
+
+__all__ = ["init", "span", "__version__"]
+__version__ = "0.0.1.dev0"

ctxlineage/_cli.py

@@ -0,0 +1,84 @@
+"""ctxlineage CLI (installed as `ctxlineage` and `ctxl`)."""
+
+from __future__ import annotations
+
+import json
+import re
+import webbrowser
+from pathlib import Path
+
+import click
+
+from ctxlineage._report import html, normalize, redact
+
+
+@click.group()
+@click.version_option(package_name="ctxlineage")
+def main() -> None:
+    """See exactly what context your LLM calls consumed."""
+
+
+@main.command()
+@click.option(
+    "--dir",
+    "-d",
+    "directory",
+    default=".ctxlineage",
+    show_default=True,
+    help="Directory containing events.jsonl.",
+)
+@click.option(
+    "--out",
+    "-o",
+    default="ctxlineage-report.html",
+    show_default=True,
+    help="Output HTML path.",
+)
+@click.option("--open", "open_browser", is_flag=True, help="Open the report in a browser.")
+@click.option("--json", "as_json", is_flag=True, help="Print report data as JSON instead of HTML.")
+@click.option(
+    "--redact",
+    "redact_patterns",
+    multiple=True,
+    metavar="PATTERN",
+    help="Regex; every match in prompt/output text becomes [redacted]. Repeatable. "
+    "Applied after matching, so token counts and match rates stay honest.",
+)
+def report(
+    directory: str,
+    out: str,
+    open_browser: bool,
+    as_json: bool,
+    redact_patterns: tuple[str, ...],
+) -> None:
+    """Build the HTML report from recorded events."""
+    events_path = Path(directory) / "events.jsonl"
+    if not events_path.exists():
+        raise click.ClickException(
+            f"No events found at {events_path}. "
+            "Run your app with ctxlineage.init() first (or pass --dir)."
+        )
+    events, skipped = normalize.load_events(events_path)
+    data = normalize.build_report_data(events)
+
+    redacted = 0
+    if redact_patterns:
+        try:
+            redacted = redact.apply(data, list(redact_patterns))
+        except re.error as exc:
+            raise click.ClickException(f"Invalid --redact pattern {exc.pattern!r}: {exc}") from exc
+
+    if as_json:
+        click.echo(json.dumps(data, ensure_ascii=False, indent=2))
+        return
+
+    out_path = Path(out)
+    out_path.write_text(html.render(data), encoding="utf-8")
+    summary = (
+        f"{data['stats']['calls']} call(s) across {data['stats']['sessions']} session(s)"
+        + (f", {skipped} malformed line(s) skipped" if skipped else "")
+        + (f", {redacted} match(es) redacted" if redact_patterns else "")
+    )
+    click.echo(f"Wrote {out_path} ({summary})")
+    if open_browser:
+        webbrowser.open(out_path.resolve().as_uri())

ctxlineage/_events.py

@@ -0,0 +1,66 @@
+"""Event construction and the append-only JSONL writer (schema v1)."""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+SCHEMA_VERSION = 1
+
+
+def json_str(value) -> str:
+    """Single serialization policy for anything ctxlineage persists."""
+    return json.dumps(value, ensure_ascii=False, default=str)
+
+
+def new_id() -> str:
+    return uuid.uuid4().hex
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def make_event(
+    event_type: str,
+    session_id: str,
+    payload: dict,
+    *,
+    span_id: str | None = None,
+    call_id: str | None = None,
+) -> dict:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "event_type": event_type,
+        "session_id": session_id,
+        "span_id": span_id,
+        "call_id": call_id,
+        "timestamp": utc_now_iso(),
+        "payload": payload,
+    }
+
+
+class EventWriter:
+    """Append-only JSONL writer. One event per line, no buffering.
+
+    Opens the file per write so a crash never loses buffered events and
+    multiple processes can append to the same file (POSIX append mode).
+    """
+
+    def __init__(self, directory: str | os.PathLike):
+        self._dir = Path(directory)
+        self.path = self._dir / "events.jsonl"
+        self._lock = threading.Lock()
+
+    def write(self, event: dict) -> None:
+        # via json_str: non-JSON values degrade to strings instead of
+        # losing the whole event.
+        line = json_str(event)
+        with self._lock:
+            self._dir.mkdir(parents=True, exist_ok=True)
+            with self.path.open("a", encoding="utf-8") as f:
+                f.write(line + "\n")

ctxlineage/_instrument/__init__.py

@@ -0,0 +1,29 @@
+"""SDK instrumentation orchestration. Each provider module is best-effort."""
+
+from __future__ import annotations
+
+import threading
+
+from ctxlineage._instrument import anthropic_patch, openai_patch
+
+_installed_providers: list[str] | None = None
+# Guards check-then-act on _installed_providers so two concurrent init() calls
+# cannot both run the patch step and double-wrap every SDK method.
+_install_lock = threading.Lock()
+
+
+def install() -> list[str]:
+    """Patch every available SDK once per process. Returns installed provider names."""
+    global _installed_providers
+    if _installed_providers is not None:
+        return _installed_providers
+    with _install_lock:
+        if _installed_providers is not None:  # another thread won the race
+            return _installed_providers
+        providers = []
+        if openai_patch.install():
+            providers.append("openai")
+        if anthropic_patch.install():
+            providers.append("anthropic")
+        _installed_providers = providers
+        return providers

ctxlineage/_instrument/_common.py

@@ -0,0 +1,190 @@
+"""Shared plumbing for SDK patch modules.
+
+Every provider patch stays thin: record kwargs wholesale, dump responses with
+model_dump, pass unknown fields through untouched. Recording must never break
+the host call: wrappers no-op when ctxlineage is unconfigured, and
+_state.emit() already swallows write failures.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+
+import wrapt
+
+from ctxlineage import _events, _state
+from ctxlineage._stack import stack_summary
+
+
+def base_payload(provider: str, api: str, kwargs: dict) -> dict:
+    return {
+        "provider": provider,
+        "api": api,
+        "request": dict(kwargs),
+        "stream": bool(kwargs.get("stream")),
+        "call_stack": stack_summary(),
+    }
+
+
+def dump(obj):
+    try:
+        return obj.model_dump(mode="json")
+    except Exception:
+        return str(obj)
+
+
+def finish_payload(payload: dict, start: float) -> dict:
+    payload["duration_ms"] = (time.monotonic() - start) * 1000
+    return payload
+
+
+def record_response(payload: dict, result) -> None:
+    data = dump(result)
+    payload["response"] = data
+    payload["usage"] = data.get("usage") if isinstance(data, dict) else None
+    _state.emit("llm_call", payload, call_id=_events.new_id())
+
+
+def record_error(payload: dict, exc: BaseException) -> None:
+    payload["error"] = {"type": type(exc).__name__, "message": str(exc)}
+    _state.emit("llm_call", payload, call_id=_events.new_id())
+
+
+class StreamRecorderMixin:
+    """Shared chunk accounting; subclasses only differ in (a)sync plumbing."""
+
+    def _self_init(self, payload: dict, assemble: Callable[[list], dict], span_id=None) -> None:
+        self._self_payload = payload
+        self._self_assemble = assemble
+        self._self_span_id = span_id
+        self._self_chunks: list = []
+        self._self_done = False
+
+    def _self_add(self, chunk) -> None:
+        self._self_chunks.append(dump(chunk))
+
+    def _self_record_error(self, exc: BaseException) -> None:
+        # mid-stream failure (in-band SSE error, network drop): keep the
+        # partial assembly but mark the event so it is distinguishable from
+        # a client-side abandon. GeneratorExit is excluded at the call sites.
+        if not self._self_done:
+            self._self_payload["error"] = {"type": type(exc).__name__, "message": str(exc)}
+
+    def _self_finish(self) -> None:
+        if self._self_done:
+            return
+        self._self_done = True
+        try:
+            payload = self._self_payload
+            payload["response"] = self._self_assemble(self._self_chunks)
+            payload["usage"] = payload["response"].get("usage")
+            _state.emit("llm_call", payload, call_id=_events.new_id(), span_id=self._self_span_id)
+        except Exception as exc:  # e.g. malformed chunk shapes: never raise into the host
+            _state.warn_once(
+                "stream_finish",
+                f"ctxlineage: failed to record a stream ({exc!r}); the stream itself is intact",
+            )
+
+
+class StreamProxy(wrapt.ObjectProxy, StreamRecorderMixin):
+    """Recording proxy over an SDK stream.
+
+    Dunder protocol methods must be defined here: ObjectProxy does not fill
+    type slots, so builtins like next()/anext() bypass __getattr__ delegation
+    and would raise TypeError without explicit definitions. Known limitation:
+    isinstance(proxy, SDKStreamClass) is False when the SDK class uses a
+    custom metaclass __instancecheck__ (anthropic.Stream does).
+    """
+
+    def __init__(self, wrapped, payload: dict, assemble: Callable[[list], dict], span_id=None):
+        super().__init__(wrapped)
+        self._self_init(payload, assemble, span_id)
+
+    def __iter__(self):
+        try:
+            for chunk in self.__wrapped__:
+                self._self_add(chunk)
+                yield chunk
+        except Exception as exc:  # not GeneratorExit: abandonment is not an error
+            self._self_record_error(exc)
+            raise
+        finally:
+            self._self_finish()
+
+    def __next__(self):
+        try:
+            chunk = self.__wrapped__.__next__()
+        except StopIteration:
+            self._self_finish()
+            raise
+        except Exception as exc:
+            self._self_record_error(exc)
+            self._self_finish()
+            raise
+        self._self_add(chunk)
+        return chunk
+
+    def __enter__(self):
+        self.__wrapped__.__enter__()
+        return self
+
+    def __exit__(self, *exc):
+        try:
+            return self.__wrapped__.__exit__(*exc)
+        finally:
+            self._self_finish()
+
+    def close(self):
+        try:
+            return self.__wrapped__.close()
+        finally:
+            self._self_finish()
+
+
+class AsyncStreamProxy(wrapt.ObjectProxy, StreamRecorderMixin):
+    """Async twin of StreamProxy; see its docstring for the dunder rationale."""
+
+    def __init__(self, wrapped, payload: dict, assemble: Callable[[list], dict], span_id=None):
+        super().__init__(wrapped)
+        self._self_init(payload, assemble, span_id)
+
+    async def __aiter__(self):
+        try:
+            async for chunk in self.__wrapped__:
+                self._self_add(chunk)
+                yield chunk
+        except Exception as exc:  # not GeneratorExit: abandonment is not an error
+            self._self_record_error(exc)
+            raise
+        finally:
+            self._self_finish()
+
+    async def __anext__(self):
+        try:
+            chunk = await self.__wrapped__.__anext__()
+        except StopAsyncIteration:
+            self._self_finish()
+            raise
+        except Exception as exc:
+            self._self_record_error(exc)
+            self._self_finish()
+            raise
+        self._self_add(chunk)
+        return chunk
+
+    async def __aenter__(self):
+        await self.__wrapped__.__aenter__()
+        return self
+
+    async def __aexit__(self, *exc):
+        try:
+            return await self.__wrapped__.__aexit__(*exc)
+        finally:
+            self._self_finish()
+
+    async def close(self):
+        try:
+            return await self.__wrapped__.close()
+        finally:
+            self._self_finish()

ctxlineage/_instrument/anthropic_patch.py

@@ -0,0 +1,221 @@
+"""anthropic SDK instrumentation (Messages API, incl. both streaming paths).
+
+Shared design constraints live in _common.py. Two streaming surfaces exist:
+
+- messages.create(stream=True) returns a raw Stream[RawMessageStreamEvent],
+  wrapped in the same recording proxy the openai patch uses.
+- messages.stream() never goes through create(): it returns a manager that
+  fires the HTTP request in __enter__ and wraps the raw stream in a
+  MessageStream. The manager proxy below swaps that MessageStream's
+  _raw_stream for a recording proxy, so every consumption path (iteration,
+  text_stream, get_final_message) and MessageStream.close() flow through it
+  and both streaming paths share one raw-event assembler.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+import wrapt
+
+from ctxlineage import _span, _state
+from ctxlineage._instrument._common import (
+    AsyncStreamProxy,
+    StreamProxy,
+    base_payload,
+    finish_payload,
+    record_error,
+    record_response,
+)
+
+_PATCHED = False
+# Guards check-then-act on _PATCHED so concurrent installs wrap each method once.
+_install_lock = threading.Lock()
+
+
+def install() -> bool:
+    global _PATCHED
+    if _PATCHED:
+        return True
+    with _install_lock:
+        if _PATCHED:  # another thread won the race
+            return True
+        try:
+            import anthropic  # noqa: F401
+        except ImportError:
+            return False
+        wrapt.wrap_function_wrapper("anthropic.resources.messages", "Messages.create", _sync_create)
+        wrapt.wrap_function_wrapper(
+            "anthropic.resources.messages", "AsyncMessages.create", _async_create
+        )
+        wrapt.wrap_function_wrapper("anthropic.resources.messages", "Messages.stream", _sync_stream)
+        wrapt.wrap_function_wrapper(
+            "anthropic.resources.messages", "AsyncMessages.stream", _async_stream
+        )
+        _PATCHED = True
+        return True
+
+
+def _sync_create(wrapped, instance, args, kwargs):
+    if not _state.is_configured():
+        return wrapped(*args, **kwargs)
+    payload = base_payload("anthropic", "messages", kwargs)
+    start = time.monotonic()
+    try:
+        result = wrapped(*args, **kwargs)
+    except Exception as exc:
+        record_error(finish_payload(payload, start), exc)
+        raise
+    finish_payload(payload, start)
+    if payload["stream"]:
+        # streams may be consumed after the span exits: bind the span now
+        return StreamProxy(result, payload, _assemble_messages, _span.current_id())
+    record_response(payload, result)
+    return result
+
+
+async def _async_create(wrapped, instance, args, kwargs):
+    if not _state.is_configured():
+        return await wrapped(*args, **kwargs)
+    payload = base_payload("anthropic", "messages", kwargs)
+    start = time.monotonic()
+    try:
+        result = await wrapped(*args, **kwargs)
+    except Exception as exc:
+        record_error(finish_payload(payload, start), exc)
+        raise
+    finish_payload(payload, start)
+    if payload["stream"]:
+        # streams may be consumed after the span exits: bind the span now
+        return AsyncStreamProxy(result, payload, _assemble_messages, _span.current_id())
+    record_response(payload, result)
+    return result
+
+
+def _sync_stream(wrapped, instance, args, kwargs):
+    if not _state.is_configured():
+        return wrapped(*args, **kwargs)
+    payload = base_payload("anthropic", "messages", kwargs)
+    payload["stream"] = True  # .stream() takes no stream kwarg
+    return _ManagerProxy(wrapped(*args, **kwargs), payload, _span.current_id())
+
+
+def _async_stream(wrapped, instance, args, kwargs):
+    # AsyncMessages.stream is a sync method returning an async manager
+    if not _state.is_configured():
+        return wrapped(*args, **kwargs)
+    payload = base_payload("anthropic", "messages", kwargs)
+    payload["stream"] = True
+    return _AsyncManagerProxy(wrapped(*args, **kwargs), payload, _span.current_id())
+
+
+class _ManagerProxy(wrapt.ObjectProxy):
+    """Records through a MessageStreamManager; the request only fires in __enter__."""
+
+    def __init__(self, wrapped, payload: dict, span_id=None):
+        super().__init__(wrapped)
+        self._self_payload = payload
+        self._self_span_id = span_id
+
+    def __enter__(self):
+        start = time.monotonic()
+        try:
+            stream = self.__wrapped__.__enter__()
+        except Exception as exc:
+            record_error(finish_payload(self._self_payload, start), exc)
+            raise
+        finish_payload(self._self_payload, start)
+        # MessageStream consumes lazily, so the fresh _raw_stream can be
+        # swapped for a recording proxy; MessageStream.close() closes it too.
+        # _raw_stream is a private SDK attribute: if the swap fails, hand back
+        # the untouched stream (unrecorded) rather than break the host app.
+        try:
+            stream._raw_stream = StreamProxy(
+                stream._raw_stream, self._self_payload, _assemble_messages, self._self_span_id
+            )
+        except Exception as exc:
+            _state.warn_once(
+                "anthropic_raw_stream_swap",
+                f"ctxlineage: could not instrument messages.stream() ({exc!r}); "
+                "this stream will not be recorded",
+            )
+        return stream
+
+    def __exit__(self, *exc):
+        return self.__wrapped__.__exit__(*exc)
+
+
+class _AsyncManagerProxy(wrapt.ObjectProxy):
+    """Async twin of _ManagerProxy (AsyncMessageStreamManager)."""
+
+    def __init__(self, wrapped, payload: dict, span_id=None):
+        super().__init__(wrapped)
+        self._self_payload = payload
+        self._self_span_id = span_id
+
+    async def __aenter__(self):
+        start = time.monotonic()
+        try:
+            stream = await self.__wrapped__.__aenter__()
+        except Exception as exc:
+            record_error(finish_payload(self._self_payload, start), exc)
+            raise
+        finish_payload(self._self_payload, start)
+        # See _ManagerProxy.__enter__: a failed swap degrades to no recording.
+        try:
+            stream._raw_stream = AsyncStreamProxy(
+                stream._raw_stream, self._self_payload, _assemble_messages, self._self_span_id
+            )
+        except Exception as exc:
+            _state.warn_once(
+                "anthropic_raw_stream_swap",
+                f"ctxlineage: could not instrument messages.stream() ({exc!r}); "
+                "this stream will not be recorded",
+            )
+        return stream
+
+    async def __aexit__(self, *exc):
+        return await self.__wrapped__.__aexit__(*exc)
+
+
+def _merge_usage(usage: dict, new) -> None:
+    # message_delta's usage model dumps unset fields as None (e.g. input_tokens);
+    # overlaying those verbatim would erase message_start's real counts.
+    if isinstance(new, dict):
+        usage.update({k: v for k, v in new.items() if v is not None})
+
+
+def _assemble_messages(chunks: list) -> dict:
+    """Reduce raw Messages stream events into one response-like summary."""
+    content: dict[int, str] = {}
+    usage: dict = {}
+    stop_reason = None
+    message_id = None
+    model = None
+    for chunk in chunks:
+        if not isinstance(chunk, dict):
+            continue
+        kind = chunk.get("type", "")
+        if kind == "message_start":
+            message = chunk.get("message") or {}
+            message_id = message.get("id") or message_id
+            model = message.get("model") or model
+            _merge_usage(usage, message.get("usage"))
+        elif kind == "content_block_delta":
+            delta = chunk.get("delta") or {}
+            if delta.get("type") == "text_delta" and delta.get("text"):
+                index = chunk.get("index", 0)
+                content[index] = content.get(index, "") + delta["text"]
+        elif kind == "message_delta":
+            _merge_usage(usage, chunk.get("usage"))
+            stop_reason = (chunk.get("delta") or {}).get("stop_reason") or stop_reason
+    return {
+        "object": "message.assembled",
+        "id": message_id,
+        "model": model,
+        "content": {str(i): text for i, text in content.items()},
+        "stop_reason": stop_reason,
+        "usage": usage or None,
+        "chunk_count": len(chunks),
+    }