aimpg 0.1.0__py3-none-any.whl

aimpg/__init__.py

@@ -0,0 +1 @@
+"""aimpg: real-world energy per solved task for AI coding agents."""

aimpg/attribution.py

@@ -0,0 +1,252 @@
+"""Tie AI requests to the commits they produced.
+
+Tier 1 (exact): a Bash tool call ran `git commit`, and a commit in that
+repo has a committer time inside the call's [start, end] interval (±2s
+for whole-second git timestamps). Measured 8/8 on real commit history,
+including a commit whose hooks made it land 147s after the call started.
+
+Energy split (time segments): within one session, the requests made after
+commit k-1 and up to commit k belong to commit k, whatever repo they ran
+in. A session's cwd is often not the repo it works on (absolute paths,
+`cd x && ...`), so grouping by folder would strand requests.
+
+    session s:   r r r [c1 in A] r r r r [c2 in B] r r
+                 └── c1 ───┘  └──── c2 ─────┘  └ no commit yet
+
+Long sessions: a 2h+ pause starts a new work burst. Only the final burst
+before a commit is its direct energy; earlier bursts since the previous
+commit are reported as its "lead-up", never dropped.
+
+Tier 2 (fuzzy): a session's leftover requests (after its last exact
+commit) go to commits in any repo it worked in, made between its first leftover
+request and 2h after its last, authored by you (repo user.email) that touch a file the session edited
+(Edit/Write tools or Bash: sed -i, redirects, mv/cp/rm). Several matches
+split the requests by lines changed. Commits after the session's last
+request are labeled "grace". Built because the first real run showed exact
+matches covered only ~48% of in-repo energy (design gate: 70%).
+"""
+
+from __future__ import annotations
+
+import os
+from collections import defaultdict
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Callable
+
+from aimpg.gitkept import DAY, Commit, GitError, KeptChecker, load_commits, repo_root, user_email
+from aimpg.model import CommitCall, ParseResult, Request, Task
+
+PAD = 2.0  # seconds; git timestamps are whole seconds
+GRACE = 2 * 3600.0
+BREAK = 2 * 3600.0  # a pause this long between requests starts a new work burst  # hand commits often land a while after the session goes quiet
+
+NOT_IN_REPO = "not in a git repo (or repo moved/deleted)"
+NO_COMMIT_YET = "no commit from this session yet"
+GIT_FAILED = "git error"
+
+
+@dataclass
+class RepoInfo:
+    ref: str = ""
+    ref_updated: float = 0.0
+    error: str = ""
+
+
+@dataclass
+class Attribution:
+    tasks: list[Task] = field(default_factory=list)
+    unattributed: dict[str, list[Request]] = field(default_factory=dict)
+    repos: dict[str, RepoInfo] = field(default_factory=dict)
+    # session_id -> repos it committed in, ran in, or edited files in
+    session_repos: dict[str, set[str]] = field(default_factory=dict)
+
+
+def attribute(
+    parsed: ParseResult,
+    since: float,
+    now: float,
+    *,
+    refresh: bool = False,
+    find_root: Callable[[str], str | None] = repo_root,
+) -> Attribution:
+    roots: dict[str, str | None] = {}
+
+    def root(path: str) -> str | None:
+        if path not in roots:
+            roots[path] = find_root(path)
+        return roots[path]
+
+    result = Attribution()
+    by_session: dict[str, list[Request]] = defaultdict(list)
+    for r in parsed.requests:
+        if r.ts >= since:
+            by_session[r.session_id].append(r)
+
+    calls_by_session: dict[str, list[tuple[str, CommitCall]]] = defaultdict(list)
+    for call in parsed.commit_calls:
+        end = call.end if call.end is not None else call.start
+        repo = root(call.cwd) if end >= since else None
+        if repo is not None:
+            calls_by_session[call.session_id].append((repo, call))
+
+    # Repos each session may have worked in: where it committed, where its
+    # requests ran, and where the files it edited live. A session's cwd is
+    # often not the repo it worked on (absolute paths, `cd x && ...`).
+    session_repos: dict[str, set[str]] = {}
+    for session, group in by_session.items():
+        repos = {repo for repo, _ in calls_by_session.get(session, [])}
+        repos |= {root(r.cwd) for r in group} - {None}
+        for cwd, path in parsed.files_touched.get(session, set()):
+            full = path if os.path.isabs(path) else os.path.join(cwd, path)
+            repos |= {root(os.path.dirname(os.path.normpath(full)))} - {None}
+        session_repos[session] = repos
+    result.session_repos = session_repos
+
+    commits_by_repo: dict[str, dict[str, Commit]] = {}
+    status_by_repo: dict[str, dict[str, str]] = {}
+    all_repos = sorted(set().union(*session_repos.values()) if session_repos else set())
+    # git subprocesses release the GIL, so repos load in parallel
+    with ThreadPoolExecutor(max_workers=min(8, len(all_repos) or 1)) as pool:
+        loaded = list(pool.map(lambda repo: _load_repo(repo, since - DAY, now, refresh), all_repos))
+    for repo, (commits, statuses, info) in zip(all_repos, loaded):
+        commits_by_repo[repo] = {c.sha: c for c in commits}
+        status_by_repo[repo] = statuses
+        result.repos[repo] = info
+
+    def task_for(repo: str, commit: Commit, attribution: str) -> Task:
+        key = (repo, commit.sha)
+        if key not in tasks:
+            tasks[key] = Task(
+                repo=repo,
+                sha=commit.sha,
+                ts=commit.ts,
+                subject=commit.subject,
+                attribution=attribution,
+                status=status_by_repo.get(repo, {}).get(commit.sha, GIT_FAILED),
+            )
+        return tasks[key]
+
+    # Tier 1: time segments between the session's exact commits, in any repo.
+    tasks: dict[tuple[str, str], Task] = {}
+    leftovers: dict[str, list[Request]] = {}
+    for session, group in by_session.items():
+        group.sort(key=lambda r: r.ts)
+        i = 0
+        for repo, commit in _anchors(calls_by_session.get(session, []), commits_by_repo):
+            task = task_for(repo, commit, "exact")
+            j = i
+            while j < len(group) and group[j].ts <= commit.ts + PAD:
+                j += 1
+            _add_bursts(task, group[i:j], 1.0)
+            i = j
+        if i < len(group):
+            leftovers[session] = group[i:]
+
+    # Tier 2 runs after every exact anchor is known, so a Claude-made commit
+    # is never also claimed as someone's hand-made commit.
+    exact = set(tasks)
+    emails: dict[str, str] = {}
+    for session, rest in leftovers.items():
+        matches: list[tuple[str, Commit]] = []
+        for repo in sorted(session_repos.get(session, set())):
+            if repo not in emails:
+                emails[repo] = user_email(repo)
+            touched = _repo_relative(parsed.files_touched.get(session, set()), repo)
+            matches += [(repo, c) for c in _fuzzy(rest, touched, commits_by_repo.get(repo, {}), exact, repo, emails[repo])]
+        if not matches:
+            reason = NO_COMMIT_YET if session_repos.get(session) else NOT_IN_REPO
+            result.unattributed.setdefault(reason, []).extend(rest)
+            continue
+        total_lines = sum(max(c.lines_changed, 1) for _, c in matches)
+        for repo, commit in matches:
+            task = task_for(repo, commit, "fuzzy" if commit.ts <= rest[-1].ts + PAD else "grace")
+            share = max(commit.lines_changed, 1) / total_lines
+            _add_bursts(task, rest, share)
+
+    result.tasks = sorted(tasks.values(), key=lambda t: t.ts)
+    return result
+
+
+def _add_bursts(task: Task, segment: list[Request], weight: float) -> None:
+    """The final work burst before a commit is its direct cost; earlier bursts are lead-up.
+
+        r r r  ··· 2h+ break ···  r r  ··· 5h break ···  r r r [commit]
+        └ lead-up ┘                └ lead-up ┘           └ direct ┘
+    """
+    start = 0
+    for k in range(1, len(segment)):
+        if segment[k].ts - segment[k - 1].ts >= BREAK:
+            start = k
+    for k, r in enumerate(segment):
+        task.add(r, weight, lead_up=k < start)
+
+
+def _load_repo(repo: str, since: float, now: float, refresh: bool) -> tuple[list[Commit], dict[str, str], RepoInfo]:
+    info = RepoInfo()
+    commits: list[Commit] = []
+    statuses: dict[str, str] = {}
+    try:
+        commits = load_commits(repo, since)
+        checker = KeptChecker(repo, since, now, refresh=refresh, commits=commits)
+        info.ref, info.ref_updated = checker.ref, checker.ref_updated
+        statuses = {sha: s.value for sha, s in checker.classify(commits).items()}
+    except GitError as exc:
+        # Commits may still have loaded (e.g. no default branch): attribute
+        # them, and their status reads "git error" in the receipt.
+        info.error = str(exc)
+    return commits, statuses, info
+
+
+def _repo_relative(touched: set[tuple[str, str]], repo: str) -> set[str]:
+    out = set()
+    for cwd, path in touched:
+        full = os.path.normpath(path if os.path.isabs(path) else os.path.join(cwd, path))
+        full = os.path.realpath(full) if os.path.exists(full) else full
+        rel = os.path.relpath(full, repo)
+        if not rel.startswith(".."):
+            out.add(rel)
+    return out
+
+
+def _fuzzy(
+    rest: list[Request],
+    touched: set[str],
+    commits: dict[str, Commit],
+    exact: set[tuple[str, str]],
+    repo: str,
+    email: str,
+) -> list[Commit]:
+    """Your own hand-made commits in the session's window (+2h grace) that touch files it edited.
+
+    Authorship matters: after a pull, teammates' merged commits land inside the
+    window and touch the same files. Without a configured user.email we don't guess.
+    """
+    if not touched or not email:
+        return []
+    start, end = rest[0].ts - PAD, rest[-1].ts + GRACE
+    return sorted(
+        (
+            c
+            for c in commits.values()
+            if start <= c.ts <= end
+            and c.author_email == email
+            and (repo, c.sha) not in exact
+            and touched & set(c.files)
+        ),
+        key=lambda c: c.ts,
+    )
+
+
+def _anchors(calls: list[tuple[str, CommitCall]], commits_by_repo: dict[str, dict[str, Commit]]) -> list[tuple[str, Commit]]:
+    """(repo, commit) whose time falls inside one of the session's commit calls, oldest first."""
+    found: dict[tuple[str, str], tuple[str, Commit]] = {}
+    for repo, call in calls:
+        start = call.start - PAD
+        end = (call.end if call.end is not None else call.start) + PAD
+        for commit in commits_by_repo.get(repo, {}).values():
+            if start <= commit.ts <= end:
+                found[(repo, commit.sha)] = (repo, commit)
+    return sorted(found.values(), key=lambda rc: rc[1].ts)
+
+

