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 context_trie;
65pub mod error;
66pub mod markov_model;
67pub mod memory_pool;
68pub mod performance;
69pub mod string_interner;
70pub mod transition_counts;
71pub mod validation;
72
73// Re-export main types for convenience
74pub use anomaly_detector::{batch_process_sequences, AnomalyDetector, AnomalyScore};
75pub use config::AnomalyGridConfig;
76pub use context_tree::{ContextNode, ContextTree};
77pub use error::{AnomalyGridError, AnomalyGridResult};
78pub use markov_model::MarkovModel;
79pub use performance::{
80    optimize_context_tree, ContextStatistics, OptimizationConfig, PerformanceMetrics,
81};
82
83/// Library version
84pub const VERSION: &str = env!("CARGO_PKG_VERSION");
85
86/// Get library information
87pub fn info() -> String {
88    format!("Anomaly Grid v{VERSION} - Markov Chain-based Sequence Anomaly Detection")
89}
90
91#[cfg(test)]
92mod tests {
93    use super::*;
94
95    #[test]
96    fn test_library_info() {
97        let info = info();
98        assert!(info.contains("Anomaly Grid"));
99        assert!(info.contains(VERSION));
100    }
101
102    #[test]
103    fn test_basic_workflow() {
104        let mut detector = AnomalyDetector::new(2).expect("Failed to create detector");
105        let sequence = vec![
106            "A".to_string(),
107            "B".to_string(),
108            "A".to_string(),
109            "B".to_string(),
110        ];
111
112        // Training should succeed
113        assert!(detector.train(&sequence).is_ok());
114
115        // Detection should work
116        let test_sequence = vec!["A".to_string(), "X".to_string(), "Y".to_string()];
117        let anomalies = detector
118            .detect_anomalies(&test_sequence, 0.5)
119            .expect("Failed to detect anomalies");
120
121        // Should detect some anomalies or handle gracefully
122        for anomaly in anomalies {
123            assert!(anomaly.likelihood >= 0.0);
124            assert!(anomaly.likelihood <= 1.0);
125            assert!(anomaly.anomaly_strength >= 0.0);
126            assert!(anomaly.anomaly_strength <= 1.0);
127        }
128    }
129
130    #[test]
131    fn test_module_integration() {
132        // Test that all modules work together
133        let mut tree = ContextTree::new(2).expect("Failed to create context tree");
134        let sequence = vec!["A".to_string(), "B".to_string(), "C".to_string()];
135        let config = AnomalyGridConfig::default();
136
137        assert!(tree.build_from_sequence(&sequence, &config).is_ok());
138        assert!(tree.context_count() > 0);
139
140        let mut model = MarkovModel::new(2).expect("Failed to create Markov model");
141        assert!(model.train(&sequence).is_ok());
142
143        let likelihood = model.calculate_likelihood(&sequence);
144        assert!(likelihood > 0.0);
145        assert!(likelihood <= 1.0);
146
147        let mut detector = AnomalyDetector::new(2).expect("Failed to create detector");
148        assert!(detector.train(&sequence).is_ok());
149
150        let anomalies = detector
151            .detect_anomalies(&sequence, 0.1)
152            .expect("Failed to detect anomalies");
153        // Normal sequence should have few anomalies
154        assert!(anomalies.len() <= 1);
155    }
156}
anomaly_grid/lib.rs

anomaly_grid/
lib.rs
