feat(api): explicit ?compute_trigger=true flag for time-to-detection

[Chouffe]

Closes #26.

Summary

• Adds an explicit compute_trigger query param to POST /predict (default false). The default serving path is unchanged — no first-crossing search, no trigger fields, byte-identical response (guarded by the exact-shape asserts in test_predict_default / test_predict_verbose).
• ?compute_trigger=true threads the flag through ModelRunner.predict → _predict_sync → model.predict (core already supported it since perf: make trigger_search eval-only via compute_trigger gate (closes #23) #25) and adds a top-level trigger_frame_index. An explicit null means "searched, no crossing" — same convention as probability.
• With verbose=true it also fills details.decision.trigger_tube_id and per-tube details.tubes[].first_crossing_frame, which core already emits and the mapper previously dropped.
• Serialization relies on the route's existing response_model_exclude_unset=True: the new DTO fields stay unset (omitted) unless the flag is on.

Design spec: docs/specs/2026-06-11-api-compute-trigger-design.md. The ticket's predict_sequence step is obsolete — that function was refactored away; the runner calls model.predict directly.

Request / response examples

Request body is unchanged in all cases:

POST /predict?compute_trigger=true
Content-Type: application/json

{
  "frames": ["cam12/adf_2023-05-23T17-18-01.jpg", "cam12/adf_2023-05-23T17-18-31.jpg"],
  "bucket": "frames"
}

Default (POST /predict) — unchanged, fast path:

{
  "is_smoke": true,
  "probability": 0.98,
  "version": {"api": "0.3.0", "model": "1.2.0"}
}

POST /predict?compute_trigger=true — runs the first-crossing search, adds the top-level TTD field:

{
  "is_smoke": true,
  "probability": 0.98,
  "trigger_frame_index": 3,
  "version": {"api": "0.3.0", "model": "1.2.0"}
}

"trigger_frame_index": null means the search ran and nothing crossed (e.g. a negative decision).

POST /predict?compute_trigger=true&verbose=true — also fills the trigger fields inside details:

{
  "is_smoke": true,
  "probability": 0.98,
  "trigger_frame_index": 3,
  "version": {"api": "0.3.0", "model": "1.2.0"},
  "details": {
    "decision": {
      "aggregation": "max_logit",
      "threshold": 0.5,
      "threshold_overridden": false,
      "packaged_threshold": null,
      "trigger_tube_id": 7
    },
    "preprocessing": {
      "num_frames_input": 30,
      "num_truncated": 0,
      "padded_frame_indices": [],
      "num_tube_candidates": 2,
      "num_tubes_outside_roi": 0
    },
    "tubes": [
      {
        "tube_id": 7,
        "start_frame": 2,
        "end_frame": 12,
        "logit": 3.4,
        "probability": 0.98,
        "first_crossing_frame": 3,
        "entries": [
          {"frame_idx": 2, "bbox": [0.41, 0.55, 0.04, 0.03], "is_gap": false, "confidence": 0.8}
        ]
      }
    ]
  }
}

POST /predict?verbose=true (without the flag) — details as today, still no trigger fields.

Test plan

• api: make lint clean, make test → 132 passed, 1 skipped
• New tests: runner forwarding (2), DTO gating incl. null semantics and verbose-without-flag (5), route behavior for all param combinations (3)

[MateoLostanlen]

All good, thanks