thrdi 0.0.1__py3-none-any.whl

thirdeye/__init__.py

@@ -0,0 +1,4 @@
+try:
+    from thirdeye._version import version as __version__
+except ImportError:
+    __version__ = "0.0.0+unknown"

thirdeye/__main__.py

@@ -0,0 +1,4 @@
+from thirdeye.cli import main
+
+if __name__ == "__main__":
+    main()

thirdeye/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.0.1'
+__version_tuple__ = version_tuple = (0, 0, 1)
+
+__commit_id__ = commit_id = None

thirdeye/cli.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import click
+
+from thirdeye import __version__
+from thirdeye.commands.add import add, remove
+from thirdeye.commands.ingest import ingest
+from thirdeye.commands.reads import event, events, list_sessions, search, show, stats, tail
+from thirdeye.commands.tags import tag, tags
+
+
+@click.group(name="thirdeye", help="Trace agentic CLIs to a unified local store.")
+@click.version_option(__version__, prog_name="thirdeye")
+def main() -> None:
+    pass
+
+
+main.add_command(add)
+main.add_command(remove)
+main.add_command(ingest)
+main.add_command(list_sessions)
+main.add_command(show)
+main.add_command(events)
+main.add_command(tail)
+main.add_command(event)
+main.add_command(search)
+main.add_command(tag)
+main.add_command(tags)
+main.add_command(stats)

thirdeye/codec.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import Any
+
+import msgpack
+import zstandard as zstd
+
+_compressor = zstd.ZstdCompressor()
+_decompressor = zstd.ZstdDecompressor()
+
+
+def encode_event(event: dict[str, Any]) -> bytes:
+    packed = msgpack.packb(event, use_bin_type=True)
+    return _compressor.compress(packed)
+
+
+def decode_event(frame: bytes) -> dict[str, Any]:
+    packed = _decompressor.decompress(frame)
+    return msgpack.unpackb(packed, raw=False)

thirdeye/commands/add.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import click
+
+from thirdeye.platforms.base import Platform
+from thirdeye.platforms.claude.install import ClaudePlatform
+from thirdeye.platforms.codex.install import CodexPlatform
+from thirdeye.platforms.gemini.install import GeminiPlatform
+
+PLATFORMS: dict[str, type[Platform]] = {
+    "claude": ClaudePlatform,
+    "gemini": GeminiPlatform,
+    "codex": CodexPlatform,
+}
+
+
+def _platform_options(fn):
+    fn = click.option("--codex", "platform_flag", flag_value="codex", help="Codex CLI.")(fn)
+    fn = click.option("--gemini", "platform_flag", flag_value="gemini", help="Gemini CLI.")(fn)
+    fn = click.option("--claude", "platform_flag", flag_value="claude", help="Claude Code.")(fn)
+    return fn
+
+
+def _resolve_platform(platform_flag: str | None) -> Platform:
+    if not platform_flag:
+        raise click.UsageError("Pick a platform: --claude, --gemini, --codex")
+    return PLATFORMS[platform_flag]()
+
+
+@click.command(help="Install tracing hooks for an agentic platform.")
+@_platform_options
+def add(platform_flag: str | None) -> None:
+    platform = _resolve_platform(platform_flag)
+    platform.install()
+    click.echo(f"Installed tracing for {platform.display_name}")
+
+
+@click.command(help="Remove tracing hooks for an agentic platform.")
+@_platform_options
+def remove(platform_flag: str | None) -> None:
+    platform = _resolve_platform(platform_flag)
+    platform.uninstall()
+    click.echo(f"Removed tracing for {platform.display_name}")

thirdeye/commands/ingest.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+
+from thirdeye.config import Config
+from thirdeye.ids import new_ulid
+from thirdeye.store import Store
+
+
+@click.command(help="Read newline-delimited JSON events from stdin and append them to a session.")
+@click.option("--platform", required=True, help="Platform name (e.g. claude, cursor).")
+@click.option("--session-id", default=None, help="Session ID. Generated if omitted.")
+@click.option("--cwd", default=None, help="Working directory for the session.")
+def ingest(platform: str, session_id: str | None, cwd: str | None) -> None:
+    sid = session_id or new_ulid()
+    cwd_val = cwd or "."
+    store = Store(Config.load())
+    written = 0
+    with store.open_session(sid, platform=platform, cwd=cwd_val) as w:
+        for line in sys.stdin:
+            line = line.strip()
+            if not line:
+                continue
+            obj = json.loads(line)
+            t = obj.pop("t", "event")
+            data = obj.pop("data", None)
+            w.append(t, data)
+            written += 1
+    click.echo(f"{sid}\t{written} events", err=True)
+    click.echo(sid)

thirdeye/commands/reads.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+
+import click
+
+from thirdeye.config import Config
+from thirdeye.render import render_event_jsonl, render_event_terse, render_event_tree
+from thirdeye.search import search as search_fn
+from thirdeye.store import Store
+from thirdeye.tags import validate_tag
+from thirdeye.timeparse import parse_when
+
+
+def _store() -> Store:
+    return Store(Config.load())
+
+
+def _emit_events(events, *, json_mode: bool, tree_mode: bool, width: int) -> None:
+    for event in events:
+        if json_mode:
+            click.echo(render_event_jsonl(event))
+        elif tree_mode:
+            click.echo(render_event_tree(event))
+        else:
+            click.echo(render_event_terse(event, width=width))
+
+
+def _resolve_platform(platform: str | None, harness: str | None) -> str | None:
+    if platform is not None and harness is not None and platform != harness:
+        raise click.ClickException("--harness and --platform disagree")
+    return platform if platform is not None else harness
+
+
+def _parse_when_or_die(value: str | None, flag: str):
+    if value is None:
+        return None
+    try:
+        return parse_when(value)
+    except ValueError as e:
+        raise click.ClickException(f"could not parse {flag} {value!r}: {e}") from e
+
+
+def _resolve_tags(tags: tuple[str, ...]) -> set[str] | None:
+    if not tags:
+        return None
+    resolved: set[str] = set()
+    for t in tags:
+        try:
+            resolved.add(validate_tag(t))
+        except ValueError as e:
+            raise click.ClickException(str(e)) from e
+    return resolved
+
+
+@click.command("list", help="List recorded sessions.")
+@click.option("--platform", default=None)
+@click.option("--harness", default=None, help="Alias for --platform.")
+@click.option("--cwd", default=None)
+@click.option("--status", default=None)
+@click.option("--tag", "tags", multiple=True, help="Filter by tag (repeatable, AND'd).")
+@click.option("--since", default=None, help="Include sessions active at/after this time.")
+@click.option("--until", default=None, help="Include sessions active at/before this time.")
+@click.option("--json", "json_mode", is_flag=True, help="JSON-per-line output (default).")
+@click.option("--tree", is_flag=True, help="Human-readable tree output.")
+def list_sessions(platform, harness, cwd, status, tags, since, until, json_mode, tree):
+    resolved_platform = _resolve_platform(platform, harness)
+    resolved_tags = _resolve_tags(tags)
+    since_dt = _parse_when_or_die(since, "--since")
+    until_dt = _parse_when_or_die(until, "--until")
+
+    store = _store()
+    for meta in store.list_sessions(
+        platform=resolved_platform,
+        cwd=cwd,
+        status=status,
+        tags=resolved_tags,
+        since=since_dt,
+        until=until_dt,
+    ):
+        if tree:
+            click.echo(
+                f"{meta.session_id}  [{meta.platform}]  {meta.cwd}  "
+                f"{meta.status}  events={meta.event_count}"
+            )
+        else:
+            click.echo(json.dumps(asdict(meta), default=str, separators=(",", ":")))
+
+
+@click.command(help="Print events for a session.")
+@click.argument("session_prefix")
+@click.option("--type", "types", multiple=True, help="Filter by event type (repeatable).")
+@click.option("--json", "json_mode", is_flag=True)
+@click.option("--tree", "tree_mode", is_flag=True)
+@click.option("--width", default=120, type=int, help="Line width (0 = unlimited).")
+def events(session_prefix, types, json_mode, tree_mode, width):
+    reader = _store().reader(session_prefix)
+    iter_ = reader.iter_events(types=set(types) if types else None)
+    _emit_events(iter_, json_mode=json_mode, tree_mode=tree_mode, width=width)
+
+
+@click.command(help="Show all events for a session (alias of `events`).")
+@click.argument("session_prefix")
+@click.option("--json", "json_mode", is_flag=True)
+@click.option("--tree", "tree_mode", is_flag=True)
+@click.option("--width", default=120, type=int)
+def show(session_prefix, json_mode, tree_mode, width):
+    reader = _store().reader(session_prefix)
+    _emit_events(reader.iter_events(), json_mode=json_mode, tree_mode=tree_mode, width=width)
+
+
+@click.command(help="Last N events for a session.")
+@click.argument("session_prefix")
+@click.option("-n", "n", default=10, type=int)
+@click.option("--json", "json_mode", is_flag=True)
+@click.option("--tree", "tree_mode", is_flag=True)
+@click.option("--width", default=120, type=int)
+def tail(session_prefix, n, json_mode, tree_mode, width):
+    reader = _store().reader(session_prefix)
+    all_events = list(reader.iter_events())
+    _emit_events(all_events[-n:], json_mode=json_mode, tree_mode=tree_mode, width=width)
+
+
+@click.command(help="Print a single event by seq, fully expanded.")
+@click.argument("session_prefix")
+@click.argument("seq", type=int)
+@click.option("--field", default=None, help="Print only one field of `data`.")
+def event(session_prefix, seq, field):
+    e = _store().reader(session_prefix).get_event(seq)
+    if field is not None:
+        data = e.get("data")
+        if isinstance(data, dict) and field in data:
+            value = data[field]
+            if isinstance(value, (str, int, float, bool)):
+                click.echo(value)
+            else:
+                click.echo(json.dumps(value, default=str, ensure_ascii=False))
+            return
+        raise click.ClickException(f"field {field!r} not found in event data")
+    click.echo(json.dumps(e, default=str, ensure_ascii=False, indent=2))
+
+
+@click.command(help="Search across sessions.")
+@click.argument("query")
+@click.option("--platform", default=None)
+@click.option("--harness", default=None, help="Alias for --platform.")
+@click.option("--cwd", default=None)
+@click.option("--tag", "tags", multiple=True, help="Filter by tag (repeatable, AND'd).")
+@click.option("--since", default=None, help="Include events at/after this time.")
+@click.option("--until", default=None, help="Include events at/before this time.")
+def search(query, platform, harness, cwd, tags, since, until):
+    resolved_platform = _resolve_platform(platform, harness)
+    resolved_tags = _resolve_tags(tags)
+    since_dt = _parse_when_or_die(since, "--since")
+    until_dt = _parse_when_or_die(until, "--until")
+
+    for hit in search_fn(
+        _store(),
+        query,
+        platform=resolved_platform,
+        cwd=cwd,
+        tags=resolved_tags,
+        since=since_dt,
+        until=until_dt,
+    ):
+        click.echo(json.dumps(asdict(hit), default=str, ensure_ascii=False, separators=(",", ":")))
+
+
+@click.command(help="Stats for a session, or global if no id given.")
+@click.argument("session_prefix", required=False)
+def stats(session_prefix):
+    store = _store()
+    s = store.stats(session_id=session_prefix) if session_prefix else store.stats()
+    click.echo(json.dumps(s, default=str, ensure_ascii=False))

