aditya
9273f0d8de
Squash 7 estimation migrations (m6_003, 992484befd85, m6_005, m6_006, m6_007, m6_008, m7_002) into a single clean m6_003_estimation_schema with linear dependency on m4_003_plan_env_columns. Rename column estimation_skipped_json to estimation_skipped for naming consistency. Domain model hardening: replace deprecated FieldValidationInfo with ValidationInfo, change historical_basis from list[str] to tuple[str,...] to prevent mutation on frozen model, add max_length=10_000 to rationale. Service improvements: remove unnecessary ThreadPoolExecutor wrapping, add EstimationActorProtocol for pluggable actor dispatch, log unexpected exceptions at error level, document EstimationService as stateless. Deduplicate estimation serialization via static helpers on LifecyclePlanModel used by both from_domain() and _update_plan_row(). Remove 6 out-of-scope coverage-boost files (container_73_lines, plan_cli_print_coverage, resume_coverage) and revert 3 unrelated benchmark import fixes. Add Behave scenario for update_plan_overrides atomic field setting. ISSUES CLOSED: #209
72 lines
2.2 KiB
Markdown
72 lines
2.2 KiB
Markdown
# Estimation Reference
|
|
|
|
CleverAgents supports optional pre-execution estimation through the
|
|
`estimation_actor` role. The actor produces a structured `EstimationReport`
|
|
that is persisted on plans and shown in plan status output.
|
|
|
|
## EstimationReport Schema
|
|
|
|
```json
|
|
{
|
|
"cost_range_usd_min": 0.5,
|
|
"cost_range_usd_max": 2.0,
|
|
"token_estimate_input": 1200,
|
|
"token_estimate_output": 600,
|
|
"expected_steps": 4,
|
|
"expected_child_plans": 1,
|
|
"rollback_risk": 0.25,
|
|
"confidence": 0.75,
|
|
"estimated_duration_minutes": 18.0,
|
|
"rationale": "Derived from plan size and constraints",
|
|
"historical_basis": [],
|
|
"actor_used": "local/estimator",
|
|
"generated_at": "2026-03-12T10:00:00Z"
|
|
}
|
|
```
|
|
|
|
### Field Summary
|
|
|
|
- `cost_range_usd_min` / `cost_range_usd_max`: Estimated USD cost band.
|
|
- `token_estimate_input` / `token_estimate_output`: LLM token expectations.
|
|
- `expected_steps`, `expected_child_plans`: Work-size projection.
|
|
- `rollback_risk`: Rollback likelihood in `[0.0, 1.0]`.
|
|
- `confidence`: Model confidence in `[0.0, 1.0]`.
|
|
- `estimated_duration_minutes`: Duration estimate in minutes.
|
|
- `rationale`: Human-readable explanation of estimate.
|
|
- `historical_basis`: Optional prior plan IDs used as basis.
|
|
- `actor_used`: Namespaced actor identifier (`namespace/name`).
|
|
- `generated_at`: Timestamp of estimation generation.
|
|
|
|
### Validation Rules
|
|
|
|
- `cost_range_usd_max >= cost_range_usd_min`
|
|
- `rollback_risk` and `confidence` are bounded to `[0.0, 1.0]`
|
|
- all count/duration/token values are non-negative
|
|
- `actor_used` (when present) must be namespaced
|
|
|
|
## CLI Integration
|
|
|
|
Use `--no-estimate` to explicitly skip estimation:
|
|
|
|
```bash
|
|
agents plan use local/refactor my-project --no-estimate
|
|
```
|
|
|
|
When estimation is skipped, `estimation_skipped` is recorded with the reason.
|
|
|
|
## Persistence
|
|
|
|
Estimation data is stored on `v3_plans`:
|
|
|
|
- `estimation_report`: JSON-serialized `EstimationReport`
|
|
- `estimation_skipped`: JSON-serialized `EstimationSkipped`
|
|
|
|
## Runtime Behavior
|
|
|
|
Estimation runs during `plan use`:
|
|
|
|
1. create plan from action
|
|
2. invoke estimation actor if configured and not skipped
|
|
3. store either `estimation_report` or `estimation_skipped`
|
|
4. continue lifecycle (estimation is informational only)
|