aight 0.2.0__tar.gz → 0.2.2__tar.gz

aight-0.2.2/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: aight
+Version: 0.2.2
+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
+Project-URL: Documentation, https://aight.studio/docs
+Project-URL: Repository, https://github.com/theunknownport/aight-clients
+Keywords: llm,llm-cost,ai-agents,observability,llmops,profiler,claude-code,langchain,langgraph,openai,anthropic,finops
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opentelemetry-api>=1.27
+Requires-Dist: opentelemetry-sdk>=1.27
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: langgraph>=0.2; extra == "examples"
+Provides-Extra: openai
+Requires-Dist: opentelemetry-instrumentation-openai>=0.30.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.30.0; extra == "anthropic"
+Dynamic: license-file
+
+# aight (Python SDK)
+
+Attributes LLM spend to the exact source line that issued it, and pushes it
+to your [aight.studio](https://aight.studio) AIght Workspace.
+
+No price table ships in this SDK, by design. The SDK sends the model and the
+token counts; **the platform prices them** — it recomputes `cost_usd` for
+every row at receive time — so the dollar figures in the AIght Workspace are
+always the platform's current prices, never a snapshot frozen at install
+time. `traced_llm_call` therefore returns `None`, not a cost.
+
+## Install
+
+```bash
+pip install aight
+```
+
+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
+
+Paste this into Claude Code, Cursor, or any other coding agent, in whatever
+project you want traced:
+
+> Run `pip install "aight[openai,anthropic]"`, then read the `AGENTS.md` file
+> next to the installed `aight` package and follow it to wire up cost
+> attribution for this project.
+
+`AGENTS.md` ships inside the package (`python -c "import aight, pathlib; print(pathlib.Path(aight.__file__).parent / 'AGENTS.md')"`)
+so the agent has the full integration recipe locally — no extra fetch, and
+nothing it has to be able to reach over the network.
+
+## Use
+
+```python
+from aight.tracing import traced_llm_call, COST_PROCESSOR
+from aight.remote import push
+
+traced_llm_call("gpt-4o-mini", input_tokens=180, output_tokens=60)
+# ...wrap every LLM call your agent makes the same way...
+
+push(COST_PROCESSOR.buckets)  # reads AIGHT_API_KEY from the environment
+```
+
+Get an API key from Project settings in your AIght Workspace, then:
+
+```bash
+export AIGHT_API_KEY="aight_..."
+```
+
+`traced_llm_call` walks the call stack past known framework packages
+(LangGraph, LangChain) to attribute the span to your code, not theirs.
+
+### Latency is yours to measure
+
+This SDK does not time the LLM call. It is called *after* your call returns,
+not around it, so a duration taken here would measure the cost of recording
+rather than the cost of the model. Time the call yourself and pass it:
+
+```python
+import time
+from aight.tracing import traced_llm_call
+
+started = time.perf_counter()
+response = client.chat.completions.create(...)
+elapsed_ms = (time.perf_counter() - started) * 1000
+
+traced_llm_call(model, input_tokens, output_tokens, latency_ms=elapsed_ms)
+```
+
+Leave `latency_ms` out and no latency is claimed — the Workspace shows "—" on
+that agent's Speed axis rather than an impossibly fast number. The
+auto-instrumented path cannot measure it either, so rows it records carry
+none: if you want Speed for a call, wrap that call by hand.
+
+## Auto-instrument (no manual wrapping)
+
+```bash
+pip install "aight[openai]"   # or aight[anthropic]
+```
+
+```python
+from aight.auto import auto_instrument
+from aight.remote import push
+from aight.tracing import COST_PROCESSOR
+
+auto_instrument()
+# ...call the OpenAI/Anthropic client exactly as you normally would...
+
+push(COST_PROCESSOR.buckets)
+```
+
+`auto_instrument()` silently skips any provider whose instrumentor package
+isn't installed, so it's safe to call unconditionally. It patches the provider
+client, not the call, so the rows it records carry no latency — see above.
+
+## Spent vs earned
+
+Report the value your agent generates alongside its spend, to power the
+AIght Workspace's spent-vs-earned view:
+
+```python
+from aight.tracing import report_value, VALUE_BY_FILE
+from aight.remote import push_value
+
+report_value(49.0)  # a closed deal, a resolved ticket — whatever you count
+push_value(VALUE_BY_FILE)
+```
+
+`push_value` sends what has accumulated and clears it once the server has
+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
+calls-and-tokens-by-line report with no network calls, useful for local
+debugging or fully offline use. It has no dollar figure: pricing is the
+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
+
+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`. 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_..."
+
+aight-collect --dry-run   # print the rows instead of sending them
+aight-collect             # push them
+```
+
+It reads Claude Code's transcripts under `~/.claude/projects` and pushes one
+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:
+
+```bash
+aight-collect --watch              # re-scan every 30s, until Ctrl-C
+aight-collect --watch --interval 10
+```
+
+`--watch` cannot be combined with `--since` or `--all-time`. Those name a scope
+to re-send, and a loop would re-send it every interval — which the API *adds* to
+what it already holds, so the second tick would double the first. Run them once
+to catch up, then start the watcher.
+
+Three things are worth knowing before the first run:
+
+- **A plain run resumes.** It records the newest call it pushed for each
+  transcript file in `~/.aight/`, so a second run sends only what is new.
+  Running it repeatedly is the intended use.
+- **`--all-time` does not resume.** It re-sends the whole history, and the API
+  *adds* what it receives to what it already holds — so pushing the same calls
+  twice doubles the recorded spend permanently. Cost is frozen at receive time
+  and there is no repair path. Reach for it only on a transcript that has never
+  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 settings
+  otherwise reads exactly like success, and fills a workspace nobody is
+  looking at.
+
+Without installing anything:
+
+```bash
+uvx --from aight aight-collect --dry-run
+```
+
+The same machinery covers three more agents, each as its own command:
+
+| Command | Reads | Needs |
+|---|---|---|
+| `aight-collect` | Claude Code — `~/.claude/projects` | nothing |
+| `aight-collect-codex` | Codex CLI — `~/.codex/sessions` (`CODEX_HOME` respected) | nothing |
+| `aight-collect-gemini` | Gemini CLI — `~/.gemini/tmp` | nothing |
+| `aight-collect-aider` | Aider's `--analytics-log` file | **you must pass the path** |
+
+Everything above applies to all four — the resume marker, `--since`/`--all-time`,
+`--watch`, and the destination check — because they share one implementation of
+it rather than one copy each.
+
+Aider is the odd one and the command says so when it has nothing to read: it
+writes a per-call log **only** if it was started with `--analytics-log FILE`,
+and there is no default location. A session that already ran without that flag
+cannot be collected, because Aider recorded nothing for it. Start Aider with
+the flag, then point this at the same file.
+
+The proxy below is the fallback for an agent none of these cover — including
+the ones whose records are not readable at all.
+
+## Any other agent (the proxy)
+
+The collector above reads Claude Code's own transcripts, which means one parser
+per agent — and several agents keep no readable per-call record at all. Cursor
+keeps no token counts on disk; Amp emits no model name anywhere. So for those
+there is nothing to parse, and the answer is not another parser.
+
+`aight-proxy` stands between the agent and the API instead. It sees the request
+and the response, so it does not need to know what the agent is:
+
+```bash
+aight-proxy                                  # 127.0.0.1:8787
+export OPENAI_BASE_URL=http://127.0.0.1:8787/openai
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8787/anthropic
+```
+
+The path prefix picks the upstream, because both APIs live under `/v1/` and
+`/v1/messages` would otherwise be ambiguous. Everything after the prefix is
+forwarded unchanged, including your `Authorization` header — the proxy holds no
+credentials of its own and stores nothing from the request or the response.
+
+It works for anything that lets you point its base URL somewhere else, which is
+most agents. Name them so several through one proxy stay distinct:
+
+```bash
+AIGHT_PROXY_AGENT=codex aight-proxy
+```
+
+Four things worth knowing:
+
+- **It measures latency**, which the SDKs cannot. They record after the call
+  returns, so a duration taken there would time the recording; the proxy sits
+  around the call, so `latency_ms` is real.
+- **OpenAI's cached tokens are subtracted.** `prompt_tokens` counts the cached
+  prefix and AIght's `input_tokens` does not, so sending the inclusive number
+  would bill those tokens twice — permanently, since cost is frozen at receive
+  time. Anthropic reports the split itself and nothing is subtracted there.
+- **Streaming OpenAI requests get `stream_options.include_usage` added.** That
+  is a change to your request, not a passive read: without it a streaming call
+  carries no usage at all, and most calls stream. Anthropic needs no equivalent.
+- **Nothing is priced here.** Rows go up with `cost_usd` 0.0 and the platform
+  prices them from its own table at receive time.
+
+## Example
+
+`examples/langgraph_spike.py` traces a 3-node LangGraph agent and prints the
+attribution report (also pushes it, if `AIGHT_API_KEY` is set). It ships in the
+repo rather than in the wheel, so run it from a clone:
+
+```bash
+cd /path/to/aight-clients/python
+pip install ".[examples]"     # langgraph; ".[dev,examples]" adds pytest and ruff
+python -m examples.langgraph_spike
+```

{aight-0.2.0 → aight-0.2.2}/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.2}/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.2}/aight/__init__.py

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

