aight 0.1.0__py3-none-any.whl

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/__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/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/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.
+"""