Heuristic:Helicone Helicone Cost Precision Multiplier
| Knowledge Sources | |
|---|---|
| Domains | Cost_Calculation, Data_Precision |
| Last Updated | 2026-02-14 06:00 GMT |
Overview
Store LLM costs as integers multiplied by 1 billion (1,000,000,000) in ClickHouse to avoid floating-point precision errors in financial calculations.
Description
LLM token costs are extremely small numbers (e.g., $0.000003 per token). Storing these as floating-point numbers in ClickHouse leads to cumulative rounding errors when aggregating millions of requests. The `COST_PRECISION_MULTIPLIER` constant (1 billion) converts all cost values to integers before storage. When displaying costs to users, the stored integer is divided by the multiplier to recover the original dollar amount. This is a fixed-point arithmetic pattern commonly used in financial systems.
Usage
Apply this heuristic whenever reading or writing cost data to/from ClickHouse. Any code that inserts cost values must multiply by `COST_PRECISION_MULTIPLIER`. Any code that reads costs for display or billing must divide by the multiplier. The constant is exported from `packages/cost/costCalc.ts`.
The Insight (Rule of Thumb)
- Action: Multiply all cost values by `COST_PRECISION_MULTIPLIER` (1,000,000,000) before inserting into ClickHouse. Divide by the same value when reading for display.
- Value: `COST_PRECISION_MULTIPLIER = 1_000_000_000` (1 billion).
- Trade-off: Requires consistent application across all cost read/write paths. Forgetting to multiply or divide produces values that are off by 9 orders of magnitude.
Reasoning
LLM API costs per token are on the order of $0.000001 to $0.01. IEEE 754 double-precision floating-point has approximately 15 significant digits, but aggregating millions of small values accumulates rounding errors. For example, summing 10 million requests at $0.0000025 each should yield $25.00, but floating-point accumulation can produce $24.99999... or $25.00001..., which creates billing discrepancies. Fixed-point integer arithmetic eliminates this class of error entirely.
The multiplier of 1 billion provides 9 decimal places of precision, which is sufficient to represent sub-cent costs accurately down to $0.000000001 (one billionth of a dollar).
Code evidence from `packages/cost/costCalc.ts:7-8`:
// since costs in clickhouse are multiplied by the multiplier
// divide to get real cost in USD in dollars
export const COST_PRECISION_MULTIPLIER = 1_000_000_000;
Usage in ClickHouse queries from `valhalla/jawn/src/managers/creditsManager.ts:129`:
SELECT spend / ${COST_PRECISION_MULTIPLIER / 100} as spend_cents
FROM organization_ptb_spend_mv FINAL
WHERE organization_id = {val_0 : String}