thirdeye/commands/tags.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+
+import click
+
+from thirdeye.config import Config
+from thirdeye.meta import read_meta, write_meta
+from thirdeye.paths import meta_path, session_dir
+from thirdeye.store import Store
+from thirdeye.tags import TagStore, validate_tag
+
+
+def _store() -> Store:
+    return Store(Config.load())
+
+
+def _parse_tags(raw: str) -> list[str]:
+    out: list[str] = []
+    for piece in raw.split(","):
+        orig = piece.strip()
+        if not orig:
+            continue
+        try:
+            out.append(validate_tag(orig.lower()))
+        except ValueError:
+            raise click.ClickException(
+                f"invalid tag '{orig}': must match [a-z0-9_-]{{1,64}}"
+            ) from None
+    return out
+
+
+@click.command("tag", help="Add, remove, or list tags on session events.")
+@click.argument("session_prefix")
+@click.argument("seq", required=False, type=int)
+@click.option("--add", "add_raw", default=None, help="Comma-separated tags to add.")
+@click.option("--remove", "remove_raw", default=None, help="Comma-separated tags to remove.")
+@click.option("--list", "list_mode", is_flag=True, help="List tagged events in session.")
+def tag(session_prefix, seq, add_raw, remove_raw, list_mode):
+    store = _store()
+    try:
+        platform, sid = store.resolve_session_id(session_prefix)
+    except ValueError as e:
+        raise click.ClickException(str(e)) from None
+
+    sd = session_dir(store.config.root, platform, sid)
+    mp = meta_path(sd)
+
+    if list_mode:
+        if add_raw is not None or remove_raw is not None:
+            raise click.ClickException("--list cannot be combined with --add or --remove")
+        if seq is not None:
+            raise click.ClickException("--list does not take a seq argument")
+        ts = TagStore(sd)
+        for s in sorted(ts.all_tags().keys()):
+            tags_sorted = sorted(ts.tags_for(s))
+            click.echo(json.dumps({"seq": s, "tags": tags_sorted}, separators=(",", ":")))
+        return
+
+    if add_raw is None and remove_raw is None:
+        raise click.ClickException("provide --add, --remove, or --list")
+    if seq is None:
+        raise click.ClickException("SEQ is required for --add/--remove")
+
+    meta = read_meta(mp)
+    if meta is None:
+        raise click.ClickException(f"no meta for session {sid}")
+    n = meta.event_count
+    if seq < 0 or seq >= n:
+        raise click.ClickException(f"seq {seq} not found in session {sid} (event_count={n})")
+
+    ts = TagStore(sd)
+    if add_raw is not None:
+        for t in _parse_tags(add_raw):
+            ts.add(seq, t)
+    if remove_raw is not None:
+        for t in _parse_tags(remove_raw):
+            ts.remove(seq, t)
+
+    meta.tag_count = ts.tagged_seq_count()
+    write_meta(mp, meta)
+
+
+@click.command("tags", help="Show global tag inventory across all sessions.")
+@click.option("--json", "json_mode", is_flag=True, help="Emit one JSON object per line.")
+def tags(json_mode):
+    store = _store()
+    event_counts: dict[str, int] = {}
+    session_counts: dict[str, int] = {}
+    for meta in store.list_sessions():
+        sd = session_dir(store.config.root, meta.platform, meta.session_id)
+        ts = TagStore(sd)
+        per_tag_events: dict[str, int] = {}
+        for tag_set in ts.all_tags().values():
+            for t in tag_set:
+                per_tag_events[t] = per_tag_events.get(t, 0) + 1
+        for t, c in per_tag_events.items():
+            event_counts[t] = event_counts.get(t, 0) + c
+            session_counts[t] = session_counts.get(t, 0) + 1
+
+    rows = sorted(event_counts.items(), key=lambda kv: (-kv[1], kv[0]))
+    for tag_name, ev_count in rows:
+        sess_count = session_counts[tag_name]
+        if json_mode:
+            click.echo(
+                json.dumps(
+                    {"tag": tag_name, "events": ev_count, "sessions": sess_count},
+                    separators=(",", ":"),
+                )
+            )
+        else:
+            click.echo(f"{tag_name}\t{ev_count}\t{sess_count}")

