anomaly_grid/
lib.rs

1//! Anomaly Grid - Sequential Pattern Analysis Library
2//!
3//! A focused library for anomaly detection in finite-alphabet sequences using
4//! variable-order Markov chains with hierarchical context selection.
5//!
6//! This library provides pattern-based anomaly detection through
7//! information-theoretic measures and probability estimation.
8//!
9//! # Features
10//!
11//! - **Variable-Order Markov Models**: Hierarchical context selection with Laplace smoothing
12//! - **Information Theory**: Shannon entropy, KL divergence  
13//! - **Hierarchical Context Selection**: Automatic fallback from longer to shorter contexts
14//! - **Parallel Processing**: Batch analysis using Rayon for multiple sequences
15//!
16//! # Quick Start
17//!
18//! ```rust
19//! use anomaly_grid::*;
20//!
21//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
22//! // Create and train detector
23//! let mut detector = AnomalyDetector::new(3)?;
24//! let normal_sequence = vec![
25//!     "A".to_string(), "B".to_string(), "C".to_string(),
26//!     "A".to_string(), "B".to_string(), "C".to_string(),
27//! ];
28//! detector.train(&normal_sequence)?;
29//!
30//! // Detect anomalies
31//! let test_sequence = vec![
32//!     "A".to_string(), "X".to_string(), "Y".to_string(),
33//! ];
34//! let anomalies = detector.detect_anomalies(&test_sequence, 0.1)?;
35//!
36//! for anomaly in anomalies {
37//!     println!("Anomaly: {:?}, Likelihood: {:.6}",
38//!              anomaly.sequence, anomaly.likelihood);
39//! }
40//! # Ok(())
41//! # }
42//! ```
43//!
44//! # Architecture
45//!
46//! The library is organized into three main modules:
47//!
48//! - [`context_tree`]: Context storage and probability estimation
49//! - [`markov_model`]: Variable-order Markov chain implementation  
50//! - [`anomaly_detector`]: Anomaly detection using Markov models
51//!
52//! # Use Cases
53//!
54//! - **Network Security**: Detecting unusual protocol sequences and attack patterns
55//! - **User Behavior Analysis**: Identifying privilege escalation and suspicious activities
56//! - **Financial Fraud**: Detecting unusual transaction patterns and velocity attacks
57//! - **System Monitoring**: Identifying anomalous log sequences and security incidents
58//! - **Bioinformatics**: Detecting mutations and unusual genetic sequences
59
60pub mod anomaly_detector;
61pub mod config;
62pub mod constants;
63pub mod context_tree;
64pub mod error;
65pub mod markov_model;
66pub mod performance;
67pub mod string_interner;
68pub mod memory_pool;
69pub mod transition_counts;
70pub mod context_trie;
71
72// Re-export main types for convenience
73pub use anomaly_detector::{batch_process_sequences, AnomalyDetector, AnomalyScore};
74pub use config::AnomalyGridConfig;
75pub use context_tree::{ContextNode, ContextTree};
76pub use error::{AnomalyGridError, AnomalyGridResult};
77pub use markov_model::MarkovModel;
78pub use performance::{
79    optimize_context_tree, ContextStatistics, OptimizationConfig, PerformanceMetrics,
80};
81
82/// Library version
83pub const VERSION: &str = env!("CARGO_PKG_VERSION");
84
85/// Get library information
86pub fn info() -> String {
87    format!("Anomaly Grid v{VERSION} - Markov Chain-based Sequence Anomaly Detection")
88}
89
90#[cfg(test)]
91mod tests {
92    use super::*;
93
94    #[test]
95    fn test_library_info() {
96        let info = info();
97        assert!(info.contains("Anomaly Grid"));
98        assert!(info.contains(VERSION));
99    }
100
101    #[test]
102    fn test_basic_workflow() {
103        let mut detector = AnomalyDetector::new(2).expect("Failed to create detector");
104        let sequence = vec![
105            "A".to_string(),
106            "B".to_string(),
107            "A".to_string(),
108            "B".to_string(),
109        ];
110
111        // Training should succeed
112        assert!(detector.train(&sequence).is_ok());
113
114        // Detection should work
115        let test_sequence = vec!["A".to_string(), "X".to_string(), "Y".to_string()];
116        let anomalies = detector
117            .detect_anomalies(&test_sequence, 0.5)
118            .expect("Failed to detect anomalies");
119
120        // Should detect some anomalies or handle gracefully
121        for anomaly in anomalies {
122            assert!(anomaly.likelihood >= 0.0);
123            assert!(anomaly.likelihood <= 1.0);
124            assert!(anomaly.anomaly_strength >= 0.0);
125            assert!(anomaly.anomaly_strength <= 1.0);
126        }
127    }
128
129    #[test]
130    fn test_module_integration() {
131        // Test that all modules work together
132        let mut tree = ContextTree::new(2).expect("Failed to create context tree");
133        let sequence = vec!["A".to_string(), "B".to_string(), "C".to_string()];
134        let config = AnomalyGridConfig::default();
135
136        assert!(tree.build_from_sequence(&sequence, &config).is_ok());
137        assert!(tree.context_count() > 0);
138
139        let mut model = MarkovModel::new(2).expect("Failed to create Markov model");
140        assert!(model.train(&sequence).is_ok());
141
142        let likelihood = model.calculate_likelihood(&sequence);
143        assert!(likelihood > 0.0);
144        assert!(likelihood <= 1.0);
145
146        let mut detector = AnomalyDetector::new(2).expect("Failed to create detector");
147        assert!(detector.train(&sequence).is_ok());
148
149        let anomalies = detector
150            .detect_anomalies(&sequence, 0.1)
151            .expect("Failed to detect anomalies");
152        // Normal sequence should have few anomalies
153        assert!(anomalies.len() <= 1);
154    }
155}
anomaly_grid/lib.rs

anomaly_grid/
lib.rs
