Skip to content

[T-075a] analyze_campaign pipeline + versioned report.json and analysis artefacts #137

Closed

Description

@CodewithJha

Task T-075a · Milestone M6 — Analysis + risk · Size M · Priority P0 · Epic #6

Implements 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.
  • Analyzer port and registry group roboprobe.analyzers (doc 05 §13) so steps are pluggable.
  • analysis.finished log/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 Analyzer objects (analysis/base.py: class Analyzer(Protocol): name: str; def run(self, ctx: AnalysisContext) -> None) registered under entry-point group roboprobe.analyzers (doc 05 §13). Default chain: features → clustering → modes+matching → importance → rules → GP refit → risk slices → volumes. incremental kind runs features→clustering→modes→volumes only.
  • AnalysisContext holds inputs and accumulates outputs; each step logs analysis.step with duration and is individually timed into roboprobe_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 against schemas/analysis_report.schema.json before write), modes.parquet, shap_values.npz, risk_slices.npz — stored via ArtifactStore.put (SHA-256 recorded).
  • Persistence in one UoW: upsert failure_modes (using T-071b mapping), insert risk_maps, analyses row (status, kind, duration, artefact refs), outbox events mode.discovered for new codes and analysis.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 artifacts table.
  • 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/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.py
  • backend/src/roboprobe/analysis/base.py
  • schemas/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)

Activity

  1. added
    area:analysisFailure clustering, SHAP, rules, interactions
    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:analysisFailure clustering, SHAP, rules, interactionsmilestone:M6M6 — Analysis + riskpriority: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