Skip to main content

hyprstream_core/storage/
adapter_manager.rs

1//! Adapter management for LoRA models
2//!
3//! This module handles the storage, discovery, and composition of LoRA adapters
4//! within the git-versioned model repositories.
5//!
6//! Two modes of operation:
7//! - **Direct** (sync): Uses `PathBuf` and `std::fs` for standalone/test use.
8//! - **FsOps** (async): Uses `WorktreeClient` for worktree-scoped, path-contained access.
9
10use anyhow::{Context, Result};
11use serde::{Deserialize, Serialize};
12use std::collections::HashMap;
13use std::path::{Path, PathBuf};
14
15use crate::services::WorktreeClientExt;
16use hyprstream_rpc_std::registry_client::WorktreeClient;
17
18/// Information about a discovered adapter
19#[derive(Debug, Clone, Serialize, Deserialize)]
20pub struct AdapterInfo {
21    /// Full filename (e.g., "00_base.safetensors")
22    pub filename: String,
23    /// Numeric index parsed from filename
24    pub index: u32,
25    /// Base name without index (e.g., "base")
26    pub name: String,
27    /// Full path to the adapter file
28    pub path: PathBuf,
29    /// Size in bytes
30    pub size: u64,
31    /// Associated config file if exists
32    pub config_path: Option<PathBuf>,
33}
34
35/// Adapter configuration stored alongside the weights
36#[derive(Debug, Clone, Serialize, Deserialize)]
37pub struct AdapterConfig {
38    pub rank: u32,
39    pub alpha: f32,
40    pub learning_rate: f64,
41    pub batch_size: usize,
42    pub epochs: usize,
43    pub created_at: String,
44    pub model_ref: String,
45    pub training_data: Option<String>,
46    pub metadata: HashMap<String, String>,
47}
48
49impl Default for AdapterConfig {
50    fn default() -> Self {
51        Self {
52            rank: 16,
53            alpha: 32.0,
54            learning_rate: 1e-4,
55            batch_size: 4,
56            epochs: 10,
57            created_at: chrono::Utc::now().to_rfc3339(),
58            model_ref: String::new(),
59            training_data: None,
60            metadata: HashMap::new(),
61        }
62    }
63}
64
65/// Manages LoRA adapters within a model's git repository
66pub struct AdapterManager {
67    pub adapters_dir: PathBuf,
68    /// Optional FsOps for worktree-scoped file operations.
69    /// When present, async methods use contained-root access.
70    /// When absent, sync methods use direct filesystem access.
71    fs: Option<WorktreeClient>,
72}
73
74impl AdapterManager {
75    /// Create a new adapter manager for a model (direct filesystem access)
76    pub fn new(model_path: impl AsRef<Path>) -> Self {
77        let adapters_dir = model_path.as_ref().join("adapters");
78        Self {
79            adapters_dir,
80            fs: None,
81        }
82    }
83
84    /// Create a new adapter manager with WorktreeClient for worktree-scoped access
85    pub fn with_fs(fs: WorktreeClient) -> Self {
86        // adapters_dir is kept for backward compat but not used when fs is Some
87        Self {
88            adapters_dir: PathBuf::from("adapters"),
89            fs: Some(fs),
90        }
91    }
92
93    /// Returns true if this manager is using FsOps for file operations
94    pub fn has_fs(&self) -> bool {
95        self.fs.is_some()
96    }
97
98    // =========================================================================
99    // Sync methods (direct filesystem access — backward compatible)
100    // =========================================================================
101
102    /// Ensure the adapters directory exists
103    pub fn ensure_adapters_dir(&self) -> Result<()> {
104        if !self.adapters_dir.exists() {
105            std::fs::create_dir_all(&self.adapters_dir).with_context(|| {
106                format!(
107                    "Failed to create adapters directory: {:?}",
108                    self.adapters_dir
109                )
110            })?;
111        }
112        Ok(())
113    }
114
115    /// List all adapters in the model, sorted by index
116    pub fn list_adapters(&self) -> Result<Vec<AdapterInfo>> {
117        let mut adapters = Vec::new();
118
119        if !self.adapters_dir.exists() {
120            return Ok(adapters);
121        }
122
123        for entry in std::fs::read_dir(&self.adapters_dir)? {
124            let entry = entry?;
125            let path = entry.path();
126            let filename = entry.file_name();
127
128            if let Some(name_str) = filename.to_str() {
129                // Only process .safetensors files
130                if !name_str.ends_with(".safetensors") {
131                    continue;
132                }
133
134                // Parse index and name from filename like "00_base.safetensors"
135                let base_name = name_str.trim_end_matches(".safetensors");
136                let (index, name) = if let Some(underscore_pos) = base_name.find('_') {
137                    let index_str = &base_name[..underscore_pos];
138                    let name_str = &base_name[underscore_pos + 1..];
139
140                    if let Ok(idx) = index_str.parse::<u32>() {
141                        (idx, name_str.to_owned())
142                    } else {
143                        // If parsing fails, treat whole name as adapter name with index 999
144                        (999, base_name.to_owned())
145                    }
146                } else {
147                    // No index prefix, assign high index
148                    (999, base_name.to_owned())
149                };
150
151                let metadata = std::fs::metadata(&path)?;
152                let config_path = self.adapters_dir.join(format!("{base_name}.config.json"));
153
154                adapters.push(AdapterInfo {
155                    filename: name_str.to_owned(),
156                    index,
157                    name,
158                    path,
159                    size: metadata.len(),
160                    config_path: if config_path.exists() {
161                        Some(config_path)
162                    } else {
163                        None
164                    },
165                });
166            }
167        }
168
169        // Sort by index
170        adapters.sort_by_key(|a| a.index);
171        Ok(adapters)
172    }
173
174    /// Get the next available index for a new adapter
175    pub fn get_next_index(&self) -> Result<u32> {
176        let adapters = self.list_adapters()?;
177        if adapters.is_empty() {
178            Ok(0)
179        } else {
180            Ok(adapters.last().map(|a| a.index + 1).unwrap_or(0))
181        }
182    }
183
184    /// Create an indexed adapter filename
185    pub fn create_indexed_name(&self, name: &str, index: Option<u32>) -> Result<String> {
186        let idx = if let Some(i) = index {
187            i
188        } else {
189            self.get_next_index()?
190        };
191        Ok(format!("{idx:02}_{name}"))
192    }
193
194    /// Initialize adapter with proper implementation
195    pub fn initialize_adapter(
196        &self,
197        name: &str,
198        index: Option<u32>,
199        config: AdapterConfig,
200    ) -> Result<std::path::PathBuf> {
201        self.ensure_adapters_dir()?;
202
203        let idx = if let Some(i) = index {
204            i
205        } else {
206            self.get_next_index()?
207        };
208
209        let adapter_name = format!("{idx:02}_{name}");
210        let adapter_path = self
211            .adapters_dir
212            .join(format!("{adapter_name}.safetensors"));
213
214        // Save configuration file
215        let config_path = self
216            .adapters_dir
217            .join(format!("{adapter_name}.config.json"));
218        let config_json = serde_json::to_string_pretty(&config)
219            .with_context(|| "Failed to serialize adapter config")?;
220        std::fs::write(&config_path, config_json)
221            .with_context(|| format!("Failed to write adapter config: {config_path:?}"))?;
222
223        // Create empty adapter file (weights will be added during training)
224        std::fs::File::create(&adapter_path)
225            .with_context(|| format!("Failed to create adapter file: {adapter_path:?}"))?;
226
227        Ok(adapter_path)
228    }
229
230    /// Load all adapter paths sorted by index
231    pub fn get_adapter_paths(&self) -> Result<Vec<PathBuf>> {
232        let adapters = self.list_adapters()?;
233        Ok(adapters.into_iter().map(|a| a.path).collect())
234    }
235
236    /// Load configuration for a specific adapter
237    pub fn load_adapter_config(&self, adapter_name: &str) -> Result<AdapterConfig> {
238        let config_path = self
239            .adapters_dir
240            .join(format!("{adapter_name}.config.json"));
241        let config_str = std::fs::read_to_string(&config_path)
242            .with_context(|| format!("Failed to read adapter config: {config_path:?}"))?;
243        let config: AdapterConfig = serde_json::from_str(&config_str)?;
244        Ok(config)
245    }
246
247    /// Check if any adapters exist for this model
248    pub fn has_adapters(&self) -> bool {
249        self.adapters_dir.exists() && !self.list_adapters().unwrap_or_default().is_empty()
250    }
251
252    /// Get total size of all adapters
253    pub fn get_total_size(&self) -> Result<u64> {
254        let adapters = self.list_adapters()?;
255        Ok(adapters.iter().map(|a| a.size).sum())
256    }
257
258    /// Remove an adapter by name or index
259    pub fn remove_adapter(&self, identifier: &str) -> Result<()> {
260        let adapters = self.list_adapters()?;
261
262        // Try to parse as index first
263        let to_remove = if let Ok(idx) = identifier.parse::<u32>() {
264            adapters.iter().find(|a| a.index == idx)
265        } else {
266            // Otherwise match by name
267            adapters
268                .iter()
269                .find(|a| a.name == identifier || a.filename.starts_with(identifier))
270        };
271
272        if let Some(adapter) = to_remove {
273            // Remove adapter file
274            if adapter.path.exists() {
275                std::fs::remove_file(&adapter.path)?;
276            }
277
278            // Remove config if exists
279            if let Some(config_path) = &adapter.config_path {
280                if config_path.exists() {
281                    std::fs::remove_file(config_path)?;
282                }
283            }
284
285            Ok(())
286        } else {
287            anyhow::bail!("Adapter '{}' not found", identifier)
288        }
289    }
290
291    // =========================================================================
292    // Async methods (FsOps — worktree-scoped, path-contained access)
293    // =========================================================================
294
295    /// Ensure the adapters directory exists (async, via FsOps)
296    pub async fn ensure_adapters_dir_async(&self) -> Result<()> {
297        if let Some(fs) = &self.fs {
298            fs.mkdir_p("adapters").await?;
299            Ok(())
300        } else {
301            self.ensure_adapters_dir()
302        }
303    }
304
305    /// List all adapters via FsOps, sorted by index
306    pub async fn list_adapters_async(&self) -> Result<Vec<AdapterInfo>> {
307        let fs = match &self.fs {
308            Some(fs) => fs,
309            None => return self.list_adapters(),
310        };
311
312        let mut adapters = Vec::new();
313
314        // Check if adapters dir exists
315        if !fs
316            .stat_path("adapters")
317            .await
318            .map(|s| s.exists)
319            .unwrap_or(false)
320        {
321            return Ok(adapters);
322        }
323
324        let entries = fs.list_dir_path("adapters").await?;
325
326        for entry in entries {
327            let name_str = &entry.name;
328
329            // Only process .safetensors files
330            if !name_str.ends_with(".safetensors") {
331                continue;
332            }
333
334            // Parse index and name from filename like "00_base.safetensors"
335            let base_name = name_str.trim_end_matches(".safetensors");
336            let (index, name) = if let Some(underscore_pos) = base_name.find('_') {
337                let index_str = &base_name[..underscore_pos];
338                let adapter_name = &base_name[underscore_pos + 1..];
339
340                if let Ok(idx) = index_str.parse::<u32>() {
341                    (idx, adapter_name.to_owned())
342                } else {
343                    (999, base_name.to_owned())
344                }
345            } else {
346                (999, base_name.to_owned())
347            };
348
349            let rel_config = format!("adapters/{base_name}.config.json");
350            let config_exists = fs
351                .stat_path(&rel_config)
352                .await
353                .map(|s| s.exists)
354                .unwrap_or(false);
355
356            adapters.push(AdapterInfo {
357                filename: name_str.clone(),
358                index,
359                name,
360                // For FsOps, path is relative within worktree
361                path: PathBuf::from(format!("adapters/{name_str}")),
362                size: entry.size,
363                config_path: if config_exists {
364                    Some(PathBuf::from(rel_config))
365                } else {
366                    None
367                },
368            });
369        }
370
371        adapters.sort_by_key(|a| a.index);
372        Ok(adapters)
373    }
374
375    /// Get the next available index (async, via FsOps)
376    pub async fn get_next_index_async(&self) -> Result<u32> {
377        let adapters = self.list_adapters_async().await?;
378        if adapters.is_empty() {
379            Ok(0)
380        } else {
381            Ok(adapters.last().map(|a| a.index + 1).unwrap_or(0))
382        }
383    }
384
385    /// Create an indexed adapter filename (async, via FsOps)
386    pub async fn create_indexed_name_async(
387        &self,
388        name: &str,
389        index: Option<u32>,
390    ) -> Result<String> {
391        let idx = if let Some(i) = index {
392            i
393        } else {
394            self.get_next_index_async().await?
395        };
396        Ok(format!("{idx:02}_{name}"))
397    }
398
399    /// Initialize adapter via FsOps (async)
400    ///
401    /// Returns the relative path within the worktree (e.g., "adapters/00_base.safetensors").
402    pub async fn initialize_adapter_async(
403        &self,
404        name: &str,
405        index: Option<u32>,
406        config: AdapterConfig,
407    ) -> Result<String> {
408        let fs = match &self.fs {
409            Some(fs) => fs,
410            None => {
411                let path = self.initialize_adapter(name, index, config)?;
412                return Ok(path.to_string_lossy().to_string());
413            }
414        };
415
416        fs.mkdir_p("adapters").await?;
417
418        let idx = if let Some(i) = index {
419            i
420        } else {
421            self.get_next_index_async().await?
422        };
423
424        let adapter_name = format!("{idx:02}_{name}");
425
426        // Save configuration file
427        let rel_config = format!("adapters/{adapter_name}.config.json");
428        let config_json = serde_json::to_string_pretty(&config)
429            .with_context(|| "Failed to serialize adapter config")?;
430        fs.write_file_chunked(&rel_config, config_json.as_bytes())
431            .await?;
432
433        // Create empty adapter file
434        let rel_adapter = format!("adapters/{adapter_name}.safetensors");
435        fs.write_file_chunked(&rel_adapter, &[]).await?;
436
437        Ok(rel_adapter)
438    }
439
440    /// Load configuration for a specific adapter (async, via FsOps)
441    pub async fn load_adapter_config_async(&self, adapter_name: &str) -> Result<AdapterConfig> {
442        let fs = match &self.fs {
443            Some(fs) => fs,
444            None => return self.load_adapter_config(adapter_name),
445        };
446
447        let rel_config = format!("adapters/{adapter_name}.config.json");
448        let config_str = String::from_utf8(fs.read_file_chunked(&rel_config).await?)?;
449        let config: AdapterConfig = serde_json::from_str(&config_str)?;
450        Ok(config)
451    }
452
453    /// Check if any adapters exist (async, via FsOps)
454    pub async fn has_adapters_async(&self) -> Result<bool> {
455        let fs = match &self.fs {
456            Some(fs) => fs,
457            None => return Ok(self.has_adapters()),
458        };
459
460        if !fs
461            .stat_path("adapters")
462            .await
463            .map(|s| s.exists)
464            .unwrap_or(false)
465        {
466            return Ok(false);
467        }
468
469        let adapters = self.list_adapters_async().await?;
470        Ok(!adapters.is_empty())
471    }
472
473    /// Remove an adapter by name or index (async, via FsOps)
474    pub async fn remove_adapter_async(&self, identifier: &str) -> Result<()> {
475        let fs = match &self.fs {
476            Some(fs) => fs,
477            None => return self.remove_adapter(identifier),
478        };
479
480        let adapters = self.list_adapters_async().await?;
481
482        let to_remove = if let Ok(idx) = identifier.parse::<u32>() {
483            adapters.iter().find(|a| a.index == idx)
484        } else {
485            adapters
486                .iter()
487                .find(|a| a.name == identifier || a.filename.starts_with(identifier))
488        };
489
490        if let Some(adapter) = to_remove {
491            // Remove adapter file (path is relative for FsOps)
492            let rel_path = adapter.path.to_string_lossy();
493            fs.remove_path(&rel_path).await?;
494
495            // Remove config if exists
496            if let Some(config_path) = &adapter.config_path {
497                let rel_config = config_path.to_string_lossy();
498                if fs
499                    .stat_path(&rel_config)
500                    .await
501                    .map(|s| s.exists)
502                    .unwrap_or(false)
503                {
504                    fs.remove_path(&rel_config).await?;
505                }
506            }
507
508            Ok(())
509        } else {
510            anyhow::bail!("Adapter '{}' not found", identifier)
511        }
512    }
513
514    /// Write adapter config file (async, via FsOps)
515    pub async fn write_config_async(
516        &self,
517        adapter_name: &str,
518        config: &AdapterConfig,
519    ) -> Result<()> {
520        let fs = match &self.fs {
521            Some(fs) => fs,
522            None => {
523                let config_path = self
524                    .adapters_dir
525                    .join(format!("{adapter_name}.config.json"));
526                let config_json = serde_json::to_string_pretty(config)?;
527                std::fs::write(&config_path, config_json)?;
528                return Ok(());
529            }
530        };
531
532        let rel_config = format!("adapters/{adapter_name}.config.json");
533        let config_json = serde_json::to_string_pretty(config)?;
534        fs.write_file_chunked(&rel_config, config_json.as_bytes())
535            .await?;
536        Ok(())
537    }
538
539    /// Write adapter weights data (async, via FsOps)
540    pub async fn write_adapter_data_async(&self, adapter_name: &str, data: &[u8]) -> Result<()> {
541        let fs = match &self.fs {
542            Some(fs) => fs,
543            None => {
544                let adapter_path = self
545                    .adapters_dir
546                    .join(format!("{adapter_name}.safetensors"));
547                std::fs::write(&adapter_path, data)?;
548                return Ok(());
549            }
550        };
551
552        let rel_path = format!("adapters/{adapter_name}.safetensors");
553        fs.write_file_chunked(&rel_path, data).await?;
554        Ok(())
555    }
556
557    /// Read adapter weights data (async, via FsOps)
558    pub async fn read_adapter_data_async(&self, adapter_name: &str) -> Result<Vec<u8>> {
559        let fs = match &self.fs {
560            Some(fs) => fs,
561            None => {
562                let adapter_path = self
563                    .adapters_dir
564                    .join(format!("{adapter_name}.safetensors"));
565                return Ok(std::fs::read(&adapter_path)?);
566            }
567        };
568
569        let rel_path = format!("adapters/{adapter_name}.safetensors");
570        fs.read_file_chunked(&rel_path).await
571    }
572}
573
574#[cfg(test)]
575mod tests {
576    use super::*;
577    use tempfile::tempdir;
578
579    #[test]
580    fn test_adapter_indexing() -> Result<()> {
581        let temp_dir = tempdir()?;
582        let model_path = temp_dir.path().join("test_model");
583        std::fs::create_dir_all(&model_path)?;
584
585        let manager = AdapterManager::new(&model_path);
586        manager.ensure_adapters_dir()?;
587
588        // Test getting next index on empty directory
589        assert_eq!(manager.get_next_index()?, 0);
590
591        // Create some test adapters
592        let adapters_dir = model_path.join("adapters");
593        std::fs::write(adapters_dir.join("00_base.safetensors"), b"")?;
594        std::fs::write(adapters_dir.join("01_custom.safetensors"), b"")?;
595
596        // Test getting next index with existing adapters
597        assert_eq!(manager.get_next_index()?, 2);
598
599        // Test listing adapters
600        let adapters = manager.list_adapters()?;
601        assert_eq!(adapters.len(), 2);
602        assert_eq!(adapters[0].index, 0);
603        assert_eq!(adapters[0].name, "base");
604        assert_eq!(adapters[1].index, 1);
605        assert_eq!(adapters[1].name, "custom");
606        Ok(())
607    }
608
609    #[test]
610    fn test_adapter_initialization() -> Result<()> {
611        let temp_dir = tempdir()?;
612        let model_path = temp_dir.path().join("test_model");
613        std::fs::create_dir_all(&model_path)?;
614
615        let manager = AdapterManager::new(&model_path);
616
617        let mut config = AdapterConfig::default();
618        config.model_ref = "test_model".to_owned();
619
620        // Initialize adapter with auto-index
621        let adapter_path = manager.initialize_adapter("test", None, config.clone())?;
622        assert!(adapter_path.exists());
623        let path_str = adapter_path
624            .to_str()
625            .ok_or_else(|| anyhow::anyhow!("path not valid utf-8"))?;
626        assert!(path_str.contains("00_test"));
627
628        // Initialize adapter with specific index
629        let adapter_path = manager.initialize_adapter("custom", Some(5), config)?;
630        assert!(adapter_path.exists());
631        let path_str = adapter_path
632            .to_str()
633            .ok_or_else(|| anyhow::anyhow!("path not valid utf-8"))?;
634        assert!(path_str.contains("05_custom"));
635
636        // Check that configs were created
637        let adapters_dir = model_path.join("adapters");
638        assert!(adapters_dir.join("00_test.config.json").exists());
639        assert!(adapters_dir.join("05_custom.config.json").exists());
640
641        // Verify adapter files were created
642        assert!(adapters_dir.join("00_test.safetensors").exists());
643        assert!(adapters_dir.join("05_custom.safetensors").exists());
644        Ok(())
645    }
646}