Skip to main content

paper/core/models/
manager.rs

1use super::specs::{all_specs, ModelKind, ModelSpec, DEFAULT_EMBEDDING, OPTIONAL_RERANKER};
2use super::{Embedder, Reranker};
3use crate::core::paths::Paths;
4use anyhow::{bail, Context, Result};
5use indicatif::{ProgressBar, ProgressStyle};
6use reqwest::Client;
7use sha2::{Digest, Sha256};
8use std::collections::HashSet;
9use std::path::{Path, PathBuf};
10use std::sync::Mutex;
11use tokio::io::AsyncWriteExt;
12
13/// Downloads, verifies and loads models. Every artifact is pinned by commit and
14/// SHA256; nothing is fetched implicitly during search.
15pub struct ModelManager {
16    cache_dir: PathBuf,
17    client: Client,
18    specs: Vec<ModelSpec>,
19    offline: bool,
20    /// Installed model IDs cached in memory so repeated `is_installed()` calls
21    /// don't re-hash multi-GB model files on every search (I1).
22    installed_cache: Mutex<HashSet<String>>,
23}
24
25impl Default for ModelManager {
26    fn default() -> Self {
27        Self::new()
28    }
29}
30
31impl ModelManager {
32    pub fn new() -> Self {
33        Self::with_cache_dir(Paths::new().model_cache_dir())
34    }
35
36    pub fn with_cache_dir(cache_dir: PathBuf) -> Self {
37        let offline = std::env::var("PAPER_OFFLINE")
38            .map(|v| v == "1" || v.eq_ignore_ascii_case("true"))
39            .unwrap_or(false);
40        Self {
41            cache_dir,
42            client: Client::new(),
43            specs: all_specs(),
44            offline,
45            installed_cache: Mutex::new(HashSet::new()),
46        }
47    }
48
49    pub fn cache_dir(&self) -> &Path {
50        &self.cache_dir
51    }
52
53    pub fn specs(&self) -> &[ModelSpec] {
54        &self.specs
55    }
56
57    pub fn spec(&self, model_id: &str) -> Result<&ModelSpec> {
58        self.specs
59            .iter()
60            .find(|s| s.id == model_id)
61            .ok_or_else(|| anyhow::anyhow!("unknown model: {model_id}"))
62    }
63
64    pub fn model_dir(&self, model_id: &str) -> PathBuf {
65        self.cache_dir.join(model_id)
66    }
67
68    pub fn file_path(&self, model_id: &str, file: &str) -> PathBuf {
69        self.model_dir(model_id).join(file)
70    }
71
72    /// True when every artifact is present *and* matches its pinned hash.
73    /// Results are cached so repeated calls don't re-hash multi-GB files (I1).
74    pub fn is_installed(&self, model_id: &str) -> bool {
75        // Fast path: already verified in this process.
76        {
77            let cache = self.installed_cache.lock().unwrap();
78            if cache.contains(model_id) {
79                return true;
80            }
81        }
82        let Ok(spec) = self.spec(model_id) else {
83            return false;
84        };
85        let installed = spec.files.iter().all(|f| {
86            let path = self.file_path(model_id, f.name);
87            path.exists() && verify_sha256(&path, f.sha256).unwrap_or(false)
88        });
89        if installed {
90            self.installed_cache
91                .lock()
92                .unwrap()
93                .insert(model_id.to_string());
94        }
95        installed
96    }
97
98    /// Ensure every file of `model_id` is present and verified, downloading what
99    /// is missing or corrupt. Returns the model directory.
100    pub async fn ensure(&self, model_id: &str) -> Result<PathBuf> {
101        let spec = self.spec(model_id)?.clone();
102        let dir = self.model_dir(model_id);
103        tokio::fs::create_dir_all(&dir).await?;
104
105        for file in spec.files {
106            let dest = dir.join(file.name);
107            if dest.exists() && verify_sha256(&dest, file.sha256)? {
108                continue;
109            }
110            if dest.exists() {
111                tracing::warn!("{} failed checksum verification; re-downloading", file.name);
112            }
113            if self.offline {
114                bail!(
115                    "{model_id}/{} is missing or corrupt and PAPER_OFFLINE is set",
116                    file.name
117                );
118            }
119            // GitHub Releases first, Hugging Face as fallback (see
120            // `ModelSpec::download_urls`). Both are SHA256-verified below.
121            let mut last_error = None;
122            for url in spec.download_urls(file.name) {
123                match self
124                    .download(&url, &dest, &format!("{model_id}/{}", file.name), file.size)
125                    .await
126                {
127                    Ok(()) => {
128                        last_error = None;
129                        break;
130                    }
131                    Err(e) => {
132                        tracing::warn!("download failed from {url}: {e:#}; trying next source");
133                        last_error = Some(e);
134                    }
135                }
136            }
137            if let Some(e) = last_error {
138                return Err(e);
139            }
140            if !verify_sha256(&dest, file.sha256)? {
141                let _ = tokio::fs::remove_file(&dest).await;
142                bail!(
143                    "checksum mismatch for {model_id}/{}; deleted the corrupt download",
144                    file.name
145                );
146            }
147        }
148        self.installed_cache
149            .lock()
150            .unwrap()
151            .insert(model_id.to_string());
152        Ok(dir)
153    }
154
155    async fn download(&self, url: &str, dest: &Path, label: &str, size: u64) -> Result<()> {
156        // Resume support: if a `.partial` file exists, request bytes from where
157        // we left off (I2). Hugging Face supports Range requests.
158        let tmp = dest.with_extension("partial");
159        let mut downloaded = if tmp.exists() {
160            tmp.metadata().map(|m| m.len()).unwrap_or(0)
161        } else {
162            0
163        };
164
165        let pb = ProgressBar::new(size);
166        pb.set_style(
167            ProgressStyle::with_template(
168                "{msg} [{bar:40.cyan/blue}] {bytes}/{total_bytes} ({eta})",
169            )
170            .unwrap_or_else(|_| ProgressStyle::default_bar())
171            .progress_chars("##-"),
172        );
173        pb.set_message(format!("Downloading {label}"));
174        pb.set_position(downloaded);
175
176        let mut builder = self.client.get(url);
177        if downloaded > 0 {
178            builder = builder.header(reqwest::header::RANGE, format!("bytes={downloaded}-"));
179        }
180        let mut resp = builder
181            .send()
182            .await
183            .with_context(|| format!("downloading {url}"))?
184            .error_for_status()
185            .with_context(|| format!("download failed for {url}"))?;
186
187        // A resumed request must be answered with 206 Partial Content. If the
188        // server ignored the Range header and sent the whole file (200), the
189        // existing `.partial` prefix is stale: start it over instead of
190        // appending a second copy and failing the checksum later.
191        if downloaded > 0 && resp.status() != reqwest::StatusCode::PARTIAL_CONTENT {
192            tracing::debug!("server ignored Range for {label}; restarting download");
193            tokio::fs::remove_file(&tmp).await?;
194            downloaded = 0;
195            pb.set_position(0);
196        }
197
198        // `.partial` first: an interrupted download is never mistaken for a model.
199        let mut file = tokio::fs::OpenOptions::new()
200            .create(true)
201            .append(true)
202            .open(&tmp)
203            .await?;
204        while let Some(chunk) = resp.chunk().await? {
205            file.write_all(&chunk).await?;
206            downloaded += chunk.len() as u64;
207            pb.set_position(downloaded);
208        }
209        file.flush().await?;
210        drop(file);
211        tokio::fs::rename(&tmp, dest).await?;
212        pb.finish_and_clear();
213        Ok(())
214    }
215
216    pub fn list(&self) -> Vec<ModelInfo> {
217        self.specs
218            .iter()
219            .map(|s| ModelInfo {
220                id: s.id.to_string(),
221                name: s.name.to_string(),
222                size_mb: s.size_mb(),
223                kind: s.kind,
224                license: s.license.to_string(),
225                languages: s.languages.to_string(),
226                installed: self.is_installed(s.id),
227                is_default: s.id == DEFAULT_EMBEDDING,
228            })
229            .collect()
230    }
231
232    pub fn load_embedder(&self, model_id: &str) -> Result<Embedder> {
233        let spec = self.spec(model_id)?;
234        if spec.kind != ModelKind::Embedding {
235            bail!("{model_id} is not an embedding model");
236        }
237        Embedder::new(&self.model_dir(model_id), spec)
238    }
239
240    /// Load the default embedder if (and only if) it is already on disk.
241    pub fn embedder_if_installed(&self, model_id: &str) -> Option<Embedder> {
242        match self.load_embedder(model_id) {
243            Ok(e) => Some(e),
244            Err(e) => {
245                tracing::debug!("embedder {model_id} unavailable: {e}");
246                None
247            }
248        }
249    }
250
251    pub fn load_reranker(&self) -> Result<Reranker> {
252        let spec = self.spec(OPTIONAL_RERANKER)?;
253        Reranker::new(&self.model_dir(OPTIONAL_RERANKER), spec)
254    }
255
256    pub fn reranker_if_installed(&self) -> Option<Reranker> {
257        match self.load_reranker() {
258            Ok(r) => Some(r),
259            Err(e) => {
260                tracing::debug!("reranker unavailable: {e}");
261                None
262            }
263        }
264    }
265
266    pub async fn remove(&self, model_id: &str) -> Result<()> {
267        self.spec(model_id)?;
268        let dir = self.model_dir(model_id);
269        if dir.exists() {
270            tokio::fs::remove_dir_all(&dir).await?;
271        }
272        Ok(())
273    }
274}
275
276pub fn verify_sha256(path: &Path, expected: &str) -> Result<bool> {
277    let mut file = std::fs::File::open(path)?;
278    let mut hasher = Sha256::new();
279    std::io::copy(&mut file, &mut hasher)?;
280    let actual = hex::encode(hasher.finalize());
281    Ok(actual.eq_ignore_ascii_case(expected))
282}
283
284#[derive(Debug, serde::Serialize)]
285pub struct ModelInfo {
286    pub id: String,
287    pub name: String,
288    pub size_mb: u64,
289    pub kind: ModelKind,
290    pub license: String,
291    pub languages: String,
292    pub installed: bool,
293    pub is_default: bool,
294}