Skip to content

[T-003a] Typed layered settings: RoboProbeSettings tree, sources & precedence, fail-fast validation #19

Closed

Description

@CodewithJha

Task T-003a · Milestone M1 — Foundation · Size M · Priority P0 · Epic #1

Implements 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: RoboProbeSettings and nested DatabaseSettings, 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 at ROBOPROBE_CONFIG_FILE or ./roboprobe.toml, secrets dir ROBOPROBE_SECRETS_DIR (default /run/secrets).
  • load_settings(cli_overrides: Mapping[str, Any] | None = None) -> RoboProbeSettings and explain_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_file merged into DSN.

Out of scope

  • roboprobe config show command (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 lists settings.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 from roboprobe.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.TomlConfigSettingsSource and a custom settings_customise_sources to realise the precedence order.
  • os.environ may be read only in this package (doc 27 §6 rule 2).
  • env literal: local | ci | lab | prod. api.host non-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() or model_dump() (masked).
  • api.host=0.0.0.0 without api.token fails 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 Unreleased updated 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.py using monkeypatch + tmp_path TOML/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:

Activity

  1. added this to the M1 — Foundation milestone on Nov 19, 2026
  2. added
    area:coreDomain core, plugin registry, shared types
    area:configTyped settings / configuration
    priority:P0Critical path / blocks others
    taskChild task of a milestone epic
    on Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:configTyped settings / configurationarea:coreDomain core, plugin registry, shared typesmilestone:M1M1 — Foundationpriority:P0Critical path / blocks otherssize:M1-3 daystaskChild task of a milestone epictype:featureNew functionality

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions