Savings ledger

Why a ledger and not one number

Cost-saving techniques do not all save the same kind of thing. A receipt keeps repeated bytes out of the next request. Shell shaping keeps a build log small. The provider's own prompt cache discounts a prefix the model still reads in full. Cheap-model routing changes which model answers, not how many tokens it reads. Rolling those into one savings figure would hide the differences that matter.

So each occurrence gets a row of its own, tagged with the technique behind it. A summary can then say which techniques fired, how many bytes each kept out, whether a dollar figure sits behind the number, and how much of the total was measured rather than modeled.

Cheap-model routing shows why the labels earn their keep. When the router judges a turn simple enough for the cheap rung, Squeezy records the saving as the same tokens re-priced at the rate of the model the turn would otherwise have run on, minus what that rung billed and minus the small model call the router used to decide. That is the main model for the mode the turn is in, so a Plan-mode turn is priced against your planner rather than your default. It never ran, so the comparison is modeled, not a charge. The row is written only when the router made the choice and the cheaper run produced an answer, never when you pinned a turn cheap yourself.

Every row says how it knows

A saving is only worth reading if you can tell how it was arrived at. Every row carries one of four confidence labels, and reports keep them visible rather than averaging them into a single figure.

The dollar figure on a row carries a label of its own, because the two can differ. A byte reduction Squeezy measured exactly is still priced through a bytes-per-token ratio, and that ratio is never labeled measured: it is a deterministic estimate once it has been calibrated against the provider's own reported token counts, and a heuristic until then. Where no rate for the model is known, the row carries no dollar figure at all rather than a guessed one.

• measured: Squeezy saw both sizes, or the provider's own usage counters reported the effect.
• deterministic_estimate: derived from local facts that repeat, such as a known byte size, an output hash, or the request Squeezy assembled.
• counterfactual_estimate: what happened, compared with an alternative that did not happen. Good for ranking techniques, not a charge.
• heuristic: directional, and presented as such.

What a summary adds up

Grouped by technique, a summary gives the event count, the mix of confidence labels, the size before the reduction, the size the model actually saw (model_visible_bytes), and the difference between the two (saved_bytes). Token and dollar estimates come along when the rows carried them.

Bytes stay apart by what they reduce. Trimming a prompt, trimming a response, resizing an image before it is sent, and compressing something on disk are four different resources, and the ledger totals them separately so a disk saving is never added to a prompt saving.

Partial totals say so. When only some rows in a group carry a dollar figure, the report states how many of them were priced instead of showing a subtotal as though it were the whole. Negative rows stay visible too: a cache write costs more on the turn that pays for it, and hiding that up-front cost would flatter every number after it.

The provider's discounts are not Squeezy's savings

Two rows in the ledger are the provider's doing rather than Squeezy's. A prompt_cache_read row records the discount a provider applies when a request repeats a prefix it already holds, and a cache_retention_policy row records the premium paid to put that prefix in the cache in the first place. Any client sending the same request shape would get both.

So they are labeled as the provider's and reported beside the savings total instead of inside it. In the terminal those rows are marked provider pricing, and the provider figure gets a line of its own, called out as not a Squeezy saving. In JSON and CSV every mechanism row carries an attribution field, so a script can group before it sums.

A cache read also carries no token saving. Those tokens were still sent and still processed; only the price changed. The row shows a dollar figure and leaves the token field off rather than presenting cached input as input the model never read.

Reading it back

The ledger is kept on your machine, across sessions, for the last 90 days, and nothing has to be running to read it. squeezy savings prints every breakdown as a table: one grouped by technique, one by model, one by time bucket. Pick a single breakdown with --by, set the bucket width with --time-bucket, and turn any of them into machine output with --json or --format csv. --export-html writes a standalone report you can hand to someone else.

The report puts the spend recorded over the same window next to the saving, so the total has a scale to be read against instead of standing alone.

Inside a session, /cost saving is the short form: the techniques that fired, ranked, and what share of the bill they avoided. /cost discover is the wider view, including the places a saving could have fired and did not.

squeezy savings
squeezy savings --by mechanism --json
squeezy savings --by time --time-bucket weekly
squeezy savings --export-html cost-report.html

How to use it

Read it to decide what to tune next. If receipts dominate, repeated reads are being avoided. If shell shaping dominates, command output is being kept small. If the cache rows dominate, the provider's cache behavior is driving the number, and what is worth protecting is a stable prompt prefix.

Do not read it as an invoice. It is built so savings can be compared and audited while the difference between a measured byte, a locally estimated one, and a comparison with a run that never happened stays on the record.

Related

• Control the bill
• Don't pay for the same bytes twice
• Benchmarks