feat(estimation): implement EstimationReport domain model and estimation_produced decision type #649

Open
opened 2026-03-09 20:15:13 +00:00 by freemo · 1 comment
Owner

Metadata

  • Commit Message: feat(estimation): implement EstimationReport domain model and estimation_produced decision type
  • Branch: feature/m6-estimation-report-model

Background and Context

The specification (lines 18996-19013) requires the estimation actor to produce structured multi-dimensional output containing: LLM tokens/cost range (min/max USD), expected steps/child plans, rollback risk (0.0-1.0), and estimated execution time. Currently, the database only stores a scalar cost_estimate_usd REAL column on the plans table (line 43456), and there is no structured domain model for estimation output. Additionally, the decision type enum includes prompt_definition, invariant_enforced, strategy_choice, subplan_spawn, and subplan_parallel_spawn but no estimation_produced type for recording estimation results in the decision tree.

This issue is a natural companion to #209 (estimation actor implementation) and provides the data layer that PR #528's EstimationSkipped and CostEstimate models should be built upon.

Expected Behavior

A proper EstimationReport Pydantic domain model exists that captures the full multi-dimensional output of the estimation actor, with an Alembic migration to persist it, and an estimation_produced decision type to record it in the decision tree.

Acceptance Criteria

  1. EstimationReport Pydantic model exists in src/cleveragents/domain/models/core/ with fields: cost_range_usd (min/max), expected_steps (int), expected_child_plans (int), rollback_risk (float 0-1), estimated_duration_minutes (float), confidence (float 0-1), rationale (str), historical_basis (optional list of plan IDs).
  2. estimation_produced is added to the decision type enum.
  3. Alembic migration adds estimation_report JSON column to the plans table alongside the existing scalar cost_estimate_usd.
  4. Full serialization/deserialization roundtrip tests pass for EstimationReport.
  5. The model validates that rollback_risk and confidence are in [0.0, 1.0] range.
  6. All existing tests continue to pass.

Subtasks

  • Create EstimationReport Pydantic model in src/cleveragents/domain/models/core/estimation.py
  • Add field validators for range constraints (rollback_risk, confidence in [0,1])
  • Add estimation_produced to the decision type enum
  • Create Alembic migration adding estimation_report JSON column to plans table
  • Tests (Behave): Add scenarios for EstimationReport serialization/deserialization
  • Tests (Robot): Add integration test for estimation report persistence roundtrip
  • Verify coverage >=97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
## Metadata - **Commit Message**: `feat(estimation): implement EstimationReport domain model and estimation_produced decision type` - **Branch**: `feature/m6-estimation-report-model` ## Background and Context The specification (lines 18996-19013) requires the estimation actor to produce structured multi-dimensional output containing: LLM tokens/cost range (min/max USD), expected steps/child plans, rollback risk (0.0-1.0), and estimated execution time. Currently, the database only stores a scalar `cost_estimate_usd REAL` column on the plans table (line 43456), and there is no structured domain model for estimation output. Additionally, the decision type enum includes `prompt_definition`, `invariant_enforced`, `strategy_choice`, `subplan_spawn`, and `subplan_parallel_spawn` but no `estimation_produced` type for recording estimation results in the decision tree. This issue is a natural companion to #209 (estimation actor implementation) and provides the data layer that PR #528's `EstimationSkipped` and `CostEstimate` models should be built upon. ## Expected Behavior A proper `EstimationReport` Pydantic domain model exists that captures the full multi-dimensional output of the estimation actor, with an Alembic migration to persist it, and an `estimation_produced` decision type to record it in the decision tree. ## Acceptance Criteria 1. `EstimationReport` Pydantic model exists in `src/cleveragents/domain/models/core/` with fields: `cost_range_usd` (min/max), `expected_steps` (int), `expected_child_plans` (int), `rollback_risk` (float 0-1), `estimated_duration_minutes` (float), `confidence` (float 0-1), `rationale` (str), `historical_basis` (optional list of plan IDs). 2. `estimation_produced` is added to the decision type enum. 3. Alembic migration adds `estimation_report` JSON column to the plans table alongside the existing scalar `cost_estimate_usd`. 4. Full serialization/deserialization roundtrip tests pass for `EstimationReport`. 5. The model validates that `rollback_risk` and `confidence` are in [0.0, 1.0] range. 6. All existing tests continue to pass. ## Subtasks - [x] Create `EstimationReport` Pydantic model in `src/cleveragents/domain/models/core/estimation.py` - [x] Add field validators for range constraints (rollback_risk, confidence in [0,1]) - [x] Add `estimation_produced` to the decision type enum - [x] Create Alembic migration adding `estimation_report` JSON column to plans table - [x] Tests (Behave): Add scenarios for EstimationReport serialization/deserialization - [x] Tests (Robot): Add integration test for estimation report persistence roundtrip - [x] Verify coverage >=97% via `nox -s coverage_report` - [x] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.
freemo added this to the v3.5.0 milestone 2026-03-09 20:15:23 +00:00
freemo self-assigned this 2026-04-02 06:13:57 +00:00
Author
Owner

PR #1209 Review Complete — Changes Requested (Rebase Required)

PR #1209 has been reviewed independently. The code quality is excellent — the EstimationReport domain model, estimation_produced decision type, Alembic migration, ORM integration, and tests (20 BDD + 6 Robot) all align well with the specification and project standards.

Blocking issue: The branch feature/m6-estimation-report-model has merge conflicts with master and cannot be merged. The branch needs to be rebased onto the latest master with conflicts resolved. Once rebased and CI passes, the PR is ready to merge — no code changes needed.

**PR #1209 Review Complete — Changes Requested (Rebase Required)** PR #1209 has been reviewed independently. The code quality is excellent — the `EstimationReport` domain model, `estimation_produced` decision type, Alembic migration, ORM integration, and tests (20 BDD + 6 Robot) all align well with the specification and project standards. **Blocking issue**: The branch `feature/m6-estimation-report-model` has merge conflicts with `master` and cannot be merged. The branch needs to be rebased onto the latest `master` with conflicts resolved. Once rebased and CI passes, the PR is ready to merge — no code changes needed.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#649
No description provided.