Integrate state changes with review items (#24503)

* Integrate state changes with review items

* Cleanup and fixes

* Improve report context management

docs/docs/configuration/custom_classification/state_classification.md

@@ -85,6 +85,14 @@ An optional config, `save_attempts`, can be set as a key under the model name. T
 </TabItem>
 </ConfigTabs>
 
+## Review items
+
+When a model's state changes while its camera has an active review item, the change is recorded on that review item. This includes changes in the few seconds before the item starts, such as a garage door opening just before the car is detected. State changes never create or extend review items on their own, and the first state reported after Frigate starts is not recorded as a change.
+
+Recorded changes appear in the review item's data as `classification_state_changes` (see the [`frigate/reviews`](/integrations/mqtt#frigatereviews) MQTT topic) and are passed to [GenAI review summaries](/configuration/genai/genai_review) as facts, so a description can note that a gate was opened during the activity.
+
+Change times are most accurate with `motion: true`. A model that only runs on an `interval` notices a change at its next run, so the change may be recorded late or attached to a later review item.
+
 ## Training the model
 
 Creating and training the model is done within the Frigate UI using the `Classification` page. The process consists of three steps:

docs/docs/configuration/genai/review_summaries.md

@@ -201,6 +201,8 @@ Review items are sent to the model as a sequence of still frames. Some models fo
 
 The notes come from tracking data rather than from the images, so they describe activity the model may not have picked up on its own. In testing with a person carrying three waste bins to the curb one at a time, `gemma4` described a single trip on every attempt with `frames`, and consistently described multiple trips with `annotated_frames`. Models that already handle these sequences well, such as the `qwen3-vl` family, gain little and should stay on `frames`.
 
+Changes reported by [state classification](/configuration/custom_classification/state_classification#review-items) models during the review item are listed in the prompt in both modes. `annotated_frames` also notes each change before the frame where it happened.
+
 Annotated mode also caps the number of frames, since the notes already establish the order of events and extra near-duplicate frames tend to crowd out the middle of a clip. Longer review items are sampled more sparsely as a result, and typically use fewer tokens than `frames` mode for the same item.
 
 :::note

docs/docs/integrations/mqtt.md

@@ -212,6 +212,7 @@ An `update` with the same ID will be published when:
 - The severity changes from `detection` to `alert`
 - Additional objects are detected
 - An object is recognized via face, lpr, etc.
+- A [state classification](/configuration/custom_classification/state_classification#review-items) model changes state
 
 When the review activity has ended a final `end` message is published.
 
@@ -235,7 +236,8 @@ When the review activity has ended a final `end` message is published.
       "objects": ["person", "car"],
       "sub_labels": [],
       "zones": [],
-      "audio": []
+      "audio": [],
+      "classification_state_changes": []
     }
   },
   "after": {
@@ -254,7 +256,16 @@ When the review activity has ended a final `end` message is published.
       "objects": ["person", "car"],
       "sub_labels": ["Bob"],
       "zones": ["front_yard"],
-      "audio": []
+      "audio": [],
+      "classification_state_changes": [
+        // verified changes of state classification models on this camera
+        {
+          "model": "front_gate",
+          "from": "closed",
+          "to": "open",
+          "timestamp": 1718987131.52
+        }
+      ]
     }
   }
 }