Summary
Add a normalized token accounting model with explicit evidence labels so PromptFuel can report token usage consistently across providers without blurring measured, derived, estimated, and unavailable values.
The goal is to make token totals, cache utilization, provider-reported totals, and future cost/rate-limit estimates clearer and harder to double-count.
Current behavior
Provider token fields can have different meanings across sources. Input, output, cached input, cache creation, reasoning tokens, provider totals, and derived totals are not consistently represented as separate concepts with evidence labels.
Desired behavior
PromptFuel should normalize token data into disjoint components and derive totals from those components. Every value that is not directly measured should carry an evidence label.
Requirements
- Add normalized fields for:
uncachedInputTokenscacheReadInputTokenscacheWriteInputTokensoutputTokensreasoningOutputTokens, when availablelogicalInputTokens, derivedtotalLogicalTokens, derivedproviderReportedTotalTokens, when availablecacheHitRatio, derived when supportableestimatedCacheSavings, only when supportablerateLimitImpactTokens, only when supportablebilledEquivalentTokens, only when supportable
- Add evidence labels:
measuredderivedestimatedheuristicunavailable
- Keep logical token volume, billing impact, and rate-limit impact as separate concepts.
- Avoid universal formulas that assume cached tokens are always additive.
- Preserve raw/provider-reported fields needed for debugging and cross-checking.
- Add tests for providers where cached tokens are disjoint fields and providers where cached tokens are subsets of input.
- Document provider-specific mapping caveats.
Non-goals / constraints
- Do not implement a full dashboard in this issue unless required for validation.
- Do not infer billing or rate-limit impact without enough provider/pricing evidence.
- Do not remove existing provider fields that are still useful for diagnostics.
- Do not present estimated values as measured.
Suggested implementation
Create or extend a normalized token accounting layer that maps provider-specific usage fields into disjoint normalized components. Derive totals from normalized fields and store provider-reported totals separately for anomaly detection.
Acceptance criteria
Summary
Add a normalized token accounting model with explicit evidence labels so PromptFuel can report token usage consistently across providers without blurring measured, derived, estimated, and unavailable values.
The goal is to make token totals, cache utilization, provider-reported totals, and future cost/rate-limit estimates clearer and harder to double-count.
Current behavior
Provider token fields can have different meanings across sources. Input, output, cached input, cache creation, reasoning tokens, provider totals, and derived totals are not consistently represented as separate concepts with evidence labels.
Desired behavior
PromptFuel should normalize token data into disjoint components and derive totals from those components. Every value that is not directly measured should carry an evidence label.
Requirements
uncachedInputTokenscacheReadInputTokenscacheWriteInputTokensoutputTokensreasoningOutputTokens, when availablelogicalInputTokens, derivedtotalLogicalTokens, derivedproviderReportedTotalTokens, when availablecacheHitRatio, derived when supportableestimatedCacheSavings, only when supportablerateLimitImpactTokens, only when supportablebilledEquivalentTokens, only when supportablemeasuredderivedestimatedheuristicunavailableNon-goals / constraints
Suggested implementation
Create or extend a normalized token accounting layer that maps provider-specific usage fields into disjoint normalized components. Derive totals from normalized fields and store provider-reported totals separately for anomaly detection.
Acceptance criteria