Skip to content

[T-075b] AnalysisJobRunner: automatic (ANALYZING), incremental (every N runs) and on-demand analysis; roboprobe analyze #138

Closed

Description

@CodewithJha

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

Implements FR-ANA-006

Branch feat/t-075b-analysisjobrunner-automatic-analyzing-incremental-every — one task = one branch = one PR (doc 32 §6)

Summary

Run analysis automatically when a campaign enters ANALYZING (then COMPLETED), incrementally every runner.analysis.incremental_every_n completed runs (clustering + volumes only, kind incremental) and on demand (CLI roboprobe analyze <id>); guard against concurrent analyses per campaign.

Context / motivation

The live dashboard shows modes appearing during the campaign; the final report needs the full analysis (sequence in doc 09 §8).

Scope

In scope

  • runner/analysis_jobs.py; cli/analyze.py.
  • Failure of analysis → analysis row ERROR, campaign still COMPLETED with reason (no lost campaign).

Implementation guidance

  • roboprobe/runner/analysis_jobs.py: class AnalysisJobRunner: def __init__(self, uow_factory, artifact_store, settings, executor: Executor, clock: Clock); methods on_campaign_status(campaign), on_run_finished(campaign_id, n_completed), request(campaign_id, kind) -> UUID.
  • Triggers: (1) campaign enters ANALYZING ⇒ FULL analysis then transition to COMPLETED (doc 14 §3); (2) every runner.analysis.incremental_every_n completed runs ⇒ INCREMENTAL; (3) CLI/API on-demand.
  • Concurrency guard: Postgres advisory lock keyed on hash(campaign_id) (pg_try_advisory_lock) so only one analysis per campaign runs across orchestrator replicas; a skipped incremental is logged, not queued.
  • Executor: ProcessPoolExecutor(max_workers=runner.analysis.max_workers) (new, default 1) so heavy numpy/torch work never blocks the orchestrator tick; analysis code receives only IDs and builds its own UoW inside the worker process.
  • Failure: analysis row ERROR + alert event ANALYSIS_FAILED (new alert code, add to doc 21 §5.5) and campaign still → COMPLETED with status_reason.
  • CLI roboprobe analyze <campaign_id> [--kind full|incremental] [--wait] in cli/analyze.py, registered with one line in cli/main.py.
  • 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).

  • runner.analysis.incremental_every_n
  • runner.analysis.max_workers (new)

Acceptance criteria

  • End-to-end: campaign completes → status ANALYZING → COMPLETED with modes.
  • Incremental analysis triggered at N, 2N…
  • Advisory lock prevents concurrent analyses (two threads test).
  • Orchestrator tick latency unaffected while analysis runs (test with slow stub analyzer).
  • CLI exit codes follow the error → exit-code mapping (T-008).
  • 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_analysis_jobs.py.
  • Fake-clock unit tests for trigger arithmetic (25, 50, …).

Dependencies

Blocked by: #137 (T-075a), #95 (T-048)

Blocks: #153 (T-082c)

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/runner/analysis_jobs.py
  • backend/src/roboprobe/cli/analyze.py

Independent modules.

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-075b (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 §8 · doc 14 §3 · doc 21 §5.5

Requirements: FR-ANA-006 (traceability: doc 28)

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:analysisFailure clustering, SHAP, rules, interactionsarea:cliCommand-line interfacearea:runnerQueue, workers, campaign orchestrationmilestone:M6M6 — Analysis + riskpriority:P0Critical path / blocks otherssize:S<= 1 daytaskChild task of a milestone epictype:featureNew functionality

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions