Metadata-Version: 2.4
Name: agentcents
Version: 1.1.2
Summary: LLM API cost interceptor and budget enforcer for AI agents
Author-email: Labham LLC <founder1@labham.com>
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: httpx>=0.24.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.23.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: pro
Requires-Dist: fastembed>=0.1.0; extra == "pro"
Requires-Dist: sqlite-vec>=0.1.0; extra == "pro"
Requires-Dist: xgboost>=2.0.0; extra == "pro"
Requires-Dist: scikit-learn>=1.3.0; extra == "pro"
Requires-Dist: textual>=0.40.0; extra == "pro"
Dynamic: license-file

# agentcents

**Stop overpaying for the wrong model.**

agentcents sits between your agent and any LLM. Before each call it forecasts the
cost as an honest range — measured input, estimated output, per candidate model —
tracks every cent you actually spend, and proves its own forecasting accuracy on a
calibration page. Point your client at it. Change nothing else.

```bash
pip install agentcents
```

*No API keys. No accounts. No code changes beyond one base URL.*

---

## New in 0.2.5

The release where agentcents stops just watching and starts forecasting:

- **`agentcents explain`** — EXPLAIN COST for an LLM call. Pipe a request in,
  get every candidate model priced as a **p50 → p90 range** before you spend.
  Input tokens are measured; output tokens are estimated from your own workload's
  histogram — and when two candidates swap rank inside the range, the decision is
  flagged **unstable** instead of pretending to certainty.
- **Calibration page** (`/explain`) — every proxied call silently logs its forecast
  next to what it actually cost. Coverage gauges, q-error, and a per-call
  calibration strip show whether the estimator has earned your trust.
  `agentcents explain --accuracy` gives the same report in the terminal.
- **Orchestrator page** (`/orchestrator`) — the plan-chooser, shown before it binds:
  per-node routing decisions, each gated by robustness, a capability quality floor,
  tool-use and provider-boundary rules. Advisory today; auto-apply only unlocks once
  the calibration page shows the forecasts hold.
- **Two Cents** — a neutral cost guide built into every dashboard page. It answers
  from your own ledger, runs on your own local model by default (~$0 per answer,
  metered in your own dashboard), and is allowed to say *"use the free local
  model"* — because it isn't selling tokens.
- **Cache-aware cost accounting** — cached input tokens (OpenAI
  `prompt_tokens_details`, Anthropic `cache_read/creation_input_tokens`) are now
  priced correctly. Previously, heavily-cached traffic was over-counted by the
  cache discount; ledgers are accurate from this release forward.
- Redesigned dashboard — a ledger, not a cockpit — with dark mode.

---

## The problem

Most agents pick one frontier model and use it for everything — classifying,
retrieving, the hard reasoning step, the trivial cleanup step. The easy steps don't
need a frontier model. You're paying Opus-4.8 prices to decide whether a message is a
question or a complaint.

agentcents shows you, per step, what you pay and what you *could* pay — then routes
each step to the cheapest model that clears the bar. In a typical 7-step task:

> **all-Opus-4.8 $0.114 → cost-routed $0.055 — 51% cheaper**, keeping the flagship
> only where the work demands it.

---

## How it works

A local proxy sits between your agent and the LLM provider. You point at it; it does
the rest — identifies each task (no tagging required), prices it against every current
model, checks capability, and shows you the plan.

```
your agent  →  agentcents (localhost:8082)  →  any LLM provider
```

1. `pip install agentcents` — Python ≥ 3.9
2. `agentcents start` — the local proxy comes up on port 8082
3. Point your client at it (one base URL, or wrap your run — see below)
4. `agentcents usage` — see exactly where every cent went

---

## Forecast, calibrate, orchestrate — the trust ladder

Cost tools that auto-route on day one are asking you to trust an estimator you've
never seen graded. agentcents does it in the order an engineer would:

**1 · Forecast.** `agentcents explain` prices a request on every candidate model
*before it runs*. The parts that can be measured are measured (your prompt's tokens,
known cache state); the part that can't — how much the model will say — is an honest
p50 → p90 range learned from your own traffic, never a falsely precise point.

```
$ echo '{"model":"gpt-4o","messages":[...]}' | agentcents explain --tag whatsapp

CANDIDATE              TOTAL p50→p90            note
ollama/local           $0.000015 → $0.000018    ← pick · util 12%
openai/gpt-4o-mini     $0.000294 → $0.000498
openai/gpt-4o          $0.004900 → $0.008300    requested
```

**2 · Calibrate.** Every call through the proxy silently logs its forecast next to
the actual. The `/explain` calibration page — and `agentcents explain --accuracy` —
grade the estimator in public: p90 coverage against its 90% target, q-error against
1.00, one candle per call on the calibration strip. You watch the forecasts earn
their keep on *your* workload, not a benchmark.

