use alloc::{
string::{
String,
ToString,
},
sync::Arc,
vec::Vec,
};
use core::marker::PhantomData;
use burn::tensor::Device;
use log::Level;
#[cfg(doc)]
use super::ResourceMap;
use super::{
Construct,
Deferred,
Loaded,
Pretrained,
PretrainedCache,
PretrainedProvider,
PretrainedRef,
not_found,
};
use crate::errors::{
BunsenError,
BunsenErrorKind,
BunsenResult,
LookupError,
ResultContext,
};
#[derive(Debug)]
pub struct PretrainedFactory<H: Construct> {
providers: Vec<Arc<dyn PretrainedProvider>>,
hook: PhantomData<H>,
}
impl<H: Construct> Clone for PretrainedFactory<H> {
fn clone(&self) -> Self {
Self {
providers: self.providers.clone(),
hook: PhantomData,
}
}
}
impl<H: Construct> Default for PretrainedFactory<H> {
fn default() -> Self {
Self::new()
}
}
impl<H: Construct> PretrainedFactory<H> {
pub fn new() -> Self {
Self {
providers: Vec::new(),
hook: PhantomData,
}
}
pub fn kit(&self) -> &'static str {
H::KIT
}
pub fn register(
&mut self,
provider: Arc<dyn PretrainedProvider>,
) -> BunsenResult<()> {
if self.provider(provider.name()).is_some() {
return Err(BunsenError::from_cause(
BunsenErrorKind::Illegal,
LookupError::duplicate("provider", provider.name()),
)
.context(H::KIT));
}
self.providers.push(provider);
Ok(())
}
pub fn with_provider(
mut self,
provider: Arc<dyn PretrainedProvider>,
) -> BunsenResult<Self> {
self.register(provider)?;
Ok(self)
}
pub fn with_providers(
mut self,
providers: impl IntoIterator<Item = Arc<dyn PretrainedProvider>>,
) -> BunsenResult<Self> {
for provider in providers {
self.register(provider)?;
}
Ok(self)
}
pub fn remove(
&mut self,
name: &str,
) -> Option<Arc<dyn PretrainedProvider>> {
let at = self.providers.iter().position(|p| p.name() == name)?;
Some(self.providers.remove(at))
}
pub fn providers(&self) -> &[Arc<dyn PretrainedProvider>] {
&self.providers
}
pub fn provider(
&self,
name: &str,
) -> Option<&Arc<dyn PretrainedProvider>> {
self.providers.iter().find(|p| p.name() == name)
}
pub fn list(&self) -> Vec<(String, Pretrained)> {
self.providers
.iter()
.flat_map(|provider| {
let name = provider.name().to_string();
provider
.list()
.into_iter()
.map(move |row| (name.clone(), row))
})
.collect()
}
pub fn ids(&self) -> Vec<String> {
self.providers.iter().flat_map(|p| p.ids()).collect()
}
pub fn for_prefab(
&self,
prefab: &str,
) -> Vec<(String, Pretrained)> {
self.providers
.iter()
.flat_map(|provider| {
let name = provider.name().to_string();
provider
.for_prefab(prefab)
.into_iter()
.map(move |row| (name.clone(), row))
})
.collect()
}
pub fn lookup(
&self,
spec: &str,
) -> BunsenResult<(String, Pretrained)> {
match self.find(spec, |provider, name| provider.lookup(name))? {
Some(found) => Ok(found),
None => Err(self.not_found(spec)),
}
}
pub fn resolve(
&self,
spec: &str,
cache: &PretrainedCache,
) -> BunsenResult<Deferred<H>> {
let resolve = || -> BunsenResult<Deferred<H>> {
let found = self.find(spec, |provider, name| provider.resolve(name, H::KIT, cache))?;
let (provider, pretrained) = match found {
Some(found) => found,
None => return Err(self.not_found(spec)),
};
Deferred::new(PretrainedRef::Named {
provider,
pretrained,
})
};
let defered = resolve().as_policy()?;
if log::log_enabled!(Level::Info) {
log::info!("Resolved pretrained model: {}\n{:#?}", spec, defered.model);
}
Ok(defered)
}
pub fn load(
&self,
spec: &str,
cache: &PretrainedCache,
device: &Device,
) -> BunsenResult<Loaded<H::Built>> {
self.resolve(spec, cache)?.load(cache, device)
}
pub(crate) fn find(
&self,
spec: &str,
ask: impl Fn(&dyn PretrainedProvider, &str) -> BunsenResult<Option<Pretrained>>,
) -> BunsenResult<Option<(String, Pretrained)>> {
if let Some((head, rest)) = spec.split_once(':')
&& let Some(provider) = self.provider(head)
{
return Ok(ask(provider.as_ref(), rest)?.map(|row| (provider.name().to_string(), row)));
}
for provider in &self.providers {
if !provider.answers_bare_names() {
continue;
}
if let Some(row) = ask(provider.as_ref(), spec)? {
return Ok(Some((provider.name().to_string(), row)));
}
}
Ok(None)
}
#[track_caller]
pub(crate) fn not_found(
&self,
spec: &str,
) -> BunsenError {
if let Some((head, rest)) = spec.split_once(':') {
if let Some(provider) = self.provider(head) {
let ids = provider.ids();
let ids: Vec<&str> = ids.iter().map(String::as_str).collect();
return not_found(Some(provider.name()), "pretrained", rest, &ids);
}
let names: Vec<&str> = self.providers.iter().map(|p| p.name()).collect();
return not_found(Some(H::KIT), "provider", head, &names);
}
let ids = self.ids();
let ids: Vec<&str> = ids.iter().map(String::as_str).collect();
not_found(Some(H::KIT), "pretrained", spec, &ids)
}
}
#[cfg(test)]
pub(crate) mod testing {
use alloc::{
format,
vec,
};
use core::sync::atomic::{
AtomicUsize,
Ordering,
};
use std::path::PathBuf;
use super::*;
use crate::data::pretrained::{
LoadedResources,
Resource,
ResourceMap,
Source,
};
#[derive(Debug, Default)]
pub struct ListsNothing {
pub lookups: AtomicUsize,
}
impl ListsNothing {
pub fn lookups(&self) -> usize {
self.lookups.load(Ordering::SeqCst)
}
}
impl PretrainedProvider for ListsNothing {
fn name(&self) -> &str {
"hub"
}
fn description(&self) -> &str {
"answers `hub:<org>/<repo>`; lists nothing"
}
fn origin(&self) -> Option<&str> {
Some("https://hub.example")
}
fn list(&self) -> Vec<Pretrained> {
Vec::new()
}
fn lookup(
&self,
name: &str,
) -> BunsenResult<Option<Pretrained>> {
self.lookups.fetch_add(1, Ordering::SeqCst);
let Some((org, repo)) = name.split_once('/') else {
return Ok(None);
};
let base = format!("https://hub.example/{org}/{repo}/resolve/main");
let file = |key: &str, file: &str, kind: &str| Resource {
key: key.to_string(),
file: file.to_string(),
sha256: None,
kind: Some(kind.to_string()),
namespace: "hub".to_string(),
sources: vec![Source::Url(format!("{base}/{file}"))],
};
let resources = ResourceMap::new(name)
.with_resource(file("checkpoint", "model.safetensors", "safetensors"))
.with_resource(file("config", "config.json", "json"));
Ok(Some(Pretrained {
name: name.to_string(),
aliases: Vec::new(),
description: format!("{org}/{repo}, from the hub"),
license: None,
origin: Some(base),
prefab: None,
resources,
}))
}
fn answers_bare_names(&self) -> bool {
false
}
}
#[derive(Debug, Default)]
pub struct Failing;
impl PretrainedProvider for Failing {
fn name(&self) -> &str {
"failing"
}
fn description(&self) -> &str {
"cannot be reached"
}
fn list(&self) -> Vec<Pretrained> {
Vec::new()
}
fn lookup(
&self,
_name: &str,
) -> BunsenResult<Option<Pretrained>> {
Err(BunsenError::unavailable("failing: unreachable"))
}
}
#[derive(Clone, Debug, Default)]
pub struct CheckpointPath;
impl Construct for CheckpointPath {
type Built = PathBuf;
const KIT: &'static str = "kit";
fn for_map(_map: &ResourceMap) -> BunsenResult<Self> {
Ok(Self)
}
fn construct(
&self,
_model: &PretrainedRef,
loaded: &LoadedResources,
_device: &Device,
) -> BunsenResult<Arc<PathBuf>> {
Ok(Arc::new(loaded.expect("checkpoint")?.to_path_buf()))
}
}
}
#[cfg(test)]
mod tests {
use alloc::vec;
use std::path::Path;
use super::{
testing::{
CheckpointPath,
Failing,
ListsNothing,
},
*,
};
use crate::{
data::pretrained::{
PretrainedGroup,
PretrainedTable,
Resource,
ResourceMap,
Source,
WELL_KNOWN,
},
errors::{
LookupProblem,
testing::{
ErrorMatcher,
predicate,
text,
},
},
};
fn row(
name: &str,
aliases: &[&str],
prefab: &str,
) -> Pretrained {
Pretrained {
name: name.to_string(),
aliases: aliases.iter().map(|a| a.to_string()).collect(),
description: format!("row {name}"),
license: None,
origin: None,
prefab: Some(prefab.to_string()),
resources: ResourceMap::new(name).with_resource(Resource {
key: "checkpoint".to_string(),
file: format!("{name}.pt"),
sha256: None,
kind: Some("pytorch".to_string()),
namespace: "t".to_string(),
sources: vec![Source::Url(format!("https://t.example/{name}.pt"))],
}),
}
}
fn local_row(
name: &str,
path: &Path,
) -> Pretrained {
Pretrained {
name: name.to_string(),
aliases: Vec::new(),
description: format!("row {name}, on disk"),
license: None,
origin: None,
prefab: None,
resources: ResourceMap::given(name, "checkpoint", path),
}
}
fn group(
name: &str,
items: Vec<Pretrained>,
) -> PretrainedGroup {
PretrainedGroup {
name: name.to_string(),
description: format!("group {name}"),
license: None,
origin: None,
items,
}
}
fn table(
name: &str,
groups: Vec<PretrainedGroup>,
) -> Arc<dyn PretrainedProvider> {
Arc::new(PretrainedTable {
name: name.to_string(),
description: format!("table {name}"),
groups,
})
}
fn well_known() -> Arc<dyn PretrainedProvider> {
table(
WELL_KNOWN,
vec![
group(
"a",
vec![
row("small", &["s"], "small"),
row("large-v1", &[], "large"),
row("large-v2", &["large"], "large"),
],
),
group(
"b",
vec![row("small", &[], "small"), row("tiny", &[], "tiny")],
),
],
)
}
fn offline_cache(dir: &std::path::Path) -> PretrainedCache {
use crate::data::{
cache::BunsenDiskCacheOptions,
pretrained::PretrainedCacheOptions,
};
PretrainedCache::new(
PretrainedCacheOptions::default()
.with_disk(
BunsenDiskCacheOptions::default()
.with_cache_dir(Some(dir.join("cache")))
.without_transfer_observers(),
)
.with_offline(true),
)
.unwrap()
}
fn factory() -> PretrainedFactory<CheckpointPath> {
PretrainedFactory::new()
.with_providers([well_known(), Arc::new(ListsNothing::default()) as _])
.unwrap()
}
#[test]
fn test_register_refuses_a_duplicate_name_and_remove_frees_it() {
let mut factory = PretrainedFactory::<CheckpointPath>::new()
.with_provider(well_known())
.unwrap();
assert_eq!(factory.kit(), "kit");
assert_eq!(factory.providers().len(), 1);
assert!(factory.provider(WELL_KNOWN).is_some());
ErrorMatcher::kind(BunsenErrorKind::Illegal)
.display(text::eq("kit: duplicate provider \"well-known\""))
.cause(predicate("a duplicate provider", |c: &LookupError| {
c.problem == LookupProblem::Duplicate
}))
.assert_err(&factory.register(well_known()));
assert_eq!(factory.providers().len(), 1);
assert!(factory.remove("nobody").is_none());
let removed = factory.remove(WELL_KNOWN).unwrap();
assert_eq!(removed.name(), WELL_KNOWN);
assert!(factory.providers().is_empty());
factory.register(well_known()).unwrap();
assert!(format!("{factory:?}").contains("PretrainedTable"));
assert_eq!(factory.clone().providers().len(), 1);
assert!(
PretrainedFactory::<CheckpointPath>::default()
.providers()
.is_empty()
);
assert!(
PretrainedFactory::<CheckpointPath>::new()
.with_providers([well_known(), well_known()])
.is_err()
);
}
#[test]
fn test_a_qualified_spec_goes_to_one_provider() {
let factory = factory();
let (provider, row) = factory.lookup("well-known:b/tiny").unwrap();
assert_eq!(
(provider.as_str(), row.name.as_str()),
("well-known", "b/tiny")
);
let (provider, row) = factory.lookup("well-known:large").unwrap();
assert_eq!(
(provider.as_str(), row.name.as_str()),
("well-known", "a/large-v2")
);
ErrorMatcher::kind(BunsenErrorKind::Lookup)
.display(text::starts_with("well-known: no pretrained \"a/tiny\""))
.message_contains("well-known:a/small")
.assert_err(&factory.lookup("well-known:a/tiny"));
ErrorMatcher::kind(BunsenErrorKind::Lookup)
.display(text::starts_with("kit: no provider \"nobody\""))
.cause(predicate("the providers there are", |c: &LookupError| {
c.candidates == ["well-known", "hub"]
}))
.assert_err(&factory.lookup("nobody:a/small"));
}
#[test]
fn test_a_bare_spec_searches_in_order_and_skips_decliners() {
let second = table(
"second",
vec![group(
"a",
vec![row("small", &[], "small"), row("only-here", &[], "x")],
)],
);
let factory = PretrainedFactory::<CheckpointPath>::new()
.with_providers([Arc::new(ListsNothing::default()) as _, well_known(), second])
.unwrap();
let (provider, row) = factory.lookup("small").unwrap();
assert_eq!(
(provider.as_str(), row.name.as_str()),
("well-known", "a/small")
);
let (provider, row) = factory.lookup("only-here").unwrap();
assert_eq!(
(provider.as_str(), row.name.as_str()),
("second", "a/only-here")
);
let (provider, row) = factory.lookup("second:a/small").unwrap();
assert_eq!(
(provider.as_str(), row.name.as_str()),
("second", "a/small")
);
let (_, row) = factory.lookup("tiny").unwrap();
assert_eq!(row.name, "b/tiny");
let (_, row) = factory.lookup("a/s").unwrap();
assert_eq!(row.name, "a/small");
ErrorMatcher::kind(BunsenErrorKind::Lookup)
.display(text::starts_with("kit: no pretrained \"gigantic\""))
.message_contains("well-known:a/small")
.message_contains("second:a/only-here")
.assert_err(&factory.lookup("gigantic"));
let hub = factory.provider("hub").unwrap();
assert!(!hub.answers_bare_names());
}
#[test]
fn test_a_lookup_only_provider_answers_qualified_names_only() {
let hub = Arc::new(ListsNothing::default());
let factory = PretrainedFactory::<CheckpointPath>::new()
.with_providers([well_known(), hub.clone() as _])
.unwrap();
assert_eq!(factory.list().len(), 5, "the hub lists nothing");
assert_eq!(factory.ids().len(), 5);
assert!(factory.ids().iter().all(|id| id.starts_with("well-known:")));
let (provider, row) = factory.lookup("hub:openai/whisper-base").unwrap();
assert_eq!(provider, "hub");
assert_eq!(row.name, "openai/whisper-base");
assert_eq!(row.resources.keys(), ["checkpoint", "config"]);
assert_eq!(
row.resources.get("checkpoint").unwrap().urls(),
["https://hub.example/openai/whisper-base/resolve/main/model.safetensors"]
);
assert_eq!(hub.lookups(), 1);
ErrorMatcher::kind(BunsenErrorKind::Lookup).assert_err(&factory.lookup("whisper-base"));
assert_eq!(hub.lookups(), 1, "a bare name never reached the hub");
ErrorMatcher::kind(BunsenErrorKind::Lookup)
.display(text::eq("hub: no pretrained \"nonsense\""))
.cause(predicate("no candidates", |c: &LookupError| {
c.candidates.is_empty()
}))
.assert_err(&factory.lookup("hub:nonsense"));
assert_eq!(hub.lookups(), 2);
}
#[test]
fn test_a_providers_error_aborts_the_lookup() {
let factory = PretrainedFactory::<CheckpointPath>::new()
.with_providers([Arc::new(Failing) as _, well_known()])
.unwrap();
ErrorMatcher::kind(BunsenErrorKind::Unavailable).assert_err(&factory.lookup("failing:x"));
ErrorMatcher::kind(BunsenErrorKind::Unavailable).assert_err(&factory.lookup("small"));
assert_eq!(
factory.lookup("well-known:small").unwrap().1.name,
"a/small"
);
}
#[test]
fn test_resolve_names_and_aliases_only() {
let factory = factory();
let dir = tempfile::tempdir().unwrap();
let cache = offline_cache(dir.path());
let model = factory.resolve("well-known:a/small", &cache).unwrap();
assert_eq!(model.id(), "well-known:a/small");
let model = factory.resolve("s", &cache).unwrap();
assert_eq!(model.id(), "well-known:a/small");
assert_eq!(
model.model.named().map(|(p, row)| (p, row.name.as_str())),
Some(("well-known", "a/small"))
);
assert_eq!(model.to_map().name, "well-known:a/small");
assert!(format!("{:?}", model.hook).contains("CheckpointPath"));
let model = factory.resolve("hub:x/y", &cache).unwrap();
assert_eq!(model.id(), "hub:x/y");
let file = dir.path().join("ckpt.pt");
std::fs::write(&file, b"x").unwrap();
ErrorMatcher::kind(BunsenErrorKind::Lookup)
.message_contains("well-known:a/small")
.assert_err(&factory.resolve(file.to_str().unwrap(), &cache));
ErrorMatcher::kind(BunsenErrorKind::Lookup)
.assert_err(&factory.resolve("well-known:a/gigantic", &cache));
}
#[test]
fn test_load_goes_through_the_hook() {
use crate::{
data::pretrained::Provenance,
support::testing::cpu_device,
};
let dir = tempfile::tempdir().unwrap();
let cache = offline_cache(dir.path());
let file = dir.path().join("ckpt.pt");
std::fs::write(&file, b"x").unwrap();
let on_disk = table("disk", vec![group("l", vec![local_row("ckpt", &file)])]);
let factory = PretrainedFactory::<CheckpointPath>::new()
.with_providers([well_known(), on_disk])
.unwrap();
let loaded = factory.load("disk:l/ckpt", &cache, &cpu_device()).unwrap();
assert_eq!(*loaded.handle, file);
assert_eq!(loaded.name, "disk:l/ckpt");
assert_eq!(
loaded.resources.get("checkpoint").unwrap().provenance,
Provenance::LocalDir
);
let other = dir.path().join("other.pt");
std::fs::write(&other, b"y").unwrap();
let loaded = factory
.resolve("ckpt", &cache)
.unwrap()
.with_overlay(ResourceMap::given("mine", "checkpoint", &other))
.unwrap()
.load(&cache, &cpu_device())
.unwrap();
assert_eq!(*loaded.handle, other);
ErrorMatcher::kind(BunsenErrorKind::Policy)
.frame_contains("loading kit \"well-known:a/small\"")
.message_contains("the cache is offline")
.assert_err(&factory.load("well-known:a/small", &cache, &cpu_device()));
}
#[test]
fn test_list_ids_and_for_prefab_cover_every_provider() {
let factory = factory();
let listed: Vec<String> = factory
.list()
.iter()
.map(|(p, row)| format!("{p}:{}", row.name))
.collect();
assert_eq!(listed, factory.ids());
assert_eq!(
factory.ids(),
[
"well-known:a/small",
"well-known:a/large-v1",
"well-known:a/large-v2",
"well-known:b/small",
"well-known:b/tiny",
]
);
let small: Vec<String> = factory
.for_prefab("small")
.iter()
.map(|(p, row)| format!("{p}:{}", row.name))
.collect();
assert_eq!(small, ["well-known:a/small", "well-known:b/small"]);
assert!(factory.for_prefab("nothing").is_empty());
}
}