Skip to main content

tpt_gpu_model_registry/
lib.rs

1//! TPT shared model registry — `~/.tpt/models/`
2//!
3//! Provides read/write access to the `models.json` manifest that all TPT
4//! tools (tpt-gpu, tpt-spark, tpt-crucible) share. See `MODELS_REGISTRY.md`
5//! at the repo root for the full specification.
6
7use std::fs;
8use std::path::{Path, PathBuf};
9
10use anyhow::{bail, Context, Result};
11use serde::{Deserialize, Serialize};
12
13pub mod hf;
14
15const MANIFEST_VERSION: &str = "1";
16const MANIFEST_FILE: &str = "models.json";
17const REGISTRY_DIR: &str = ".tpt/models";
18
19/// A single entry in the manifest.
20#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
21pub struct ModelEntry {
22    /// Human-readable, URL-safe identifier used as lookup key.
23    pub name: String,
24    /// Filename relative to the registry directory.
25    pub file: String,
26    /// Architecture tag: `llama3`, `mistral`, `phi3`, `gemma2`, …
27    pub arch: String,
28    /// Approximate on-disk size in GiB.
29    pub size_gb: f64,
30    /// SHA-256 of the GGUF or TPTF file (optional — integrity verification).
31    #[serde(skip_serializing_if = "Option::is_none")]
32    pub sha256: Option<String>,
33    /// Original download URL (optional — informational).
34    #[serde(skip_serializing_if = "Option::is_none")]
35    pub source: Option<String>,
36    /// Per-layer bit depths produced by `tpt-gpu-model-optimizer` (2/4/6/8/16).
37    /// `None` means the model is unoptimized (full f32/f16 weights).
38    #[serde(skip_serializing_if = "Option::is_none")]
39    pub quant_bits: Option<Vec<u8>>,
40    /// Domains removed during surgical pruning (e.g. `["sql", "typescript"]`).
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub pruned_domains: Option<Vec<String>>,
43    /// Registry name of the unoptimized source model this was derived from.
44    #[serde(skip_serializing_if = "Option::is_none")]
45    pub source_model: Option<String>,
46}
47
48/// The `models.json` manifest.
49#[derive(Debug, Clone, Serialize, Deserialize)]
50pub struct Manifest {
51    pub version: String,
52    pub models: Vec<ModelEntry>,
53}
54
55impl Manifest {
56    fn empty() -> Self {
57        Self {
58            version: MANIFEST_VERSION.to_string(),
59            models: Vec::new(),
60        }
61    }
62}
63
64/// Handle to the registry directory and its manifest.
65pub struct ModelRegistry {
66    dir: PathBuf,
67    manifest: Manifest,
68}
69
70impl ModelRegistry {
71    /// Open (or create) the registry at `~/.tpt/models/`.
72    pub fn open() -> Result<Self> {
73        let dir = registry_dir()?;
74        Self::open_at(dir)
75    }
76
77    /// Open (or create) the registry at an explicit path — useful for tests.
78    pub fn open_at(dir: impl Into<PathBuf>) -> Result<Self> {
79        let dir = dir.into();
80        fs::create_dir_all(&dir)
81            .with_context(|| format!("cannot create registry dir {}", dir.display()))?;
82
83        let manifest_path = dir.join(MANIFEST_FILE);
84        let manifest = if manifest_path.exists() {
85            let raw = fs::read_to_string(&manifest_path)
86                .with_context(|| format!("cannot read {}", manifest_path.display()))?;
87            let m: Manifest =
88                serde_json::from_str(&raw).with_context(|| "models.json is not valid JSON")?;
89            if m.version != MANIFEST_VERSION {
90                bail!(
91                    "unsupported manifest version '{}' (this tool supports '{}')",
92                    m.version,
93                    MANIFEST_VERSION
94                );
95            }
96            m
97        } else {
98            Manifest::empty()
99        };
100
101        Ok(Self { dir, manifest })
102    }
103
104    /// Return the path to the registry directory.
105    pub fn dir(&self) -> &Path {
106        &self.dir
107    }
108
109    /// Return all registered models.
110    pub fn models(&self) -> &[ModelEntry] {
111        &self.manifest.models
112    }
113
114    /// Look up a model by name.
115    pub fn find_by_name(&self, name: &str) -> Option<&ModelEntry> {
116        self.manifest.models.iter().find(|m| m.name == name)
117    }
118
119    /// Return the absolute path to a model's GGUF file, if it exists on disk.
120    pub fn model_path(&self, entry: &ModelEntry) -> PathBuf {
121        self.dir.join(&entry.file)
122    }
123
124    /// Add or update a model entry, then persist the manifest.
125    pub fn register(&mut self, entry: ModelEntry) -> Result<()> {
126        if let Some(existing) = self
127            .manifest
128            .models
129            .iter_mut()
130            .find(|m| m.name == entry.name)
131        {
132            *existing = entry;
133        } else {
134            self.manifest.models.push(entry);
135        }
136        self.save()
137    }
138
139    /// Remove a model entry by name. Does NOT delete the file on disk.
140    pub fn unregister(&mut self, name: &str) -> Result<bool> {
141        let before = self.manifest.models.len();
142        self.manifest.models.retain(|m| m.name != name);
143        let removed = self.manifest.models.len() < before;
144        if removed {
145            self.save()?;
146        }
147        Ok(removed)
148    }
149
150    /// Persist the manifest to disk.
151    fn save(&self) -> Result<()> {
152        let path = self.dir.join(MANIFEST_FILE);
153        let json =
154            serde_json::to_string_pretty(&self.manifest).context("cannot serialize manifest")?;
155        fs::write(&path, json).with_context(|| format!("cannot write {}", path.display()))?;
156        Ok(())
157    }
158}
159
160/// Resolve `~/.tpt/models/` on the current platform.
161pub fn registry_dir() -> Result<PathBuf> {
162    let home = home_dir().context("cannot determine home directory")?;
163    Ok(home.join(REGISTRY_DIR))
164}
165
166fn home_dir() -> Option<PathBuf> {
167    // std::env::home_dir is deprecated but still functional; use env vars as
168    // the primary path to avoid the deprecation warning.
169    #[cfg(windows)]
170    {
171        std::env::var_os("USERPROFILE").map(PathBuf::from)
172    }
173    #[cfg(not(windows))]
174    {
175        std::env::var_os("HOME").map(PathBuf::from)
176    }
177}
178
179#[cfg(test)]
180mod tests {
181    use super::*;
182    use std::env;
183
184    fn temp_dir() -> PathBuf {
185        use std::sync::atomic::{AtomicU64, Ordering};
186        static COUNTER: AtomicU64 = AtomicU64::new(0);
187        let id = COUNTER.fetch_add(1, Ordering::Relaxed);
188        let mut p = env::temp_dir();
189        p.push(format!("tpt_registry_test_{}_{}", std::process::id(), id));
190        p
191    }
192
193    #[test]
194    fn create_and_persist() {
195        let dir = temp_dir();
196        let mut reg = ModelRegistry::open_at(&dir).unwrap();
197        assert!(reg.models().is_empty());
198
199        let entry = ModelEntry {
200            name: "llama-3-8b-q4".to_string(),
201            file: "llama-3-8b-q4.gguf".to_string(),
202            arch: "llama3".to_string(),
203            size_gb: 4.7,
204            sha256: None,
205            source: Some("https://huggingface.co/example".to_string()),
206            quant_bits: None,
207            pruned_domains: None,
208            source_model: None,
209        };
210        reg.register(entry.clone()).unwrap();
211
212        // Re-open to verify persistence
213        let reg2 = ModelRegistry::open_at(&dir).unwrap();
214        let found = reg2.find_by_name("llama-3-8b-q4").unwrap();
215        assert_eq!(found.arch, "llama3");
216        assert!((found.size_gb - 4.7).abs() < 0.001);
217
218        // Cleanup
219        let _ = fs::remove_dir_all(&dir);
220    }
221
222    #[test]
223    fn unregister_removes_entry() {
224        let dir = temp_dir();
225        let mut reg = ModelRegistry::open_at(&dir).unwrap();
226        reg.register(ModelEntry {
227            name: "test-model".to_string(),
228            file: "test.gguf".to_string(),
229            arch: "llama3".to_string(),
230            size_gb: 1.0,
231            sha256: None,
232            source: None,
233            quant_bits: None,
234            pruned_domains: None,
235            source_model: None,
236        })
237        .unwrap();
238
239        let removed = reg.unregister("test-model").unwrap();
240        assert!(removed);
241        assert!(reg.find_by_name("test-model").is_none());
242
243        let removed_again = reg.unregister("test-model").unwrap();
244        assert!(!removed_again);
245
246        let _ = fs::remove_dir_all(&dir);
247    }
248
249    #[test]
250    fn upsert_updates_existing() {
251        let dir = temp_dir();
252        let mut reg = ModelRegistry::open_at(&dir).unwrap();
253
254        reg.register(ModelEntry {
255            name: "m".to_string(),
256            file: "m.gguf".to_string(),
257            arch: "phi3".to_string(),
258            size_gb: 2.0,
259            sha256: None,
260            source: None,
261            quant_bits: None,
262            pruned_domains: None,
263            source_model: None,
264        })
265        .unwrap();
266        reg.register(ModelEntry {
267            name: "m".to_string(),
268            file: "m.gguf".to_string(),
269            arch: "phi3".to_string(),
270            size_gb: 2.5,
271            sha256: None,
272            source: None,
273            quant_bits: Some(vec![4, 4, 6, 8]),
274            pruned_domains: Some(vec!["sql".to_string()]),
275            source_model: Some("m-orig".to_string()),
276        })
277        .unwrap();
278
279        assert_eq!(reg.models().len(), 1);
280        assert!((reg.find_by_name("m").unwrap().size_gb - 2.5).abs() < 0.001);
281
282        let _ = fs::remove_dir_all(&dir);
283    }
284}