Metadata-Version: 2.4
Name: agentcents
Version: 0.2.4
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 shows you the
cheapest model that can actually do the job — priced live, ranked by real capability
scores — and tracks every cent you spend. Point your client at it. Change nothing else.

```bash
pip install agentcents
```

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

---

## 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

---

## 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.** See a request's exact cost on every candidate model —
  fresh input, cached input, output — not a guess.
- **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."
- **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 recent
claude-opus-4-8    512 tok   $0.013   my-agent
claude-sonnet-5    1.2k tok  $0.012   research-agent
gpt-5.6-terra      800 tok   $0.012   my-agent
```

Other commands: `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
- Exact-match cache
- Budget alerts + hard block
- Full CLI reporting
- Web dashboard
- Local Ollama tracking
- Cost advisor + frontier showdown (on demo data)

**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
