Repository navigation
Description
Task
T-003a· Milestone M1 — Foundation · Size M · Priority P0 · Epic #1Implements NFR-CFG-001 · NFR-CFG-002 · PR-12
Branch
feat/t-003a-typed-layered-settings-roboprobesettings-tree— one task = one branch = one PR (doc 32 §6)
Summary
Implement roboprobe.core.settings with every key of doc 27 §4 as typed, validated pydantic-settings models, loaded from CLI overrides > env > .env > TOML > secret files > defaults.
Context / motivation
"No hard-coded tunables" (ADR-0015) is only enforceable if every tunable already has a home. Defining the complete settings tree now means later tasks consume settings instead of editing a shared file, which avoids merge conflicts between parallel agents.
Scope
In scope
- Models:
RoboProbeSettingsand nestedDatabaseSettings,StorageSettings,ApiSettings(+SseSettings),RunnerSettings(+auto_pause, retry, analysis),WorkerSettings,BackendsSettings(Kinematic2DSettings,GazeboNav2Settings),SelectionDefaults(probe, gp, acq, ofat, grid),OracleThresholds(clear, goal, prog, loc, nav, stab, osc, infra),AnalysisSettings,RiskSettings,ExperimentSettings,ObservabilitySettings,LoggingSettings— fields, types, defaults and units exactly as doc 27 §4.1–4.10. - Sources & precedence per doc 27 §2: env prefix
ROBOPROBE_, nested delimiter__, aliases (ROBOPROBE_DATABASE_URL,ROBOPROBE_API_TOKEN),.env, TOML atROBOPROBE_CONFIG_FILEor./roboprobe.toml, secrets dirROBOPROBE_SECRETS_DIR(default/run/secrets). load_settings(cli_overrides: Mapping[str, Any] | None = None) -> RoboProbeSettingsandexplain_sources(settings) -> dict[str, str](which source set each value).- Fail fast: aggregated validation errors raised as
ConfigError(CLI maps to exit code 2). - Secrets as
SecretStr;database.password_filemerged into DSN.
Out of scope
roboprobe config showcommand (T-003b)- Generated doc tables (T-003c)
- Domain-specific params models such as
ProbeParams(live in their packages, T-060)
Implementation guidance
- Package layout to keep files < 400 lines:
backend/src/roboprobe/core/settings/__init__.py(root model +load_settings) and one module per section (database.py,storage.py,api.py,runner.py,worker.py,backends.py,selection.py,oracles.py,analysis.py,experiments.py,observability.py). Doc 16 listssettings.py; a package with the same import path is compatible — update doc 16 §1 in the PR. - Layering: core must not import domain packages, so the defaults models (
OracleThresholds,SelectionDefaults, …) live here and domain packages import them fromroboprobe.core.settings(domain → core is allowed). - Every field:
Field(default, description="… [unit]", gt/ge/le …). Descriptions are the source for the generated docs (T-003c), so write them carefully. - Use
pydantic_settings.TomlConfigSettingsSourceand a customsettings_customise_sourcesto realise the precedence order. os.environmay be read only in this package (doc 27 §6 rule 2).envliteral:local | ci | lab | prod.api.hostnon-loopback ⇒ token required: implement as model validator.- Standards: respect the layering contracts (doc 16 §2) and conventions in doc 34; no hard-coded tunables — thresholds/defaults come from typed settings (doc 27); no magic numbers (ruff
PLR2004); public APIs typed (mypy strict) and documented.
Configuration keys
From the configuration reference (doc 27). Keys marked (new) must be added to the typed settings models and appear in the generated reference (T-003c).
- all keys in doc 27 §4.1–§4.10
Acceptance criteria
- Every key in doc 27 §4.1–4.10 present with documented type/default/unit/validation.
- Precedence tests: same key set in defaults, TOML, .env, env and CLI → CLI wins; each layer removed in turn yields the next.
- Invalid config lists all errors and raises
ConfigError. - Secrets never appear in
repr()ormodel_dump()(masked). -
api.host=0.0.0.0withoutapi.tokenfails validation. - ≥ 95 % coverage of the settings package.
- Tests listed below added and green in CI; coverage of new code meets the gate in doc 18 §3.
- Docs, config reference and CHANGELOG
Unreleasedupdated where behaviour, keys or interfaces changed. - Definition of Done (doc 32 §3) satisfied.
Tests required
tests/unit/core/test_settings_precedence.py,test_settings_validation.py,test_settings_secrets.pyusingmonkeypatch+tmp_pathTOML/secret files.
Dependencies
Blocked by: #12 (T-001), #16 (T-002b)
Blocks: #21 (T-003b), #22 (T-003c), #23 (T-004a), #24 (T-004b), #66 (T-013a), #46 (T-031b), #49 (T-029), #68 (T-036a)
Parallelization notes
Files / paths owned by this task — avoid editing other paths; shared files (pyproject.toml entry points, cli/main.py, api/routers/__init__.py, router.tsx, docker/compose.yaml, ci.yml) are append-only:
backend/src/roboprobe/core/settings/**backend/tests/unit/core/test_settings_*.py
Owns the settings package. After merge, other tasks only read settings; adding a new key is a small additive change to one section module + regenerated docs (T-003c).
Definition of Done
Per doc 32 §3 and AGENTS.md §5: lint, format, mypy strict and import-linter green; tests added and passing; docs updated; PR template completed with Closes #<this issue>; Conventional Commit messages referencing T-003a (doc 16 §6); commits authored only by the repository owner identity (AGENTS.md §4); CI green; reviewer checklist (doc 32 §5.1) satisfied.
References
Design docs: doc 27 §1 · doc 27 §2 · doc 27 §3 · doc 27 §4 · doc 27 §6 · ADR-0015 · doc 16 §1
Requirements: NFR-CFG-001 · NFR-CFG-002 · PR-12 (traceability: doc 28)
External:
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone
Activity
roboprobe config show [--sources]command with masked secrets #21scripts/gen_config_docs.py --check) #22configs/backends/kinematic2d_v1.yaml#49