**3 · Orchestrate.** The `/orchestrator` page shows the plan-chooser's per-node
decisions, each passing five gates: **robustness** (a swap binds only if it's
cheapest across the whole forecast range), a **quality floor** (never route below the
node's capability bar), **tool-use** and **provider-boundary** safety, and the
**trust gate** — binding requires the calibration page to prove the forecasts first.
Advisory today, by design. The switch flips when the evidence does.

---

## Two Cents — the neutral cost guide

Every dashboard page carries **✦ two cents**: ask about your spend, your calibration,
your tags, or how anything on screen works, in plain language.

What makes it different from the AI assistant in every other tool:

- **It runs on your hardware by default.** Local-first: it picks a model from your
  own Ollama installation, answers for fractions of a cent of electricity, and shows
  you the cost of each answer — metered in your own ledger, subject to your own
  budgets, like any other agent.
- **It isn't selling tokens.** A cloud vendor's chatbot will never tell you to use
  the free local model. Two Cents will, because that's often the right answer.
  Cloud fallback exists but only among models *you've actually used and hold a key
  for* — never a catalog — and always with a billing warning.
- **It sees aggregates, never prompts.** Spend summaries, calibration stats, what's
  on your screen. Your prompt contents are not stored and not shared.
- **Its memory is yours.** Conversation memory lives in your local ledger, compressed
  over time by your own local model, and survives switching to any LLM.

---

## Quick start

**Zero-config — wrap your run:**

```bash
agentcents run -- python my_agent.py
```

agentcents sets the base URLs, groups the run into one session, and gets out of the
way. Your agent code is untouched.

**Or one env var:**

```bash
export OPENAI_BASE_URL="http://localhost:8082/openai"
python my_agent.py
```

**Or one line in code:**

```python
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8082/openai")
# everything else stays exactly the same
```

Already setting your own session or tag headers? agentcents recognizes the common
ones (`X-Session-ID`, `X-Request-ID`, and more) automatically. The proxy adapts to
your client — never the other way around.

---

## What the proxy does

It doesn't just log. It advises.

- **Cost, before you spend.** A request's cost on every candidate model as an honest
  range — fresh input, cached input, cache writes, output — never a false point
  estimate.
- **Cheapest *capable* model, not just cheapest.** Every candidate is ranked by a real
  capability score (Artificial Analysis Intelligence Index) alongside its price, so the
  advice is "cheapest model that clears this step's bar," never "cheapest, quality be
  damned."
- **Accuracy you can inspect.** Predicted vs actual on every call, graded on the
  calibration page. Routing goes binding only after the numbers hold.
- **Current models.** Prices and capability sync from the providers and public
  leaderboards — Opus 4.8, Fable 5, GPT-5.6, Sonnet 5, Gemini — not last year's lineup.
- **Your whole task as a plan.** agentcents reconstructs the multi-step plan your agent
  actually ran and shows the cost of each node — like a query plan, for LLM calls.
- **Local as a first-class option.** Running Ollama? It's priced in (power cost, not
  $0), so you see exactly when local beats the cloud and when it doesn't.

---

## CLI

```
$ agentcents usage
─────────────────────────────────
Total spend (last 48h)   $3.42
  my-agent          $2.10   61%
  research-agent    $1.32   39%
─────────────────────────────────
Daily budget             $5.00
Remaining                $1.58

$ agentcents explain --accuracy
  MODEL                  TAG        N   p90 cov   q-err med
  ollama/gpt-oss:20b     my-agent  212      92%       1.18
  overall: p90 coverage 92% (target ~90%), median q-error 1.18
```

Other commands: `agentcents explain` (pipe a request in), `agentcents models`,
`agentcents sync`, `agentcents agents`, `agentcents rolling`, `agentcents local`,
`agentcents features`.

---

## Supported providers

Anything that speaks the OpenAI or Anthropic format: OpenAI, Anthropic, Google Gemini,
OpenRouter, Groq, and local Ollama. Pricing syncs automatically on proxy startup from
public catalogs, with current frontier prices carried in a bundled config the
aggregators lag on.

---

## Free vs Pro

**Free forever** — no account needed:

- Proxy + cost logging (cache-aware, cost-accurate)
- Cost forecasts (`agentcents explain`) + calibration page
- Two Cents guide — local-first, ~$0 per answer
- Exact-match cache
- Budget alerts + hard block
- Full CLI reporting
- Web dashboard (light + dark) · plan · orchestrator showcase
- Local Ollama tracking

**Pro** — one-time license (`agentcents activate <key>`):

- Everything in Free
- Advisor + routing on *your own traffic* (which cheaper models actually clear the bar
  on your workload, learned from your real calls)
- Semantic similarity cache
- Multi-agent TUI dashboard + live call watch
- Auto-routing (swap mode)
- XGBoost cost predictor

For Pro dependencies: `pip install 'agentcents[pro]'`.

Get Pro: https://labhamfounder.gumroad.com/l/agentcents-pro

---

## License

agentcents is proprietary software, © Labham LLC. All rights reserved. The source is
distributed for transparency and inspection; use is licensed, not sold. See
`LICENSE.txt` for terms. Pro features require a valid license key.

Contact: founder1@labham.com · https://labham.com