{aight-0.2.0 → aight-0.2.2}/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.2}/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.2}/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.2/aight.egg-info/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: aight
+Version: 0.2.2
+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
+Project-URL: Documentation, https://aight.studio/docs
+Project-URL: Repository, https://github.com/theunknownport/aight-clients
+Keywords: llm,llm-cost,ai-agents,observability,llmops,profiler,claude-code,langchain,langgraph,openai,anthropic,finops
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opentelemetry-api>=1.27
+Requires-Dist: opentelemetry-sdk>=1.27
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: langgraph>=0.2; extra == "examples"
+Provides-Extra: openai
+Requires-Dist: opentelemetry-instrumentation-openai>=0.30.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.30.0; extra == "anthropic"
+Dynamic: license-file
+
+# aight (Python SDK)
+
+Attributes LLM spend to the exact source line that issued it, and pushes it
+to your [aight.studio](https://aight.studio) AIght Workspace.
+
+No price table ships in this SDK, by design. The SDK sends the model and the
+token counts; **the platform prices them** — it recomputes `cost_usd` for
+every row at receive time — so the dollar figures in the AIght Workspace are
+always the platform's current prices, never a snapshot frozen at install
+time. `traced_llm_call` therefore returns `None`, not a cost.
+
+## Install
+
+```bash
+pip install aight
+```
+
+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
+
+Paste this into Claude Code, Cursor, or any other coding agent, in whatever
+project you want traced:
+
+> Run `pip install "aight[openai,anthropic]"`, then read the `AGENTS.md` file
+> next to the installed `aight` package and follow it to wire up cost
+> attribution for this project.
+
+`AGENTS.md` ships inside the package (`python -c "import aight, pathlib; print(pathlib.Path(aight.__file__).parent / 'AGENTS.md')"`)
+so the agent has the full integration recipe locally — no extra fetch, and
+nothing it has to be able to reach over the network.
+
+## Use
+
+```python
+from aight.tracing import traced_llm_call, COST_PROCESSOR
+from aight.remote import push
+
+traced_llm_call("gpt-4o-mini", input_tokens=180, output_tokens=60)
+# ...wrap every LLM call your agent makes the same way...
+
+push(COST_PROCESSOR.buckets)  # reads AIGHT_API_KEY from the environment
+```
+
+Get an API key from Project settings in your AIght Workspace, then:
+
+```bash
+export AIGHT_API_KEY="aight_..."
+```
+
+`traced_llm_call` walks the call stack past known framework packages
+(LangGraph, LangChain) to attribute the span to your code, not theirs.
+
+### Latency is yours to measure
+
+This SDK does not time the LLM call. It is called *after* your call returns,
+not around it, so a duration taken here would measure the cost of recording
+rather than the cost of the model. Time the call yourself and pass it:
+
+```python
+import time
+from aight.tracing import traced_llm_call
+
+started = time.perf_counter()
+response = client.chat.completions.create(...)
+elapsed_ms = (time.perf_counter() - started) * 1000
+
+traced_llm_call(model, input_tokens, output_tokens, latency_ms=elapsed_ms)
+```
+
+Leave `latency_ms` out and no latency is claimed — the Workspace shows "—" on
+that agent's Speed axis rather than an impossibly fast number. The
+auto-instrumented path cannot measure it either, so rows it records carry
+none: if you want Speed for a call, wrap that call by hand.
+
+## Auto-instrument (no manual wrapping)
+
+```bash
+pip install "aight[openai]"   # or aight[anthropic]
+```
+
+```python
+from aight.auto import auto_instrument
+from aight.remote import push
+from aight.tracing import COST_PROCESSOR
+
+auto_instrument()
+# ...call the OpenAI/Anthropic client exactly as you normally would...
+
+push(COST_PROCESSOR.buckets)
+```
+
+`auto_instrument()` silently skips any provider whose instrumentor package
+isn't installed, so it's safe to call unconditionally. It patches the provider
+client, not the call, so the rows it records carry no latency — see above.
+
+## Spent vs earned
+
+Report the value your agent generates alongside its spend, to power the
+AIght Workspace's spent-vs-earned view:
+
+```python
+from aight.tracing import report_value, VALUE_BY_FILE
+from aight.remote import push_value
+
+report_value(49.0)  # a closed deal, a resolved ticket — whatever you count
+push_value(VALUE_BY_FILE)
+```
+
+`push_value` sends what has accumulated and clears it once the server has
+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
+calls-and-tokens-by-line report with no network calls, useful for local
+debugging or fully offline use. It has no dollar figure: pricing is the
+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
+
+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`. 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_..."
+
+aight-collect --dry-run   # print the rows instead of sending them
+aight-collect             # push them
+```
+
+It reads Claude Code's transcripts under `~/.claude/projects` and pushes one
+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:
+
+```bash
+aight-collect --watch              # re-scan every 30s, until Ctrl-C
+aight-collect --watch --interval 10
+```
+
+`--watch` cannot be combined with `--since` or `--all-time`. Those name a scope
+to re-send, and a loop would re-send it every interval — which the API *adds* to
+what it already holds, so the second tick would double the first. Run them once
+to catch up, then start the watcher.
+
+Three things are worth knowing before the first run:
+
+- **A plain run resumes.** It records the newest call it pushed for each
+  transcript file in `~/.aight/`, so a second run sends only what is new.
+  Running it repeatedly is the intended use.
+- **`--all-time` does not resume.** It re-sends the whole history, and the API
+  *adds* what it receives to what it already holds — so pushing the same calls
+  twice doubles the recorded spend permanently. Cost is frozen at receive time
+  and there is no repair path. Reach for it only on a transcript that has never
+  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 settings
+  otherwise reads exactly like success, and fills a workspace nobody is
+  looking at.
+
+Without installing anything:
+
+```bash
+uvx --from aight aight-collect --dry-run
+```
+
+The same machinery covers three more agents, each as its own command:
+
+| Command | Reads | Needs |
+|---|---|---|
+| `aight-collect` | Claude Code — `~/.claude/projects` | nothing |
+| `aight-collect-codex` | Codex CLI — `~/.codex/sessions` (`CODEX_HOME` respected) | nothing |
+| `aight-collect-gemini` | Gemini CLI — `~/.gemini/tmp` | nothing |
+| `aight-collect-aider` | Aider's `--analytics-log` file | **you must pass the path** |
+
+Everything above applies to all four — the resume marker, `--since`/`--all-time`,
+`--watch`, and the destination check — because they share one implementation of
+it rather than one copy each.
+
+Aider is the odd one and the command says so when it has nothing to read: it
+writes a per-call log **only** if it was started with `--analytics-log FILE`,
+and there is no default location. A session that already ran without that flag
+cannot be collected, because Aider recorded nothing for it. Start Aider with
+the flag, then point this at the same file.
+
+The proxy below is the fallback for an agent none of these cover — including
+the ones whose records are not readable at all.
+
+## Any other agent (the proxy)
+
+The collector above reads Claude Code's own transcripts, which means one parser
+per agent — and several agents keep no readable per-call record at all. Cursor
+keeps no token counts on disk; Amp emits no model name anywhere. So for those
+there is nothing to parse, and the answer is not another parser.
+
+`aight-proxy` stands between the agent and the API instead. It sees the request
+and the response, so it does not need to know what the agent is:
+
+```bash
+aight-proxy                                  # 127.0.0.1:8787
+export OPENAI_BASE_URL=http://127.0.0.1:8787/openai
+export ANTHROPIC_BASE_URL=http://127.0.0.1:8787/anthropic
+```
+
+The path prefix picks the upstream, because both APIs live under `/v1/` and
+`/v1/messages` would otherwise be ambiguous. Everything after the prefix is
+forwarded unchanged, including your `Authorization` header — the proxy holds no
+credentials of its own and stores nothing from the request or the response.
+
+It works for anything that lets you point its base URL somewhere else, which is
+most agents. Name them so several through one proxy stay distinct:
+
+```bash
+AIGHT_PROXY_AGENT=codex aight-proxy
+```
+
+Four things worth knowing:
+
+- **It measures latency**, which the SDKs cannot. They record after the call
+  returns, so a duration taken there would time the recording; the proxy sits
+  around the call, so `latency_ms` is real.
+- **OpenAI's cached tokens are subtracted.** `prompt_tokens` counts the cached
+  prefix and AIght's `input_tokens` does not, so sending the inclusive number
+  would bill those tokens twice — permanently, since cost is frozen at receive
+  time. Anthropic reports the split itself and nothing is subtracted there.
+- **Streaming OpenAI requests get `stream_options.include_usage` added.** That
+  is a change to your request, not a passive read: without it a streaming call
+  carries no usage at all, and most calls stream. Anthropic needs no equivalent.
+- **Nothing is priced here.** Rows go up with `cost_usd` 0.0 and the platform
+  prices them from its own table at receive time.
+
+## Example
+
+`examples/langgraph_spike.py` traces a 3-node LangGraph agent and prints the
+attribution report (also pushes it, if `AIGHT_API_KEY` is set). It ships in the
+repo rather than in the wheel, so run it from a clone:
+
+```bash
+cd /path/to/aight-clients/python
+pip install ".[examples]"     # langgraph; ".[dev,examples]" adds pytest and ruff
+python -m examples.langgraph_spike
+```

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

@@ -1,12 +1,22 @@
 [project]
 name = "aight"
-version = "0.2.0"
+version = "0.2.2"
 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
 # 77 — older versions want the deprecated {text = "Apache-2.0"} table instead.
 license = "Apache-2.0"
 requires-python = ">=3.11"
+readme = "README.md"
+keywords = ["llm", "llm-cost", "ai-agents", "observability", "llmops", "profiler",
+            "claude-code", "langchain", "langgraph", "openai", "anthropic", "finops"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Monitoring",
+]
 dependencies = [
     "opentelemetry-api>=1.27",
     "opentelemetry-sdk>=1.27",
@@ -30,6 +40,7 @@ aight-proxy = "aight.collect.proxy:cli"
 
 [project.urls]
 Homepage = "https://aight.studio"
+Documentation = "https://aight.studio/docs"
 Repository = "https://github.com/theunknownport/aight-clients"
 
 [build-system]

{aight-0.2.0 → aight-0.2.2}/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

aight-0.2.0/PKG-INFO

@@ -1,21 +0,0 @@
-Metadata-Version: 2.4
-Name: aight
-Version: 0.2.0
-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
-Project-URL: Repository, https://github.com/theunknownport/aight-clients
-Requires-Python: >=3.11
-License-File: LICENSE
-Requires-Dist: opentelemetry-api>=1.27
-Requires-Dist: opentelemetry-sdk>=1.27
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Provides-Extra: examples
-Requires-Dist: langgraph>=0.2; extra == "examples"
-Provides-Extra: openai
-Requires-Dist: opentelemetry-instrumentation-openai>=0.30.0; extra == "openai"
-Provides-Extra: anthropic
-Requires-Dist: opentelemetry-instrumentation-anthropic>=0.30.0; extra == "anthropic"
-Dynamic: license-file

aight-0.2.0/aight.egg-info/PKG-INFO

@@ -1,21 +0,0 @@
-Metadata-Version: 2.4
-Name: aight
-Version: 0.2.0
-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
-Project-URL: Repository, https://github.com/theunknownport/aight-clients
-Requires-Python: >=3.11
-License-File: LICENSE
-Requires-Dist: opentelemetry-api>=1.27
-Requires-Dist: opentelemetry-sdk>=1.27
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Provides-Extra: examples
-Requires-Dist: langgraph>=0.2; extra == "examples"
-Provides-Extra: openai
-Requires-Dist: opentelemetry-instrumentation-openai>=0.30.0; extra == "openai"
-Provides-Extra: anthropic
-Requires-Dist: opentelemetry-instrumentation-anthropic>=0.30.0; extra == "anthropic"
-Dynamic: license-file