1use std::collections::HashMap;
32use std::path::PathBuf;
33
34use super::context_detector::ContextType;
35
36#[derive(Debug, Clone, PartialEq, Eq)]
39pub enum LoRAError {
40 Io(String),
41 InvalidHeader,
42 InvalidMagic,
43 ChecksumMismatch,
44 DimensionMismatch {
45 expected: (usize, usize),
46 got: (usize, usize),
47 },
48 AdapterNotFound(ContextType),
49 InferenceDimMismatch {
50 input_len: usize,
51 lora_n_in: usize,
52 },
53}
54
55impl std::fmt::Display for LoRAError {
56 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
57 match self {
58 LoRAError::Io(e) => write!(f, "LoRA I/O error: {e}"),
59 LoRAError::InvalidHeader => write!(f, "LoRA header too short"),
60 LoRAError::InvalidMagic => write!(f, "LoRA bad magic (expected LORA)"),
61 LoRAError::ChecksumMismatch => write!(f, "LoRA checksum mismatch"),
62 LoRAError::DimensionMismatch { expected, got } => write!(
63 f,
64 "LoRA dimension mismatch: expected {expected:?}, got {got:?}"
65 ),
66 LoRAError::AdapterNotFound(ctx) => write!(f, "LoRA adapter not found for {ctx}"),
67 LoRAError::InferenceDimMismatch {
68 input_len,
69 lora_n_in,
70 } => write!(
71 f,
72 "LoRA inference: input len {input_len} ≠ lora n_in {lora_n_in}"
73 ),
74 }
75 }
76}
77
78impl std::error::Error for LoRAError {}
79
80#[derive(Clone)]
86pub struct LoRATensor {
87 pub data: Box<[f32]>,
88 pub rows: usize,
89 pub cols: usize,
90}
91
92impl LoRATensor {
93 pub fn new(data: Box<[f32]>, rows: usize, cols: usize) -> Self {
95 assert_eq!(data.len(), rows * cols, "LoRATensor data length mismatch");
96 Self { data, rows, cols }
97 }
98
99 #[inline]
102 pub fn matvec_add(&self, x: &[f32], out: &mut [f32]) {
103 debug_assert_eq!(x.len(), self.cols);
104 debug_assert_eq!(out.len(), self.rows);
105 for i in 0..self.rows {
106 let row = &self.data[i * self.cols..(i + 1) * self.cols];
107 let mut acc = 0f32;
108 for (a, b) in row.iter().zip(x.iter()) {
109 acc += a * b;
110 }
111 out[i] += acc;
112 }
113 }
114}
115
116impl std::fmt::Debug for LoRATensor {
117 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
118 write!(f, "LoRATensor({}×{})", self.rows, self.cols)
119 }
120}
121
122#[derive(Debug, Clone)]
125pub struct LoRAMetadata {
126 pub name: String,
127 pub version: String,
128 pub adapter_id: u8,
129 pub rank: u32,
130 pub alpha: f32,
131 pub n_in: usize,
132 pub n_out: usize,
133 pub checksum: [u8; 32],
134 pub file_size: usize,
135}
136
137impl LoRAMetadata {
138 #[inline]
140 pub fn scaling(&self) -> f32 {
141 self.alpha / self.rank.max(1) as f32
142 }
143}
144
145#[derive(Debug, Clone)]
149pub struct LoRAAdapter {
150 pub context_type: ContextType,
151 pub meta: LoRAMetadata,
152 pub lora_a: LoRATensor,
154 pub lora_b: LoRATensor,
156}
157
158impl LoRAAdapter {
159 pub fn apply_cpu_buffered(
167 &self,
168 input: &[f32],
169 output: &mut [f32],
170 rank_scratch: &mut [f32],
171 ) -> Result<(), LoRAError> {
172 let n_in = self.meta.n_in;
173 let n_out = self.meta.n_out;
174 let rank = self.meta.rank as usize;
175
176 if input.len() != n_in {
177 return Err(LoRAError::InferenceDimMismatch {
178 input_len: input.len(),
179 lora_n_in: n_in,
180 });
181 }
182 if rank_scratch.len() < rank {
183 return Err(LoRAError::InferenceDimMismatch {
184 input_len: rank_scratch.len(),
185 lora_n_in: rank,
186 });
187 }
188
189 rank_scratch[..rank].fill(0f32);
191 self.lora_a.matvec_add(input, &mut rank_scratch[..rank]);
192
193 let scaling = self.meta.scaling();
195 for i in 0..n_out {
196 let row = &self.lora_b.data[i * rank..(i + 1) * rank];
197 let mut acc = 0f32;
198 for (bval, zval) in row.iter().zip(rank_scratch[..rank].iter()) {
199 acc += bval * zval;
200 }
201 output[i] += acc * scaling;
202 }
203
204 Ok(())
205 }
206
207 pub fn apply_cpu(&self, input: &[f32], output: &mut [f32]) -> Result<(), LoRAError> {
212 let rank = self.meta.rank as usize;
213 let mut z = vec![0f32; rank];
214 self.apply_cpu_buffered(input, output, &mut z)
215 }
216
217 pub fn compute_delta(&self, input: &[f32]) -> Result<Vec<f32>, LoRAError> {
220 let mut delta = vec![0f32; self.meta.n_out];
221 let mut output_ref = vec![0f32; self.meta.n_out];
222 self.apply_cpu(input, &mut output_ref)?;
223 delta.copy_from_slice(&output_ref);
224 Ok(delta)
225 }
226}
227
228const HEADER_SIZE: usize = 64;
231const MAGIC: [u8; 4] = *b"LORA";
232
233#[repr(C, packed)]
234struct RawHeader {
235 magic: [u8; 4],
236 version: u32,
237 adapter_id: u8,
238 _pad0: [u8; 3],
239 rank: u32,
240 alpha_bits: u32, n_in: u32,
242 n_out: u32,
243 _pad1: u32,
244 checksum: [u8; 32],
245}
246
247const _: () = assert!(std::mem::size_of::<RawHeader>() == HEADER_SIZE);
248
249fn parse_adapter(data: &[u8], context_type: ContextType) -> Result<LoRAAdapter, LoRAError> {
252 if data.len() < HEADER_SIZE {
253 return Err(LoRAError::InvalidHeader);
254 }
255
256 let hdr: RawHeader = unsafe { std::ptr::read_unaligned(data.as_ptr() as *const RawHeader) };
258
259 if hdr.magic != MAGIC {
260 return Err(LoRAError::InvalidMagic);
261 }
262
263 let rank = u32::from_le(hdr.rank) as usize;
264 let alpha = f32::from_bits(u32::from_le(hdr.alpha_bits));
265 let n_in = u32::from_le(hdr.n_in) as usize;
266 let n_out = u32::from_le(hdr.n_out) as usize;
267
268 let a_elems = rank * n_in;
269 let b_elems = n_out * rank;
270 let payload_bytes = (a_elems + b_elems) * 4;
271
272 if data.len() < HEADER_SIZE + payload_bytes {
273 return Err(LoRAError::DimensionMismatch {
274 expected: (a_elems + b_elems, 4),
275 got: (data.len().saturating_sub(HEADER_SIZE), 4),
276 });
277 }
278
279 let payload = &data[HEADER_SIZE..HEADER_SIZE + payload_bytes];
280
281 let expected = hdr.checksum;
283 let actual = sha256(payload);
284 if actual != expected {
285 return Err(LoRAError::ChecksumMismatch);
286 }
287
288 let a_bytes = &payload[..a_elems * 4];
289 let b_bytes = &payload[a_elems * 4..a_elems * 4 + b_elems * 4];
290
291 let lora_a = LoRATensor::new(f32_slice_from_le_bytes(a_bytes), rank, n_in);
292 let lora_b = LoRATensor::new(f32_slice_from_le_bytes(b_bytes), n_out, rank);
293
294 Ok(LoRAAdapter {
295 context_type,
296 meta: LoRAMetadata {
297 name: format!("{}", context_type),
298 version: format!("{}", u32::from_le(hdr.version)),
299 adapter_id: hdr.adapter_id,
300 rank: rank as u32,
301 alpha,
302 n_in,
303 n_out,
304 checksum: expected,
305 file_size: data.len(),
306 },
307 lora_a,
308 lora_b,
309 })
310}
311
312#[inline]
313fn f32_slice_from_le_bytes(bytes: &[u8]) -> Box<[f32]> {
314 bytes
315 .chunks_exact(4)
316 .map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]]))
317 .collect::<Vec<_>>()
318 .into_boxed_slice()
319}
320
321fn sha256(data: &[u8]) -> [u8; 32] {
322 use sha2::{Digest, Sha256};
323 let mut h = Sha256::new();
324 h.update(data);
325 let result = h.finalize();
326 let mut out = [0u8; 32];
327 out.copy_from_slice(&result);
328 out
329}
330
331pub fn encode_adapter(
334 context_type: ContextType,
335 adapter_id: u8,
336 rank: u32,
337 alpha: f32,
338 lora_a: &LoRATensor, lora_b: &LoRATensor, ) -> Vec<u8> {
341 let n_in = lora_a.cols;
342 let n_out = lora_b.rows;
343
344 let a_bytes: Vec<u8> = lora_a.data.iter().flat_map(|&f| f.to_le_bytes()).collect();
345 let b_bytes: Vec<u8> = lora_b.data.iter().flat_map(|&f| f.to_le_bytes()).collect();
346 let mut payload = a_bytes;
347 payload.extend_from_slice(&b_bytes);
348 let checksum = sha256(&payload);
349
350 let _ = context_type; let mut hdr = [0u8; HEADER_SIZE];
352 hdr[0..4].copy_from_slice(&MAGIC);
353 hdr[4..8].copy_from_slice(&1u32.to_le_bytes()); hdr[8] = adapter_id;
355 hdr[12..16].copy_from_slice(&(rank as u32).to_le_bytes());
356 hdr[16..20].copy_from_slice(&alpha.to_bits().to_le_bytes());
357 hdr[20..24].copy_from_slice(&(n_in as u32).to_le_bytes());
358 hdr[24..28].copy_from_slice(&(n_out as u32).to_le_bytes());
359 hdr[32..64].copy_from_slice(&checksum);
360
361 let mut out = hdr.to_vec();
362 out.extend_from_slice(&payload);
363 out
364}
365
366struct LruCache<K, V> {
369 cap: usize,
370 store: HashMap<K, (V, u64)>,
371 clock: u64,
372}
373
374impl<K: Eq + std::hash::Hash + Clone, V: Clone> LruCache<K, V> {
375 fn new(cap: usize) -> Self {
376 Self {
377 cap: cap.max(1),
378 store: HashMap::new(),
379 clock: 0,
380 }
381 }
382
383 fn get(&mut self, key: &K) -> Option<&V> {
384 if let Some(entry) = self.store.get_mut(key) {
385 self.clock += 1;
386 entry.1 = self.clock;
387 Some(unsafe { &*((&entry.0) as *const V) })
389 } else {
390 None
391 }
392 }
393
394 fn put(&mut self, key: K, val: V) {
395 self.clock += 1;
396 if self.store.len() >= self.cap && !self.store.contains_key(&key) {
397 let lru_key = self
399 .store
400 .iter()
401 .min_by_key(|(_, (_, ts))| ts)
402 .map(|(k, _)| k.clone());
403 if let Some(k) = lru_key {
404 self.store.remove(&k);
405 }
406 }
407 self.store.insert(key, (val, self.clock));
408 }
409
410 fn contains(&self, key: &K) -> bool {
411 self.store.contains_key(key)
412 }
413}
414
415pub struct LoRAAdapterManager {
424 adapter_dir: PathBuf,
425 cache: LruCache<ContextType, LoRAAdapter>,
426 active_adapter: Option<LoRAAdapter>,
427 pub detector: super::context_detector::ContextDetector,
428 pub expected_n_in: Option<usize>,
430 pub expected_n_out: Option<usize>,
432 active_adapter_by_hash: std::collections::HashMap<u64, u64>,
435}
436
437impl LoRAAdapterManager {
438 pub fn new(adapter_dir: impl Into<PathBuf>) -> Self {
443 Self {
444 adapter_dir: adapter_dir.into(),
445 cache: LruCache::new(10),
446 active_adapter: None,
447 detector: super::context_detector::ContextDetector::new(),
448 expected_n_in: None,
449 expected_n_out: None,
450 active_adapter_by_hash: std::collections::HashMap::new(),
451 }
452 }
453
454 pub fn default_path() -> PathBuf {
456 let home = std::env::var("HOME")
457 .or_else(|_| std::env::var("USERPROFILE"))
458 .unwrap_or_else(|_| ".".to_string());
459 PathBuf::from(home).join(".qualia").join("lora_adapters")
460 }
461
462 pub fn set_expected_dims(&mut self, n_in: usize, n_out: usize) {
465 self.expected_n_in = Some(n_in);
466 self.expected_n_out = Some(n_out);
467 }
468
469 pub fn detect_context(&self, prompt: &str) -> (ContextType, f32) {
475 self.detector.analyze_text(prompt)
476 }
477
478 pub fn active_adapter_for_hash(&self, content_hash: u64) -> Option<u64> {
481 self.active_adapter_by_hash.get(&content_hash).copied()
482 }
483
484 pub fn set_adapter_for_hash(&mut self, content_hash: u64, adapter_id: u64) {
486 self.active_adapter_by_hash.insert(content_hash, adapter_id);
487 }
488
489 pub fn clear_hash_associations(&mut self) {
491 self.active_adapter_by_hash.clear();
492 }
493
494 pub fn switch_to(&mut self, target: ContextType) -> Result<bool, LoRAError> {
500 if let Some(ref a) = self.active_adapter {
502 if a.context_type == target {
503 return Ok(false);
504 }
505 }
506
507 if self.cache.contains(&target) {
509 let adapter = self.cache.get(&target).unwrap().clone();
510 self.active_adapter = Some(adapter);
511 return Ok(true);
512 }
513
514 let adapter = self.load_from_disk(target)?;
516
517 if let Some(n_in) = self.expected_n_in {
519 if adapter.meta.n_in != n_in {
520 return Err(LoRAError::DimensionMismatch {
521 expected: (n_in, adapter.meta.n_out),
522 got: (adapter.meta.n_in, adapter.meta.n_out),
523 });
524 }
525 }
526
527 self.cache.put(target, adapter.clone());
528 self.active_adapter = Some(adapter);
529 Ok(true)
530 }
531
532 pub fn auto_switch(&mut self, prompt: &str, threshold: f32) -> (ContextType, f32, bool) {
536 let (ctx, conf) = self.detect_context(prompt);
537
538 if conf < threshold {
539 return (ContextType::General, conf, false);
540 }
541
542 let switched = self.switch_to(ctx).unwrap_or(false);
543 (ctx, conf, switched)
544 }
545
546 pub fn apply_active(&self, input: &[f32], output: &mut [f32]) -> Result<(), LoRAError> {
553 match &self.active_adapter {
554 Some(a) => a.apply_cpu(input, output),
555 None => Ok(()),
556 }
557 }
558
559 pub fn active(&self) -> Option<&LoRAAdapter> {
561 self.active_adapter.as_ref()
562 }
563
564 pub fn deactivate(&mut self) {
566 self.active_adapter = None;
567 }
568
569 fn adapter_path(&self, ctx: ContextType) -> PathBuf {
572 self.adapter_dir.join(ctx.adapter_filename())
573 }
574
575 fn load_from_disk(&self, ctx: ContextType) -> Result<LoRAAdapter, LoRAError> {
576 let path = self.adapter_path(ctx);
577
578 #[cfg(not(target_arch = "wasm32"))]
580 {
581 use std::fs::File;
582 let file =
583 File::open(&path).map_err(|e| LoRAError::Io(format!("{}: {e}", path.display())))?;
584 let mmap = unsafe { memmap2::MmapOptions::new().map(&file) }
585 .map_err(|e| LoRAError::Io(format!("mmap {}: {e}", path.display())))?;
586 parse_adapter(&mmap, ctx)
587 }
588
589 #[cfg(target_arch = "wasm32")]
590 {
591 let data = std::fs::read(&path)
592 .map_err(|e| LoRAError::Io(format!("{}: {e}", path.display())))?;
593 parse_adapter(&data, ctx)
594 }
595 }
596
597 pub fn available_adapters(&self) -> Vec<ContextType> {
599 ContextType::all()
600 .iter()
601 .filter(|&&ctx| self.adapter_path(ctx).exists())
602 .copied()
603 .collect()
604 }
605
606 pub fn save_adapter(
608 &self,
609 ctx: ContextType,
610 adapter: &LoRAAdapter,
611 ) -> Result<PathBuf, LoRAError> {
612 let path = self.adapter_path(ctx);
613 if let Some(parent) = path.parent() {
614 std::fs::create_dir_all(parent).map_err(|e| LoRAError::Io(e.to_string()))?;
615 }
616 let bytes = encode_adapter(
617 ctx,
618 adapter.meta.adapter_id,
619 adapter.meta.rank,
620 adapter.meta.alpha,
621 &adapter.lora_a,
622 &adapter.lora_b,
623 );
624 std::fs::write(&path, &bytes).map_err(|e| LoRAError::Io(e.to_string()))?;
625 Ok(path)
626 }
627
628 pub fn build_synthetic(
631 ctx: ContextType,
632 rank: u32,
633 alpha: f32,
634 n_in: usize,
635 n_out: usize,
636 adapter_id: u8,
637 ) -> LoRAAdapter {
638 let scale = (2.0 / n_in as f32).sqrt();
639 let seed_a: Box<[f32]> = (0..rank as usize * n_in)
641 .map(|i| {
642 let x = (i as u64)
644 .wrapping_mul(6364136223846793005)
645 .wrapping_add(1442695040888963407);
646 let frac = (x >> 32) as f32 / u32::MAX as f32; (frac * 2.0 - 1.0) * scale
648 })
649 .collect::<Vec<_>>()
650 .into_boxed_slice();
651
652 let seed_b = vec![0f32; n_out * rank as usize].into_boxed_slice();
653
654 let lora_a = LoRATensor::new(seed_a, rank as usize, n_in);
655 let lora_b = LoRATensor::new(seed_b, n_out, rank as usize);
656
657 LoRAAdapter {
658 context_type: ctx,
659 meta: LoRAMetadata {
660 name: ctx.to_string(),
661 version: "synthetic".to_string(),
662 adapter_id,
663 rank,
664 alpha,
665 n_in,
666 n_out,
667 checksum: [0u8; 32],
668 file_size: 0,
669 },
670 lora_a,
671 lora_b,
672 }
673 }
674}
675
676#[cfg(test)]
679mod tests {
680 use super::*;
681
682 fn make_adapter(rank: u32, n_in: usize, n_out: usize) -> LoRAAdapter {
683 LoRAAdapterManager::build_synthetic(
684 ContextType::Technical,
685 rank,
686 rank as f32,
687 n_in,
688 n_out,
689 5,
690 )
691 }
692
693 #[test]
694 fn test_apply_cpu_shape() {
695 let adapter = make_adapter(4, 16, 32);
696 let input = vec![1.0f32; 16];
697 let mut out = vec![0.0f32; 32];
698 adapter.apply_cpu(&input, &mut out).unwrap();
699 assert!(out.iter().all(|&v| v == 0.0));
701 }
702
703 #[test]
704 fn test_apply_cpu_nonzero() {
705 let rank = 2usize;
707 let n_in = 4;
708 let n_out = 4;
709 let lora_a = LoRATensor::new(vec![1.0; rank * n_in].into_boxed_slice(), rank, n_in);
710 let lora_b = LoRATensor::new(vec![1.0; n_out * rank].into_boxed_slice(), n_out, rank);
711 let adapter = LoRAAdapter {
712 context_type: ContextType::Technical,
713 meta: LoRAMetadata {
714 name: "test".into(),
715 version: "0".into(),
716 adapter_id: 0,
717 rank: rank as u32,
718 alpha: rank as f32,
719 n_in,
720 n_out,
721 checksum: [0; 32],
722 file_size: 0,
723 },
724 lora_a,
725 lora_b,
726 };
727 let input = vec![1.0f32; n_in];
728 let mut out = vec![0.0f32; n_out];
729 adapter.apply_cpu(&input, &mut out).unwrap();
730 for &v in &out {
736 assert!((v - 8.0).abs() < 1e-5, "expected 8.0, got {v}");
737 }
738 }
739
740 #[test]
741 fn test_roundtrip_encode_parse() {
742 let adapter = make_adapter(4, 8, 16);
743 let bytes = encode_adapter(
744 ContextType::Technical,
745 adapter.meta.adapter_id,
746 adapter.meta.rank,
747 adapter.meta.alpha,
748 &adapter.lora_a,
749 &adapter.lora_b,
750 );
751 let parsed = parse_adapter(&bytes, ContextType::Technical).unwrap();
752 assert_eq!(parsed.meta.rank, adapter.meta.rank);
753 assert_eq!(parsed.meta.n_in, adapter.meta.n_in);
754 assert_eq!(parsed.meta.n_out, adapter.meta.n_out);
755 assert_eq!(parsed.lora_a.data.len(), adapter.lora_a.data.len());
756 for (a, b) in parsed.lora_a.data.iter().zip(adapter.lora_a.data.iter()) {
757 assert!(
758 (a - b).abs() < 1e-6,
759 "A matrix roundtrip mismatch: {a} vs {b}"
760 );
761 }
762 }
763
764 #[test]
765 fn test_bad_magic_rejected() {
766 let mut bytes = encode_adapter(
767 ContextType::Medical,
768 0,
769 4,
770 1.0,
771 &LoRATensor::new(vec![0.0f32; 4].into_boxed_slice(), 1, 4),
772 &LoRATensor::new(vec![0.0f32; 4].into_boxed_slice(), 4, 1),
773 );
774 bytes[0] = b'X'; assert!(matches!(
776 parse_adapter(&bytes, ContextType::Medical),
777 Err(LoRAError::InvalidMagic)
778 ));
779 }
780
781 #[test]
782 fn test_checksum_corruption_detected() {
783 let mut bytes = encode_adapter(
792 ContextType::Medical,
793 0,
794 1,
795 1.0,
796 &LoRATensor::new(vec![0.0f32; 4].into_boxed_slice(), 1, 4),
797 &LoRATensor::new(vec![0.0f32; 4].into_boxed_slice(), 4, 1),
798 );
799 *bytes.last_mut().unwrap() ^= 0xFF;
801 assert!(matches!(
802 parse_adapter(&bytes, ContextType::Medical),
803 Err(LoRAError::ChecksumMismatch)
804 ));
805 }
806
807 #[test]
808 fn test_synthetic_output_zeroed_initially() {
809 let adapter =
810 LoRAAdapterManager::build_synthetic(ContextType::Biological, 8, 8.0, 32, 64, 4);
811 let input = vec![1.0f32; 32];
813 let mut out = vec![0.0f32; 64];
814 adapter.apply_cpu(&input, &mut out).unwrap();
815 assert!(out.iter().all(|&v| v == 0.0));
816 }
817
818 #[test]
819 fn test_lru_eviction() {
820 let mut cache: LruCache<u32, u32> = LruCache::new(3);
821 cache.put(1, 10);
822 cache.put(2, 20);
823 cache.put(3, 30);
824 let _ = cache.get(&1); cache.put(4, 40); assert!(!cache.contains(&2));
827 assert!(cache.contains(&1));
828 assert!(cache.contains(&3));
829 assert!(cache.contains(&4));
830 }
831
832 #[test]
833 fn test_manager_auto_switch_below_threshold() {
834 let mgr = LoRAAdapterManager::new("/tmp/nonexistent_lora");
835 let (ctx, conf) = mgr.detector.analyze_text("hello world");
837 assert_eq!(ctx, ContextType::General);
838 assert!(conf < mgr.detector.confidence_threshold);
839 }
840}