Trusting Your Telemetry All Tiers
Where a token estimate or model recommendation actually comes from, and why calibration doesn't kick in immediately.
This page is about provenance — knowing whether a number PairCoder shows you is your own configuration, learned from your project's history, or a generic fallback. For telemetry privacy levels and data handling, see the Telemetry guide.
Three possible sources for any estimate
When PairCoder estimates tokens for a task, or recommends a model, the number didn't come from one place. It comes from a small precedence chain, and every estimate now carries a source tag telling you which tier produced it:
| Source | Meaning | Wins when |
|---|---|---|
declared |
You explicitly configured it in .paircoder/config.yaml |
Config is present at all — wins outright, no blending |
calibrated |
No explicit config; learned from your project's own completed-task history | No declared config, and enough real samples exist |
default |
Neither of the above; a built-in static formula | No config, and calibration doesn't have enough data yet |
Declared config always wins when present — it doesn't get blended with or overridden by calibration data, even once calibration has plenty of samples. That's a deliberate choice: an explicit setting is operator intent, and data shouldn't quietly override intent. Model routing follows the identical three-tier logic (explicit model pin > calibration recommendation > complexity-based fallback) — the same precedent, applied to a second question.
What calibration actually needs
Calibration only activates once a project has accumulated enough real task records — a small sample-count threshold, not a single data point. Below that threshold, you're on the default formula, and that's expected behavior on a new project, not a bug.
More importantly, calibration needs the records themselves to be honest. A calibration record is only useful if it carries:
- Real token counts, not a placeholder zero from a session that couldn't measure them
- The actual model used, not an
"unknown"fallback from environment-variable guessing - The real task type, not a default that every task collapses into
- One record per task — duplicate emissions from multiple producers skew the average
This matters because calibration is just an average over whatever records exist. If most of a project's records are estimates, unknowns, and duplicates, the "learned" recommendation isn't learning anything real — it's amplifying noise. A large share of zero-token or unknown-model records in your own history is exactly the failure mode that should make you suspicious of a calibrated number.
bpsai-pair plan estimate --json includes a source field per task and a source_counts summary (e.g. {"declared": 3, "calibrated": 0, "default": 2}). If most of your tasks show default, that's not broken — it just means calibration hasn't accumulated enough honest samples yet, or you haven't declared token_estimates: in config.
Why this is worth knowing
Without a visible source, "calibration" and "guess" look identical, and it's easy to either over-trust a number built on thin data or distrust a number that's actually well-calibrated. Knowing which tier produced an estimate turns "why did I get this number?" into a quick lookup instead of an investigation — the same principle that makes a fail-closed gate or a partitioned run summary trustworthy also applies here: a system is only as trustworthy as its ability to show its own provenance.