Rename LLM agent `reasoning` config property to `reasoning_feedback` #142

New issue

Open

opened 2026-08-21 21:01:03 +00:00 by CoreRasurae · 0 comments

CoreRasurae commented

2026-08-21 21:01:03 +00:00

Member

Copy link

Metadata

Commit Message: refactor(agents): rename reasoning config field to reasoning_feedback
Branch: feature/m1-rename-reasoning-config-property

Background and context

ADR-2036 (spec v1.3.0, §4.4 / §4.4.1) introduced an optional boolean field named reasoning on the type: llm agent configuration. When true and the agent's provider is non-native (any provider outside openai/anthropic/google), it routes the agent through a reasoning-aware client that preserves and round-trips the provider's reasoning_content across a multi-turn tool-call loop.

The name reasoning collides conceptually with the wire-protocol concept it is toggling — "the model performed reasoning" versus "round-trip the model's reasoning content back to it on the next turn." Operators skimming agents.<name> configuration cannot tell from the field name alone that it controls feedback/round-tripping behavior rather than, say, enabling a reasoning-capable model or a "thinking mode" toggle. Renaming the field to reasoning_feedback makes its actual effect (feeding the provider's own reasoning content back to it) explicit.

This is a rename of a normative field name in the Actor Configuration Standard (docs/index.md, currently version 1.5.0) and therefore requires the ADR process: docs/adr/ADR-2036-reasoning-aware-provider-routing.md must be revised in place (a new proposed D-N, no new ADR file) and accepted before docs/index.md or any code is touched.

Current behavior

type: llm agent configuration accepts a boolean field literally named reasoning (default false).
src/cleveractors/agents/llm_client.py reads it via config.get("reasoning", False), validates it is a boolean ("'reasoning' must be a boolean, got ..."), and passes it as a reasoning: bool parameter.
src/cleveractors/agents/llm.py inspects the same "reasoning" key when constructing/validating agent configuration.
docs/index.md §4.4 documents the field as reasoning; §4.4.1 shows a reasoning: true example; §21.1 records its introduction under spec version 1.3.0.
Behave (features/reasoning_provider_routing.feature, features/llm_agent_coverage.feature) and Robot (robot/reasoning_provider_routing.robot) tests, plus docs/guides/reasoning-aware-llm-agents.md, all reference the reasoning: key by that name.

Expected behavior

The same boolean configuration field is named reasoning_feedback instead of reasoning, with identical semantics, default (false), validation, and routing effect (non-native providers only).
docs/adr/ADR-2036-reasoning-aware-provider-routing.md carries an accepted revision documenting the rename decision and rationale.
docs/index.md §4.4 / §4.4.1 reflect the new field name, and §21.1 Revision History has a new row attributing the change to the accepted ADR-2036 revision (per the project's spec-revision procedure — no other inline edits to docs/index.md).
All code, Behave scenarios, Robot tests, and the docs/guides/reasoning-aware-llm-agents.md guide reference reasoning_feedback instead of reasoning.
No behavior is renamed or altered beyond the configuration key itself: reasoning_content / reasoning_details (the wire-protocol fields the flag round-trips), cleveractors.agents.llm_reasoning.ReasoningChatModel, and the "reasoning-aware routing" feature/module naming are explicitly out of scope and must not change.

Acceptance criteria

docs/adr/ADR-2036-reasoning-aware-provider-routing.md contains an accepted revision (new D-N, added in place — no new ADR file) proposing and justifying the rename from reasoning to reasoning_feedback, including the spec-versioning treatment (the revision decides whether this is a breaking major-version bump or ships with a deprecation path, per the standard's own semver rules in §0).
docs/index.md §4.4 field table names the property reasoning_feedback (the literal string reasoning no longer appears as a field name in §4.4/§4.4.1).
docs/index.md §4.4.1 example configuration uses reasoning_feedback: true.
docs/index.md §21.1 Revision History has a new row attributing the rename to the accepted ADR-2036 revision.
src/cleveractors/agents/llm_client.py reads config.get("reasoning_feedback", False); the validation error message references reasoning_feedback; the reasoning: bool parameter is renamed to reasoning_feedback: bool throughout the module.
src/cleveractors/agents/llm.py references the renamed key wherever it inspects type: llm agent configuration.
No source file under src/cleveractors/ reads or writes the literal config key "reasoning" for this purpose.
docs/guides/reasoning-aware-llm-agents.md examples and prose use reasoning_feedback.
features/reasoning_provider_routing.feature, features/llm_agent_coverage.feature, and their step files (features/steps/llm_agent_steps.py, features/steps/reasoning_provider_routing_steps.py) exercise reasoning_feedback instead of reasoning.
robot/reasoning_provider_routing.robot (and robot/ReasoningRoutingTestLib.py if it references the key) exercise reasoning_feedback.
nox (full default session suite) passes.
nox -s coverage_report reports coverage at or above the project's configured threshold.

Supporting information

docs/index.md — §4.4 field table (~line 316), §4.4.1 example (~lines 360-369), routing prose (~line 386), §21.1 revision row for v1.3.0 (~line 4046).
docs/adr/ADR-2036-reasoning-aware-provider-routing.md — D-1 defines the current field name and its default/validation rules.
docs/guides/reasoning-aware-llm-agents.md.
src/cleveractors/agents/llm_client.py — config.get("reasoning", False), boolean validation, reasoning: bool parameter.
src/cleveractors/agents/llm.py — configuration inspection referencing the "reasoning" key.
features/reasoning_provider_routing.feature, features/llm_agent_coverage.feature, features/steps/llm_agent_steps.py, features/steps/reasoning_provider_routing_steps.py, features/mocks/reasoning_model.py.
robot/reasoning_provider_routing.robot, robot/ReasoningRoutingTestLib.py.

Subtasks

Add a proposed revision (new D-N, in place — no new ADR file) to docs/adr/ADR-2036-reasoning-aware-provider-routing.md renaming the reasoning LLM agent configuration field to reasoning_feedback, including rationale and the spec-versioning treatment
Obtain acceptance of the ADR-2036 revision before making any spec or code change
Update docs/index.md §4.4 / §4.4.1 to the new field name and example, and add a §21.1 Revision History row attributing the change to the accepted ADR-2036 revision
Rename the config key, parameter, and validation message in src/cleveractors/agents/llm_client.py from reasoning to reasoning_feedback
Update the corresponding configuration-inspection reference in src/cleveractors/agents/llm.py
Update docs/guides/reasoning-aware-llm-agents.md examples to use reasoning_feedback
Tests (Behave): update features/reasoning_provider_routing.feature, features/llm_agent_coverage.feature, and their step definitions to use reasoning_feedback
Tests (Robot): update robot/reasoning_provider_routing.robot to use reasoning_feedback
Verify coverage meets the project's configured threshold 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.
The ADR-2036 revision proposing the rename has been accepted.
docs/index.md reflects the renamed property with a correctly attributed §21.1 revision-history entry.
A Git commit is created where the first line matches the Commit Message in Metadata exactly.
The commit is pushed to the branch matching the Branch in Metadata exactly.
The commit is submitted as a PR to master, reviewed, and merged.

## Metadata Commit Message: `refactor(agents): rename reasoning config field to reasoning_feedback` Branch: `feature/m1-rename-reasoning-config-property` ## Background and context ADR-2036 (spec v1.3.0, §4.4 / §4.4.1) introduced an optional boolean field named `reasoning` on the `type: llm` agent configuration. When `true` and the agent's `provider` is non-native (any provider outside `openai`/`anthropic`/`google`), it routes the agent through a reasoning-aware client that preserves and round-trips the provider's `reasoning_content` across a multi-turn tool-call loop. The name `reasoning` collides conceptually with the wire-protocol concept it is toggling — "the model performed reasoning" versus "round-trip the model's reasoning content back to it on the next turn." Operators skimming `agents.<name>` configuration cannot tell from the field name alone that it controls feedback/round-tripping behavior rather than, say, enabling a reasoning-capable model or a "thinking mode" toggle. Renaming the field to `reasoning_feedback` makes its actual effect (feeding the provider's own reasoning content back to it) explicit. This is a rename of a normative field name in the Actor Configuration Standard (`docs/index.md`, currently version 1.5.0) and therefore requires the ADR process: `docs/adr/ADR-2036-reasoning-aware-provider-routing.md` must be revised in place (a new proposed `D-N`, no new ADR file) and accepted before `docs/index.md` or any code is touched. ## Current behavior - `type: llm` agent configuration accepts a boolean field literally named `reasoning` (default `false`). - `src/cleveractors/agents/llm_client.py` reads it via `config.get("reasoning", False)`, validates it is a boolean (`"'reasoning' must be a boolean, got ..."`), and passes it as a `reasoning: bool` parameter. - `src/cleveractors/agents/llm.py` inspects the same `"reasoning"` key when constructing/validating agent configuration. - `docs/index.md` §4.4 documents the field as `reasoning`; §4.4.1 shows a `reasoning: true` example; §21.1 records its introduction under spec version 1.3.0. - Behave (`features/reasoning_provider_routing.feature`, `features/llm_agent_coverage.feature`) and Robot (`robot/reasoning_provider_routing.robot`) tests, plus `docs/guides/reasoning-aware-llm-agents.md`, all reference the `reasoning:` key by that name. ## Expected behavior - The same boolean configuration field is named `reasoning_feedback` instead of `reasoning`, with identical semantics, default (`false`), validation, and routing effect (non-native providers only). - `docs/adr/ADR-2036-reasoning-aware-provider-routing.md` carries an accepted revision documenting the rename decision and rationale. - `docs/index.md` §4.4 / §4.4.1 reflect the new field name, and §21.1 Revision History has a new row attributing the change to the accepted ADR-2036 revision (per the project's spec-revision procedure — no other inline edits to `docs/index.md`). - All code, Behave scenarios, Robot tests, and the `docs/guides/reasoning-aware-llm-agents.md` guide reference `reasoning_feedback` instead of `reasoning`. - No behavior is renamed or altered beyond the configuration key itself: `reasoning_content` / `reasoning_details` (the wire-protocol fields the flag round-trips), `cleveractors.agents.llm_reasoning.ReasoningChatModel`, and the "reasoning-aware routing" feature/module naming are explicitly **out of scope** and must not change. ## Acceptance criteria - [ ] `docs/adr/ADR-2036-reasoning-aware-provider-routing.md` contains an accepted revision (new `D-N`, added in place — no new ADR file) proposing and justifying the rename from `reasoning` to `reasoning_feedback`, including the spec-versioning treatment (the revision decides whether this is a breaking major-version bump or ships with a deprecation path, per the standard's own semver rules in §0). - [ ] `docs/index.md` §4.4 field table names the property `reasoning_feedback` (the literal string `reasoning` no longer appears as a field name in §4.4/§4.4.1). - [ ] `docs/index.md` §4.4.1 example configuration uses `reasoning_feedback: true`. - [ ] `docs/index.md` §21.1 Revision History has a new row attributing the rename to the accepted ADR-2036 revision. - [ ] `src/cleveractors/agents/llm_client.py` reads `config.get("reasoning_feedback", False)`; the validation error message references `reasoning_feedback`; the `reasoning: bool` parameter is renamed to `reasoning_feedback: bool` throughout the module. - [ ] `src/cleveractors/agents/llm.py` references the renamed key wherever it inspects `type: llm` agent configuration. - [ ] No source file under `src/cleveractors/` reads or writes the literal config key `"reasoning"` for this purpose. - [ ] `docs/guides/reasoning-aware-llm-agents.md` examples and prose use `reasoning_feedback`. - [ ] `features/reasoning_provider_routing.feature`, `features/llm_agent_coverage.feature`, and their step files (`features/steps/llm_agent_steps.py`, `features/steps/reasoning_provider_routing_steps.py`) exercise `reasoning_feedback` instead of `reasoning`. - [ ] `robot/reasoning_provider_routing.robot` (and `robot/ReasoningRoutingTestLib.py` if it references the key) exercise `reasoning_feedback`. - [ ] `nox` (full default session suite) passes. - [ ] `nox -s coverage_report` reports coverage at or above the project's configured threshold. ## Supporting information - `docs/index.md` — §4.4 field table (~line 316), §4.4.1 example (~lines 360-369), routing prose (~line 386), §21.1 revision row for v1.3.0 (~line 4046). - `docs/adr/ADR-2036-reasoning-aware-provider-routing.md` — D-1 defines the current field name and its default/validation rules. - `docs/guides/reasoning-aware-llm-agents.md`. - `src/cleveractors/agents/llm_client.py` — `config.get("reasoning", False)`, boolean validation, `reasoning: bool` parameter. - `src/cleveractors/agents/llm.py` — configuration inspection referencing the `"reasoning"` key. - `features/reasoning_provider_routing.feature`, `features/llm_agent_coverage.feature`, `features/steps/llm_agent_steps.py`, `features/steps/reasoning_provider_routing_steps.py`, `features/mocks/reasoning_model.py`. - `robot/reasoning_provider_routing.robot`, `robot/ReasoningRoutingTestLib.py`. ## Subtasks - [ ] Add a proposed revision (new `D-N`, in place — no new ADR file) to `docs/adr/ADR-2036-reasoning-aware-provider-routing.md` renaming the `reasoning` LLM agent configuration field to `reasoning_feedback`, including rationale and the spec-versioning treatment - [ ] Obtain acceptance of the ADR-2036 revision before making any spec or code change - [ ] Update `docs/index.md` §4.4 / §4.4.1 to the new field name and example, and add a §21.1 Revision History row attributing the change to the accepted ADR-2036 revision - [ ] Rename the config key, parameter, and validation message in `src/cleveractors/agents/llm_client.py` from `reasoning` to `reasoning_feedback` - [ ] Update the corresponding configuration-inspection reference in `src/cleveractors/agents/llm.py` - [ ] Update `docs/guides/reasoning-aware-llm-agents.md` examples to use `reasoning_feedback` - [ ] Tests (Behave): update `features/reasoning_provider_routing.feature`, `features/llm_agent_coverage.feature`, and their step definitions to use `reasoning_feedback` - [ ] Tests (Robot): update `robot/reasoning_provider_routing.robot` to use `reasoning_feedback` - [ ] Verify coverage meets the project's configured threshold 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. - The ADR-2036 revision proposing the rename has been accepted. - `docs/index.md` reflects the renamed property with a correctly attributed §21.1 revision-history entry. - A Git commit is created where the first line matches the Commit Message in Metadata exactly. - The commit is pushed to the branch matching the Branch in Metadata exactly. - The commit is submitted as a PR to `master`, reviewed, and merged.

CoreRasurae added the

labels

2026-08-21 21:01:03 +00:00

CoreRasurae added a new dependency

2026-08-21 21:02:20 +00:00

#77 Epic: LLM Agent Runtime Stabilization — reliability, resource enforcement & correctness hardening

CoreRasurae added

State