aimpg/cli.py

@@ -0,0 +1,40 @@
+"""`aimpg report`: print the fuel receipt for your local Claude Code usage."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+from aimpg.attribution import attribute
+from aimpg.gitkept import DAY
+from aimpg.logs import DEFAULT_ROOT, iter_log_files, parse_logs
+from aimpg.receipt import render
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="aimpg", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    report = sub.add_parser("report", help="print the energy receipt")
+    report.add_argument("--days", type=int, default=30, help="window size in days (default 30)")
+    report.add_argument("--logs", type=Path, default=DEFAULT_ROOT, help="Claude Code projects dir")
+    report.add_argument("--fetch", action="store_true", help="git fetch each repo first (uses the network)")
+    args = parser.parse_args(argv)
+
+    if args.days <= 0:
+        parser.error("--days must be positive")
+    if not args.logs.is_dir():
+        print(f"No Claude Code logs found at {args.logs}. Nothing to report.")
+        return 0
+
+    now = time.time()
+    since = now - args.days * DAY
+    parsed = parse_logs(iter_log_files(args.logs))
+    attribution = attribute(parsed, since, now, refresh=args.fetch)
+    sys.stdout.write(render(parsed, attribution, since, now))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aimpg/energy.py

@@ -0,0 +1,195 @@
+"""The one place energy is computed. Everything else calls this module.
+
+Per request (joules, before overhead):
+
+    prefill   = (fresh_in + cache_write) * E_pre        # a cache write is a full prefill
+    cache     =  cache_read * E_kv                       # free if still in HBM, a reload if not
+    decode    =  output * (E_dec + E_ctx * ctx_len)      # every output token re-reads the KV cache
+
+    E_pre = 2 * P * J_flop * prefill_inefficiency
+    E_dec = (P * weight_bits / batch) * J_bit + 2 * P * J_flop
+    E_ctx = kv_bits_per_token * J_bit
+    E_kv  = kv_bits_per_token * J_bit * kv_reload_multiplier
+
+    Wh = overhead * joules / 3600
+
+Every input is a [low, high] range from factors.json. The formula is
+monotone increasing in each factor (taking batch_size reversed), so the
+all-low and all-high corners bound the result.
+
+Ranking (W) removes the model-class scale: W = joules / E_pre. Because the
+ratios inside W are estimates, `compare` checks every corner of the factor
+ranges and only names a winner when it wins at all of them.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+from dataclasses import dataclass
+from enum import Enum
+from functools import lru_cache
+from importlib import resources
+from typing import Iterable
+
+from aimpg.model import Request, Usage
+
+_RANGE_KEYS = (
+    "batch_size",
+    "weight_bits",
+    "kv_bits_per_token",
+    "prefill_inefficiency",
+    "kv_reload_multiplier",
+)
+
+
+@dataclass(frozen=True)
+class Factors:
+    params: float  # active parameters (count, not billions)
+    batch_size: float
+    weight_bits: float
+    kv_bits_per_token: float
+    prefill_inefficiency: float
+    kv_reload_multiplier: float
+    overhead: float
+    j_flop: float
+    j_bit: float
+
+    @property
+    def e_pre(self) -> float:
+        return 2 * self.params * self.j_flop * self.prefill_inefficiency
+
+    @property
+    def e_dec(self) -> float:
+        return (self.params * self.weight_bits / self.batch_size) * self.j_bit + 2 * self.params * self.j_flop
+
+    @property
+    def e_ctx(self) -> float:
+        return self.kv_bits_per_token * self.j_bit
+
+    @property
+    def e_kv(self) -> float:
+        return self.kv_bits_per_token * self.j_bit * self.kv_reload_multiplier
+
+
+@dataclass(frozen=True)
+class WhRange:
+    low: float
+    high: float
+
+    def __add__(self, other: "WhRange") -> "WhRange":
+        return WhRange(self.low + other.low, self.high + other.high)
+
+    def __mul__(self, k: float) -> "WhRange":
+        return WhRange(self.low * k, self.high * k)
+
+    @property
+    def mid(self) -> float:
+        return (self.low * self.high) ** 0.5  # geometric: the range spans orders of magnitude
+
+
+ZERO = WhRange(0.0, 0.0)
+
+
+@lru_cache(maxsize=1)
+def load_factors() -> dict:
+    return json.loads(resources.files("aimpg").joinpath("factors.json").read_text())
+
+
+def model_class(model: str) -> tuple[str, bool]:
+    """(class name, assumed) — assumed is True when the name matched no class."""
+    data = load_factors()
+    name = model.lower()
+    for cls, spec in data["classes"].items():
+        if any(token in name for token in spec["matches"]):
+            return cls, False
+    return data["default_class"], True
+
+
+def corners(cls: str) -> list[Factors]:
+    """Every combination of low/high for the uncertain factors, for one class."""
+    data = load_factors()
+    ranges = data["ranges"]
+    consts = data["constants"]
+    params = data["classes"][cls]["active_params_billion"]
+    out = []
+    axes = [("params", params)] + [(k, ranges[k]) for k in _RANGE_KEYS] + [("overhead", ranges["overhead"])]
+    for picks in itertools.product(("low", "high"), repeat=len(axes)):
+        values = {name: spec[pick] for (name, spec), pick in zip(axes, picks)}
+        values["params"] *= 1e9
+        out.append(Factors(j_flop=consts["joules_per_flop"]["value"], j_bit=consts["joules_per_hbm_bit"]["value"], **values))
+    return out
+
+
+def _end(cls: str, which: str) -> Factors:
+    data = load_factors()
+    ranges = data["ranges"]
+    consts = data["constants"]
+    return Factors(
+        params=data["classes"][cls]["active_params_billion"][which] * 1e9,
+        overhead=ranges["overhead"][which],
+        j_flop=consts["joules_per_flop"]["value"],
+        j_bit=consts["joules_per_hbm_bit"]["value"],
+        **{k: ranges[k][which] for k in _RANGE_KEYS},
+    )
+
+
+def joules(usage: Usage, f: Factors) -> float:
+    """GPU-side joules for one request, before datacenter overhead."""
+    prefill = (usage.fresh_in + usage.cache_write) * f.e_pre
+    cache = usage.cache_read * f.e_kv
+    decode = usage.output * (f.e_dec + f.e_ctx * usage.ctx_len)
+    return prefill + cache + decode
+
+
+def wh(usage: Usage, f: Factors) -> float:
+    return f.overhead * joules(usage, f) / 3600.0
+
+
+def request_wh(request: Request) -> WhRange:
+    cls, _ = model_class(request.model)
+    return WhRange(wh(request.usage, _end(cls, "low")), wh(request.usage, _end(cls, "high")))
+
+
+def total_wh(requests: Iterable[Request]) -> WhRange:
+    total = ZERO
+    for r in requests:
+        total = total + request_wh(r)
+    return total
+
+
+def weighted_wh(requests: Iterable[Request], weights: Iterable[float]) -> WhRange:
+    total = ZERO
+    for r, w in zip(requests, weights):
+        total = total + request_wh(r) * w
+    return total
+
+
+def weighted_tokens(usages: Iterable[Usage], f: Factors) -> float:
+    """W: joules with the model-class scale (E_pre) divided out."""
+    return sum(joules(u, f) for u in usages) / f.e_pre
+
+
+class Verdict(str, Enum):
+    A_WINS = "A uses less"
+    B_WINS = "B uses less"
+    TOO_CLOSE = "too close to call with current energy data"
+    NOT_COMPARABLE = "not directly comparable (different model classes)"
+
+
+def compare(a: list[Request], b: list[Request]) -> Verdict:
+    """Same-model-class comparison that holds at every corner of the factor ranges."""
+    classes = {model_class(r.model)[0] for r in a + b}
+    if len(classes) != 1:
+        return Verdict.NOT_COMPARABLE
+    (cls,) = classes
+    ua, ub = [r.usage for r in a], [r.usage for r in b]
+    signs = {
+        (weighted_tokens(ua, f) > weighted_tokens(ub, f)) - (weighted_tokens(ua, f) < weighted_tokens(ub, f))
+        for f in corners(cls)
+    }
+    if signs == {-1}:
+        return Verdict.A_WINS
+    if signs == {1}:
+        return Verdict.B_WINS
+    return Verdict.TOO_CLOSE

aimpg/factors.json

@@ -0,0 +1,63 @@
+{
+  "version": "2026-10-01",
+  "constants": {
+    "joules_per_flop": {
+      "value": 0.52e-12,
+      "citation": "From Tokens to Watt-hours (arXiv 2607.26571): tensor-core coefficient alpha_TC = 0.52 pJ/FLOP, H100 BF16"
+    },
+    "joules_per_hbm_bit": {
+      "value": 11.68e-12,
+      "citation": "From Tokens to Watt-hours (arXiv 2607.26571): HBM energy e_HBM = 11.68 pJ/bit, H100"
+    }
+  },
+  "ranges": {
+    "overhead": {
+      "low": 1.25,
+      "high": 1.5,
+      "citation": "EcoLogits LLM inference methodology: non-GPU server power 1.2 kW per 8-GPU server, provider PUE 1.09-1.20"
+    },
+    "batch_size": {
+      "low": 128,
+      "high": 32,
+      "citation": "Assumption. EcoLogits fixes B=64; we bracket it. Larger batches amortize weight reads, so 128 is the low-energy end"
+    },
+    "weight_bits": {
+      "low": 8,
+      "high": 16,
+      "citation": "Assumption: FP8 to BF16 serving precision"
+    },
+    "kv_bits_per_token": {
+      "low": 0.5e6,
+      "high": 3.0e6,
+      "citation": "Assumption: 2 x layers x kv_heads x head_dim x bytes for GQA models (e.g. 80x8x128x2x2 bytes = 2.6 Mbit BF16); FP8/compressed caches are lower"
+    },
+    "prefill_inefficiency": {
+      "low": 1.0,
+      "high": 2.0,
+      "citation": "Assumption: static power and sub-peak utilization during prefill on top of pure FLOP energy"
+    },
+    "kv_reload_multiplier": {
+      "low": 0.0,
+      "high": 4.0,
+      "citation": "Assumption: a cache read is free if the prefix is still in HBM (low) or costs a reload from host memory at about 4x HBM read energy (high)"
+    }
+  },
+  "classes": {
+    "large": {
+      "active_params_billion": {"low": 100, "high": 400},
+      "matches": ["opus", "fable"],
+      "citation": "Assumption: parameter counts are not disclosed for frontier closed models"
+    },
+    "mid": {
+      "active_params_billion": {"low": 30, "high": 150},
+      "matches": ["sonnet"],
+      "citation": "Assumption: parameter counts are not disclosed for frontier closed models"
+    },
+    "small": {
+      "active_params_billion": {"low": 8, "high": 40},
+      "matches": ["haiku"],
+      "citation": "Assumption: parameter counts are not disclosed for frontier closed models"
+    }
+  },
+  "default_class": "mid"
+}