UAT: Settings class uses non-spec env var names for budget, index, and context keys — CLEVERAGENTS_BUDGET_PER_PLAN should be CLEVERAGENTS_PLAN_BUDGET etc. #4093

New issue

Open

opened 2026-04-06 10:17:40 +00:00 by freemo · 1 comment

freemo commented

2026-04-06 10:17:40 +00:00

Owner

Metadata

Branch: fix/settings-env-var-names
Commit Message: fix(config): add spec-required env var aliases to Settings for budget, index, and context keys
Milestone: (backlog — non-critical)
Parent Epic: (config/settings epic)

Bug Report

What was tested: Environment variable names in Settings class vs specification

Expected behavior (from spec, section "Global Configuration Keys"):

The spec defines specific environment variable names for each configuration key. Users and CI systems that set environment variables per the spec documentation expect these exact names to work.

Actual behavior:

The Settings class (src/cleveragents/config/settings.py) uses different environment variable names than what the spec defines for several keys. The ConfigService registry correctly uses the spec-required names, but Settings (the pydantic-settings class used for runtime configuration) does not respond to the spec-required env var names.

Mismatched env var names:

Spec-required env var	Settings field	Settings env var	Impact
`CLEVERAGENTS_PLAN_BUDGET`	`budget_per_plan`	`CLEVERAGENTS_BUDGET_PER_PLAN`	Setting `CLEVERAGENTS_PLAN_BUDGET` has no effect
`CLEVERAGENTS_SESSION_BUDGET`	`session_max_cost_usd`	`CLEVERAGENTS_SESSION_MAX_COST_USD`	Setting `CLEVERAGENTS_SESSION_BUDGET` has no effect
`CLEVERAGENTS_PLAN_BUDGET_WARN`	`budget_warning_threshold`	`CLEVERAGENTS_BUDGET_WARNING_THRESHOLD`	Setting `CLEVERAGENTS_PLAN_BUDGET_WARN` has no effect
`CLEVERAGENTS_INDEX_VECTOR_BACKEND`	`vector_store_backend`	`CLEVERAGENTS_VECTOR_STORE_BACKEND`	Setting `CLEVERAGENTS_INDEX_VECTOR_BACKEND` has no effect
`CLEVERAGENTS_INDEX_VECTOR_DIR`	`vector_store_path`	`CLEVERAGENTS_VECTOR_STORE_PATH`	Setting `CLEVERAGENTS_INDEX_VECTOR_DIR` has no effect
`CLEVERAGENTS_EMBEDDING_PROVIDER`	`vector_embeddings_provider`	`CLEVERAGENTS_VECTOR_EMBEDDINGS_PROVIDER`	Setting `CLEVERAGENTS_EMBEDDING_PROVIDER` has no effect
`CLEVERAGENTS_EMBEDDING_MODEL`	`vector_embeddings_model`	`CLEVERAGENTS_VECTOR_EMBEDDINGS_MODEL`	Setting `CLEVERAGENTS_EMBEDDING_MODEL` has no effect
`CLEVERAGENTS_EMBEDDING_DIMENSIONS`	`vector_embeddings_dimension`	`CLEVERAGENTS_VECTOR_EMBEDDINGS_DIMENSION`	Setting `CLEVERAGENTS_EMBEDDING_DIMENSIONS` has no effect
`CLEVERAGENTS_CTX_HOT_TOKENS`	`context_max_tokens_hot`	`CLEVERAGENTS_CONTEXT_MAX_TOKENS_HOT`	Setting `CLEVERAGENTS_CTX_HOT_TOKENS` has no effect
`CLEVERAGENTS_CTX_WARM_DECISIONS`	`context_max_decisions_warm`	`CLEVERAGENTS_CONTEXT_MAX_DECISIONS_WARM`	Setting `CLEVERAGENTS_CTX_WARM_DECISIONS` has no effect
`CLEVERAGENTS_CTX_COLD_DECISIONS`	`context_max_decisions_cold`	`CLEVERAGENTS_CONTEXT_MAX_DECISIONS_COLD`	Setting `CLEVERAGENTS_CTX_COLD_DECISIONS` has no effect

Code locations:

src/cleveragents/config/settings.py, lines 248-273 (budget fields)
src/cleveragents/config/settings.py, lines 332-355 (vector store / index fields)
src/cleveragents/config/settings.py, lines 286-303 (context tier fields)

Steps to reproduce:

Set CLEVERAGENTS_PLAN_BUDGET=5.0 in the environment
Instantiate Settings()
Check settings.budget_per_plan — it returns None (the default) instead of 5.0
The spec-required env var CLEVERAGENTS_PLAN_BUDGET is silently ignored

