Repository navigation
Description
Task
T-075a· Milestone M6 — Analysis + risk · Size M · Priority P0 · Epic #6Implements FR-ANA-006
Branch
feat/t-075a-analyze-campaign-pipeline-versioned-and— one task = one branch = one PR (doc 32 §6)
Summary
Implement analysis/pipeline.py analyze_campaign(campaign_id, uow, artifact_store) -> AnalysisReport (doc 09 §2/§7): features → clustering → modes (+matching) → importance → rules → GP refit → risk slices → volumes; write report.json (analysis_schema_version: 1), modes.parquet, shap_values.npz, risk_slices.npz; upsert modes/risk maps/analysis row.
Context / motivation
Single entry point used by the post-campaign job, incremental updates, CLI and API.
Scope
In scope
schemas/analysis_report.schema.json.Analyzerport and registry grouproboprobe.analyzers(doc 05 §13) so steps are pluggable.analysis.finishedlog/event.- Schema doc section added to doc 09 §7 if fields differ.
Implementation guidance
- Module
roboprobe/analysis/pipeline.py(application layer):def analyze_campaign(campaign_id: UUID, uow: UnitOfWork, artifact_store: ArtifactStore, *, kind: AnalysisKind = AnalysisKind.FULL, settings: AnalysisSettings, clock: Clock) -> AnalysisReport(doc 05 §7 signature + explicit deps for testability). - Steps as pluggable
Analyzerobjects (analysis/base.py:class Analyzer(Protocol): name: str; def run(self, ctx: AnalysisContext) -> None) registered under entry-point grouproboprobe.analyzers(doc 05 §13). Default chain: features → clustering → modes+matching → importance → rules → GP refit → risk slices → volumes.incrementalkind runs features→clustering→modes→volumes only. AnalysisContextholds inputs and accumulates outputs; each step logsanalysis.stepwith duration and is individually timed intoroboprobe_analysis_step_seconds{step}(new metric, register in T-004b registry).- Artefacts under
campaigns/<id>/analysis/<analysis_id>/:report.json(analysis_schema_version: 1, validated againstschemas/analysis_report.schema.jsonbefore write),modes.parquet,shap_values.npz,risk_slices.npz— stored viaArtifactStore.put(SHA-256 recorded). - Persistence in one UoW: upsert
failure_modes(using T-071b mapping), insertrisk_maps,analysesrow (status, kind, duration, artefact refs), outbox eventsmode.discoveredfor new codes andanalysis.finished. - A failing optional step (e.g. importance with < 2 classes) records a warning in the report and continues; a failing core step marks the analysis ERROR without touching existing modes.
- 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
- k2d campaign fixture → report.json validates; modes and risk maps persisted.
- Re-running is idempotent (mode ids stable).
- Step failure isolation tested (importance raises → report has warning, modes still saved).
- Third-party analyzer registered via entry point is executed (test plugin in
tests/plugins/). - report.json validates; artefact hashes recorded in
artifactstable. - 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/integration/analysis/test_pipeline.py.- Integration test on the seeded k2d campaign fixture with Testcontainers Postgres.
Dependencies
Blocked by: #129 (T-071a), #130 (T-071b), #131 (T-072), #132 (T-073), #136 (T-077)
Blocks: #138 (T-075b), #139 (T-078a), #151 (T-082a), #159 (T-107)
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/analysis/pipeline.pybackend/src/roboprobe/analysis/base.pyschemas/analysis_report.schema.json
Integration point of M6.
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-075a (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 09 §2 · doc 09 §7 · doc 09 §8 · doc 05 §7 · doc 05 §13 · doc 21 §5.2 · ADR-0012
Requirements: FR-ANA-006 (traceability: doc 28)
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsBacklog
Activity
roboprobe analyze#138fixtures/db/seed_small.sqlandscripts/seed_demo.py(60 runs, 3 modes) #159