1use anyhow::Result;
17use serde::{Deserialize, Serialize};
18use std::collections::HashMap;
19use std::path::Path;
20use tch::{Kind, Tensor};
21use tracing::{info, warn};
22
23use crate::runtime::model_config::ModelConfig;
24
25#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
30pub enum LayerType {
31 FullAttention,
32 GatedDeltaNet,
33 StandardAttention,
34}
35
36#[derive(Debug, Clone, Serialize, Deserialize)]
37pub struct LayerAnalysis {
38 pub layer_idx: usize,
39 pub layer_type: LayerType,
40 pub perplexity_delta: Option<f64>,
42 pub recommended_rank: usize,
43 pub target_modules: Vec<String>,
44}
45
46#[derive(Debug, Clone, Serialize, Deserialize)]
47pub struct LayerProfile {
48 pub model_id: String,
49 pub num_layers: usize,
50 pub hidden_size: usize,
51 pub baseline_perplexity: Option<f64>,
52 pub layers: Vec<LayerAnalysis>,
53 pub computed_at: Option<String>,
55}
56
57pub fn qwen3_5_0_8b_profile() -> LayerProfile {
67 let attn_layers = [
72 (23usize, Some(8.40f64), 32usize),
73 (3usize, Some(5.62f64), 24usize),
74 (19usize, Some(4.39f64), 16usize),
75 (15usize, Some(3.22f64), 16usize),
76 (7usize, Some(2.16f64), 8usize),
77 (11usize, Some(1.13f64), 8usize),
78 ];
79 let attn_set: std::collections::HashSet<usize> = attn_layers.iter().map(|(i, ..)| *i).collect();
80
81 let mut layers: Vec<LayerAnalysis> = Vec::with_capacity(24);
82
83 for (idx, ppl_delta, rank) in &attn_layers {
85 layers.push(LayerAnalysis {
86 layer_idx: *idx,
87 layer_type: LayerType::FullAttention,
88 perplexity_delta: *ppl_delta,
89 recommended_rank: *rank,
90 target_modules: vec![
91 "q_proj".to_owned(),
92 "v_proj".to_owned(),
93 "o_proj".to_owned(),
94 ],
95 });
96 }
97
98 for idx in 0..24usize {
100 if !attn_set.contains(&idx) {
101 layers.push(LayerAnalysis {
102 layer_idx: idx,
103 layer_type: LayerType::GatedDeltaNet,
104 perplexity_delta: None,
105 recommended_rank: GDN_LORA_RANK,
106 target_modules: vec!["o_proj".to_owned()],
107 });
108 }
109 }
110
111 layers.sort_by_key(|l| l.layer_idx);
112
113 LayerProfile {
114 model_id: "Qwen/Qwen3.5-0.8B".to_owned(),
115 num_layers: 24,
116 hidden_size: 1024,
117 baseline_perplexity: Some(29.54),
118 layers,
119 computed_at: None,
120 }
121}
122
123pub fn find_embedded_profile(
129 model_type: &str,
130 num_layers: usize,
131 hidden_size: usize,
132) -> Option<LayerProfile> {
133 let normalized = model_type.to_lowercase();
134 let normalized = normalized.as_str();
135 let known_family = matches!(normalized, "qwen3_5" | "qwen3.5" | "qwen3_5_text");
136 match (normalized, num_layers, hidden_size) {
137 ("qwen3_5" | "qwen3.5" | "qwen3_5_text", 24, 1024) => Some(qwen3_5_0_8b_profile()),
138 _ => {
139 if known_family {
140 warn!(
141 model_type,
142 num_layers,
143 hidden_size,
144 "Known model family but unexpected geometry — no embedded \
145 rank profile matches; falling through to unvalidated \
146 allocation"
147 );
148 }
149 None
150 }
151 }
152}
153
154const ANALYSIS_DIR: &str = ".analysis";
159const PROFILE_FILE: &str = "layer_profile.json";
160
161pub fn load_cached_profile(model_path: &Path) -> Option<LayerProfile> {
163 let path = model_path.join(ANALYSIS_DIR).join(PROFILE_FILE);
164 let content = std::fs::read_to_string(&path).ok()?;
165 serde_json::from_str(&content).ok()
166}
167
168pub fn save_cached_profile(model_path: &Path, profile: &LayerProfile) -> Result<()> {
170 let dir = model_path.join(ANALYSIS_DIR);
171 std::fs::create_dir_all(&dir)?;
172 let content = serde_json::to_string_pretty(profile)?;
173 let tmp = dir.join(format!("{PROFILE_FILE}.tmp.{}", std::process::id()));
174 std::fs::write(&tmp, &content)?;
175 std::fs::rename(&tmp, dir.join(PROFILE_FILE))?; Ok(())
177}
178
179fn entropy_of_nonneg(s: &Tensor) -> f64 {
188 let total: f64 = s.sum(Kind::Double).double_value(&[]);
189 if total < 1e-30 {
190 return 0.0;
191 }
192 let p = s / total;
193 let mask = p.gt(1e-30);
194 let p_valid = p.masked_select(&mask);
195 -(&p_valid * p_valid.log())
196 .sum(Kind::Double)
197 .double_value(&[])
198}
199
200const UNVALIDATED_RANK_CAP: usize = 8;
205
206const GDN_LORA_RANK: usize = 4;
212
213fn detect_layer_type(
220 config: &ModelConfig,
221 layer_idx: usize,
222 weights: &HashMap<String, Tensor>,
223 prefix: &str,
224) -> LayerType {
225 if let Some(lt) = config.layer_types.get(layer_idx) {
227 return match lt.as_str() {
228 "linear_attention" => LayerType::GatedDeltaNet,
229 "full_attention" | "global" | "sliding_window" => LayerType::FullAttention,
230 _ => LayerType::StandardAttention,
231 };
232 }
233
234 let gdn_key = format!("{prefix}.linear_attn.out_proj.weight");
236 if weights.contains_key(&gdn_key) {
237 return LayerType::GatedDeltaNet;
238 }
239 let attn_key = format!("{prefix}.self_attn.q_proj.weight");
240 if weights.contains_key(&attn_key) {
241 return LayerType::FullAttention;
242 }
243
244 LayerType::StandardAttention
245}
246
247pub fn compute_layer_profile(
254 weights: &HashMap<String, Tensor>,
255 config: &ModelConfig,
256 model_path: &Path,
257) -> Result<LayerProfile> {
258 let _guard = tch::no_grad_guard();
259 info!(
260 "Computing TTN layer profile for {} ({} layers)...",
261 config.model_type, config.num_hidden_layers
262 );
263
264 let prefix_base = if weights
267 .keys()
268 .any(|k| k.starts_with("model.language_model."))
269 {
270 "model.language_model.layers"
271 } else {
272 "model.layers"
273 };
274
275 let mut layers = Vec::new();
276
277 for layer_idx in 0..config.num_hidden_layers {
278 let prefix = format!("{prefix_base}.{layer_idx}");
279
280 let layer_type = detect_layer_type(config, layer_idx, weights, &prefix);
281
282 let recommended_rank = if layer_type == LayerType::GatedDeltaNet {
292 GDN_LORA_RANK
293 } else {
294 UNVALIDATED_RANK_CAP
295 };
296
297 let target_modules = match layer_type {
299 LayerType::FullAttention => {
300 vec![
301 "q_proj".to_owned(),
302 "v_proj".to_owned(),
303 "o_proj".to_owned(),
304 ]
305 }
306 LayerType::GatedDeltaNet => vec!["o_proj".to_owned()],
307 LayerType::StandardAttention => {
308 vec!["q_proj".to_owned(), "v_proj".to_owned()]
309 }
310 };
311
312 layers.push(LayerAnalysis {
313 layer_idx,
314 layer_type,
315 perplexity_delta: None,
316 recommended_rank,
317 target_modules,
318 });
319 }
320
321 let profile = LayerProfile {
322 model_id: config.model_type.clone(),
323 num_layers: config.num_hidden_layers,
324 hidden_size: config.hidden_size,
325 baseline_perplexity: None,
326 layers,
327 computed_at: Some(chrono::Utc::now().to_rfc3339()),
328 };
329
330 if let Err(e) = save_cached_profile(model_path, &profile) {
332 warn!("Failed to cache layer profile: {e}");
333 }
334
335 info!(
336 "TTN profile computed: {} layers analyzed",
337 profile.layers.len()
338 );
339 Ok(profile)
340}
341
342fn uniform_fallback_profile(config: &ModelConfig) -> LayerProfile {
348 let layers = (0..config.num_hidden_layers)
349 .map(|layer_idx| LayerAnalysis {
350 layer_idx,
351 layer_type: LayerType::StandardAttention,
352 perplexity_delta: None,
353 recommended_rank: UNVALIDATED_RANK_CAP, target_modules: vec!["o_proj".to_owned()],
355 })
356 .collect();
357
358 LayerProfile {
359 model_id: config.model_type.clone(),
360 num_layers: config.num_hidden_layers,
361 hidden_size: config.hidden_size,
362 baseline_perplexity: None,
363 layers,
364 computed_at: None,
365 }
366}
367
368pub fn get_layer_profile(
381 model_path: &Path,
382 config: &ModelConfig,
383 weights: Option<&HashMap<String, Tensor>>,
384) -> Result<LayerProfile> {
385 if let Some(profile) = find_embedded_profile(
387 &config.model_type,
388 config.num_hidden_layers,
389 config.hidden_size,
390 ) {
391 info!(
392 "Using embedded TTN profile for {} ({} layers)",
393 config.model_type, config.num_hidden_layers
394 );
395 return Ok(profile);
396 }
397
398 if let Some(mut profile) = load_cached_profile(model_path) {
400 info!("Loaded cached TTN profile from {}", model_path.display());
401 for layer in &mut profile.layers {
405 if layer.recommended_rank > UNVALIDATED_RANK_CAP {
406 warn!(
407 layer_idx = layer.layer_idx,
408 cached_rank = layer.recommended_rank,
409 "Cached profile exceeds the unvalidated-rank cap; clamping"
410 );
411 layer.recommended_rank = UNVALIDATED_RANK_CAP;
412 }
413 }
414 return Ok(profile);
415 }
416
417 if let Some(weights) = weights {
419 warn!(
420 model_type = %config.model_type,
421 rank_cap = UNVALIDATED_RANK_CAP,
422 "Unknown model — Tier 3 entropy-based rank allocation is unvalidated \
423 (no embedded ablation data). A conservative rank cap is applied until \
424 the mapping is validated against ablation ground truth. Consider \
425 contributing an embedded profile."
426 );
427 info!("Computing TTN profile for new model (one-time analysis)...");
428 return compute_layer_profile(weights, config, model_path);
429 }
430
431 warn!("No weights available for TTN analysis, using uniform profile");
433 Ok(uniform_fallback_profile(config))
434}
435
436pub fn delta_rank_utilization(lora_a: &Tensor, lora_b: &Tensor) -> f64 {
453 let _guard = tch::no_grad_guard();
454 let _ = lora_a; let gram = lora_b.tr().matmul(lora_b);
458 let (_, s, _) = gram.svd(true, false); let max_entropy = (s.size()[0] as f64).ln();
460 if max_entropy < 1e-10 {
461 return 0.0;
462 }
463 entropy_of_nonneg(&s) / max_entropy
465}
466
467pub fn attention_entropy(attn_weights: &Tensor) -> Tensor {
477 let _guard = tch::no_grad_guard();
478 let eps = 1e-10f64;
479 let p = attn_weights.clamp_min(eps);
480 -(&p * p.log()).sum_dim_intlist(&[-1i64][..], false, None)
481}
482
483pub fn attention_sparsity(attn_weights: &Tensor, top_k: i64) -> Tensor {
489 let _guard = tch::no_grad_guard();
490 let (top_vals, _) = attn_weights.topk(top_k, -1, true, false);
491 top_vals.sum_dim_intlist(&[-1i64][..], false, None)
492}
493
494#[derive(Debug, Clone)]
503pub struct RankUtilizationTracker {
504 window_size: usize,
505 history: HashMap<String, std::collections::VecDeque<f64>>,
506}
507
508#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
510pub enum RankSignal {
511 Increase,
512 Decrease,
513 Hold,
514}
515
516#[derive(Debug, Clone)]
518pub struct UtilizationSummary {
519 pub mean: f64,
520 pub min: f64,
521 pub max: f64,
522 pub count: usize,
523}
524
525impl RankUtilizationTracker {
526 pub fn new(window_size: usize) -> Self {
527 Self {
528 window_size,
529 history: HashMap::new(),
530 }
531 }
532
533 pub fn record(&mut self, key: &str, utilization: f64) {
534 let entry = self.history.entry(key.to_owned()).or_default();
535 entry.push_back(utilization);
536 while entry.len() > self.window_size {
537 entry.pop_front();
538 }
539 }
540
541 pub fn summary(&self, key: &str) -> Option<UtilizationSummary> {
542 let h = self.history.get(key)?;
543 if h.is_empty() {
544 return None;
545 }
546 let count = h.len();
547 let sum: f64 = h.iter().sum();
548 let min = h.iter().copied().fold(f64::MAX, f64::min);
549 let max = h.iter().copied().fold(f64::MIN, f64::max);
550 Some(UtilizationSummary {
551 mean: sum / count as f64,
552 min,
553 max,
554 count,
555 })
556 }
557
558 pub fn rank_adaptation_signals(
559 &self,
560 low_threshold: f64,
561 high_threshold: f64,
562 ) -> HashMap<String, RankSignal> {
563 self.history
564 .keys()
565 .filter_map(|key| {
566 let s = self.summary(key)?;
567 let signal = if s.mean < low_threshold {
568 RankSignal::Decrease
569 } else if s.mean > high_threshold {
570 RankSignal::Increase
571 } else {
572 RankSignal::Hold
573 };
574 Some((key.clone(), signal))
575 })
576 .collect()
577 }
578}
579
580#[cfg(test)]
581#[allow(clippy::expect_used, clippy::unwrap_used)]
582mod tests {
583 use super::*;
584
585 #[test]
586 fn test_qwen3_5_profile_structure() {
587 let profile = qwen3_5_0_8b_profile();
588 assert_eq!(profile.num_layers, 24);
589 assert_eq!(profile.layers.len(), 24);
590
591 let attn_23 = profile
593 .layers
594 .iter()
595 .find(|l| l.layer_idx == 23)
596 .expect("layer 23 should exist");
597 assert_eq!(attn_23.recommended_rank, 32);
598 assert_eq!(attn_23.layer_type, LayerType::FullAttention);
599 assert_eq!(attn_23.perplexity_delta, Some(8.40));
600
601 let gdn_0 = profile
602 .layers
603 .iter()
604 .find(|l| l.layer_idx == 0)
605 .expect("layer 0 should exist");
606 assert_eq!(gdn_0.recommended_rank, GDN_LORA_RANK);
607 assert_eq!(gdn_0.layer_type, LayerType::GatedDeltaNet);
608 }
609
610 #[test]
611 fn test_find_embedded_profile() {
612 assert!(find_embedded_profile("qwen3_5", 24, 1024).is_some());
613 assert!(find_embedded_profile("qwen3.5", 24, 1024).is_some());
614 assert!(find_embedded_profile("llama", 32, 4096).is_none());
615 assert!(find_embedded_profile("qwen3_5", 32, 4096).is_none()); }
617
618 #[test]
619 fn test_tier3_synthetic_profile_golden() {
620 let _guard = tch::no_grad_guard();
621 tch::manual_seed(42);
622 let dir = tempfile::tempdir().expect("tempdir");
623
624 let config = ModelConfig {
625 model_type: "synthetic_test".to_owned(),
626 num_hidden_layers: 2,
627 hidden_size: 64,
628 ..Default::default()
629 };
630
631 let mut weights: HashMap<String, Tensor> = HashMap::new();
633 weights.insert(
634 "model.layers.0.linear_attn.out_proj.weight".to_owned(),
635 Tensor::randn([64, 64], (Kind::Float, tch::Device::Cpu)),
636 );
637 for proj in ["q_proj", "k_proj", "v_proj", "o_proj"] {
638 weights.insert(
639 format!("model.layers.1.self_attn.{proj}.weight"),
640 Tensor::randn([64, 64], (Kind::Float, tch::Device::Cpu)),
641 );
642 }
643
644 let profile = compute_layer_profile(&weights, &config, dir.path()).expect("profile");
645 assert_eq!(profile.layers.len(), 2);
646
647 let gdn = &profile.layers[0];
648 assert_eq!(gdn.layer_type, LayerType::GatedDeltaNet);
649 assert_eq!(gdn.recommended_rank, GDN_LORA_RANK);
650
651 let attn = &profile.layers[1];
652 assert_eq!(attn.layer_type, LayerType::FullAttention);
653 assert_eq!(
654 attn.recommended_rank, UNVALIDATED_RANK_CAP,
655 "unprofiled attention layers get the flat unvalidated cap"
656 );
657
658 assert!(load_cached_profile(dir.path()).is_some());
660 }
661
662 #[test]
663 fn test_cached_profile_rank_is_capped_on_load() {
664 let dir = tempfile::tempdir().expect("tempdir");
665 let config = ModelConfig {
666 model_type: "synthetic_test".to_owned(),
667 num_hidden_layers: 1,
668 hidden_size: 64,
669 ..Default::default()
670 };
671
672 let mut profile = uniform_fallback_profile(&config);
674 profile.layers[0].recommended_rank = 32;
675 save_cached_profile(dir.path(), &profile).expect("save");
676
677 let loaded = get_layer_profile(dir.path(), &config, None).expect("load");
679 assert_eq!(loaded.layers[0].recommended_rank, UNVALIDATED_RANK_CAP);
680 }
681
682 #[test]
683 fn test_delta_rank_utilization() {
684 let _guard = tch::no_grad_guard();
685 let rank = 8i64;
686 let in_f = 64i64;
687 let out_f = 64i64;
688
689 let a = Tensor::randn([rank, in_f], (Kind::Float, tch::Device::Cpu));
690 let b = Tensor::zeros([out_f, rank], (Kind::Float, tch::Device::Cpu));
691 let util = delta_rank_utilization(&a, &b);
693 assert_eq!(util, 0.0);
694 }
695
696 #[test]
699 fn test_utilization_tracker_records() {
700 let mut tracker = RankUtilizationTracker::new(5);
701 tracker.record("0.q_proj", 0.3);
702 tracker.record("0.q_proj", 0.5);
703 let summary = tracker.summary("0.q_proj");
704 assert!(summary.is_some());
705 let s = summary.unwrap();
706 assert_eq!(s.count, 2);
707 assert!((s.mean - 0.4).abs() < 1e-9);
708 }
709
710 #[test]
711 fn test_utilization_tracker_window() {
712 let mut tracker = RankUtilizationTracker::new(3);
713 tracker.record("k", 0.1);
714 tracker.record("k", 0.2);
715 tracker.record("k", 0.3);
716 tracker.record("k", 0.9); let s = tracker.summary("k").unwrap();
718 assert_eq!(s.count, 3);
719 assert!((s.mean - 0.4667).abs() < 0.01);
721 }
722
723 #[test]
724 fn test_utilization_tracker_rank_signals() {
725 let mut tracker = RankUtilizationTracker::new(10);
726 for _ in 0..5 {
727 tracker.record("low", 0.15);
728 }
729 for _ in 0..5 {
730 tracker.record("high", 0.95);
731 }
732 for _ in 0..5 {
733 tracker.record("ok", 0.5);
734 }
735
736 let signals = tracker.rank_adaptation_signals(0.25, 0.85);
737 assert_eq!(signals.get("low"), Some(&RankSignal::Decrease));
738 assert_eq!(signals.get("high"), Some(&RankSignal::Increase));
739 assert_eq!(signals.get("ok"), Some(&RankSignal::Hold));
740 }
741
742 #[test]
743 fn test_utilization_tracker_empty_key() {
744 let tracker = RankUtilizationTracker::new(5);
745 assert!(tracker.summary("nonexistent").is_none());
746 }
747}