thirdeye/config.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def default_root() -> Path:
+    env = os.environ.get("THIRDEYE_HOME")
+    if env:
+        return Path(env).expanduser()
+    return Path.home() / ".thirdeye"
+
+
+@dataclass(frozen=True)
+class Config:
+    root: Path
+
+    @classmethod
+    def load(cls) -> Config:
+        return cls(root=default_root())
+
+    @property
+    def traces_dir(self) -> Path:
+        return self.root / "traces"
+
+    @property
+    def config_file(self) -> Path:
+        return self.root / "config.yaml"
+
+
+def load() -> Config:
+    return Config.load()

thirdeye/ids.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import os
+import time
+
+# Crockford base32 (excludes I, L, O, U)
+_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+
+def new_ulid() -> str:
+    """26-char Crockford-base32 ULID: 48 bits ms timestamp + 80 bits randomness."""
+    ts_ms = int(time.time() * 1000) & ((1 << 48) - 1)
+    rand = int.from_bytes(os.urandom(10), "big")
+    val = (ts_ms << 80) | rand
+    out = []
+    for _ in range(26):
+        out.append(_ALPHABET[val & 0x1F])
+        val >>= 5
+    return "".join(reversed(out))
+
+
+def resolve_prefix(prefix: str, candidates: list[str]) -> str:
+    """Return the unique candidate starting with `prefix`. Raise ValueError if 0 or >1 match."""
+    matches = [c for c in candidates if c.startswith(prefix)]
+    if not matches:
+        raise ValueError(f"no session matching prefix {prefix!r}")
+    if len(matches) > 1:
+        raise ValueError(f"prefix {prefix!r} ambiguous: {matches!r}")
+    return matches[0]

