aight 0.1.0__tar.gz

aight-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

aight-0.1.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: aight
+Version: 0.1.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.1.0/README.md

@@ -0,0 +1,180 @@
+# 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 `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.
+
+## 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 the Integrate tab of 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.
+
+## 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 (Claude Code)
+
+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`:
+
+```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.
+
+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 Integrate
+  tab otherwise reads exactly like success, and fills a workspace nobody is
+  looking at.
+
+Without installing anything:
+
+```bash
+uvx --from aight aight-collect --dry-run
+```
+
+## 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.1.0/aight/AGENTS.md

@@ -0,0 +1,60 @@
+aight — instructions for an AI coding agent
+You are integrating aight into a project. aight attributes LLM spend to the exact source line that issued it, and pushes it to the hosted AIght Workspace at aight.studio. This file is your complete instruction set — follow it, don't guess at the API.
+1. Install
+You already ran the one command that got you here:
+pip install "aight[openai,anthropic]"
+Drop whichever of openai/anthropic the target project doesn't actually use — check its dependencies first.
+2. Get an API key
+Tell the user to mint one from the project's settings page in the AIght Workspace — the project selector at the top left, then Project settings — and set it as an environment variable, never hardcoded in source:
+export AIGHT_API_KEY="aight_..."
+3. Instrument the LLM calls — pick ONE path
+Path A — the project calls the OpenAI or Anthropic Python client directly. This is almost always the right path; it needs no changes to call sites:
+from aight.auto import auto_instrument
+auto_instrument()  # call once, near process startup, before any LLM calls
+Path B — no supported client library, or you want explicit control. Wrap each call site with traced_llm_call, passing the real model name and token counts from that call's actual response (never estimate them):
+from aight.tracing import traced_llm_call
+traced_llm_call(model, input_tokens=resp.usage.input_tokens, output_tokens=resp.usage.output_tokens)
+traced_llm_call returns None, and that is deliberate: this SDK ships no price table. It records the model and the token counts, and the platform prices them at receive time — the dollar figure lives in the AIght Workspace, never in your process. Never report a cost of your own for it to use.
+Do not do both — auto-instrumentation and manual wrapping of the same call double-count it.
+Latency is the caller's to measure, on both paths. This SDK records a call after it returns, not around it, so it has no duration of its own to report and must not invent one: time the call yourself and pass it as latency_ms=elapsed_ms, and let it be absent where you didn't measure it. A row with no latency shows as "—" on the agent's Speed axis in the Workspace — that is the correct answer for a call nobody timed, not a gap to fill with a guess.
+4. Push the data home
+Call this after a traced run completes (end of a request handler, a batch job, a shutdown hook — wherever makes sense for how this project runs):
+from aight.remote import push
+from aight.tracing import COST_PROCESSOR
+push(COST_PROCESSOR.buckets)
+5. Verify before you push
+Confirm attribution worked locally, with no network call, before wiring up push():
+python -c "from aight.tracing import COST_PROCESSOR; print(COST_PROCESSOR.report())"
+You should see the project's own file/line, not a framework's internal dispatch code. The report is calls and tokens per line — the sanity check is that the line and the token counts are right and the model name is real. There is no cost in it; the platform prices the pushed rows.
+6. Optional: Business value & direct metrics
+Only call report_value() if this project has a real, countable signal for what it earned — never invent or estimate a number:
+from aight.tracing import report_value, VALUE_BY_FILE
+from aight.remote import push_value
+report_value(49.0)
+push_value(VALUE_BY_FILE)
+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):
+import aight.tracing as aight
+
+with aight.TraceContext(trace_id="chk_12345_stripe", labels={"tier": "enterprise", "feature": "pdf_extractor"}):
+    aight.traced_llm_call("gpt-4", input_tokens=500, output_tokens=150)
+Option B — Passing parameters directly to a call:
+from aight.tracing import traced_llm_call
+
+traced_llm_call(
+    "gpt-4", 
+    input_tokens=200, 
+    output_tokens=50, 
+    trace_id="custom_event_id", 
+    labels={"campaign": "black_friday"}
+)
+8. Optional: Report the business event itself
+A trace_id or labels only tag the LLM cost side — to actually feed cost-vs-value matching, push the business event too (a Stripe checkout succeeding, a ticket closing, a signup). Give it a real event_name and value; leave trace_id unset to fall back to the active TraceContext:
+from aight.remote import push_event
+
+push_event("checkout_completed", value=49.0, currency="USD")
+Guardrails
+Never fabricate a metric aight doesn't actually capture — latency included. It is never estimated, never inferred from how long the SDK took, and never defaulted to zero-with-a-mention; it is simply absent until the caller measures and passes it.
+Don't wrap the same call twice (Path A and Path B together).
+AIGHT_API_KEY is a secret: env var or secrets manager, never committed.

