Skip to main content

sightloom_analysis/
anomaly.rs

1//! Backend-neutral anomaly events.
2
3#[cfg(feature = "alloc")]
4extern crate alloc;
5
6#[cfg(feature = "alloc")]
7use alloc::vec::Vec;
8
9use sightloom_core::{AnomalyId, EventId, MediaTime, SourceId, SubjectId};
10
11/// Anomaly severity for host presentation.
12#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
13pub enum Severity {
14    /// Informational.
15    Low,
16    /// Notable deviation.
17    Medium,
18    /// Strong deviation.
19    High,
20    /// Critical / safety-relevant.
21    Critical,
22}
23
24/// Machine-readable anomaly reason codes (host maps to UI copy).
25#[derive(Clone, Copy, Debug, Eq, PartialEq)]
26pub enum AnomalyReason {
27    /// Unusual appearance time.
28    UnusualAppearanceTime,
29    /// Unusual frequency.
30    UnusualFrequency,
31    /// Unusual dwell.
32    UnusualDwell,
33    /// Unusual route.
34    UnusualRoute,
35    /// Unusual co-occurrence.
36    UnusualCoOccurrence,
37    /// Missing expected appearance.
38    MissingExpectedAppearance,
39    /// Sudden behaviour change.
40    SuddenBehaviourChange,
41    /// Cross-camera hop violates topology travel window (impossible).
42    ImpossibleCrossCameraHop,
43    /// Rare camera-to-camera transition vs relational baseline.
44    UnusualCameraTransition,
45    /// Application-defined reason code.
46    Custom(u32),
47}
48
49/// Backend-neutral anomaly event exposed to host products.
50///
51/// Hosts must not depend on whether the score came from a statistical rule,
52/// classical model, or optional quantum backend.
53#[derive(Clone, Debug, PartialEq)]
54pub struct AnomalyEvent {
55    /// Anomaly id.
56    pub anomaly_id: AnomalyId,
57    /// Score (higher means more anomalous; scale is backend-defined).
58    pub score: f32,
59    /// Presentation severity.
60    pub severity: Severity,
61    /// Reason codes.
62    pub reasons: Vec<AnomalyReason>,
63    /// Supporting event ids from the same index.
64    pub evidence: Vec<EventId>,
65    /// Optional subject scope.
66    pub subject_id: Option<SubjectId>,
67    /// Optional source scope.
68    pub source_id: Option<SourceId>,
69    /// Event time.
70    pub at: MediaTime,
71}