token-aud
AI cost optimization toolkit for LLM workloads.
token-aud now includes two complementary workflows:
- Audit mode (CLI/API): Analyze historical usage logs and estimate savings opportunities with Student-Teacher-Judge sampling.
- AgentSpend SDK: Route live agent steps (
plan,reason,tool,verify,draft,summarize) to cost/quality-appropriate models with fallbacks, loop guards, and telemetry.
Installation
uv sync --no-editable
For local development tooling (tests):
uv sync --no-editable --extra dev
Quick Start (AgentSpend)
Run these three commands from repo root:
uv sync --no-editable --extra dev
uv run --no-sync python -m pytest tests/agent -q
uv run --no-sync python examples/agent_routing_demo.py
Expected results:
- Agent tests pass.
- Demo prints routed step decisions, per-step telemetry, and total run cost.
agent_telemetry.jsonlis generated locally.
AgentSpend Usage
1) Default policy
from token_aud.agent import AgentSpend
agent = AgentSpend.default()
result = agent.route_call(
step="plan",
messages=[{"role": "user", "content": "Break this task into a plan"}],
)
print(result.model_used, result.cost_usd, result.content)
2) Custom policy YAML
from token_aud.agent import AgentSpend
agent = AgentSpend.from_yaml("routing_policy.yaml")
result = agent.route_call(
step="reason",
messages=[{"role": "user", "content": "Compare two architectures"}],
)
print(result.model_used, result.fallbacks_tried)
Built-in default policy path:
src/token_aud/data/default_routing_policy.yaml
AgentSpend Core Components
src/token_aud/agent/policy.py: Pydantic policy schema + YAML loadingsrc/token_aud/agent/router.py: deterministic model selectionsrc/token_aud/agent/runtime.py:route_call()execution + fallbackssrc/token_aud/agent/loop_guard.py: repeated-turn loop detectionsrc/token_aud/agent/telemetry.py: JSONL/HTTP telemetry sinkssrc/token_aud/agent/adaptive.py: optional adaptive routing layer
AgentSpend Examples
examples/agent_routing_demo.py: end-to-end routed run with telemetryexamples/custom_policy_demo.py: loop escalation and hard-stop behaviorexamples/framework_agnostic_integration.py: generic agent-loop integration with explicit success feedbackscripts/summarize_telemetry.py: convertagent_telemetry.jsonlinto cost/fallback/latency summary
uv run --no-sync python scripts/summarize_telemetry.py agent_telemetry.jsonl
Audit CLI (legacy + still supported)
uv run --no-sync token-aud --help
uv run --no-sync token-aud analyze sample_data.csv --dry-run
Environment Variables
Common provider credentials:
OPENAI_API_KEYANTHROPIC_API_KEYGEMINI_API_KEYorGOOGLE_API_KEY(depending on provider path)
For Google Vertex flows, ensure ADC is configured (gcloud auth application-default login).
Metadata
Release files for agentspend-sdk 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentspend_sdk-0.1.0.tar.gz | 224.8 kB | Without provenance | Details for agentspend_sdk-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentspend_sdk-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agentspend_sdk-0.1.0-py3-none-any.whl |
Total release size: 279.3 kB
Release files / agentspend_sdk-0.1.0.tar.gz
| Download URL | agentspend_sdk-0.1.0.tar.gz |
|---|---|
| Size | 224.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0ba818d150f69d87cf4436219abdfd5b4ef69d6a6ecfb962fd03bc8142383493
|
|
BLAKE2b-256 checksum How to use checksums |
68f5d523c18953e01d198ea19954fb996b7401aef277ff1bdf71dc1e778c908c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Release files / agentspend_sdk-0.1.0-py3-none-any.whl
| Download URL | agentspend_sdk-0.1.0-py3-none-any.whl |
|---|---|
| Size | 54.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cd153ec9d7ea677eac8765489c2cee4c330491b9c772cfc396794ee0816e200d
|
|
BLAKE2b-256 checksum How to use checksums |
0d4e77897825a9c7e13116449cb4ff531884eddf4f0148839c548d0d8998d69f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.12
|
Security for agentspend-sdk 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.