haagenti_sparse/lib.rs
1//! Sparse Attention Masks
2//!
3//! This module implements prompt-aware attention head masking to skip
4//! computation for heads that don't contribute to the output.
5//!
6//! # Key Insight
7//!
8//! Not all attention heads are equally important for every prompt. Portrait
9//! prompts activate face-focused heads while landscape prompts activate
10//! background/composition heads. By predicting which heads matter, we can
11//! skip 50-70% of attention computation.
12//!
13//! # Architecture
14//!
15//! ```text
16//! ┌─────────────────────────────────────────────────────────────────┐
17//! │ Sparse Attention │
18//! ├─────────────────────────────────────────────────────────────────┤
19//! │ │
20//! │ Standard Attention (32 heads × 64 layers = 2048 computations) │
21//! │ ════════════════════════════════════════════════════════════ │
22//! │ [████████████████████████████████] 100% compute │
23//! │ │
24//! │ Sparse Attention (prompt-aware masking) │
25//! │ ════════════════════════════════════════════════════════════ │
26//! │ "Portrait of a woman" │
27//! │ [████████░░░░░░░░████░░░░░░░░░░░░] 35% compute │
28//! │ ↑ face ↑ skip ↑ style │
29//! │ │
30//! │ "Mountain landscape at sunset" │
31//! │ [░░░░░░░░████████████████████░░░░] 45% compute │
32//! │ ↑ skip ↑ background/lighting ↑ skip │
33//! └─────────────────────────────────────────────────────────────────┘
34//! ```
35
36mod analysis;
37mod categories;
38mod error;
39mod kernel;
40mod mask;
41mod predictor;
42
43pub use analysis::{HeadAnalysis, HeadImportance, ImportanceAnalyzer, ImportanceStats};
44pub use categories::{CategoryMapping, HeadCategory, PromptCategory};
45pub use error::{Result, SparseError};
46pub use kernel::{KernelConfig, KernelStats, SparseKernel};
47pub use mask::{AttentionMask, MaskBuilder, MaskPattern};
48pub use predictor::{MaskPredictor, Prediction, PredictorConfig};
49
50/// Default sparsity target (fraction of heads to skip)
51pub const DEFAULT_SPARSITY: f32 = 0.5;
52
53/// Minimum heads to keep active per layer
54pub const MIN_ACTIVE_HEADS: usize = 4;
55
56/// Maximum quality degradation allowed
57pub const MAX_QUALITY_LOSS: f32 = 0.02;
58
59/// Prelude for common imports
60pub mod prelude {
61 pub use super::{AttentionMask, HeadCategory, MaskPredictor, PromptCategory, Result};
62}