Upload README.md with huggingface_hub

README.md

@@ -10,7 +10,7 @@ tags:
 
 # Temporal Smoke Model (bbox-tube-temporal)
 
-> **Latest release:** [`v0.2.0`](https://huggingface.co/pyronear/temporal-model/tree/v0.2.0) — pin this revision for reproducibility, or omit `revision=` to always get the latest. All releases: the **Files and versions** tab.
+> **Latest release:** [`v0.3.0`](https://huggingface.co/pyronear/temporal-model/tree/v0.3.0) — pin this revision for reproducibility, or omit `revision=` to always get the latest. All releases: the **Files and versions** tab.
 
 A temporal wildfire-**smoke** classifier for short sequences of camera frames. A
 YOLO detector proposes boxes, boxes are linked across frames into temporal
@@ -49,7 +49,7 @@ from huggingface_hub import hf_hub_download
 from temporal_model.core.model import BboxTubeTemporalModel
 
 # 1. Download a specific release (pin the revision).
-model_zip = hf_hub_download("pyronear/temporal-model", "model.zip", revision="v0.2.0")
+model_zip = hf_hub_download("pyronear/temporal-model", "model.zip", revision="v0.3.0")
 
 # 2. Temporally-ordered frames. Filenames carry timestamps
 #    (<prefix>_<YYYY-MM-DDTHH-MM-SS>.jpg); the order is the time order.
@@ -60,21 +60,30 @@ frame_paths = sorted(Path("my_sequence").glob("*.jpg"))
 model = BboxTubeTemporalModel.from_package(Path(model_zip), device=None)
 out = model.predict_sequence(frame_paths)
 
-print("is_smoke:           ", out.is_positive)
-print("trigger_frame_index:", out.trigger_frame_index)  # 0-based; None if no smoke
+# 1. Binary verdict — the alarm decision.
+print("is_smoke:         ", out.is_positive)
 
-# Per-tube breakdown (logits, calibrated probabilities, bboxes, decision).
+# 2. Calibrated smoke probability in [0, 1]: the strongest kept tube's calibrated
+#    probability (0.0 when no tube was kept). Use is_positive for a yes/no alarm;
+#    use the probability to rank/triage sequences or apply your own threshold.
 kept = out.details.get("tubes", {}).get("kept", [])
-print("kept tubes:         ", len(kept))
+probs = [t["probability"] for t in kept if t["probability"] is not None]
+smoke_probability = max(probs) if probs else 0.0
+print("smoke probability:", smoke_probability)
+print("kept tubes:       ", len(kept))
 ```
 
 `predict_sequence(frame_paths)` returns a `TemporalModelOutput`:
 
-- `is_positive: bool` — the smoke verdict.
-- `trigger_frame_index: int | None` — 0-based frame where smoke first crosses the
-  decision threshold (time-to-detection, in frames; `None` when no smoke).
-- `details: dict` — per-tube logits, calibrated probabilities, bboxes, and the
-  decision (`aggregation`, `threshold`, trigger tube).
+- `is_positive: bool` — the smoke verdict. `True` iff at least one tube's
+  calibrated probability clears the packaged decision threshold.
+- `details: dict` — per-tube logits, calibrated probabilities, bounding boxes, and
+  the decision (`aggregation`, `threshold`). The top-level **smoke probability** is
+  the maximum kept-tube `probability` (shown above).
+
+`is_positive` and the probability are consistent: a positive sequence always has a
+kept tube whose probability is ≥ the threshold, so `smoke_probability` is ≥ the
+threshold whenever `is_smoke` is `True`.
 
 ## Served API (Docker)
 
@@ -85,10 +94,15 @@ The same model is also served as a FastAPI image with the `model.zip` baked in
 docker run --gpus all -p 8000:8000 \
   -e TEMPORAL_API_S3_BUCKET=<frames-bucket> \
   -e TEMPORAL_API_S3_ENDPOINT_URL=<s3-endpoint> \
-  pyronear/temporal-model-api:0.2.0
+  pyronear/temporal-model-api:0.3.0
 # POST /predict  {"frames": ["<s3-key>", ...]}      GET /health
 ```
 
+`POST /predict` returns `{ "is_smoke": bool, "probability": float | null, "model":
+{...} }`, where `probability` is the calibrated max kept-tube probability (`null`
+only for an uncalibrated model). Add `?verbose=true` for a `details` block with the
+per-tube breakdown and decision config.
+
 ## Provenance
 
 Every `model.zip` manifest records how it was built — the training git SHA, the