ka-telemetry 0.1.0__py3-none-any.whl

ka_telemetry/__init__.py

@@ -0,0 +1,7 @@
+"""ka_telemetry reads the transcripts Claude Code keeps on this machine and reports the tokens
+they record: per background run, per workflow step, and the current context size of one
+transcript. The readers sit in the modules of this package; this file holds no implementation."""
+
+from ka_telemetry import context_gauge, flow_usage, run_usage
+
+__all__ = ["context_gauge", "flow_usage", "run_usage"]

ka_telemetry/__main__.py

@@ -0,0 +1,15 @@
+"""`python3 -m ka_telemetry` — runs the same command as the installed `ka-telemetry`.
+
+It adds no parser and no dispatch of its own: every argument list goes to `ka_telemetry.cli.main`,
+the target `pyproject.toml` names for the console entry, so the two ways in print the same thing
+and exit with the same status.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from ka_telemetry.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

ka_telemetry/cli.py

@@ -0,0 +1,185 @@
+"""cli — the one `ka-telemetry` command: `runs`, `steps`, `context`, `receive`, `agents`, `check`,
+`turn-on`.
+
+`runs`, `steps`, `receive`, `agents`, `check` and `turn-on` hand their arguments to the module's
+own `main`, so each keeps its own parser and nothing is parsed twice. `context` is the one command
+with no `main` of its own: it wires the filesystem port here, calls `context_gauge.read_context`
+with `context_gauge.current_context` as its size reader, and prints the size and what could not be
+read. No counting, grouping, parsing or storing is done in this module.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ka_telemetry import context_gauge, flow_usage, receiver, run_usage, stream_usage, turn_on
+
+_NETWORK_PROMISE = (
+    "This tool sends no telemetry and makes no network call except the ones the job you "
+    "asked for requires."
+)
+
+
+def _top_parser() -> run_usage.CommandParser:
+    """The parser for `ka-telemetry` itself. It lists the commands and rejects what is not one;
+    a command's own arguments belong to the command's parser, built where the command is run."""
+    parser = run_usage.CommandParser(
+        prog="ka-telemetry",
+        next_step="Run `ka-telemetry --help` to see the commands and what each one accepts.",
+        description=(
+            "Reads the transcripts Claude Code keeps on this machine and reports the tokens "
+            "they record: per background run, per workflow step, and the current context size "
+            "of one transcript. Those three reports show no cost, because ka-telemetry counts "
+            "tokens and does not price them. It also receives the telemetry Claude Code can "
+            "send as OpenTelemetry over HTTP in JSON, writes it to files on this machine, and "
+            "reads those files for a per-agent report of tokens, cost and duration, and for a "
+            "totals check that holds each session's request costs against Claude Code's cost "
+            "metric. Every cost in those two comes from what Claude Code reported; "
+            "ka-telemetry never computes a cost from tokens."
+        ),
+        epilog=_NETWORK_PROMISE,
+    )
+    commands = parser.add_subparsers(
+        title="commands",
+        dest="command",
+        required=True,
+        metavar="{runs,steps,context,receive,agents,check,turn-on}",
+        parser_class=argparse.ArgumentParser,
+    )
+    commands.add_parser(
+        "runs",
+        add_help=False,
+        help="tokens used by each background run, and by each run you name by session id",
+    )
+    commands.add_parser(
+        "steps", add_help=False, help="tokens used by each step of a workflow run"
+    )
+    commands.add_parser(
+        "context", add_help=False, help="the current context size of one transcript"
+    )
+    commands.add_parser(
+        "receive",
+        add_help=False,
+        help="receive the telemetry Claude Code sends and write it to files on this machine",
+    )
+    commands.add_parser(
+        "agents",
+        add_help=False,
+        help="tokens, cost and duration per agent, read from the received telemetry",
+    )
+    commands.add_parser(
+        "check",
+        add_help=False,
+        help="each session's request costs checked against Claude Code's cost metric",
+    )
+    commands.add_parser(
+        "turn-on",
+        add_help=False,
+        help="write the keys that make Claude Code send its telemetry to the receiver on this "
+        "machine into a Claude Code settings file, remove them, or print them for one run",
+    )
+    return parser
+
+
+def _context_parser() -> run_usage.CommandParser:
+    parser = run_usage.CommandParser(
+        prog="ka-telemetry context",
+        next_step="Run `ka-telemetry context --help` to see what it accepts.",
+        description=(
+            "Reports the current context size of one Claude Code transcript: the input, "
+            "cache-read and cache-write tokens of the last response in it, added together. "
+            "Output tokens are not part of it."
+        ),
+    )
+    parser.add_argument(
+        "transcript",
+        metavar="TRANSCRIPT",
+        help="path to a transcript file, named <session id>.jsonl",
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="print the result as JSON instead of a line of text"
+    )
+    return parser
+
+
+def build_files() -> run_usage.Files:
+    """The filesystem port the context command reads through. The one place this module makes it."""
+    return run_usage.Files()
+
+
+def context_size_reader(path: Path, files: run_usage.Files) -> int | None:
+    """The size reader `read_context` is wired with: the scalar `current_context`, so the size
+    arithmetic stays in `context_gauge` and is never restated here."""
+    return context_gauge.current_context(path, files)
+
+
+# The words are `change_text.md`'s, each line whole so none is assembled from fragments.
+_CONTEXT_SIZE_KNOWN = "Context size: {size} tokens"
+_CONTEXT_SIZE_UNKNOWN = "Context size: unknown — no assistant usage read from {path}"
+_CONTEXT_LINES_SKIPPED_ONE = " — 1 unreadable line skipped in this transcript"
+_CONTEXT_LINES_SKIPPED_MANY = " — {line_count} unreadable lines skipped in this transcript"
+_CONTEXT_NOT_OPENED = (
+    "Context size: unknown — the transcript {path} could not be opened. "
+    "Run this command again once it can be read."
+)
+
+
+def _context_text(reading: context_gauge.ContextReading, transcript: str) -> str:
+    if reading.unreadable_transcripts:
+        return _CONTEXT_NOT_OPENED.format(path=transcript)
+    if reading.context_size is None:
+        line = _CONTEXT_SIZE_UNKNOWN.format(path=transcript)
+    else:
+        line = _CONTEXT_SIZE_KNOWN.format(size=reading.context_size)
+    if reading.unreadable_lines == 1:
+        line += _CONTEXT_LINES_SKIPPED_ONE
+    elif reading.unreadable_lines > 1:
+        line += _CONTEXT_LINES_SKIPPED_MANY.format(line_count=reading.unreadable_lines)
+    return line
+
+
+def _context(argv: list[str]) -> int:
+    args = _context_parser().parse_args(argv)
+    reading = context_gauge.read_context(
+        Path(args.transcript), build_files(), size_reader=context_size_reader
+    )
+
+    if args.json:
+        payload = {
+            "transcript": args.transcript,
+            "context_size": reading.context_size,
+            "unreadable_lines": reading.unreadable_lines,
+        }
+        if reading.unreadable_transcripts:
+            payload["unreadable_transcripts"] = reading.unreadable_transcripts
+        print(json.dumps(payload, indent=2))
+    else:
+        print(_context_text(reading, args.transcript))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    command, rest = (args[0], args[1:]) if args else (None, [])
+
+    if command == "runs":
+        return run_usage.main(rest)
+    if command == "steps":
+        return flow_usage.main(rest)
+    if command == "context":
+        return _context(rest)
+    if command == "receive":
+        return receiver.main(rest)
+    if command == "agents":
+        return stream_usage.main(rest)
+    if command == "check":
+        return stream_usage.check_main(rest)
+    if command == "turn-on":
+        return turn_on.main(rest)
+
+    # Nothing to run: a help request, or a usage error (no command, an unknown one, a stray flag).
+    _top_parser().parse_args(args)
+    return 0

