Repository navigation
Description
Task
T-001· Milestone M1 — Foundation · Size M · Priority P0 · Epic #1Implements NFR-MNT-001 · NFR-MNT-002 · NFR-PORT-001 · NFR-COST-001
Branch
chore/t-001-backend-monorepo-skeleton-uv-project— one task = one branch = one PR (doc 32 §6)
Summary
Create the Python side of the monorepo exactly as laid out in doc 16 §1 so that every later task has a place to put code, a lint/type/test toolchain, and make entry points.
Context / motivation
Nothing can be built until the repository has a buildable package, a locked environment and quality gates. Getting the tool configuration right once (ruff rules incl. PLR2004 magic-value rule, mypy strict, pytest markers) means every later PR is held to the same standard automatically. ADR-0004 fixes Python 3.12 + uv in a single monorepo.
Scope
In scope
backend/pyproject.tomlfor packageroboprobewith extras[ml],[worker],[api],[dev]and the full dependency set from doc 15 §1 (so later tasks rarely touch the lockfile).backend/src/roboprobe/with empty sub-packages from doc 16 §1 (core,bootstrap,scenario,selection,oracles,analysis,risk,metrics,experiments,runner,backends,geometry,perturbation,store,api,reporting,cli) each with a docstring-only__init__.py.backend/tests/{unit,integration,api,contract,property,benchmark,sim,e2e,fixtures}/withconftest.pystubs.- Tool config in
backend/pyproject.toml: ruff (line length 100, rule set from doc 16 §3, Google docstrings), mypy--strict, pytest markersunit, property, contract, integration, benchmark, sim, slow(default excludessimandslow), coverage config. - Root
Makefilewith targetssetup,lint,typecheck,test,test-fast(backend parts),.pre-commit-config.yaml(ruff, ruff-format, mypy, end-of-file, trailing whitespace, gitleaks). - Root
.env.exampleandroboprobe.example.tomlcopied from doc 27 §5 with every key commented (values only; generator in T-003c will keep them in sync). - A trivial smoke test (
tests/unit/test_import.py) somake testis green.
Out of scope
- Web app (T-007)
- Settings models (T-003a)
- CI workflows (T-006a)
- Docker (T-005a/b)
Implementation guidance
- Use
uv init --packagesemantics manually:[project] name = "roboprobe",requires-python = ">=3.12,<3.13",[build-system]hatchling,[tool.hatch.build.targets.wheel] packages = ["src/roboprobe"]. - Extras (doc 16 §1, doc 15 §1):
ml= torch (CPU), gpytorch, botorch, scikit-learn, shap;worker= pyarrow, pandas, lxml, jinja2;api= fastapi, uvicorn, sse-starlette;dev= pytest, pytest-cov, pytest-xdist, hypothesis, pytest-benchmark, testcontainers[postgres], mypy, ruff, import-linter, pip-audit, types-PyYAML. Base deps: numpy, scipy, pydantic, pydantic-settings, PyYAML, jsonschema, structlog, prometheus-client, sqlalchemy, alembic, psycopg[binary], typer, rich, uuid-utils, matplotlib. - Add the PyTorch CPU index via
[tool.uv.sources]/[[tool.uv.index]]so CI never downloads CUDA wheels. make setup→uv sync --all-extras --directory backend+pre-commit install;make test→uv run --directory backend pytest;make test-fast→-m "unit or property or contract" -n auto.- Commit
backend/uv.lock(generated, never hand-edited — doc 16 §7). - Every module docstring must state its layer (doc 16 §2) so reviewers can spot violations.
- 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.
Acceptance criteria
-
make setup && make lint && make typecheck && make testpass on a clean clone (Linux and macOS). - Package tree matches doc 16 §1 (all sub-packages importable:
python -c 'import roboprobe.selection'). - ruff config enables the rule set listed in doc 16 §3 including
PLR2004; mypy runs in strict mode onsrc/. - Pytest markers registered;
pytestdefault run excludessimandslow. -
.env.exampleandroboprobe.example.tomlexist, contain no secrets, and are referenced from README quick-start. -
uv.lockcommitted;uv sync --lockedsucceeds. - 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/test_import.pyimports every sub-package.- Pre-commit hooks run clean on the whole repo.
Dependencies
Blocked by: nothing — can start immediately
Blocks: #13 (T-007), #14 (T-009), #15 (T-002a), #16 (T-002b), #17 (T-002c), #18 (T-002d), #19 (T-003a), #20 (T-008), #25 (T-017), #26 (T-005a), #28 (T-006a), #29 (T-006b), #32 (T-020a)
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/pyproject.tomlbackend/uv.lockbackend/src/roboprobe/**/__init__.pybackend/tests/**/conftest.pyMakefile.pre-commit-config.yaml.env.exampleroboprobe.example.toml
Root task — everything else depends on it. Keep it minimal (no business logic) so it merges fast. After merge, pyproject.toml/uv.lock become shared hot files: later tasks that must add a dependency rebase and regenerate uv.lock (uv lock), never hand-merge it.
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-001 (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 16 §1 · doc 16 §3 · doc 16 §7 · doc 17 §2 · doc 17 §3 · doc 15 §1 · ADR-0004 · doc 27 §5
Requirements: NFR-MNT-001 · NFR-MNT-002 · NFR-PORT-001 · NFR-COST-001 (traceability: doc 28)
External:
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone
Activity
ci.yml: lint, typecheck, backend unit/property/contract matrix, integration, web tests #28docs.yml: markdownlint, Mermaid render check, lychee links, ADR index check #29