aight 0.2.0__tar.gz → 0.2.1__tar.gz

{aight-0.2.0 → aight-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aight
-Version: 0.2.0
+Version: 0.2.1
 Summary: Attribute LLM spend to the exact source line, and push it to the AIght Workspace at aight.studio.
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://aight.studio

{aight-0.2.0 → aight-0.2.1}/README.md

@@ -15,9 +15,10 @@ time. `traced_llm_call` therefore returns `None`, not a cost.
 pip install aight
 ```
 
-That is the whole install, and it also puts `aight-collect` on your path — the
-Claude Code collector, which is a separate thing from the SDK and is described
-under [External agents](#external-agents-claude-code) below.
+That is the whole install, and it also puts the collectors on your path — 
+`aight-collect` for Claude Code, three more for other agents, and `aight-proxy`
+for anything none of them can read. They are a separate thing from the SDK and
+are described under [External agents](#external-agents) below.
 
 ## Deploy with your AI coding agent
 
@@ -44,7 +45,7 @@ traced_llm_call("gpt-4o-mini", input_tokens=180, output_tokens=60)
 push(COST_PROCESSOR.buckets)  # reads AIGHT_API_KEY from the environment
 ```
 
-Get an API key from the Integrate tab of your AIght Workspace, then:
+Get an API key from Project settings in your AIght Workspace, then:
 
 ```bash
 export AIGHT_API_KEY="aight_..."
@@ -113,6 +114,11 @@ push_value(VALUE_BY_FILE)
 acknowledged — so calling it every flush sends each earning once, and a failed
 push keeps the total for the retry instead of losing it.
 
+It takes that map as an argument rather than reading a global, which makes it
+also the way to report value for an agent you did not write — pass the agent id
+the collector uses as the filepath. See [External
+agents](#external-agents) below.
+
 ## Local-only mode
 
 Skip `push()` and call `COST_PROCESSOR.report()` instead — a plain-text
@@ -124,14 +130,24 @@ platform's, so spend only appears in the AIght Workspace once you push.
 examples/snippet_check.py:19 (plan_step) [gpt-4o-mini] = 3 call(s), 540 in / 180 out
 ```
 
-## External agents (Claude Code)
+## External agents
 
 Everything above is for an agent *you wrote*: the SDK walks your call stack to
 find the line that issued the call. An agent you run but did not write has no
 line of yours on the stack, so there is nothing to instrument and no library to
 import. AIght traces those by reading the agent's own transcripts instead.
 
-`pip install aight` also installs `aight-collect`:
+`pip install aight` also installs `aight-collect`. To see what your Claude Code
+history would cost at API list prices, with no account and nothing sent:
+
+```bash
+pip install aight && aight-collect --report --all-projects
+```
+
+That prints a breakdown by token type, step and model. Only the model names go
+out, to fetch their rates from AIght's price table; drop `--all-projects` for
+just this directory, add `--since 2026-10-01` to narrow it. To push to your
+Workspace instead:
 
 ```bash
 export AIGHT_API_KEY="aight_..."
@@ -145,6 +161,24 @@ row per step the agent took, under an external agent called `claude-code`. Cost
 lands on the step — the tool it called and the file it touched — rather than on
 a source line, because no source line of yours is involved.
 
+That is the spend side. **Earnings you report yourself** — a collector reads
+token counts, not what the work was worth, and no SDK can infer it. Push them
+against the agent's id:
+
+```python
+from aight.remote import push_value
+
+push_value({"claude-code": 49.0})  # the id the collector roots its rows at
+```
+
+The Workspace shows that on `claude-code` exactly as it shows an agent of your
+own: the earned total, the net, the ratio, and the earning-or-burning status
+that goes with them. What an external agent never gets is a **matched** figure
+— the matching engine's time-window fallback excludes external rows outright,
+because a collector pushes no timestamp and an external row would always be the
+newest thing in the window and win the guess by default. Reported, yes; guessed,
+no.
+
 Leave it running and the spend appears as you work, rather than whenever you
 next remember to run it:
 
@@ -170,8 +204,8 @@ Three things are worth knowing before the first run:
   been pushed.
 - **The key alone decides the destination.** A run prints the project its rows
   landed in and stops rather than resuming when that differs from the project
-  its earlier pushes went to. A key copied out of another project's Integrate
-  tab otherwise reads exactly like success, and fills a workspace nobody is
+  its earlier pushes went to. A key copied out of another project's settings
+  otherwise reads exactly like success, and fills a workspace nobody is
   looking at.
 
 Without installing anything:

{aight-0.2.0 → aight-0.2.1}/aight/AGENTS.md

@@ -32,6 +32,10 @@ from aight.tracing import report_value, VALUE_BY_FILE
 from aight.remote import push_value
 report_value(49.0)
 push_value(VALUE_BY_FILE)
+For an agent the user runs but this project does not contain — Claude Code, Gemini, Codex, traced by aight's collectors — earnings go in by agent id, because there is no calling file of theirs to resolve. push_value takes the map, so pass one directly, on the same rule:
+from aight.remote import push_value
+push_value({"claude-code": 49.0})  # the agent id the collector roots its rows at
+That agent then shows a reported figure in the Workspace like any other. It never shows a matched one: the matching engine excludes external rows from its time-window fallback, so do not try to give it one through push_event.
 7. Optional: Agnostic business matching, Trace IDs & Labels
 To link LLM costs explicitly to business events (like a Stripe checkout, a conversion, or custom tiers) without hardcoding any specific business model, use TraceContext or pass parameters directly:
 Option A — Using TraceContext for an execution scope (recommended for web requests / checkouts):

{aight-0.2.0 → aight-0.2.1}/aight/__init__.py

@@ -23,4 +23,4 @@ Or trace manually, call by call:
     push(COST_PROCESSOR.buckets)
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{aight-0.2.0 → aight-0.2.1}/aight/collect/base.py

@@ -36,6 +36,7 @@ import subprocess
 import sys
 import time
 import urllib.error
+import urllib.parse
 import urllib.request
 from collections.abc import Callable
 from dataclasses import dataclass, field
@@ -284,7 +285,7 @@ def _check_destination(config: Collector, api_key: str, url: str) -> tuple[bool,
     An ingest key is otherwise write-only: every read endpoint wants the Auth0
     JWT, so a collector had no way to ask this before pushing. The marker
     records that calls were *sent*, never where, so a key minted in another
-    project's Integrate tab would resume this machine's coverage, send only
+    project's settings would resume this machine's coverage, send only
     what is newer than it into the wrong workspace, and leave the project that
     was meant permanently missing that window — silently, because every one of
     those pushes succeeds.
@@ -581,6 +582,94 @@ def watch(
             return 0
 
 
+def fetch_prices(rows: list[dict], ingest_url: str) -> dict | None:
+    """The server's per-1K rates for the models in `rows`, or None offline.
+
+    Only model names go up. The SDK ships no price table on purpose (copies
+    drifted from the server's and priced new models at zero), so a report
+    asks the one table there is, and falls back to tokens when it can't."""
+    models = sorted({r["model"] for r in rows if r.get("model")})
+    if not models:
+        return {}
+    base = ingest_url.split("/api/", 1)[0]
+    query = urllib.parse.urlencode({"models": ",".join(models)})
+    try:
+        with urllib.request.urlopen(f"{base}/api/pricing?{query}", timeout=10) as resp:
+            return json.load(resp).get("prices") or {}
+    except (urllib.error.URLError, OSError, ValueError):
+        return None
+
+
+TOKEN_KINDS = (
+    ("cache read", "cache_read_tokens", "cache_read"),
+    ("cache write", "cache_creation_tokens", "cache_creation"),
+    ("output", "output_tokens", "output"),
+    ("fresh input", "input_tokens", "input"),
+)
+
+
+def report(rows: list[dict], agent: str, prices: dict | None, top: int = 8) -> str:
+    """A breakdown worth a screenshot: what the calls in `rows` would cost at
+    list price, by token type, by step and by model. With `prices` None (the
+    server was unreachable) it reports tokens instead of dollars."""
+    priced = prices is not None
+    by_kind: dict[str, float] = {}
+    by_step: dict[str, list[float]] = {}
+    by_model: dict[str, float] = {}
+    unpriced: set[str] = set()
+    calls = 0
+    for r in rows:
+        rate = (prices or {}).get(r["model"]) if priced else None
+        if priced and rate is None:
+            unpriced.add(r["model"])
+        # A coding agent's step is the tool, whatever file it touched (and the
+        # path would put the user's directories in a shared screenshot); your
+        # own agent's step is the line, named by file, not full path.
+        frame = r["chain"][-1]
+        if r.get("kind") == "external" or not frame.get("filepath"):
+            step = frame.get("function") or "?"
+        else:
+            step = f"{Path(frame['filepath']).name}:{frame['lineno']}"
+        row_total = 0.0
+        for label, key, rate_key in TOKEN_KINDS:
+            n = r.get(key, 0) or 0
+            v = (n / 1000) * (rate or {}).get(rate_key, 0.0) if priced else n
+            by_kind[label] = by_kind.get(label, 0.0) + v
+            row_total += v
+        s = by_step.setdefault(step, [0.0, 0])
+        s[0] += row_total
+        s[1] += r.get("calls", 0)
+        by_model[r["model"]] = by_model.get(r["model"], 0.0) + row_total
+        calls += r.get("calls", 0)
+
+    total = sum(by_kind.values())
+
+    def amount(v: float) -> str:
+        return f"${v:,.2f}" if priced else f"{v:,.0f} tok"
+
+    def line(name: str, v: float, extra: str = "") -> str:
+        share = v / total if total else 0
+        bar = "█" * round(share * 24)
+        name = name if len(name) <= 28 else name[:27] + "…"
+        return f"  {name:<28} {amount(v):>14} {share:>5.0%}  {bar}{extra}"
+
+    out = [f"{agent} · {calls:,} calls · " + (
+        "priced at API list rates" if priced else "tokens only (pricing unreachable)"),
+        "", f"  {'TOTAL':<28} {amount(total):>14}", "", "By token type"]
+    out += [line(k, v) for k, v in sorted(by_kind.items(), key=lambda kv: -kv[1])]
+    out += ["", "By step"]
+    steps = sorted(by_step.items(), key=lambda kv: -kv[1][0])
+    out += [line(k, v[0], f"  {int(v[1]):,} calls") for k, v in steps[:top]]
+    if len(steps) > top:
+        out.append(f"  … {len(steps) - top} more steps")
+    out += ["", "By model"]
+    out += [line(k, v) for k, v in sorted(by_model.items(), key=lambda kv: -kv[1])[:top]]
+    if unpriced:
+        out += ["", "No list price yet for: " + ", ".join(sorted(unpriced)) + " (counted as $0)"]
+    out += ["", "Nothing was sent. Per line of your own agent's code: https://aight.studio"]
+    return "\n".join(out)
+
+
 def main(config: Collector, argv: list[str] | None = None) -> int:
     # Not description=__doc__: a module docstring is fifty lines of rationale
     # for whoever maintains the parser, and `--help` is the first thing a
@@ -603,6 +692,9 @@ def main(config: Collector, argv: list[str] | None = None) -> int:
                             "so running it again over an already-pushed directory doubles it")
     parser.add_argument("--dry-run", action="store_true",
                         help="print the rows instead of pushing them")
+    parser.add_argument("--report", action="store_true",
+                        help="print a priced breakdown (token type, step, model) and push "
+                             "nothing; every call unless --since narrows it")
     parser.add_argument("--watch", action="store_true",
                         help="keep running: re-scan and push on an interval, until interrupted")
     parser.add_argument("--interval", type=float, default=DEFAULT_INTERVAL_SECONDS,
@@ -611,6 +703,12 @@ def main(config: Collector, argv: list[str] | None = None) -> int:
                              f"(default: {DEFAULT_INTERVAL_SECONDS})")
     args = parser.parse_args(argv)
 
+    if args.report and args.watch:
+        parser.error("--report prints once; it can't be combined with --watch.")
+    # A report pushes nothing, so re-reading all history can't double anything.
+    if args.report and not args.since:
+        args.all_time = True
+
     # --since/--all-time scope every file by hand; a plain run resumes.
     manual = args.all_time or bool(args.since)
 
@@ -689,7 +787,7 @@ def main(config: Collector, argv: list[str] | None = None) -> int:
     if args.watch:
         api_key = os.environ.get("AIGHT_API_KEY")
         if not api_key:
-            print("Set AIGHT_API_KEY (Integrate tab of your AIght Workspace)", file=sys.stderr)
+            print("Set AIGHT_API_KEY (Project settings in your AIght Workspace)", file=sys.stderr)
             return 1
         url = os.environ.get("AIGHT_INGEST_URL", DEFAULT_INGEST_URL)
         ok, destination = _check_destination(config, api_key, url)
@@ -718,6 +816,10 @@ def main(config: Collector, argv: list[str] | None = None) -> int:
     rows = config.rows_for(calls)
     print(f"{len(paths)} transcript(s), {len(calls)} unique calls, {len(rows)} rows")
 
+    if args.report:
+        url = os.environ.get("AIGHT_INGEST_URL", DEFAULT_INGEST_URL)
+        print(report(rows, config.agent_id, fetch_prices(rows, url)))
+        return 0
     if args.dry_run:
         print(json.dumps(rows, indent=2))
         return 0
@@ -729,7 +831,7 @@ def main(config: Collector, argv: list[str] | None = None) -> int:
 
     api_key = os.environ.get("AIGHT_API_KEY")
     if not api_key:
-        print("Set AIGHT_API_KEY (Integrate tab of your AIght Workspace)", file=sys.stderr)
+        print("Set AIGHT_API_KEY (Project settings in your AIght Workspace)", file=sys.stderr)
         return 1
     url = os.environ.get("AIGHT_INGEST_URL", DEFAULT_INGEST_URL)
 

{aight-0.2.0 → aight-0.2.1}/aight/collect/proxy.py

@@ -434,7 +434,7 @@ def main(argv: list[str] | None = None) -> int:
 
     api_key = os.environ.get("AIGHT_API_KEY")
     if not api_key:
-        print("Set AIGHT_API_KEY (Integrate tab of your AIght Workspace)", file=sys.stderr)
+        print("Set AIGHT_API_KEY (Project settings in your AIght Workspace)", file=sys.stderr)
         return 1
     ingest_url = os.environ.get("AIGHT_INGEST_URL", DEFAULT_INGEST_URL)
     return serve(args.host, args.port, api_key, ingest_url, args.agent)

{aight-0.2.0 → aight-0.2.1}/aight/remote.py

@@ -1,8 +1,8 @@
 """Push locally-traced spend data to your hosted AIght Workspace.
 
 Stdlib only (urllib) — reporting cost data home shouldn't require pulling in
-`requests` on top of the tracing deps. Get an API key from the "Integrate"
-tab of your AIght Workspace, then after a traced run:
+`requests` on top of the tracing deps. Get an API key from Project settings
+in your AIght Workspace, then after a traced run:
 
     from aight.remote import push
     from aight.tracing import COST_PROCESSOR
@@ -68,7 +68,7 @@ def push(buckets, api_key: str | None = None, url: str | None = None) -> None:
     if not api_key:
         raise RuntimeError(
             "No API key. Pass api_key=..., or set AIGHT_API_KEY (get one from "
-            "the Integrate tab of your aight.studio dashboard)."
+            "Project settings in your AIght Workspace at aight.studio)."
         )
     url = url or os.environ.get("AIGHT_INGEST_URL", DEFAULT_INGEST_URL)
     rows = [
@@ -141,7 +141,7 @@ def push_event(
     if not api_key:
         raise RuntimeError(
             "No API key. Pass api_key=..., or set AIGHT_API_KEY (get one from "
-            "the Integrate tab of your aight.studio dashboard)."
+            "Project settings in your AIght Workspace at aight.studio)."
         )
     url = url or os.environ.get("AIGHT_EVENTS_INGEST_URL", DEFAULT_INGEST_URL.replace("/spans", "/events"))
     event = {
@@ -173,7 +173,7 @@ def push_value(value_by_file, api_key: str | None = None, url: str | None = None
     if not api_key:
         raise RuntimeError(
             "No API key. Pass api_key=..., or set AIGHT_API_KEY (get one from "
-            "the Integrate tab of your aight.studio dashboard)."
+            "Project settings in your AIght Workspace at aight.studio)."
         )
     url = url or os.environ.get("AIGHT_VALUE_INGEST_URL", DEFAULT_INGEST_URL.replace("/spans", "/value"))
     rows = [{"filepath": filepath, "value_usd": value} for filepath, value in value_by_file.items()]

{aight-0.2.0 → aight-0.2.1}/aight.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aight
-Version: 0.2.0
+Version: 0.2.1
 Summary: Attribute LLM spend to the exact source line, and push it to the AIght Workspace at aight.studio.
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://aight.studio

{aight-0.2.0 → aight-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aight"
-version = "0.2.0"
+version = "0.2.1"
 description = "Attribute LLM spend to the exact source line, and push it to the AIght Workspace at aight.studio."
 # SPDX identifier; the text it refers to is the LICENSE file in this directory.
 # The bare string is PEP 639, which is why the build floor below is setuptools

{aight-0.2.0 → aight-0.2.1}/tests/test_collect_claude_code.py

@@ -466,7 +466,7 @@ def test_a_key_for_another_project_refuses_instead_of_resuming(tmp_path, monkeyp
     """The one mistake the marker cannot catch by itself.
 
     A marker records that calls were *sent*, never where. So a key minted in a
-    different project's Integrate tab resumes this machine's coverage, pushes
+    different project's settings resumes this machine's coverage, pushes
     only what is newer than it into the wrong workspace, and leaves the project
     that was meant permanently missing that window — silently, because every
     one of those pushes succeeds. Refusing is the only safe direction.
@@ -737,3 +737,40 @@ def test_push_builds_a_request_that_reports_the_installed_version(monkeypatch):
     assert seen["headers"]["x-aight-sdk-version"] == base.SDK_VERSION
     assert seen["headers"]["x-aight-sdk-language"] == "a-collector"
     assert seen["headers"]["authorization"] == "Bearer key"
+
+
+def _row(step, model, calls, cache_read=0, output=0, filepath="", kind="external"):
+    return {
+        "chain": [{"filepath": "claude-code", "lineno": 0, "function": "claude-code"},
+                  {"filepath": filepath, "lineno": 0, "function": step}],
+        "kind": kind, "model": model, "calls": calls, "cost_usd": 0.0,
+        "input_tokens": 0, "output_tokens": output,
+        "cache_read_tokens": cache_read, "cache_creation_tokens": 0, "trace_id": "",
+    }
+
+
+def test_report_prices_with_the_server_rates_and_groups_tools_not_paths():
+    rows = [_row("reply", "m", 10, cache_read=1_000_000),
+            _row("Read", "m", 2, output=2000, filepath="/Users/someone/secret/notes.md"),
+            _row("Read", "unknown", 1, output=1000)]
+    out = collector.report(rows, "claude-code", {"m": {"cache_read": 0.0003, "output": 0.015}, "unknown": None})
+    assert "$0.30" in out.split("By step")[0]  # 1M cache read at 0.0003/1K
+    assert "$0.33" in out  # + 2K output at 0.015/1K; the unknown model is $0
+    assert "/Users/someone" not in out
+    assert out.count("Read") == 1
+    assert "No list price yet for: unknown" in out
+
+
+def test_report_falls_back_to_tokens_when_pricing_is_unreachable():
+    out = collector.report([_row("reply", "m", 1, cache_read=5000)], "claude-code", None)
+    assert "tokens only" in out and "5,000 tok" in out
+
+
+def test_report_pushes_nothing_and_reads_all_history(tmp_path, monkeypatch, capsys):
+    pushed = _recording_push(monkeypatch)
+    _recent(tmp_path / "base")
+    monkeypatch.setattr(collector, "fetch_prices", lambda rows, url: {})
+    assert main(["--root", str(tmp_path / "base"), "--report"]) == 0
+    assert pushed == []
+    out = capsys.readouterr().out
+    assert "Nothing was sent" in out and "go up" not in out