aight-0.1.0/aight/__init__.py

@@ -0,0 +1,26 @@
+"""AIght SDK: attribute LLM spend to the exact source line that issued it,
+and push that data to your hosted AIght Workspace.
+
+Auto-instrument a supported provider so every real call is traced with no
+per-call wrapping. Needs that provider's extra (`aight[openai]` /
+`aight[anthropic]`), installed from the git URL in the README — this SDK is
+not on PyPI:
+
+    from aight.auto import auto_instrument
+    from aight.remote import push
+    from aight.tracing import COST_PROCESSOR
+
+    auto_instrument()
+    # ...call your LLM client as normal...
+    push(COST_PROCESSOR.buckets)
+
+Or trace manually, call by call:
+
+    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)
+    push(COST_PROCESSOR.buckets)
+"""
+
+__version__ = "0.1.0"

aight-0.1.0/aight/auto.py

@@ -0,0 +1,53 @@
+"""Auto-instrumentation: patches supported LLM provider clients so every
+real call is traced without wrapping each one in traced_llm_call().
+
+Each provider's OTel instrumentor package is optional. Install the extra
+for whatever you use (`aight[openai]`, `aight[anthropic]`, from the git URL
+in the README — this SDK is not on PyPI); anything not installed is skipped,
+not an error, so a customer using only one provider never has to install the
+other's instrumentor.
+
+Auto-instrumented calls carry no latency. A duration is reported only when
+the caller measures the call and passes it to traced_llm_call(), and an
+instrumentor has none to pass — so those rows show "—" on the Speed axis
+rather than a number nobody took.
+"""
+from __future__ import annotations
+
+import importlib
+import logging
+
+logger = logging.getLogger("aight.auto")
+
+_INSTRUMENTORS = {
+    "openai": ("opentelemetry.instrumentation.openai", "OpenAIInstrumentor"),
+    "anthropic": ("opentelemetry.instrumentation.anthropic", "AnthropicInstrumentor"),
+}
+
+_instrumented: set[str] = set()
+
+
+def auto_instrument(providers: list[str] | None = None) -> list[str]:
+    """Instrument each named provider's client library (default: every
+    known provider). Returns the providers actually instrumented this call.
+    A provider whose instrumentor package isn't installed, or that's
+    already instrumented, is silently skipped."""
+    names = providers if providers is not None else list(_INSTRUMENTORS)
+    done = []
+    for name in names:
+        if name in _instrumented:
+            continue
+        target = _INSTRUMENTORS.get(name)
+        if target is None:
+            logger.warning("aight: unknown provider %r, skipping", name)
+            continue
+        module_name, class_name = target
+        try:
+            module = importlib.import_module(module_name)
+            instrumentor_cls = getattr(module, class_name)
+        except (ImportError, AttributeError):
+            continue
+        instrumentor_cls().instrument()
+        _instrumented.add(name)
+        done.append(name)
+    return done

aight-0.1.0/aight/collect/__init__.py

@@ -0,0 +1,7 @@
+"""Collectors for agents the customer runs but did not write.
+
+Each reads an agent's own on-disk record of the calls it made and pushes one
+row per step. Unlike the SDKs these instrument nothing — there is no customer
+code on the stack to bind to, which is why the chain they push is a step path
+rather than a source path. See docs/hub/agents.md external-agent section.
+"""