use std::ffi::OsString;
use std::path::{Path, PathBuf};
use anyhow::{Context, Result, bail};
use fastembed::{RerankerModel, TextRerank};
use crate::retrieval::rerank::parse_model;
pub const MODEL_CACHE_DIR_ENV: &str = "FASTEMBED_CACHE_DIR";
pub const TOKENIZER_FILES: [&str; 4] = [
"tokenizer.json",
"config.json",
"tokenizer_config.json",
"special_tokens_map.json",
];
pub const DEFAULT_RERANK_MODEL: &str = "jina-reranker-v1-turbo";
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CachedModel {
pub code: String,
pub files: Vec<String>,
lookup: SnapshotLookup,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum SnapshotLookup {
MainRef,
AnyComplete,
}
impl CachedModel {
pub(crate) fn new(
code: &str,
model_file: &str,
additional_files: &[String],
lookup: SnapshotLookup,
) -> Self {
let files = std::iter::once(model_file.to_string())
.chain(additional_files.iter().cloned())
.chain(TOKENIZER_FILES.iter().map(|f| f.to_string()))
.collect();
Self {
code: code.to_string(),
files,
lookup,
}
}
pub fn loadable_snapshot(&self, cache_dir: &Path) -> Option<PathBuf> {
match self.lookup {
SnapshotLookup::MainRef => main_ref_snapshot(cache_dir, self),
SnapshotLookup::AnyComplete => cached_snapshot(cache_dir, self),
}
}
}
pub(crate) fn reranker_model(model: &RerankerModel) -> CachedModel {
let info = TextRerank::get_model_info(model);
CachedModel::new(
&info.model_code,
&info.model_file,
&info.additional_files,
SnapshotLookup::AnyComplete,
)
}
pub fn default_reranker_model() -> Result<CachedModel> {
Ok(reranker_model(&parse_model(DEFAULT_RERANK_MODEL)?))
}
pub fn snapshots_dir(cache_dir: &Path, model_code: &str) -> PathBuf {
cache_dir
.join(format!("models--{}", model_code.replace('/', "--")))
.join("snapshots")
}
pub fn cached_snapshot(cache_dir: &Path, model: &CachedModel) -> Option<PathBuf> {
let mut snapshots: Vec<PathBuf> = std::fs::read_dir(snapshots_dir(cache_dir, &model.code))
.ok()?
.filter_map(|entry| entry.ok())
.map(|entry| entry.path())
.filter(|path| path.is_dir())
.collect();
snapshots.sort();
snapshots
.into_iter()
.find(|snapshot| holds_every_file(snapshot, model))
}
pub fn main_ref_snapshot(cache_dir: &Path, model: &CachedModel) -> Option<PathBuf> {
let snapshots = snapshots_dir(cache_dir, &model.code);
let main_ref = snapshots.parent()?.join("refs").join("main");
let revision = std::fs::read_to_string(main_ref).ok()?;
let snapshot = snapshots.join(revision);
holds_every_file(&snapshot, model).then_some(snapshot)
}
fn holds_every_file(snapshot: &Path, model: &CachedModel) -> bool {
model.files.iter().all(|file| snapshot.join(file).is_file())
}
pub fn model_cache_dir() -> Result<PathBuf> {
let dir = resolve(std::env::var_os(MODEL_CACHE_DIR_ENV), dirs::cache_dir())?;
std::fs::create_dir_all(&dir)
.with_context(|| format!("creating model cache dir {}", dir.display()))?;
Ok(dir)
}
pub fn model_cache_dir_in(user_cache: &Path) -> PathBuf {
user_cache.join("second-brain").join("models")
}
fn resolve(env_override: Option<OsString>, user_cache: Option<PathBuf>) -> Result<PathBuf> {
if let Some(value) = env_override.filter(|v| !v.is_empty()) {
let dir = PathBuf::from(value);
if !dir.is_absolute() {
bail!(
"{MODEL_CACHE_DIR_ENV} must be an absolute path, got {}",
dir.display()
);
}
return Ok(dir);
}
let user_cache = user_cache.with_context(|| {
format!("cannot determine the user cache directory; set {MODEL_CACHE_DIR_ENV}")
})?;
if !user_cache.is_absolute() {
bail!(
"user cache directory {} is not absolute; set {MODEL_CACHE_DIR_ENV}",
user_cache.display()
);
}
Ok(model_cache_dir_in(&user_cache))
}
#[cfg(test)]
pub(crate) mod test_support {
use std::ffi::OsString;
use std::path::Path;
use std::sync::{Mutex, MutexGuard};
use super::MODEL_CACHE_DIR_ENV;
static ENV_LOCK: Mutex<()> = Mutex::new(());
pub(crate) struct CacheDirOverride {
previous: Option<OsString>,
_lock: MutexGuard<'static, ()>,
}
impl CacheDirOverride {
pub(crate) fn new(dir: &Path) -> Self {
let lock = ENV_LOCK.lock().unwrap_or_else(|e| e.into_inner());
let previous = std::env::var_os(MODEL_CACHE_DIR_ENV);
unsafe { std::env::set_var(MODEL_CACHE_DIR_ENV, dir) };
Self {
previous,
_lock: lock,
}
}
}
impl Drop for CacheDirOverride {
fn drop(&mut self) {
unsafe {
match &self.previous {
Some(value) => std::env::set_var(MODEL_CACHE_DIR_ENV, value),
None => std::env::remove_var(MODEL_CACHE_DIR_ENV),
}
}
}
}
}
#[cfg(test)]
mod tests {
use super::test_support::CacheDirOverride;
use super::*;
fn jina() -> CachedModel {
reranker_model(&RerankerModel::JINARerankerV1TurboEn)
}
fn seed(snapshot: &Path, files: &[String]) {
for file in files {
let path = snapshot.join(file);
std::fs::create_dir_all(path.parent().unwrap()).unwrap();
std::fs::write(path, b"x").unwrap();
}
}
fn hub_snapshot(cache: &Path, repo_dir: &str, revision: &str) -> PathBuf {
cache.join(repo_dir).join("snapshots").join(revision)
}
#[test]
fn cached_snapshot_finds_a_snapshot_holding_every_required_file() {
let tmp = tempfile::tempdir().unwrap();
let model = jina();
let snap = hub_snapshot(
tmp.path(),
"models--jinaai--jina-reranker-v1-turbo-en",
"rev1",
);
seed(&snap, &model.files);
assert_eq!(cached_snapshot(tmp.path(), &model), Some(snap));
}
#[test]
fn cached_snapshot_is_none_when_tokenizer_json_is_missing() {
let tmp = tempfile::tempdir().unwrap();
let model = jina();
let snap = hub_snapshot(
tmp.path(),
"models--jinaai--jina-reranker-v1-turbo-en",
"rev1",
);
seed(&snap, &model.files);
assert_eq!(cached_snapshot(tmp.path(), &model), Some(snap.clone()));
std::fs::remove_file(snap.join("tokenizer.json")).unwrap();
assert_eq!(cached_snapshot(tmp.path(), &model), None);
}
#[test]
fn cached_snapshot_is_none_when_the_onnx_file_is_missing() {
let tmp = tempfile::tempdir().unwrap();
let model = jina();
let snap = hub_snapshot(
tmp.path(),
"models--jinaai--jina-reranker-v1-turbo-en",
"rev1",
);
seed(&snap, &model.files);
assert_eq!(cached_snapshot(tmp.path(), &model), Some(snap.clone()));
std::fs::remove_file(snap.join("onnx").join("model.onnx")).unwrap();
assert_eq!(cached_snapshot(tmp.path(), &model), None);
}
#[test]
fn cached_snapshot_skips_an_interrupted_snapshot_for_a_complete_one() {
let tmp = tempfile::tempdir().unwrap();
let model = jina();
let repo = "models--jinaai--jina-reranker-v1-turbo-en";
seed(
&hub_snapshot(tmp.path(), repo, "a-partial"),
&model.files[..1],
);
let complete = hub_snapshot(tmp.path(), repo, "b-complete");
seed(&complete, &model.files);
assert_eq!(cached_snapshot(tmp.path(), &model), Some(complete));
}
#[test]
fn cached_snapshot_is_none_when_nothing_was_downloaded() {
let tmp = tempfile::tempdir().unwrap();
assert_eq!(cached_snapshot(tmp.path(), &jina()), None);
assert_eq!(cached_snapshot(&tmp.path().join("absent"), &jina()), None);
}
fn embedder() -> CachedModel {
crate::embedding::cached_model().unwrap()
}
fn repo_snapshot(cache: &Path, model: &CachedModel, revision: &str) -> PathBuf {
snapshots_dir(cache, &model.code).join(revision)
}
fn point_main_at(cache: &Path, model: &CachedModel, contents: &str) {
let refs = snapshots_dir(cache, &model.code)
.parent()
.unwrap()
.join("refs");
std::fs::create_dir_all(&refs).unwrap();
std::fs::write(refs.join("main"), contents).unwrap();
}
#[test]
fn main_ref_snapshot_is_the_complete_snapshot_refs_main_names() {
let tmp = tempfile::tempdir().unwrap();
let model = embedder();
seed(&repo_snapshot(tmp.path(), &model, "a-older"), &model.files);
let main = repo_snapshot(tmp.path(), &model, "b-main");
seed(&main, &model.files);
point_main_at(tmp.path(), &model, "b-main");
assert_eq!(main_ref_snapshot(tmp.path(), &model), Some(main));
}
#[test]
fn main_ref_snapshot_is_none_without_refs_main() {
let tmp = tempfile::tempdir().unwrap();
let model = embedder();
seed(&repo_snapshot(tmp.path(), &model, "rev1"), &model.files);
assert_eq!(main_ref_snapshot(tmp.path(), &model), None);
}
#[test]
fn main_ref_snapshot_is_none_when_refs_main_names_an_incomplete_snapshot() {
let tmp = tempfile::tempdir().unwrap();
let model = embedder();
seed(
&repo_snapshot(tmp.path(), &model, "a-complete"),
&model.files,
);
let main = repo_snapshot(tmp.path(), &model, "b-main");
seed(&main, &model.files);
std::fs::remove_file(main.join("tokenizer.json")).unwrap();
point_main_at(tmp.path(), &model, "b-main");
assert_eq!(main_ref_snapshot(tmp.path(), &model), None);
}
#[test]
fn main_ref_snapshot_is_none_when_refs_main_names_a_missing_snapshot() {
let tmp = tempfile::tempdir().unwrap();
let model = embedder();
seed(
&repo_snapshot(tmp.path(), &model, "a-complete"),
&model.files,
);
point_main_at(tmp.path(), &model, "b-gone");
assert_eq!(main_ref_snapshot(tmp.path(), &model), None);
}
#[test]
fn main_ref_snapshot_reads_refs_main_verbatim_like_hf_hub() {
let tmp = tempfile::tempdir().unwrap();
let model = embedder();
seed(&repo_snapshot(tmp.path(), &model, "rev1"), &model.files);
point_main_at(tmp.path(), &model, "rev1\n");
assert_eq!(main_ref_snapshot(tmp.path(), &model), None);
}
#[test]
fn the_embedders_loadable_snapshot_needs_refs_main() {
let tmp = tempfile::tempdir().unwrap();
let model = embedder();
let snap = repo_snapshot(tmp.path(), &model, "rev1");
seed(&snap, &model.files);
assert_eq!(model.loadable_snapshot(tmp.path()), None);
point_main_at(tmp.path(), &model, "rev1");
assert_eq!(model.loadable_snapshot(tmp.path()), Some(snap));
}
#[test]
fn the_rerankers_loadable_snapshot_is_any_complete_snapshot() {
let tmp = tempfile::tempdir().unwrap();
let model = jina();
let snap = repo_snapshot(tmp.path(), &model, "rev1");
seed(&snap, &model.files);
assert_eq!(model.loadable_snapshot(tmp.path()), Some(snap));
}
#[test]
fn snapshots_dir_follows_the_hugging_face_hub_layout() {
assert_eq!(
snapshots_dir(Path::new("/cache"), "jinaai/jina-reranker-v1-turbo-en"),
PathBuf::from("/cache/models--jinaai--jina-reranker-v1-turbo-en/snapshots")
);
}
#[test]
fn default_reranker_model_is_fastembeds_entry_for_the_daemon_default() {
let info = TextRerank::get_model_info(&parse_model(DEFAULT_RERANK_MODEL).unwrap());
let model = default_reranker_model().unwrap();
assert_eq!(model.code, info.model_code);
assert!(model.files.contains(&info.model_file), "{model:?}");
for file in &info.additional_files {
assert!(model.files.contains(file), "{model:?}");
}
for file in TOKENIZER_FILES {
assert!(model.files.iter().any(|f| f == file), "{model:?}");
}
}
#[test]
fn unset_override_resolves_under_the_os_user_cache_dir() {
let user_cache = dirs::cache_dir().expect("test host has a user cache dir");
let dir = resolve(None, Some(user_cache.clone())).unwrap();
assert_eq!(dir, user_cache.join("second-brain").join("models"));
assert!(dir.is_absolute());
}
#[test]
fn set_override_wins_over_the_user_cache_dir() {
let dir = resolve(
Some(OsString::from("/srv/models")),
Some(PathBuf::from("/home/u/.cache")),
)
.unwrap();
assert_eq!(dir, PathBuf::from("/srv/models"));
}
#[test]
fn empty_override_counts_as_unset() {
let dir = resolve(Some(OsString::new()), Some(PathBuf::from("/home/u/.cache"))).unwrap();
assert_eq!(dir, PathBuf::from("/home/u/.cache/second-brain/models"));
}
#[test]
fn relative_override_is_rejected() {
let err = resolve(
Some(OsString::from(".fastembed_cache")),
Some(PathBuf::from("/home/u/.cache")),
)
.unwrap_err();
assert!(err.to_string().contains(MODEL_CACHE_DIR_ENV));
}
#[test]
fn missing_user_cache_dir_is_an_error_not_a_cwd_fallback() {
let err = resolve(None, None).unwrap_err();
assert!(err.to_string().contains(MODEL_CACHE_DIR_ENV));
}
#[test]
fn relative_user_cache_dir_is_rejected() {
let err = resolve(None, Some(PathBuf::from("home/.cache"))).unwrap_err();
assert!(err.to_string().contains(MODEL_CACHE_DIR_ENV));
}
#[test]
fn model_cache_dir_returns_and_creates_the_override_dir() {
let tmp = tempfile::tempdir().unwrap();
let target = tmp.path().join("nested").join("models");
let _env = CacheDirOverride::new(&target);
let dir = model_cache_dir().unwrap();
assert_eq!(dir, target);
assert!(dir.is_dir());
}
}