scorchmark 0.6.0__py3-none-any.whl

adapters.py

@@ -0,0 +1,131 @@
+"""
+adapters.py — turn logs you ALREADY HAVE into Scorchmark rows.
+
+The native Scorchmark schema (see ingest.py) is the canonical input, but almost
+nobody has a log in exactly that shape sitting around. The single biggest source
+of friction is "first, reformat your log." This module removes it: point Scorchmark
+at the logs your tools already write and it adapts them on the way in.
+
+Currently supported source formats (auto-detected):
+  - "scorchmark"     — the native schema (passthrough)
+  - "claude-code"  — Claude Code session transcripts (~/.claude/projects/**/*.jsonl)
+
+Each adapter yields RAW row dicts in the native schema; ingest.normalize_row then
+validates + prices them, so adapters stay small and the pricing/cost logic lives in
+exactly one place.
+"""
+from __future__ import annotations
+
+import json
+import os
+import glob as _glob
+
+# Default location Claude Code writes its session transcripts.
+CLAUDE_CODE_LOG_DIR = os.path.expanduser("~/.claude/projects")
+
+
+def detect_format(text: str) -> str:
+    """
+    Sniff the source format from the first usable JSON line.
+
+    Claude Code transcripts are tagged objects with a top-level "type" and a nested
+    "message" carrying "usage"; the native schema has flat token fields. Returns
+    "claude-code" or "scorchmark" (the safe default — ingest skips rows it can't use).
+    """
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(obj, dict):
+            continue
+        # Claude Code event envelope: {"type": "...", "message": {...}, "timestamp": ...}
+        if "type" in obj and isinstance(obj.get("message"), dict):
+            return "claude-code"
+        # Native schema: flat token counts on the row itself.
+        if "input_tokens" in obj or "output_tokens" in obj or "cost_usd" in obj:
+            return "scorchmark"
+        # Keep looking; a stray line shouldn't decide the format.
+    return "scorchmark"
+
+
+def from_claude_code(text: str):
+    """
+    Yield native rows from Claude Code session JSONL.
+
+    Only "assistant" events carry token usage. Each becomes one priced row:
+      agent_id   = "cc:<last-8-of-sessionId>"  → keeps a session's loop together so
+                   detect_cache_waste sees the wake-up intervals (and not the long
+                   gaps *between* sessions, which would be false TTL misses).
+      provider   = "anthropic" (Claude Code is Anthropic-only)
+      cache_*    = Anthropic's native cache_creation_/cache_read_input_tokens.
+    """
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(obj, dict) or obj.get("type") != "assistant":
+            continue
+        msg = obj.get("message")
+        if not isinstance(msg, dict):
+            continue
+        usage = msg.get("usage")
+        if not isinstance(usage, dict):
+            continue
+        session = str(obj.get("sessionId") or "")
+        agent = f"cc:{session[-8:]}" if session else "cc:default"
+        yield {
+            "request_id": obj.get("requestId") or obj.get("uuid") or "",
+            "ts": obj.get("timestamp"),
+            "provider": "anthropic",
+            "model": msg.get("model") or "",
+            "agent_id": agent,
+            "input_tokens": usage.get("input_tokens") or 0,
+            "output_tokens": usage.get("output_tokens") or 0,
+            "cache_write_tokens": usage.get("cache_creation_input_tokens") or 0,
+            "cache_read_tokens": usage.get("cache_read_input_tokens") or 0,
+        }
+
+
+# Map of format name → raw-row generator. "scorchmark" is handled by ingest directly.
+_ADAPTERS = {"claude-code": from_claude_code}
+
+
+def to_raw_rows(text: str, fmt: str = "auto"):
+    """
+    Return a list of native raw-row dicts for the given source text.
+
+    fmt="auto" sniffs the format; an explicit fmt forces an adapter. The native
+    "scorchmark" format returns an empty list here — the caller (ingest.parse) parses
+    it directly so cost/normalization isn't duplicated.
+    """
+    if fmt == "auto":
+        fmt = detect_format(text)
+    if fmt in _ADAPTERS:
+        return list(_ADAPTERS[fmt](text))
+    return []  # native; ingest handles it
+
+
+def read_source(path: str) -> str:
+    """
+    Read a log source into text. Accepts a file, '-' (stdin), or a DIRECTORY of
+    .jsonl files (e.g. ~/.claude/projects) — directories are read recursively and
+    concatenated, which is how Claude Code stores one file per session.
+    """
+    import sys
+    if path in ("-", ""):
+        return sys.stdin.read()
+    path = os.path.expanduser(path)
+    if os.path.isdir(path):
+        files = sorted(_glob.glob(os.path.join(path, "**", "*.jsonl"), recursive=True))
+        if not files:
+            raise FileNotFoundError(f"no .jsonl files under {path}")
+        return "\n".join(open(f, encoding="utf-8", errors="replace").read() for f in files)
+    return open(path, encoding="utf-8", errors="replace").read()