Fix:

Add the spec-required env var names as additional AliasChoices entries. For example:

budget_per_plan: float | None = Field(
    default=None,
    ge=0.0,
    validation_alias=AliasChoices(
        "CLEVERAGENTS_BUDGET_PER_PLAN",
        "CLEVERAGENTS_PLAN_BUDGET",  # spec-required name
    ),
)

Apply the same pattern to all mismatched fields listed above.

Subtasks

Audit all Settings fields against spec-defined env var names in docs/specification.md
Add AliasChoices entries for CLEVERAGENTS_PLAN_BUDGET → budget_per_plan
Add AliasChoices entries for CLEVERAGENTS_SESSION_BUDGET → session_max_cost_usd
Add AliasChoices entries for CLEVERAGENTS_PLAN_BUDGET_WARN → budget_warning_threshold
Add AliasChoices entries for CLEVERAGENTS_INDEX_VECTOR_BACKEND → vector_store_backend
Add AliasChoices entries for CLEVERAGENTS_INDEX_VECTOR_DIR → vector_store_path
Add AliasChoices entries for CLEVERAGENTS_EMBEDDING_PROVIDER → vector_embeddings_provider
Add AliasChoices entries for CLEVERAGENTS_EMBEDDING_MODEL → vector_embeddings_model
Add AliasChoices entries for CLEVERAGENTS_EMBEDDING_DIMENSIONS → vector_embeddings_dimension
Add AliasChoices entries for CLEVERAGENTS_CTX_HOT_TOKENS → context_max_tokens_hot
Add AliasChoices entries for CLEVERAGENTS_CTX_WARM_DECISIONS → context_max_decisions_warm
Add AliasChoices entries for CLEVERAGENTS_CTX_COLD_DECISIONS → context_max_decisions_cold
Add/update unit tests verifying each spec-required env var name is accepted by Settings
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.
All nox stages pass.
Coverage >= 97%.

