Skip to content

Optimization estimates

Use historical calibration artifacts to compare saved predictions with saved intervention outcomes. The offline tool preserves the original models and excludes synthetic fixtures from empirical fitting; real calibration still requires permission-cleared workload evidence.

Every built-in optimization card and diagnosis finding includes an estimate record. These predictions are hypotheses until you implement a change and measure a candidate run with replay and quality checks. All current estimators use method: "heuristic" and calibrated: false; confidence describes the recommendation, not a statistical confidence interval.

Version 1.0 models

Inputs refer to the affected spans. Duration sums can include nested or overlapping work and should not be interpreted as measured elapsed-time improvements.

Estimator ID Formula Parameters
parallelize_tools sum_duration_ms - max_duration_ms none
cache_context current_cost_usd * min(max_cost_fraction, repeated_context_ratio) max_cost_fraction = 0.5
add_schema_validation sum_duration_ms * latency_fraction latency_fraction = 0.8
batch_model_calls sum_duration_ms * latency_fraction latency_fraction = 0.35
route_to_smaller_model sum_duration_ms * latency_fraction latency_fraction = 0.25
split_large_step sum_duration_ms * latency_fraction latency_fraction = 0.20
runaway_loop sum_duration_ms * latency_fraction latency_fraction = 0.30
tool_oscillation sum_duration_ms * latency_fraction latency_fraction = 0.40

The constants in this table drive the calculation. They are defaults without empirical calibration, not performance guarantees. Parallelization also retains the observed timing and declared or inferred safety evidence described in Parallelization evidence.

Read and preserve the evidence

The JSON record contains estimator_id, estimator_version, method, confidence, calibrated, formula, parameters, inputs, assumptions, and unmodeled_metrics. Inputs snapshot affected duration sum/maximum, span count, current priced cost, repeated-context ratio, cost status, and token status. The card's affected_nodes and finding's affected_spans identify the input spans. Latency outputs are rounded to three decimal places; cost outputs to six.

current_cost_usd and cost savings are null when pricing is incomplete. When tokens are estimated, the input cost retains that estimate and its explicit token_status; it is not a measured cost, and replay cost gates remain indeterminate without an evaluable token basis. unmodeled_metrics identifies a metric whose legacy zero estimate means no savings were modeled; it is not evidence that the intervention cannot affect that metric.

Markdown exports and the dashboard show the estimator, assumptions, coefficients, and uncalibrated label. JSON keeps the full snapshot for reproduction. SQLite and Postgres persist it with the finding and return that saved snapshot without rerunning the current estimator. Explicitly re-diagnosing a trace replaces its current finding payload; archive an export if you need every historical revision. Older saved findings without an estimate remain readable and are not silently assigned the current model's provenance.

Estimator versions describe savings-model semantics separately from finding-rule versions. Change the estimator version when changing its formula, parameters, or assumptions. Future versions may add calibration statistics without changing the meaning of existing snapshots.

Measured trace values remain under the report/current run fields, and replay contains the observed baseline/candidate comparison. Predictions stay in estimated_after, card savings, and finding savings. The existing savings_aggregation selection metadata still identifies exact versus approximate compatible-card selection; exact selection does not calibrate the selected predictions.