alerts.py

@@ -0,0 +1,136 @@
+"""
+alerts.py — structured alert payloads for Scorchmark.
+
+Converts a check_budget result (or any detector result with a 'status' field)
+into a structured alert payload when the status is not 'ok'. The payload is
+designed for webhook delivery — the caller (or host agent) is responsible for
+POSTing it; we provide a best-effort helper using stdlib urllib so there is
+zero new runtime dependency.
+
+Design rationale: MCP tools are stateless per-call, so we cannot run a
+background loop. The recommended pattern is:
+  1. Call check_budget (or any detector) on each agent turn / scheduled ping.
+  2. Pass the result to build_alert.
+  3. If alert["should_fire"] is True, POST alert["payload"] to your webhook,
+     or use notify_webhook() if you have a URL configured.
+
+No httpx, no requests. stdlib urllib.request only — and only when called explicitly.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any
+
+
+# Severity map: detector status → alert level.
+_LEVEL: dict[str, str] = {
+    "ok":      "info",
+    "warn":    "warning",
+    "warning": "warning",
+    "breach":  "critical",
+    "critical":"critical",
+}
+
+
+def build_alert(
+    check_result: dict[str, Any],
+    webhook_url: str | None = None,
+    source: str = "scorchmark",
+) -> dict[str, Any]:
+    """
+    Build a structured alert payload from any detector result dict.
+
+    A result with status == 'ok' returns {should_fire: False}. Everything
+    else returns a full payload with severity, message, and context — ready
+    to POST to Slack / PagerDuty / ntfy / any JSON webhook.
+
+    Args:
+        check_result: the dict returned by check_budget, detect_spend_acceleration,
+                      predict_rate_limit, or any detector.
+        webhook_url:  if provided, the payload includes the target URL (the
+                      caller decides whether to actually POST it — see
+                      notify_webhook() below for an optional helper).
+        source:       label for the alert source (used as title prefix).
+
+    Returns:
+        {
+          should_fire: bool,
+          level: 'info'|'warning'|'critical',
+          payload: { title, message, level, ts_utc, context, source },
+          webhook_url: str | None,
+        }
+    """
+    status = str(check_result.get("status", "ok")).lower()
+    level  = _LEVEL.get(status, "warning")
+    should_fire = status != "ok"
+
+    if not should_fire:
+        return {"should_fire": False, "level": "info", "payload": None, "webhook_url": webhook_url}
+
+    # Build a human-readable message from the most useful fields.
+    msg_parts = []
+    if "spent_usd" in check_result:
+        msg_parts.append(f"Spent: ${check_result['spent_usd']:.4f}")
+    if "monthly_cap_usd" in check_result:
+        msg_parts.append(f"Cap: ${check_result['monthly_cap_usd']:.2f}")
+    if "burn_rate_usd_per_hr" in check_result:
+        msg_parts.append(f"Burn: ${check_result['burn_rate_usd_per_hr']:.4f}/hr")
+    if "projected_to_reset_usd" in check_result:
+        msg_parts.append(f"Projected: ${check_result['projected_to_reset_usd']:.4f}")
+    if "eta_to_cap_hours" in check_result and check_result["eta_to_cap_hours"] is not None:
+        msg_parts.append(f"ETA to cap: {check_result['eta_to_cap_hours']:.1f}h")
+    if "recommendation" in check_result:
+        msg_parts.append(check_result["recommendation"])
+    if "accelerating" in check_result and check_result["accelerating"]:
+        msg_parts.append(f"Acceleration factor: {check_result.get('factor', '?')}x")
+
+    message = " | ".join(msg_parts) if msg_parts else f"Status: {status}"
+    title   = f"[{source}] {level.upper()}: agent spend alert"
+
+    payload = {
+        "title":    title,
+        "message":  message,
+        "level":    level,
+        "status":   status,
+        "ts_utc":   datetime.now(timezone.utc).isoformat(),
+        "context":  check_result,
+        "source":   source,
+    }
+
+    return {
+        "should_fire":  True,
+        "level":        level,
+        "payload":      payload,
+        "webhook_url":  webhook_url,
+    }
+
+
+def notify_webhook(alert: dict[str, Any]) -> dict[str, Any]:
+    """
+    Optionally POST the alert payload to the configured webhook_url.
+
+    Uses stdlib urllib.request — no new deps. Returns {sent, status_code, error}.
+    Call this only if you want the guard itself to push notifications; otherwise
+    read alert["payload"] and route it yourself (e.g. from the host agent).
+
+    Silently returns {sent: False} if should_fire is False or webhook_url is None.
+    """
+    if not alert.get("should_fire") or not alert.get("webhook_url"):
+        return {"sent": False, "status_code": None, "error": None}
+
+    import urllib.request  # noqa: PLC0415 — intentional lazy import (stdlib only)
+
+    url  = alert["webhook_url"]
+    body = json.dumps(alert["payload"]).encode("utf-8")
+    req  = urllib.request.Request(
+        url,
+        data=body,
+        headers={"Content-Type": "application/json", "User-Agent": "ScorchmarkGuard/1.1"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            return {"sent": True, "status_code": resp.status, "error": None}
+    except Exception as exc:  # noqa: BLE001
+        return {"sent": False, "status_code": None, "error": str(exc)}

cli.py

@@ -0,0 +1,318 @@
+"""
+scorchmark — run Scorchmark checks on a cost log straight from the terminal,
+no MCP client required. The zero-friction way to try it on your worst log.
+
+  scorchmark report  log.jsonl --cap 100        # everything at once (default)
+  scorchmark budget  log.jsonl --cap 100
+  scorchmark cache-waste log.jsonl
+  scorchmark by-agent log.jsonl
+  scorchmark swap    log.jsonl --to claude-haiku-4-5
+  cat log.jsonl | scorchmark report - --cap 100  # read stdin with '-'
+
+Add --json to any command for the raw machine-readable result.
+Same engine as the MCP server (ingest + detectors); pure stdlib.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+import ingest
+import detectors
+import licensing
+
+_COLOR = sys.stdout.isatty() and os.environ.get("NO_COLOR") is None
+_CODES = {"red": "31", "green": "32", "yellow": "33", "violet": "35", "dim": "2", "bold": "1"}
+_STATUS_COLOR = {"ok": "green", "warn": "yellow", "warning": "yellow",
+                 "breach": "red", "critical": "red"}
+
+
+def _c(name: str, s: str) -> str:
+    return f"\033[{_CODES[name]}m{s}\033[0m" if _COLOR and name in _CODES else s
+
+
+def _money(x: float) -> str:
+    return f"${x:,.2f}" if abs(x) >= 0.01 or x == 0 else f"${x:.4f}"
+
+
+def _bar(frac: float, width: int = 28, status: str = "ok") -> str:
+    frac = max(0.0, min(frac, 1.0))
+    filled = int(round(frac * width))
+    return _c(_STATUS_COLOR.get(status, "green"), "█" * filled) + _c("dim", "░" * (width - filled))
+
+
+def _badge(status: str) -> str:
+    return _c(_STATUS_COLOR.get(status, "green"), f"[{status.upper()}]")
+
+
+def _load(path: str, fmt: str = "auto"):
+    import adapters
+    text = adapters.read_source(path)
+    return ingest.parse(text, fmt)
+
+
+def _emit(result, as_json: bool, printer):
+    if as_json:
+        print(json.dumps(result, indent=2))
+    else:
+        printer(result)
+
+
+# --- human-readable printers ------------------------------------------------
+def _print_budget(r):
+    cap = r["monthly_cap_usd"]
+    frac = r["spent_usd"] / cap if cap > 0 else 0.0
+    print(f"  {_bar(frac, status=r['status'])} {_badge(r['status'])}")
+    print(f"  spent {_c('bold', _money(r['spent_usd']))} of {_money(cap)} cap"
+          f"   ·   burn rate {_money(r['burn_rate_usd_per_hr'])}/hr")
+    # "projected" is a straight-line extrapolation of the burn rate, not a forecast —
+    # say "at this pace" so a high number from a short sample doesn't read as a prediction.
+    if r.get("eta_to_cap_hours") is not None:
+        print(_c("dim", f"  at this pace → hits the cap in ~{r['eta_to_cap_hours']}h "
+                        f"(≈{_money(r['projected_to_reset_usd'])} by reset day)"))
+    else:
+        print(_c("dim", f"  at this pace → ≈{_money(r['projected_to_reset_usd'])} by reset day"))
+
+
+def _print_cache_waste(r):
+    if not r["ttl_miss_count"]:
+        print(_c("green", "  no systematic cache waste in window"))
+        return
+    print(f"  {_c('red', _money(r['wasted_cost_usd']) + ' wasted')} across "
+          f"{r['ttl_miss_count']} rebuild(s)  ·  loop ~{int(r['median_interval_s'])}s "
+          f"vs {r['cache_ttl_s']}s TTL ({r['cache_model']})")
+    print(_c("dim", f"  {r['recommendation']}"))
+
+
+def _print_by_agent(rows):
+    if not rows:
+        print(_c("dim", "  no spend in window"))
+        return
+    for a in rows:
+        share = a["share_of_total"] * 100
+        name = a["agent_id"]
+        req = _c("dim", f"({a['requests']} req)")
+        print(f"  {_bar(a['share_of_total'], width=20)} {share:5.1f}%  "
+              f"{name:<20} {_money(a['cost_usd'])}  {req}")
+
+
+def _print_anomalies(rows):
+    if not rows:
+        print(_c("green", "  no spend anomalies in window"))
+        return
+    for a in rows:
+        x = _c("yellow", f"{a['x_over_agent_median']}x")
+        loc = f"{a['agent_id']}/{a['request_id']}"
+        print(f"  {x}  {loc}  {_money(a['cost_usd'])}  {_c('dim', a['reason'])}")
+
+
+def _print_swap(r):
+    saved = _c("green", f"{_money(r['savings_usd'])} / {r['savings_pct']}% saved")
+    print(f"  swap → {_c('bold', r['to_model'])}: {_money(r['current_usd'])} would be "
+          f"{_money(r['simulated_usd'])}  ({saved})")
+
+
+def _print_gate(g):
+    print(f"  {_c('yellow', '🔒 ' + g['tier_required'].upper())}  {g['message']}")
+    print(_c("dim", f"  unlock: {g['upgrade_url']}"))
+
+
+def _print_license(st):
+    col = "green" if st["valid"] else "dim"
+    print(f"  tier: {_c(col, st['tier'].upper())}   ·   {st['reason']}")
+    if st.get("email"):
+        print(_c("dim", f"  licensed to {st['email']}  ·  expires {st.get('expires')}"))
+
+
+def _section(title):
+    print()
+    print(_c("violet", _c("bold", f"▸ {title}")))
+
+
+def _dur(seconds: float) -> str:
+    s = max(0, int(seconds))
+    if s < 90:
+        return f"{s}s"
+    if s < 5400:
+        return f"{s/60:.0f} min"
+    if s < 172800:
+        return f"{s/3600:.1f}h"
+    return f"{s/86400:.1f}d"
+
+
+def _print_headline(rows, args):
+    """The 'so what' up top: total, the waste found (free), and the savings available."""
+    total = sum(r["cost_usd"] for r in rows)
+    span = (rows[-1]["ts"] - rows[0]["ts"]) if len(rows) > 1 else 0
+    span_txt = f"  ·  over {_dur(span)}" if span else ""
+    print(f"  {_c('bold', _money(total))} spent across {len(rows)} requests{span_txt}")
+    cw = detectors.detect_cache_waste(rows, args.window)
+    if cw["ttl_miss_count"]:
+        pct = (100 * cw["wasted_cost_usd"] / total) if total else 0
+        print("  " + _c("red", f"💸 {_money(cw['wasted_cost_usd'])} wasted on cache rebuilds")
+              + _c("dim", f"  ({pct:.0f}% of spend — recoverable)"))
+    else:
+        print("  " + _c("green", "✓ no cache-rebuild waste found"))
+    g = licensing.gate("team")  # model-swap savings are Team
+    if g:
+        print("  " + _c("dim", "🔒 model-swap savings hidden — Team tier"))
+    else:
+        sw = detectors.simulate_model_swap(rows, args.to, None, args.window)
+        if sw["savings_usd"] > 0.005:
+            print("  " + _c("green", f"💡 {_money(sw['savings_usd'])} saveable")
+                  + _c("dim", f"  by switching to {args.to} ({sw['savings_pct']:.0f}% less)"))
+        else:
+            print("  " + _c("dim", f"  no model-swap savings vs {args.to} here"))
+
+
+# --- commands ---------------------------------------------------------------
+def _cmd_budget(rows, args):
+    return detectors.check_budget(rows, args.cap, args.reset_day, args.window), _print_budget
+
+
+def _cmd_cache(rows, args):
+    return detectors.detect_cache_waste(rows, args.window), _print_cache_waste
+
+
+def _cmd_agent(rows, args):
+    g = licensing.gate("team")  # per-agent attribution is Team
+    if g:
+        return g, _print_gate
+    return detectors.cost_by_agent(rows, args.window), _print_by_agent
+
+
+def _cmd_anomalies(rows, args):
+    return detectors.find_spend_anomalies(rows, args.threshold, args.window), _print_anomalies
+
+
+def _cmd_swap(rows, args):
+    g = licensing.gate("team")  # model-swap simulator is Team
+    if g:
+        return g, _print_gate
+    return detectors.simulate_model_swap(rows, args.to, None, args.window), _print_swap
+
+
+def _cmd_report(rows, args):
+    # Composite human view; --json emits one combined object. Premium sections are
+    # gated (replaced by the upgrade-required object) exactly like the MCP server.
+    def _g(tier, fn):
+        return licensing.gate(tier) or fn()
+
+    if args.json:
+        return {
+            "license": licensing.status(),
+            "summary": {
+                "requests": len(rows),
+                "total_spend_usd": round(sum(r["cost_usd"] for r in rows), 4),
+            },
+            "cache_waste": detectors.detect_cache_waste(rows, args.window),
+            "model_swap": _g("team", lambda: detectors.simulate_model_swap(rows, args.to, None, args.window)),
+            "budget": detectors.check_budget(rows, args.cap, args.reset_day, args.window),
+            "acceleration": _g("pro", lambda: detectors.detect_spend_acceleration(rows, args.window)),
+            "cost_by_agent": _g("team", lambda: detectors.cost_by_agent(rows, args.window)),
+            "anomalies": detectors.find_spend_anomalies(rows, args.threshold, args.window),
+        }, (lambda r: print(json.dumps(r, indent=2)))
+
+    def printer(_):
+        # Lead with the findings (what you came for), then the breakdowns.
+        _section("Bottom line")
+        _print_headline(rows, args)
+        _section("Cache waste")
+        _print_cache_waste(detectors.detect_cache_waste(rows, args.window))
+        _section(f"Savings — swap → {args.to}  (Team)")
+        gt = licensing.gate("team")
+        if gt:
+            _print_gate(gt)
+        else:
+            _print_swap(detectors.simulate_model_swap(rows, args.to, None, args.window))
+        _section(f"Budget (cap {_money(args.cap)})")
+        _print_budget(detectors.check_budget(rows, args.cap, args.reset_day, args.window))
+        _section("Spend acceleration  (Pro)")
+        gp = licensing.gate("pro")
+        if gp:
+            _print_gate(gp)
+        else:
+            acc = detectors.detect_spend_acceleration(rows, args.window)
+            print(f"  {_badge('warn' if acc['accelerating'] else 'ok')} {_c('dim', acc['recommendation'])}")
+        _section("Cost by agent  (Team)")
+        gt2 = licensing.gate("team")
+        if gt2:
+            _print_gate(gt2)
+        else:
+            _print_by_agent(detectors.cost_by_agent(rows, args.window))
+        _section("Anomalies")
+        _print_anomalies(detectors.find_spend_anomalies(rows, args.threshold, args.window))
+    return None, printer
+
+
+def _build_parser():
+    p = argparse.ArgumentParser(prog="scorchmark", description=__doc__.strip().splitlines()[1])
+    p.add_argument("--version", action="version", version="scorchmark 0.6.0")
+    sub = p.add_subparsers(dest="cmd")
+
+    def add(name, fn, help_):
+        sp = sub.add_parser(name, help=help_)
+        sp.add_argument("log", nargs="?", default="-",
+                        help="cost-log file, a directory of .jsonl, or '-' for stdin")
+        sp.add_argument("--window", default="30d", help="lookback window (e.g. 24h, 7d, 30d)")
+        sp.add_argument("--from", dest="fmt", default="auto",
+                        choices=["auto", "scorchmark", "claude-code"],
+                        help="source log format (default: auto-detect)")
+        sp.add_argument("--claude-code", action="store_true",
+                        help="analyze your own Claude Code logs (~/.claude/projects)")
+        sp.add_argument("--json", action="store_true", help="raw JSON output")
+        sp.set_defaults(_fn=fn)
+        return sp
+
+    sp = add("report", _cmd_report, "run all checks (default)")
+    sp.add_argument("--cap", type=float, default=100.0); sp.add_argument("--reset-day", type=int, default=1)
+    sp.add_argument("--threshold", type=float, default=3.0)
+    sp.add_argument("--to", default="claude-haiku-4-5",
+                    help="model to price the swap-savings estimate against (default: claude-haiku-4-5)")
+    sp = add("budget", _cmd_budget, "live budget tripwire")
+    sp.add_argument("--cap", type=float, required=True); sp.add_argument("--reset-day", type=int, default=1)
+    add("cache-waste", _cmd_cache, "detect cache-TTL waste")
+    add("by-agent", _cmd_agent, "per-agent cost attribution")
+    sp = add("anomalies", _cmd_anomalies, "flag spend spikes"); sp.add_argument("--threshold", type=float, default=3.0)
+    sp = add("swap", _cmd_swap, "simulate a model swap (Team)"); sp.add_argument("--to", required=True, help="target model, e.g. claude-haiku-4-5")
+    lp = sub.add_parser("license", help="show active license tier (SCORCHMARK_LICENSE)")
+    lp.add_argument("--json", action="store_true", help="raw JSON output")  # handled in main()
+    return p
+
+
+def main(argv=None):
+    args = _build_parser().parse_args(argv)
+    if not getattr(args, "cmd", None):
+        _build_parser().print_help()
+        return 0
+    if args.cmd == "license":  # no log needed
+        st = licensing.status()
+        print(json.dumps(st, indent=2)) if args.json else _print_license(st)
+        return 0
+    # --claude-code is shorthand: point at ~/.claude/projects and force the adapter.
+    if getattr(args, "claude_code", False):
+        import adapters
+        if args.log == "-":
+            args.log = adapters.CLAUDE_CODE_LOG_DIR
+        args.fmt = "claude-code"
+    try:
+        rows, summary = _load(args.log, getattr(args, "fmt", "auto"))
+    except FileNotFoundError as e:
+        print(_c("red", f"error: {e}"), file=sys.stderr)
+        return 2
+    if not rows:
+        print(_c("yellow", "no usable rows in log "
+                 f"(skipped {summary['rows_skipped']})"), file=sys.stderr)
+        return 1
+    print(_c("dim", f"ingested {summary['rows_ingested']} rows  ·  "
+             f"computed spend {_money(summary['computed_cost_usd'])}"))
+    result, printer = args._fn(rows, args)
+    _emit(result, args.json and result is not None, printer)
+    print()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())