Backlog note: This issue was discovered during autonomous operation on milestone (current active milestone). It does not block milestone completion and has been placed in the backlog for human review and future milestone assignment.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/settings-env-var-names` - **Commit Message**: `fix(config): add spec-required env var aliases to Settings for budget, index, and context keys` - **Milestone**: (backlog — non-critical) - **Parent Epic**: (config/settings epic) ## Bug Report **What was tested:** Environment variable names in `Settings` class vs specification **Expected behavior (from spec, section "Global Configuration Keys"):** The spec defines specific environment variable names for each configuration key. Users and CI systems that set environment variables per the spec documentation expect these exact names to work. **Actual behavior:** The `Settings` class (`src/cleveragents/config/settings.py`) uses **different** environment variable names than what the spec defines for several keys. The `ConfigService` registry correctly uses the spec-required names, but `Settings` (the pydantic-settings class used for runtime configuration) does not respond to the spec-required env var names. **Mismatched env var names:** | Spec-required env var | Settings field | Settings env var | Impact | |---|---|---|---| | `CLEVERAGENTS_PLAN_BUDGET` | `budget_per_plan` | `CLEVERAGENTS_BUDGET_PER_PLAN` | Setting `CLEVERAGENTS_PLAN_BUDGET` has no effect | | `CLEVERAGENTS_SESSION_BUDGET` | `session_max_cost_usd` | `CLEVERAGENTS_SESSION_MAX_COST_USD` | Setting `CLEVERAGENTS_SESSION_BUDGET` has no effect | | `CLEVERAGENTS_PLAN_BUDGET_WARN` | `budget_warning_threshold` | `CLEVERAGENTS_BUDGET_WARNING_THRESHOLD` | Setting `CLEVERAGENTS_PLAN_BUDGET_WARN` has no effect | | `CLEVERAGENTS_INDEX_VECTOR_BACKEND` | `vector_store_backend` | `CLEVERAGENTS_VECTOR_STORE_BACKEND` | Setting `CLEVERAGENTS_INDEX_VECTOR_BACKEND` has no effect | | `CLEVERAGENTS_INDEX_VECTOR_DIR` | `vector_store_path` | `CLEVERAGENTS_VECTOR_STORE_PATH` | Setting `CLEVERAGENTS_INDEX_VECTOR_DIR` has no effect | | `CLEVERAGENTS_EMBEDDING_PROVIDER` | `vector_embeddings_provider` | `CLEVERAGENTS_VECTOR_EMBEDDINGS_PROVIDER` | Setting `CLEVERAGENTS_EMBEDDING_PROVIDER` has no effect | | `CLEVERAGENTS_EMBEDDING_MODEL` | `vector_embeddings_model` | `CLEVERAGENTS_VECTOR_EMBEDDINGS_MODEL` | Setting `CLEVERAGENTS_EMBEDDING_MODEL` has no effect | | `CLEVERAGENTS_EMBEDDING_DIMENSIONS` | `vector_embeddings_dimension` | `CLEVERAGENTS_VECTOR_EMBEDDINGS_DIMENSION` | Setting `CLEVERAGENTS_EMBEDDING_DIMENSIONS` has no effect | | `CLEVERAGENTS_CTX_HOT_TOKENS` | `context_max_tokens_hot` | `CLEVERAGENTS_CONTEXT_MAX_TOKENS_HOT` | Setting `CLEVERAGENTS_CTX_HOT_TOKENS` has no effect | | `CLEVERAGENTS_CTX_WARM_DECISIONS` | `context_max_decisions_warm` | `CLEVERAGENTS_CONTEXT_MAX_DECISIONS_WARM` | Setting `CLEVERAGENTS_CTX_WARM_DECISIONS` has no effect | | `CLEVERAGENTS_CTX_COLD_DECISIONS` | `context_max_decisions_cold` | `CLEVERAGENTS_CONTEXT_MAX_DECISIONS_COLD` | Setting `CLEVERAGENTS_CTX_COLD_DECISIONS` has no effect | **Code locations:** - `src/cleveragents/config/settings.py`, lines 248-273 (budget fields) - `src/cleveragents/config/settings.py`, lines 332-355 (vector store / index fields) - `src/cleveragents/config/settings.py`, lines 286-303 (context tier fields) **Steps to reproduce:** 1. Set `CLEVERAGENTS_PLAN_BUDGET=5.0` in the environment 2. Instantiate `Settings()` 3. Check `settings.budget_per_plan` — it returns `None` (the default) instead of `5.0` 4. The spec-required env var `CLEVERAGENTS_PLAN_BUDGET` is silently ignored **Fix:** Add the spec-required env var names as additional `AliasChoices` entries. For example: ```python budget_per_plan: float | None = Field( default=None, ge=0.0, validation_alias=AliasChoices( "CLEVERAGENTS_BUDGET_PER_PLAN", "CLEVERAGENTS_PLAN_BUDGET", # spec-required name ), ) ``` Apply the same pattern to all mismatched fields listed above. ## Subtasks - [ ] Audit all `Settings` fields against spec-defined env var names in `docs/specification.md` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_PLAN_BUDGET` → `budget_per_plan` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_SESSION_BUDGET` → `session_max_cost_usd` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_PLAN_BUDGET_WARN` → `budget_warning_threshold` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_INDEX_VECTOR_BACKEND` → `vector_store_backend` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_INDEX_VECTOR_DIR` → `vector_store_path` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_EMBEDDING_PROVIDER` → `vector_embeddings_provider` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_EMBEDDING_MODEL` → `vector_embeddings_model` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_EMBEDDING_DIMENSIONS` → `vector_embeddings_dimension` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_CTX_HOT_TOKENS` → `context_max_tokens_hot` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_CTX_WARM_DECISIONS` → `context_max_decisions_warm` - [ ] Add `AliasChoices` entries for `CLEVERAGENTS_CTX_COLD_DECISIONS` → `context_max_decisions_cold` - [ ] Add/update unit tests verifying each spec-required env var name is accepted by `Settings` - [ ] 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. - All nox stages pass. - Coverage >= 97%. > **Backlog note:** This issue was discovered during autonomous operation on milestone (current active milestone). It does not block milestone completion and has been placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo commented

2026-04-06 10:18:12 +00:00

Author

Owner

⚠️ Orphan Issue — Needs Manual Linking

This issue was created without a known parent Epic number. Per CONTRIBUTING.md, all non-Epic/non-Legendary issues must be linked to a parent Epic via Forgejo's dependency system (child blocks parent).

A maintainer should:

Identify the appropriate config/settings Epic for this issue
Open this issue and add the Epic under "blocks", OR open the Epic and add this issue under "depends on"

This ensures the directed dependency link is machine-readable and tracked by Forgejo.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

⚠️ **Orphan Issue — Needs Manual Linking** This issue was created without a known parent Epic number. Per CONTRIBUTING.md, all non-Epic/non-Legendary issues must be linked to a parent Epic via Forgejo's dependency system (child **blocks** parent). A maintainer should: 1. Identify the appropriate config/settings Epic for this issue 2. Open this issue and add the Epic under **"blocks"**, OR open the Epic and add this issue under **"depends on"** This ensures the directed dependency link is machine-readable and tracked by Forgejo. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added the

Points

label

2026-04-06 10:20:57 +00:00

freemo referenced this issue

2026-04-06 10:22:26 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775