Metadata-Version: 2.4
Name: governer
Version: 1.0.2
Summary: Hard spend breaker for AI agents — prices cache reads, bills real usage, and refuses the request that would cross your budget.
Author-email: Kaiser0733 <amardeepkumar0733@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Kaiser0733/governer
Project-URL: Issues, https://github.com/Kaiser0733/governer/issues
Project-URL: Changelog, https://github.com/Kaiser0733/governer/blob/main/CHANGELOG.md
Keywords: ai,agents,llm,cost,finops,budget,tokens,openai,anthropic
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# governer

[![test](https://github.com/Kaiser0733/governer/actions/workflows/test.yml/badge.svg)](https://github.com/Kaiser0733/governer/actions/workflows/test.yml)

**Your agent spent $37,901 while you slept. The budget alert told you afterwards.**

`governer` prices every request the way the provider actually bills it — cache
reads and writes included — then **refuses the request that would cross your
line**. Not a warning. Not a dashboard. A kill switch.

```
$ governer box
wallet $10.00 · gpt-6-astra · 200,000 tok/turn · CACHE MISSING

  turn    1   $    2.02 / $10.00
  turn    2   $    4.05 / $10.00
  turn    3   $    6.07 / $10.00
  turn    4   $    8.10 / $10.00
  turn    5   BLOCKED  (would have cost $2.0250)

🛑 BREAKER TRIPPED at $8.10 of $10.00 — agent stopped

   paid              $      8.10  (5 turns)
   same run, cached  $      0.90
   you paid 9x the cached price — this is the $38k bug
```

No API key, no network, ninety seconds.

## Install

```bash
pipx install governer      # or: pip install governer
governer box
```

No dependencies either way. Prefer a file? Two curls and you're done:

```bash
curl -O https://raw.githubusercontent.com/Kaiser0733/governer/main/governer.py
curl -O https://raw.githubusercontent.com/Kaiser0733/governer/main/prices.json
python3 governer.py box
```

Python 3.9+.

## Commands

| command | what it does |
|---|---|
| `governer proxy --limit 5` | OpenAI-compatible shim: point your agent at it, it refuses anything past $5 |
| `governer box` | simulated agent in a virtual wallet — watch the breaker trip, no key needed |
| `governer check usage.json --limit 20` | true cost of a real log, plus where a $20 cap would have stopped it |
| `governer prices` | what every model costs right now, with its verified date |
| `governer prices --refresh` | pull live prices from the gateway — 459 models, cache pricing included |
| `governer prices --live` | every known model, cheapest first |
| `governer prices --upcoming` | announced price changes — Gemini 3.8 Flash doubles 2027-01-01 |
| `governer free` | which models are free *right now*, fetched live |
| `governer status spend.jsonl --limit 20` | the meter: spent, burn rate, projection, per-agent split |
| `governer verify ledger.jsonl` | checks a spend ledger for tampering |

## Put it in front of your agent

```bash
$ governer proxy --limit 5 --ledger spend.jsonl

governer http://127.0.0.1:8787  →  https://openrouter.ai/api/v1
wallet $5.00 · unknown models billed $0.0/$0.0 per M

  export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
  export OPENAI_API_KEY=<your key>     # governer never stores it
```

Your agent keeps working unchanged. Every request is priced at its worst case
*before it leaves the machine*, forwarded with your own key, then billed at its
real usage. Cross the limit and the request comes back `402` with
`type: governer_breaker_tripped` — and your provider never sees it.

Streaming passes straight through — governer adds `stream_options.include_usage`
so the final usage block still arrives and the stream can be billed. Unpriced models
fall back to `--default-in/--default-out`, which is also how you *shadow-price* a
free model to see what it would have cost:

```
  ✓ 200 nvidia/nemotron-3.5-lightning:free    $0.001230  $0.0012/$5.00
```

When the provider reports its own `cost` field, governer compares it against
its own number and warns when `prices.json` has gone stale.

### Budgets per agent, per day

One proxy, several caps. Copy `governer.example.json` and pass it:

```json
{
  "limit": 20.0,
  "ledger": "spend.jsonl",
  "notify": "https://ntfy.sh/your-topic",
  "agents": {
    "claude-code": { "limit": 5.0, "per": "day" },
    "ci":          { "limit": 2.0, "per": "run" }
  }
}
```

```bash
governer proxy --config governer.example.json
```

The agent names itself with a header — `X-Governer-Agent: claude-code` — and the
cap applies to it alone. `day` resets at UTC midnight, `run` lasts the process.
Both are rebuilt from the ledger on restart, so bouncing the proxy cannot reset a
budget. `notify` receives a POST when the breaker trips.

### Watch for a week before you enforce

```bash
governer proxy --limit 20 --dry-run --ledger spend.jsonl
```

Dry run books the true spend and refuses nothing, so you learn what a normal week
costs before a cap starts costing you work. Anything it would have refused is
marked `◌` in the console.

## Audit a log you already have

```
$ governer check usage.json --limit 20
requests   100
true cost  $52.00
cache miss 100 request(s) billed uncached while sending ≥10k tokens
           $43.20 of that was avoidable — ~83% of the bill
at $20.00 cap: stopped at request 39, $32.24 never spent (62% saved)
```

Reads Anthropic (`input_tokens`), OpenAI (`prompt_tokens`) and OpenRouter
(`cached_tokens`) field names, as a JSON array or JSONL.

## It prices models nobody told it about

```
$ governer prices --refresh
459 models refreshed from https://openrouter.ai/api/v1
  free right now: 20
  vendor-confirmed cache pricing: 313
```

Curated entries are hand-verified, each with a date and a source. Everything
else is pulled live, so an agent that switches to a model released last week
still gets priced — instead of silently costing nothing in your ledger because
nobody typed it into a table.

## Gate a pull request on cost

```yaml
- uses: Kaiser0733/governer@main
  with:
    usage-file: ci/agent-usage.json
    budget: "2.50"
```

`governer check --fail-over 2.50` exits `1` when the run costs more. Tests
should not be the only thing a PR can fail.

## The meter, not just the wall

A hard cap alone does not fix behaviour — it just moves the spending to the last week
of the month. The number has to be in front of you while you decide whether to kick off
another run.

```
$ governer status spend.jsonl --limit 20
spent      $2.40 of $20.00  (12% used)
burn rate  $0.40/h over 6.0h
projected  $9.60/day at this rate
runs out   in 44.0h at this rate
agent      claude-code            $2.10
agent      ci                     $0.30
chain      OK — 3 records · $2.4000 · chain intact
```

It refuses to project from a window shorter than 30 minutes, because extrapolating three
records in the same minute produces confident nonsense.

## Why this instead of the other options

| option | what it covers | what it misses |
|---|---|---|
| provider credit / key limits | a hard stop per account | not per agent, not cross-vendor, and it is exactly the layer that failed the $38k case |
| an in-process library (`budget-guard`, npm) | a cap inside one Node app | one language, needs a code change, no help for a CLI agent you did not write |
| an agent runtime with budgets (`cx`, Claude Extender) | caps for agents inside that runtime | requires adopting the whole runtime |
| gateway budgets (litellm, OmniRoute) | budget fields in the gateway | enforcement is soft, and litellm's was silently bypassed (#26672) |
| **governer** | any client in any language, no code change, cross-vendor, cache-aware pricing, tamper-evident ledger, CI gate, audit of logs you already have | one process per ledger — do not point two proxies at the same file |

## Why the bill explodes at night

- **1M-token contexts are table stakes**, so the cached prefix is replayed on
  every call. Cache reads dominate agent bills — and they are billed even when
  that content is truncated before the model attends to it.
- **"Prompt caching is supported" is not "your stack is caching."** The
  expensive failure is silent: status 200, normal-looking output, invoice 100×.
- **Alerts are not limits.** Email after the money is gone is not a safety
  mechanism, and neither are credits or a dashboard you check on Mondays.

## Receipts

The spend ledger is append-only and hash-chained: every record carries the hash
of the one before it, so editing a number breaks the chain and `verify` says so.
Tamper-evident bookkeeping, because a budget you can quietly rewrite is not a
budget.

## Prices are data, not truth

Every model in `prices.json` carries a `verified` date and a source. Cache
prices marked `~` are derived from the vendor convention (0.1× read, 1.25×
write) rather than confirmed. Re-verify before betting a number that matters,
and open a PR when a vendor moves.

## Roadmap

- ~~v0.2~~ proxy, live `free` check, CI gate — shipped
- ~~v0.5~~ price table refreshed from the gateway instead of hand-maintained — shipped
- **v0.3** per-agent and per-workflow budgets on one proxy
- **v0.4** phone push the second a breaker trips

## License

**Docs and demo:** https://kaiser0733.github.io/governer/

MIT. Built by [Kaiser0733](https://github.com/Kaiser0733) at Vastraa Labs.
