Update docs

docs/docs/configuration/genai/review_summaries.md

@@ -14,12 +14,12 @@ Generative AI review summaries can also be toggled dynamically for a [camera via
 Review summaries provide structured JSON responses that are saved for each review item:
 
 ```
-- `title` (string): A concise, one-sentence title that captures the main activity.
+- `title` (string): A concise, direct title that describes the purpose or overall action (e.g., "Person taking out trash", "Joe walking dog").
 - `scene` (string): A narrative description of what happens across the sequence from start to finish, including setting, detected objects, and their observable actions.
 - `confidence` (float): 0-1 confidence in the analysis. Higher confidence when objects/actions are clearly visible and context is unambiguous.
 - `other_concerns` (list): List of user-defined concerns that may need additional investigation.
 - `potential_threat_level` (integer): 0, 1, or 2 as defined below.
-
+```
 
 This will show in multiple places in the UI to give additional context about each activity, and allow viewing more details when extra attention is required. Frigate's built in notifications will also automatically show the title and description when the data is available.
 
@@ -32,36 +32,38 @@ Each installation and even camera can have different parameters for what is cons
 
 ```
 ### Normal Activity Indicators (Level 0)
-- Known/verified people in any zone
+- Known/verified people in any zone at any time
 - People with pets in residential areas
-- Brief activity near vehicles: approaching vehicles, brief standing, then leaving or entering vehicle (unloading, loading, checking something). Very short sequences (under 15 seconds) of vehicle access during typical hours (6 AM - 10 PM) are almost always normal.
+- Deliveries or services during daytime/evening (6 AM - 10 PM): carrying packages to doors/porches, placing items, leaving
-- Deliveries or services: brief approach to doors/porches, standing briefly, placing or retrieving items, then leaving
+- Services/maintenance workers with visible tools, uniforms, or service vehicles during daytime
-- Access to private areas: entering back yards, garages, or homes (with or without visible purpose in frame)
+- Activity confined to public areas only (sidewalks, streets) without entering property at any time
-- Brief movement through semi-public areas (driveways, front yards) with items or approaching structure/vehicle
-- Activity on public areas only (sidewalks, streets) without entering property
-- Services/maintenance workers with tools, uniforms, or vehicles
 
 ### Suspicious Activity Indicators (Level 1)
-- Testing or attempting to open doors/windows on vehicles or buildings
+- **Testing or attempting to open doors/windows/handles on vehicles or buildings** — ALWAYS Level 1 regardless of time or duration
-- Taking items that don't belong to them (stealing packages, objects from porches/driveways)
+- **Unidentified person in private areas (driveways, near vehicles/buildings) during late night/early morning (11 PM - 5 AM)** — ALWAYS Level 1 regardless of activity or duration
+- Taking items that don't belong to them (packages, objects from porches/driveways)
 - Climbing or jumping fences/barriers to access property
 - Attempting to conceal actions or items from view
-- Prolonged presence without purpose: remaining in same area (near vehicles, private zones) throughout most/all of the sequence without clear activity or task. Brief stops (a few seconds of standing) are normal; sustained presence (most of the duration) without interaction is concerning.
+- Prolonged loitering: remaining in same area without visible purpose throughout most of the sequence
-- Activity at unusual hours (11 PM - 5 AM) combined with suspicious behavior patterns. Normal commute/daytime hours (6 AM - 6 PM) do not increase suspicion by themselves.
 
 ### Critical Threat Indicators (Level 2)
 - Holding break-in tools (crowbars, pry bars, bolt cutters)
 - Weapons visible (guns, knives, bats used aggressively)
 - Forced entry in progress
 - Physical aggression or violence
-- Active property damage or theft
+- Active property damage or theft in progress
 
 ### Assessment Guidance
-**Default to Level 0** for brief activity during normal hours. When evaluating, first check if it matches Normal Activity Indicators. Very short sequences (under 15 seconds) of vehicle access, deliveries, or movement through property during typical hours (6 AM - 11 PM) should be Level 0 unless there are clear suspicious actions visible (testing doors, stealing, climbing barriers).
+Evaluate in this order:
 
-Only assign Level 1 if the activity shows clear suspicious behaviors: testing access points, stealing items, lingering throughout most of the sequence without task, climbing barriers, or other explicit violations. Brief activity with apparent purpose (approaching vehicle, delivery, passing through) is Level 0.
+1. **If person is verified/known** → Level 0 regardless of time or activity
+2. **If person is unidentified:**
+   - Check time: If late night/early morning (11 PM - 5 AM) AND in private areas (driveways, near vehicles/buildings) → Level 1
+   - Check actions: If testing doors/handles, taking items, climbing → Level 1
+   - Otherwise, if daytime/evening (6 AM - 10 PM) with clear legitimate purpose (delivery, service worker) → Level 0
+3. **Escalate to Level 2 if:** Weapons, break-in tools, forced entry in progress, violence, or active property damage visible (escalates from Level 0 or 1)
 
-Consider duration, time, zone, and actions holistically. Brief is normal; sustained suspicious behavior is concerning.
+The mere presence of an unidentified person in private areas during late night hours is inherently suspicious and warrants human review, regardless of what activity they appear to be doing or how brief the sequence is.
 ```
 
 </details>
@@ -77,11 +79,19 @@ review:
     image_source: recordings # Options: "preview" (default) or "recordings"
 ```
 
-When using `recordings`, frames are extracted at 480p resolution (480px height), providing better detail for the LLM while being mindful of context window size. This is particularly useful for scenarios where fine details matter, such as identifying license plates, reading text, or analyzing distant objects. Note that using recordings will:
+When using `recordings`, frames are extracted at 480px height while maintaining the camera's original aspect ratio, providing better detail for the LLM while being mindful of context window size. This is particularly useful for scenarios where fine details matter, such as identifying license plates, reading text, or analyzing distant objects.
+
+The number of frames sent to the LLM is dynamically calculated based on:
+
+- Your LLM provider's context window size
+- The camera's resolution and aspect ratio (ultrawide cameras like 32:9 use more tokens per image)
+- The image source (recordings use more tokens than preview images)
+
+Frame counts are automatically optimized to use ~98% of the available context window while capping at 20 frames maximum to ensure reasonable inference times. Note that using recordings will:
 
 - Provide higher quality images to the LLM (480p vs 180p preview images)
-- Use more tokens per image (~200-300 tokens vs ~100 tokens for preview)
+- Use more tokens per image due to higher resolution
-- Result in fewer frames being sent to stay within context limits (typically 6-12 frames vs 8-20 frames)
+- Result in fewer frames being sent for ultrawide cameras due to larger image size
 - Require that recordings are enabled for the camera
 
 If recordings are not available for a given time period, the system will automatically fall back to using preview frames.

docs/docs/configuration/reference.md

@@ -430,12 +430,13 @@ review:
     # Optional: Enable GenAI review summaries for detections (default: shown below)
     detections: False
     # Optional: Activity Context Prompt to give context to the GenAI what activity is and is not suspicious.
-    # It is important to be direct and detailed.
+    # It is important to be direct and detailed. See documentation for the default prompt structure.
     activity_context_prompt: """Define what is and is not suspicious
 """
     # Optional: Image source for GenAI (default: preview)
-    # Options: "preview" (uses cached preview frames at 180p) or "recordings" (extracts frames from recordings at 480p)
+    # Options: "preview" (uses cached preview frames at ~180p) or "recordings" (extracts frames from recordings at 480p)
-    # Using "recordings" provides better image quality but uses ~2-3x more tokens per image (~200-300 vs ~100 tokens)
+    # Using "recordings" provides better image quality but uses more tokens per image.
+    # Frame count is automatically calculated based on context window size, aspect ratio, and image source (capped at 20 frames).
     image_source: preview
     # Optional: Additional concerns that the GenAI should make note of (default: None)
     additional_concerns: