depth flag now drives constraint defaults #33

Merged

archeious merged 1 commit from feat/depth-presets into main

2026-04-08 22:33:49 +00:00

claude-code commented

2026-04-08 22:27:50 +00:00

Collaborator

Closes Issue #30

Problem

depth (shallow/balanced/deep) was passed only as a text hint inside the agent's user message — no mechanical effect on iterations, token budget, or source count. Effectively cosmetic.

Change

New DEPTH_PRESETS table and constraints_for_depth() helper in researchers.web.models:

Depth	max_iterations	token_budget	max_sources
shallow	2	5,000	5
balanced	5	20,000	10
deep	8	60,000	20

Wired through the stack:

WebResearcher.research: when constraints is None, builds from the depth preset
MCP research tool: max_iterations / token_budget now default to None; constraints built via constraints_for_depth with explicit values overriding the preset
CLI ask: --max-iterations / --budget default to None and are only forwarded when set, so unset flags fall through to the depth preset

balanced matches the historical defaults exactly, so existing callers see zero behavior change. Explicit flags always win.

Tests

6 new tests in test_models.py: each preset's values, balanced backward-compat, unknown-depth fallback, full override, partial override. 116/116 passing.

Live verified

--depth shallow on a simple question now caps at 2 iterations and stays under cap, exactly as the preset says.

Out of scope

Tuning the actual numbers based on stress test data — that's Phase 3 calibration territory. This PR is about wiring depth → defaults, not picking the perfect numbers.

Closes Issue #30 ## Problem `depth` (`shallow`/`balanced`/`deep`) was passed only as a text hint inside the agent's user message — no mechanical effect on iterations, token budget, or source count. Effectively cosmetic. ## Change New `DEPTH_PRESETS` table and `constraints_for_depth()` helper in `researchers.web.models`: | Depth | max_iterations | token_budget | max_sources | |---|---:|---:|---:| | shallow | 2 | 5,000 | 5 | | balanced | 5 | 20,000 | 10 | | deep | 8 | 60,000 | 20 | Wired through the stack: - **WebResearcher.research**: when `constraints is None`, builds from the depth preset - **MCP `research` tool**: `max_iterations` / `token_budget` now default to `None`; constraints built via `constraints_for_depth` with explicit values overriding the preset - **CLI `ask`**: `--max-iterations` / `--budget` default to `None` and are only forwarded when set, so unset flags fall through to the depth preset `balanced` matches the historical defaults exactly, so existing callers see zero behavior change. Explicit flags always win. ## Tests 6 new tests in `test_models.py`: each preset's values, `balanced` backward-compat, unknown-depth fallback, full override, partial override. **116/116 passing.** ## Live verified `--depth shallow` on a simple question now caps at **2 iterations** and stays under cap, exactly as the preset says. ## Out of scope Tuning the actual numbers based on stress test data — that's Phase 3 calibration territory. This PR is about wiring depth → defaults, not picking the perfect numbers.

claude-code added 1 commit 2026-04-08 22:27:51 +00:00

depth flag now drives constraint defaults (#30 ) ae48acd421

Previously the depth parameter (shallow/balanced/deep) was passed
only as a text hint inside the agent's user message, with no
mechanical effect on iterations, token budget, or source count.
The flag was effectively cosmetic — the LLM was expected to
"interpret" it.

Add DEPTH_PRESETS table and constraints_for_depth() helper in
researchers.web.models:

  shallow:  2 iters,  5,000 tokens,  5 sources
  balanced: 5 iters, 20,000 tokens, 10 sources  (= historical defaults)
  deep:     8 iters, 60,000 tokens, 20 sources

Wired through the stack:

- WebResearcher.research(): when constraints is None, builds from
  the depth preset instead of bare ResearchConstraints()
- MCP server `research` tool: max_iterations and token_budget now
  default to None; constraints are built via constraints_for_depth
  with explicit values overriding the preset
- CLI `ask` command: --max-iterations and --budget default to None;
  the CLI only forwards them to the MCP tool when set, so unset
  flags fall through to the depth preset

balanced is unchanged from the historical defaults so existing
callers see no behavior difference. Explicit --max-iterations /
--budget always win over the preset.

Tests cover each preset's values, balanced backward-compat,
unknown depth fallback, full override, and partial override.
116/116 tests passing. Live-verified: --depth shallow on a simple
question now caps at 2 iterations and stays under budget.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>