Skip to content

fix(usage): cost display honesty — sub-cent labels, cost buckets, included notes - #85569

Merged
kshitijk4poor merged 3 commits into
NousResearch:mainfrom
kshitijk4poor:cost-display-honesty
Aug 13, 2026
Merged

fix(usage): cost display honesty — sub-cent labels, cost buckets, included notes#85569
kshitijk4poor merged 3 commits into
NousResearch:mainfrom
kshitijk4poor:cost-display-honesty

Conversation

@kshitijk4poor

@kshitijk4poor kshitijk4poor commented Aug 13, 2026

Copy link
Copy Markdown
Collaborator

Summary

Three cost-display honesty fixes. Small, cheap, kills a real confusion class.

1. Sub-cent cost label rendering (#79220)

Problem: cost labels formatted at 2 decimal places, so for models priced under ~$1/Mtok (DeepSeek, etc.) a normal turn costing $0.004640 rendered ~$0.00 despite amount_usd carrying full Decimal precision.

Fix: format_cost_label(amount) scales precision to magnitude:

  • Zero → $0.00
  • Sub-cent (< $0.01) → ~$0.0046 (4 dp)
  • Below $0.00005 → ~$<0.0001 (never a zero-looking 4dp truncation)
  • Normal → ~$1.23 (2 dp, unchanged)

Shared by per-response labels (estimate_usage_cost) AND the insights aggregate formatters, so sub-cent honesty can't regress on one surface while fixed on the other.

2. Cost bucket surfacing in insights (#77223)

Problem: aggregate cost views summed estimated_cost_usd and reported a single number. Sessions with cost_status = 'included' (subscription-included providers like openai-codex) contribute zero — correct per-session, but invisible in the overview. In the reporter's DB, 315 of 473 sessions were included and didn't show at all.

Fix: both formatters now display three buckets:

  💰 Cost
  ────────────────────────────────────────────────────────
  Estimated:         ~$3.75
  Included:           315 session(s) (subscription — no provider invoice)
  Unknown:            3 session(s) (no pricing data)

Gateway: **Cost:** ~$3.75 estimated | 315 included (subscription) | 3 unknown

3. Subscription-included cost notes

estimate_usage_cost attaches a "subscription-included; no provider invoice for usage" note to CostResult for subscription-included routes, so consumers can distinguish "free because subscription" from "free because $0 pricing".

Validation

Check Result
tests/agent/test_usage_pricing.py + test_insights.py 62 passed / 0 failed
E2E probe: sub-cent label via real estimate_usage_cost route PASS (~$0.0046 observed)
E2E probe: all 7 estimate_usage_cost callers tolerate the note PASS (none parse .label)
E2E probe: repo-wide grep for 2dp-label consumers PASS (no hits — nothing breaks on 4dp)
Mutation check: reverting the formatter routing makes the sub-cent aggregate guard fail PASS
ruff clean

Fixes #79220
Fixes #77223

@alt-glitch alt-glitch added type/feature New feature or request P3 Low — cosmetic, nice to have comp/agent Core agent runtime: loop, agent_init, prompt builder, context-compression, responses endpoint area/billing Account usage, credit usage, billing (cross-cutting) area/usage-cost Token accounting, usage reporting, billing, cost tracking duplicate This issue or pull request already exists labels Aug 13, 2026
@alt-glitch

Copy link
Copy Markdown
Collaborator

This was generated by AI during triage.

Duplicate of #77247 for the included/estimated/unknown Insights cost-bucket implementation. This PR also bundles the separate sub-cent label work from #79220; please consolidate or split the overlapping bucket implementation before review.

…luded notes

Three cost-display honesty fixes:

1. Sub-cent cost label rendering (NousResearch#79220) — _format_cost_label() scales
   precision to magnitude: zero renders as '$0.00', sub-cent (< $0.01)
   renders at 4 decimal places (e.g. '~$0.0046'), normal costs keep 2dp.
   This fixes the bug where DeepSeek per-turn costs of $0.004640 rendered
   as '~$0.00' despite amount_usd carrying full Decimal precision.

2. Cost bucket surfacing (NousResearch#77223) — insights format_terminal and
   format_gateway now display three cost buckets: estimated (with dollar
   figure), included (session count, labeled 'subscription — no provider
   invoice'), and unknown (session count, labeled 'no pricing data').
   Previously, included and unknown sessions silently collapsed to $0 in
   the aggregate view, hiding 315 of 473 sessions in the reporter's DB.

3. Subscription-included cost notes — estimate_usage_cost now attaches a
   'subscription-included; no provider invoice for usage' note to
   CostResult for subscription-included routes (openai-codex), so
   consumers can distinguish 'free because subscription' from 'free
   because $0 pricing'.

Fixes NousResearch#79220
Fixes NousResearch#77223
- Insights formatters now route aggregate estimated cost through the
  shared format_cost_label() instead of hardcoded 2dp — a sub-cent
  aggregate (one cheap DeepSeek session, ~$0.0046) no longer renders
  'Estimated: ~$0.00', the exact bug class this PR fixes (NousResearch#79220).
- format_cost_label: positive amounts below $0.00005 render '~$<0.0001'
  instead of the zero-looking '~$0.0000' 4dp truncation artifact.
- Renamed _format_cost_label -> format_cost_label (now a cross-module
  shared helper).
- Tests: renamed test_gateway_format_hides_cost ->
  test_gateway_format_hides_cache_details and
  test_no_cost_section_when_all_zero ->
  test_unknown_bucket_shown_for_costless_session (names contradicted
  behavior); restored a real assertion in the custom-models test that
  had been weakened to a comment; added sub-cent-aggregate and 4dp-floor
  contract tests (mutation-checked).
- Single-source the included note as _INCLUDED_NOTE and attach it at
  BOTH status='included' sites (the zero-amount pricing-entry branch
  previously returned the same status with no note).
- Docstring/comment precision on format_cost_label: the fallback
  triggers on 4dp ROUNDING to 0.0000 (banker's rounding includes the
  exact $0.00005 boundary), not truncation; note why the rendered-label
  guard beats a naive Decimal threshold.
- Tests: replaced a dead assertion with the exact-boundary case
  ($0.00005), fixed an overclaiming comment, aligned the terminal
  cost column.
@kshitijk4poor

Copy link
Copy Markdown
Collaborator Author

Good flag — looked at #77247 closely. They overlap in the formatter hunks but aren't duplicates:

So the resolution is: this PR lands the display surfacing + label honesty; #77247's market-value estimation remains valuable as an enhancement on top (its formatter hunks will need a small rebase over this, but the computation half is untouched). Not consolidating them into one PR keeps the display fix small and the valuation feature separately reviewable.

@kshitijk4poor
kshitijk4poor enabled auto-merge (rebase) August 13, 2026 20:32
@kshitijk4poor
kshitijk4poor merged commit f80f453 into NousResearch:main Aug 13, 2026
45 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/billing Account usage, credit usage, billing (cross-cutting) area/usage-cost Token accounting, usage reporting, billing, cost tracking comp/agent Core agent runtime: loop, agent_init, prompt builder, context-compression, responses endpoint duplicate This issue or pull request already exists P3 Low — cosmetic, nice to have type/feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cost label formats at 2dp, so sub-cent per-turn costs render as $0.00 feat(usage): surface included/estimated/unknown cost buckets in aggregate views

2 participants