Struct Hub 

pub struct Hub { /* private fields */ }

Manages interactions with GitHub repository releases and Hugging Face repositories

Format Rules

• GitHub Release

  • Use <tag>/<file> format.
  • Example: "yolo/v5-n-det.onnx".

• Hugging Face

  • With Hub::from_hf(owner, repo): File paths are interpreted relative to the repo root.
    • Example: "sentencepiece.bpe.model", "onnx/tokenizer.json".
  • With Hub::default(): Paths with three segments are interpreted as <owner>/<repo>/<file>.
    • Example: "BAAI/bge-m3/sentencepiece.bpe.model".

Examples

GitHub Release Download

let mut hub = Hub::default();
// let mut hub = Hub::new(owner, repo);  // Optional: Specify owner and repo if not using default
let path = hub.try_fetch("images/bus.jpg")?; // <tag>/<file> format

Hugging Face Download (Dedicated Hub)

let mut hub = Hub::from_hf("BAAI", "bge-m3")?;
let path = hub.try_fetch("sentencepiece.bpe.model")?; // Any format works
let path = hub.try_fetch("onnx/tokenizer.json")?; // Any format works

Hugging Face Download (Temporary)

let mut hub = Hub::default().try_fetch("BAAI/bge-m3/tokenizer_config.json")?; // <owner>/<repo>/<file> format

Errors

Methods in Hub return Result types. Errors may occur due to invalid paths, failed network requests, cache write failures, or mismatched file sizes during downloads.

Implementations

impl Hub

pub fn new(owner: &str, repo: &str) -> Self

pub fn from_hf(_owner: &str, _repo: &str) -> Result<Self>

pub fn try_fetch(&mut self, s: &str) -> Result<String>

Attempts to fetch a file from a local path, GitHub release, or Hugging Face repository.

The try_fetch method supports multiple scenarios:

1. Local file: If the provided string is a valid file path, the file is returned without downloading.
2. GitHub release URL: If the input matches a valid GitHub release URL, the corresponding file is downloaded.
3. Hugging Face repository: If the hub is configured for HF or the path contains HF format, files are downloaded from HF.
4. Default repository: If no explicit URL is provided, the method uses the default or configured repository.

Parameters

• s: A string representing the file to fetch. This can be:
  • A local file path.
  • A GitHub release URL (e.g., https://github.com/owner/repo/releases/download/tag/file).
  • A <tag>/<file> format for fetching from the default GitHub repository.
  • A HF repository file path (e.g., "sentencepiece.bpe.model" when using from_hf).
  • A temporary HF path format (e.g., "BAAI/bge-m3/sentencepiece.bpe.model").

Returns

• Result<String>: On success, returns the path to the fetched file.

Errors

• Returns an error if:
  • The file cannot be found locally.
  • The URL or tag is invalid.
  • Network operations fail after the maximum retry attempts.
  • HF repository access fails.

Examples

let mut hub = Hub::default();

// Fetch a file from a local path
let local_path = hub.try_fetch("local/path/to/file").expect("File not found");

// Fetch a file from a GitHub release URL
let url_path = hub.try_fetch("https://github.com/owner/repo/releases/download/tag/file")
    .expect("Failed to fetch file");

// Fetch a file using the default GitHub repository
let default_repo_path = hub.try_fetch("yolo/v5-n-det.onnx").expect("Failed to fetch file");

// Method 1: Fetch from HF repository using dedicated hub
let mut hf_hub = Hub::from_hf("BAAI", "bge-m3")?;
let hf_path = hf_hub.try_fetch("sentencepiece.bpe.model").expect("Failed to fetch HF file");

// Method 2: Fetch from HF repository using temporary path (doesn't change hub's owner/repo)
let temp_hf_path = Hub::default().try_fetch("BAAI/bge-m3/sentencepiece.bpe.model")
    .expect("Failed to fetch HF file");

pub fn tags(&self) -> Vec<String>

pub fn files(&self, tag: &str) -> Vec<String>

pub fn is_file_expired<P: AsRef<Path>>(file: P, ttl: &Duration) -> Result<bool>

pub fn download<P: AsRef<Path> + Debug>( &self, src: &str, dst: P, message: Option<&str>, ) -> Result<()>

Download a file from a github release to a specified path with a progress bar

pub fn is_valid_github_release_url( url: &str, ) -> Option<(String, String, String, String)>

pub fn with_owner(self, owner: &str) -> Self

pub fn with_repo(self, repo: &str) -> Self

pub fn with_ttl(self, x: u64) -> Self

pub fn with_max_attempts(self, x: u32) -> Self

pub fn info(&self) -> Result<()>

Displays repository information including files and releases.

For Hugging Face repositories, shows commit SHA and file tree. For GitHub repositories, shows releases with file counts and provides usage examples.

Trait Implementations

impl Debug for Hub

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Hub

fn default() -> Self

Returns the “default value” for a type.