ka_telemetry/context_gauge.py

@@ -0,0 +1,87 @@
+"""context_gauge — how large a run's context is right now.
+
+A caller that wants to know how full a run's context is needs one number: the size of the context
+the run's latest request carried. `run_usage` sums a run's spend per class over the whole
+transcript, which is the wrong figure for this: the cache classes repeat on every request, so a
+sum over responses counts the same context once per turn. The current context is the **last**
+response's `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`, and nothing
+else. `output_tokens` is what the response produced, not what it was given, so it is left out.
+
+The de-duplication per `message.id` and the tolerance of a half-written final line are
+`run_usage.usage_records`'s, reused rather than restated: a transcript is read while its own run
+is still writing to it. This module takes no arguments and prints nothing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from ka_telemetry import run_usage
+
+_CONTEXT_CLASSES = ("input_tokens", "cache_read_input_tokens", "cache_creation_input_tokens")
+
+
+def current_context(path: Path, files: run_usage.Files) -> int | None:
+    """The three input classes of the newest API response in `path`, summed, or `None` when the
+    transcript is unreadable or holds no assistant usage.
+
+    A class the response does not carry counts as 0, so a response that never wrote the cache
+    still gives a number rather than hiding the ones it did carry.
+    """
+    latest_usage = None
+    for usage, _model, _timestamp in run_usage.usage_records(path, files):
+        latest_usage = usage
+    if latest_usage is None:
+        return None
+    return sum(latest_usage.get(name) or 0 for name in _CONTEXT_CLASSES)
+
+
+@dataclass(frozen=True)
+class ContextReading:
+    """What one transcript came to for `context`: its `context_size` (`None` when no assistant
+    usage was read), how many of its lines could not be read, and `1` in `unreadable_transcripts`
+    when something is at the path and it could not be opened. A transcript with nothing at its
+    path is `(None, 0, 0)`: absent, which is not a file that could not be opened."""
+
+    context_size: int | None
+    unreadable_lines: int = 0
+    unreadable_transcripts: int = 0
+
+
+class _Snapshot:
+    """The one completed read of a transcript, handed back as the `read_lines` seam
+    `run_usage.usage_records` reads through. It reaches no filesystem, so every pass over the
+    snapshot reads memory."""
+
+    def __init__(self, lines: tuple[str, ...]):
+        self._lines = lines
+
+    def read_lines(self, path: Path) -> list[str]:
+        return list(self._lines)
+
+
+def read_context(
+    path: Path,
+    files: run_usage.Files,
+    *,
+    size_reader: Callable[[Path, run_usage.Files], int | None],
+) -> ContextReading:
+    """The context size of `path` together with what could not be read, from one read of it.
+
+    The transcript is opened once, through `files.read_outcome`. A completed read is replayed
+    from memory twice: `size_reader` — which owns which response sets the size, and is given the
+    snapshot as its `files` — gives the size, and `run_usage.usage_records` with a fresh counter
+    gives the number of lines it could not read. `size_reader` is required and has no default, so
+    the size arithmetic stays where `current_context` keeps it and is never restated here.
+    """
+    outcome = files.read_outcome(path)
+    if outcome.lines is None:
+        return ContextReading(context_size=None, unreadable_transcripts=0 if outcome.missing else 1)
+    snapshot = _Snapshot(outcome.lines)
+    context_size = size_reader(path, snapshot)
+    counter = run_usage.UnreadableLines()
+    for _record in run_usage.usage_records(path, snapshot, unreadable_lines=counter):
+        pass
+    return ContextReading(context_size=context_size, unreadable_lines=counter.count)