thirdeye/index.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import os
+import struct
+from pathlib import Path
+
+import zstandard as zstd
+
+_ENTRY_FMT = "<Q"
+_ENTRY_SIZE = 8
+
+
+class IndexWriter:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._fp = open(path, "ab")
+
+    def append(self, offset: int) -> None:
+        self._fp.write(struct.pack(_ENTRY_FMT, offset))
+        self._fp.flush()
+        os.fsync(self._fp.fileno())
+
+    def close(self) -> None:
+        self._fp.close()
+
+    def __enter__(self) -> IndexWriter:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class IndexReader:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+
+    def count(self) -> int:
+        if not self.path.exists():
+            return 0
+        return self.path.stat().st_size // _ENTRY_SIZE
+
+    def get(self, seq: int) -> int:
+        if seq < 0 or seq >= self.count():
+            raise IndexError(f"seq {seq} out of range (count={self.count()})")
+        with open(self.path, "rb") as fp:
+            fp.seek(seq * _ENTRY_SIZE)
+            return struct.unpack(_ENTRY_FMT, fp.read(_ENTRY_SIZE))[0]
+
+    def all_offsets(self) -> list[int]:
+        if not self.path.exists():
+            return []
+        with open(self.path, "rb") as fp:
+            data = fp.read()
+        return [
+            struct.unpack(_ENTRY_FMT, data[i : i + _ENTRY_SIZE])[0]
+            for i in range(0, len(data), _ENTRY_SIZE)
+        ]
+
+
+def rebuild_index(events_log: Path, idx_path: Path) -> int:
+    """Walk events.alog frame-by-frame; rewrite idx_path. Returns event count."""
+    if idx_path.exists():
+        idx_path.unlink()
+    if not events_log.exists() or events_log.stat().st_size == 0:
+        idx_path.touch()
+        return 0
+
+    data = events_log.read_bytes()
+    offsets: list[int] = []
+    pos = 0
+    while pos < len(data):
+        offsets.append(pos)
+        dobj = zstd.ZstdDecompressor().decompressobj()
+        try:
+            dobj.decompress(data[pos:])
+        except zstd.ZstdError:
+            offsets.pop()
+            break
+        remaining = len(dobj.unused_data)
+        pos = len(data) - remaining
+
+    with IndexWriter(idx_path) as w:
+        for off in offsets:
+            w.append(off)
+    return len(offsets)

thirdeye/meta.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import os
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+SCHEMA_VERSION = 2
+
+
+@dataclass
+class SessionMeta:
+    session_id: str
+    platform: str
+    cwd: str
+    started_at: str
+    ended_at: str | None
+    status: str  # "open" | "closed" | "stale"
+    event_count: int
+    last_seq: int  # -1 if no events yet
+    last_ts: str | None
+    tag_count: int = 0
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+def write_meta(path: Path, meta: SessionMeta) -> None:
+    payload = {"schema_version": SCHEMA_VERSION, **asdict(meta)}
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    with open(tmp, "w") as f:
+        yaml.safe_dump(payload, f, sort_keys=False)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(tmp, path)
+
+
+def read_meta(path: Path) -> SessionMeta | None:
+    if not path.exists():
+        return None
+    with open(path) as f:
+        raw = yaml.safe_load(f) or {}
+    raw.pop("schema_version", None)
+    raw.setdefault("extra", {})
+    raw.setdefault("tag_count", 0)
+    return SessionMeta(**raw)

thirdeye/paths.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+
+def sessions_root(thirdeye_home: Path) -> Path:
+    return thirdeye_home / "traces"
+
+
+def platform_dir(thirdeye_home: Path, platform: str) -> Path:
+    return sessions_root(thirdeye_home) / platform
+
+
+def session_dir(thirdeye_home: Path, platform: str, session_id: str) -> Path:
+    return platform_dir(thirdeye_home, platform) / session_id
+
+
+def events_path(session_dir_: Path) -> Path:
+    return session_dir_ / "events.alog"
+
+
+def index_path(session_dir_: Path) -> Path:
+    return session_dir_ / "events.idx"
+
+
+def meta_path(session_dir_: Path) -> Path:
+    return session_dir_ / "meta.yaml"
+
+
+def tags_path(session_dir_: Path) -> Path:
+    return session_dir_ / "tags.jsonl"