Class: DurableHuggingfaceHub::HfApi

Inherits:
Object
  • Object
show all
Defined in:
lib/durable_huggingface_hub/hf_api.rb

Overview

Main API client for interacting with the HuggingFace Hub

This class provides methods for accessing and managing repositories, models, datasets, and spaces on the HuggingFace Hub. It handles authentication, request management, and response parsing.

Examples:

Initialize with default configuration

api = DurableHuggingfaceHub::HfApi.new

Initialize with custom token and endpoint

api = DurableHuggingfaceHub::HfApi.new(
  token: "hf_...",
  endpoint: "https://huggingface.co"
)

Get model information

model = api.model_info("bert-base-uncased")
puts model.id
puts model.downloads

List models with filtering

models = api.list_models(filter: "text-classification", limit: 10)
models.each { |m| puts m.id }

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(token: nil, endpoint: nil) ⇒ HfApi

Initialize a new HfApi client

Examples:

Create client with auto-detected token

api = DurableHuggingfaceHub::HfApi.new

Create client with explicit token

api = DurableHuggingfaceHub::HfApi.new(token: "hf_...")

Create client with custom endpoint

api = DurableHuggingfaceHub::HfApi.new(
  endpoint: "https://custom-hub.example.com"
)

Parameters:

  • token (String, nil) (defaults to: nil) —

    HuggingFace authentication token. If nil, will attempt to retrieve from environment or token file.

  • endpoint (String, nil) (defaults to: nil) —

    Base URL for the HuggingFace Hub API. Defaults to Constants::ENDPOINT.



63
64
65
66
67
68
69
70
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 63

def initialize(token: nil, endpoint: nil)
  @token = token || DurableHuggingfaceHub::Utils::Auth.get_token
  @endpoint = endpoint || DurableHuggingfaceHub.configuration.endpoint
  @http_client = DurableHuggingfaceHub::Utils::HttpClient.new(
    endpoint: @endpoint,
    token: @token
  )
end

Instance Attribute Details

#endpoint ⇒ String (readonly)

Returns Base endpoint URL for the HuggingFace Hub.

Returns:

  • (String) —

    Base endpoint URL for the HuggingFace Hub



41
42
43
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 41

def endpoint
  @endpoint
end

#http_client ⇒ DurableHuggingfaceHub::Utils::HttpClient (readonly)

Returns HTTP client instance.

Returns:



44
45
46
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 44

def http_client
  @http_client
end

#token ⇒ String? (readonly)

Returns Authentication token for API requests.

Returns:

  • (String, nil) —

    Authentication token for API requests



38
39
40
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 38

def token
  @token
end

Instance Method Details

#build_tree_structure(items) ⇒ Hash

Build a tree structure from the API response.

Parameters:

  • items (Array<Hash>) —

    Raw API response items

Returns:

  • (Hash) —

    Organized tree structure



586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 586

def build_tree_structure(items)
  tree = {}

  items.each do |item|
    path = item["path"]
    path_parts = path.split("/")

    # Navigate/create nested structure
    current = tree
    path_parts.each_with_index do |part, index|
      is_last = index == path_parts.length - 1

      if is_last
        # This is a file
        current[part] = {
          type: "file",
          size: item["size"],
          oid: item["oid"], # SHA for Git LFS files
          lfs: item["lfs"] # LFS information if applicable
        }.compact
      else
        # This is a directory
        current[part] ||= { type: "directory", children: {} }
        current = current[part][:children]
      end
    end
  end

  tree
end

#create_branch(repo_id:, branch_name:, repo_type: "model", revision: nil, timeout: nil) ⇒ String

Create a new branch in a repository.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • branch_name (String) —

    The name of the new branch.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA) to branch from. Defaults to “main”.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (String) —

    The name of the newly created branch.

Raises:



1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 1055

def create_branch(repo_id:, branch_name:, repo_type: "model", revision: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  path = "/api/#{repo_type}s/#{repo_id}/branches"
   payload = {
     name: branch_name,
     revision: revision
   }.compact

   response = http_client.post(path, body: payload, timeout: timeout)
   body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
   body["name"]
end

#create_commit(repo_id:, operations:, repo_type: "model", revision: nil, commit_message: nil, commit_description: nil, parent_commit: nil, timeout: nil) ⇒ String

Create a new commit with multiple file operations.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • operations (Array<Hash>) —

    An array of file operations (add, delete, update). Each operation is a hash with at least a ‘:path` and `:operation` key. Example: [{ path: “file.txt”, operation: “add”, content: “new content” }]

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA) to commit to. Defaults to “main”.

  • commit_message (String, nil) (defaults to: nil) —

    A custom commit message for the upload.

  • commit_description (String, nil) (defaults to: nil) —

    A custom commit description.

  • parent_commit (String, nil) (defaults to: nil) —

    The SHA of the parent commit.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (String) —

    The SHA of the newly created commit.

Raises:



1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 1016

def create_commit(
  repo_id:,
  operations:,
  repo_type: "model",
  revision: nil,
  commit_message: nil,
  commit_description: nil,
  parent_commit: nil,
  timeout: nil
)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  path = "/api/#{repo_type}s/#{repo_id}/commits/#{revision}"
  payload = {
    operations: operations,
    commit_message: commit_message || "Commit from Ruby client",
    commit_description: commit_description,
    parent_commit: parent_commit
  }.compact

  response = http_client.post(path, body: payload, timeout: timeout)
  body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
  body["commit_id"]
end

#create_repo(repo_id:, repo_type: "model", private: false, organization: nil, timeout: nil) ⇒ String

Create a new repository on the HuggingFace Hub.

Parameters:

  • repo_id (String) —

    The ID of the repository to create (e.g., “my-username/my-repo”).

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository (“model”, “dataset”, or “space”). Defaults to “model”.

  • private (Boolean) (defaults to: false) —

    Whether the repository should be private. Defaults to false.

  • organization (String, nil) (defaults to: nil) —

    The organization namespace to create the repository under. If nil, the repository is created under the authenticated user’s namespace.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (String) —

    The URL of the newly created repository.

Raises:



628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 628

def create_repo(repo_id:, repo_type: "model", private: false, organization: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)

  # Extract organization from repo_id if not provided
  repo_parts = repo_id.split("/")
  if organization.nil? && repo_parts.length == 2
    # Get current username to check if it's a personal repo
    current_user = whoami
    potential_org = repo_parts[0]
    # Only set organization if it's not the current user
    organization = potential_org unless potential_org == current_user.name
  end
  repo_name = repo_parts.last

  path = "/api/repos/create"
  payload = {
    name: repo_name,
    private: private
  }
  payload[:type] = repo_type if repo_type != "model"
  payload[:organization] = organization if organization

  response = http_client.post(path, body: payload, timeout: timeout)
  body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
  body["url"]
end

#create_tag(repo_id:, tag_name:, repo_type: "model", revision: nil, message: nil, timeout: nil) ⇒ String

Create a new tag in a repository.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • tag_name (String) —

    The name of the new tag.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA) to tag from. Defaults to “main”.

  • message (String, nil) (defaults to: nil) —

    An optional message for the tag.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (String) —

    The name of the newly created tag.

Raises:



1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 1104

def create_tag(repo_id:, tag_name:, repo_type: "model", revision: nil, message: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  path = "/api/#{repo_type}s/#{repo_id}/tags"
   payload = {
     name: tag_name,
     revision: revision,
     message: message
   }.compact

   response = http_client.post(path, body: payload, timeout: timeout)
   body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
   body["name"]
end

#dataset_info(repo_id, revision: nil, timeout: nil) ⇒ DurableHuggingfaceHub::Types::DatasetInfo

Get information about a specific dataset

This is a convenience method that calls #repo_info with repo_type: “dataset”.

Examples:

Get dataset info

dataset = api.dataset_info("squad")
puts "Downloads: #{dataset.downloads}"
puts "Tags: #{dataset.tags}"

Parameters:

  • repo_id (String) —

    Dataset repository identifier

  • revision (String, nil) (defaults to: nil) —

    Git revision (branch, tag, or commit SHA). Defaults to “main”

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:

Raises:



193
194
195
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 193

def dataset_info(repo_id, revision: nil, timeout: nil)
  repo_info(repo_id, repo_type: "dataset", revision: revision, timeout: timeout)
end

#delete_branch(repo_id:, branch_name:, repo_type: "model", timeout: nil) ⇒ Boolean

Delete a branch from a repository.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • branch_name (String) —

    The name of the branch to delete.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Boolean) —

    True if the branch was successfully deleted.

Raises:



1083
1084
1085
1086
1087
1088
1089
1090
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 1083

def delete_branch(repo_id:, branch_name:, repo_type: "model", timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)

  path = "/api/#{repo_type}s/#{repo_id}/branches/#{branch_name}"
  http_client.delete(path)
  true
end

#delete_file(repo_id:, path_in_repo:, repo_type: "model", revision: nil, commit_message: nil, commit_description: nil, timeout: nil) ⇒ Boolean

Delete a file from a repository on the HuggingFace Hub.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • path_in_repo (String) —

    The path to the file within the repository to delete.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA) to delete from. Defaults to “main”.

  • commit_message (String, nil) (defaults to: nil) —

    A custom commit message for the deletion.

  • commit_description (String, nil) (defaults to: nil) —

    A custom commit description.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Boolean) —

    True if the file was successfully deleted.

Raises:



896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 896

def delete_file(
  repo_id:,
  path_in_repo:,
  repo_type: "model",
  revision: nil,
  commit_message: nil,
  commit_description: nil,
  timeout: nil
)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  path = "/api/#{repo_type}s/#{repo_id}/upload/#{path_in_repo}"
  params = {
    commit_message: commit_message || "Delete #{path_in_repo}",
    commit_description: commit_description,
    revision: revision
  }.compact

  http_client.delete(path, params: params)
  true
end

#delete_folder(repo_id:, folder_path_in_repo:, repo_type: "model", revision: nil, commit_message: nil, commit_description: nil, timeout: nil) ⇒ Boolean

Delete an entire folder from a repository on the HuggingFace Hub.

This method lists all files within the specified folder in the repository and deletes them one by one.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • folder_path_in_repo (String) —

    The path to the folder within the repository to delete.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA) to delete from. Defaults to “main”.

  • commit_message (String, nil) (defaults to: nil) —

    A custom commit message for the deletion.

  • commit_description (String, nil) (defaults to: nil) —

    A custom commit description.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Boolean) —

    True if the folder and its contents were successfully deleted.

Raises:



937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 937

def delete_folder(
  repo_id:,
  folder_path_in_repo:,
  repo_type: "model",
  revision: nil,
  commit_message: nil,
  commit_description: nil,
  timeout: nil
)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  # List all files in the folder
  files_to_delete = list_repo_files(
    repo_id: repo_id,
    repo_type: repo_type,
    revision: revision,
    timeout: timeout
  ).select { |file_path| file_path.start_with?(folder_path_in_repo) }

  # Delete each file
  files_to_delete.each do |file_path|
    delete_file(
      repo_id: repo_id,
      path_in_repo: file_path,
      repo_type: repo_type,
      revision: revision,
      commit_message: commit_message || "Delete #{file_path} from #{folder_path_in_repo}",
      commit_description: commit_description,
      timeout: timeout
    )
  end
  true
end

#delete_repo(repo_id:, repo_type: "model", token: nil, timeout: nil) ⇒ Boolean

Delete a repository from the HuggingFace Hub.

Parameters:

  • repo_id (String) —

    The ID of the repository to delete (e.g., “my-username/my-repo”).

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository (“model”, “dataset”, or “space”). Defaults to “model”.

  • token (String, nil) (defaults to: nil) —

    HuggingFace API token. If nil, will attempt to retrieve from environment or token file.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Boolean) —

    True if the repository was successfully deleted.

Raises:



666
667
668
669
670
671
672
673
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 666

def delete_repo(repo_id:, repo_type: "model", token: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)

  path = "/api/#{repo_type}s/#{repo_id}"
  http_client.delete(path)
  true
end

#delete_tag(repo_id:, tag_name:, repo_type: "model", timeout: nil) ⇒ Boolean

Delete a tag from a repository.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • tag_name (String) —

    The name of the tag to delete.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Boolean) —

    True if the tag was successfully deleted.

Raises:



1133
1134
1135
1136
1137
1138
1139
1140
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 1133

def delete_tag(repo_id:, tag_name:, repo_type: "model", timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)

  path = "/api/#{repo_type}s/#{repo_id}/tags/#{tag_name}"
  http_client.delete(path)
  true
end

#duplicate_space(from_repo_id:, to_repo_id:, private: nil, organization: nil, timeout: nil) ⇒ String

Duplicate a Space repository.

Parameters:

  • from_repo_id (String) —

    The ID of the Space to duplicate.

  • to_repo_id (String) —

    The ID for the new duplicated Space.

  • private (Boolean, nil) (defaults to: nil) —

    Whether the new Space should be private. Defaults to the original Space’s visibility.

  • organization (String, nil) (defaults to: nil) —

    The organization namespace to create the new Space under.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (String) —

    The URL of the newly duplicated Space.

Raises:



768
769
770
771
772
773
774
775
776
777
778
779
780
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 768

def duplicate_space(from_repo_id:, to_repo_id:, private: nil, organization: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(from_repo_id)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(to_repo_id)

  path = "/api/spaces/#{from_repo_id}/duplicate"
  payload = { newPath: to_repo_id }
  payload[:private] = private unless private.nil?
  payload[:organization] = organization unless organization.nil?

  response = http_client.post(path, body: payload, timeout: timeout)
  body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
  body["url"]
end

#file_exists(repo_id:, path_in_repo:, repo_type: "model", revision: nil, timeout: nil) ⇒ Boolean

Check if a file exists in a repository on the HuggingFace Hub.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • path_in_repo (String) —

    The path to the file within the repository to check.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA) to check. Defaults to “main”.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Boolean) —

    True if the file exists, false otherwise.

Raises:



985
986
987
988
989
990
991
992
993
994
995
996
997
998
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 985

def file_exists(repo_id:, path_in_repo:, repo_type: "model", revision: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  path = "/api/#{repo_type}s/#{repo_id}/resolve/#{revision}/#{path_in_repo}"
   begin
     http_client.head(path, timeout: timeout)
     true
   rescue DurableHuggingfaceHub::RepositoryNotFoundError, DurableHuggingfaceHub::EntryNotFoundError
     false
   end
end

#get_hf_file_metadata(repo_id:, filename:, repo_type: "model", revision: nil, timeout: nil) ⇒ Hash

Get metadata about a file in a repository without downloading it.

This method retrieves file metadata including size, ETag, and other information from the HuggingFace Hub API without downloading the actual file content.

Examples:

Get metadata for a model file

metadata = api.get_hf_file_metadata(
  repo_id: "bert-base-uncased",
  filename: "config.json"
)
puts "Size: #{metadata[:size]} bytes"
puts "ETag: #{metadata[:etag]}"

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • filename (String) —

    The path to the file within the repository.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA). Defaults to “main”.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Hash) —

    File metadata including :size, :etag, :commit_hash, :last_modified, etc.

Raises:



490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 490

def get_hf_file_metadata(repo_id:, filename:, repo_type: "model", revision: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  DurableHuggingfaceHub::Utils::Validators.validate_filename(filename)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  path = "/api/#{repo_type}s/#{repo_id}/resolve/#{revision}/#{filename}"

  begin
    response = http_client.head(path, timeout: timeout)

    # Extract metadata from response headers
    headers = response.headers
    {
      size: headers["x-linked-size"]&.to_i,
      etag: DurableHuggingfaceHub::FileDownload.extract_etag(headers["etag"] || headers["x-linked-etag"]),
      commit_hash: headers["x-repo-commit"],
      last_modified: headers["last-modified"] ? Time.parse(headers["last-modified"]) : nil,
      content_type: headers["content-type"],
      filename: filename,
      repo_id: repo_id,
      repo_type: repo_type,
      revision: revision
    }.compact
  rescue DurableHuggingfaceHub::EntryNotFoundError
    raise
  rescue DurableHuggingfaceHub::HfHubHTTPError => e
    # Convert 404 to EntryNotFoundError for consistency
    if e.status_code == 404
      raise DurableHuggingfaceHub::EntryNotFoundError.new(
        "File #{filename} not found in #{repo_id}@#{revision}"
      )
    end
    raise
  end
end

#get_paths_info(repo_id:, paths:, repo_type: "model", revision: nil, timeout: nil) ⇒ Array<Hash>

Get metadata for multiple paths in a repository.

This method efficiently retrieves metadata for multiple files or paths in a repository using batch requests where possible.

Examples:

Get metadata for multiple files

paths = ["config.json", "pytorch_model.bin", "tokenizer.json"]
metadata_list = api.get_paths_info(
  repo_id: "bert-base-uncased",
  paths: paths
)
metadata_list.each_with_index do |metadata, i|
  if metadata
    puts "#{paths[i]}: #{metadata[:size]} bytes"
  else
    puts "#{paths[i]}: not found"
  end
end

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • paths (Array<String>) —

    Array of file paths within the repository.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA). Defaults to “main”.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Array<Hash>) —

    Array of metadata hashes, one for each path. Missing files return nil.

Raises:



557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 557

def get_paths_info(repo_id:, paths:, repo_type: "model", revision: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  raise ArgumentError, "paths must be an array" unless paths.is_a?(Array)
  paths.each { |path| DurableHuggingfaceHub::Utils::Validators.validate_filename(path) }
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  # For now, implement sequentially. In the future, this could be optimized
  # with concurrent requests or batch API calls if available.
  paths.map do |path|
    begin
      get_hf_file_metadata(
        repo_id: repo_id,
        filename: path,
        repo_type: repo_type,
        revision: revision,
        timeout: timeout
      )
    rescue DurableHuggingfaceHub::EntryNotFoundError
      nil # Return nil for missing files
    end
  end
end

#list_datasets(filter: nil, author: nil, search: nil, sort: nil, direction: nil, limit: nil, full: false, timeout: nil) ⇒ Array<DurableHuggingfaceHub::Types::DatasetInfo>

List datasets from the HuggingFace Hub with optional filtering

Returns a list of datasets matching the specified criteria.

Examples:

List popular datasets

datasets = api.list_datasets(sort: "downloads", limit: 10)

Parameters:

  • filter (String, Hash, nil) (defaults to: nil) —

    Filter criteria

  • author (String, nil) (defaults to: nil) —

    Filter by author/organization

  • search (String, nil) (defaults to: nil) —

    Search query

  • sort (String, Symbol, nil) (defaults to: nil) —

    Sort criterion

  • direction (Integer, nil) (defaults to: nil) —

    Sort direction: -1 for descending, 1 for ascending

  • limit (Integer, nil) (defaults to: nil) —

    Maximum number of results

  • full (Boolean) (defaults to: false) —

    Fetch full dataset information

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:



305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 305

def list_datasets(filter: nil, author: nil, search: nil, sort: nil,
                  direction: nil, limit: nil, full: false, timeout: nil)
  path = "/api/datasets"
  params = build_list_params(
    filter: filter,
    author: author,
    search: search,
    sort: sort,
    direction: direction,
    limit: limit,
    full: full
  )

   response = http_client.get(path, params: params, timeout: timeout)
   body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
   body.map { |dataset_data| DurableHuggingfaceHub::Types::DatasetInfo.from_hash(dataset_data) }
end

#list_lfs_files(repo_id:, repo_type: "model", revision: nil, timeout: nil) ⇒ Array<Hash>

List Git LFS files in a repository.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA) to list LFS files from. Defaults to “main”.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Array<Hash>) —

    A list of LFS file information hashes.

Raises:



1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 1216

def list_lfs_files(repo_id:, repo_type: "model", revision: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  path = "/api/#{repo_type}s/#{repo_id}/lfs/objects"
  params = { revision: revision }.compact

   response = http_client.get(path, params: params, timeout: timeout)
   response.body.is_a?(String) ? JSON.parse(response.body) : response.body
end

#list_models(filter: nil, author: nil, search: nil, sort: nil, direction: nil, limit: nil, full: false, timeout: nil) ⇒ Array<DurableHuggingfaceHub::Types::ModelInfo>

List models from the HuggingFace Hub with optional filtering

Returns a list of models matching the specified criteria. Results can be filtered by tags, author, search query, and sorted by various metrics.

Examples:

List all models

models = api.list_models

List models by author

models = api.list_models(author: "google")

Search for specific models

models = api.list_models(search: "bert")

Filter by task and sort by downloads

models = api.list_models(
  filter: {task: "text-classification"},
  sort: "downloads",
  direction: -1,
  limit: 10
)

Filter by multiple criteria

models = api.list_models(
  filter: {
    author: "facebook",
    library: "pytorch",
    language: "en"
  },
  limit: 20
)

Parameters:

  • filter (String, Hash, nil) (defaults to: nil) —

    Filter criteria:

    • String: Search query or single tag

    • Hash: Structured filters (e.g., “google”, task: “text-classification”)

  • author (String, nil) (defaults to: nil) —

    Filter by author/organization

  • search (String, nil) (defaults to: nil) —

    Search query for model names and descriptions

  • sort (String, Symbol, nil) (defaults to: nil) —

    Sort criterion: “downloads”, “likes”, “updated”, “created”, “trending”

  • direction (Integer, nil) (defaults to: nil) —

    Sort direction: -1 for descending, 1 for ascending

  • limit (Integer, nil) (defaults to: nil) —

    Maximum number of results to return

  • full (Boolean) (defaults to: false) —

    If true, fetch full model information (slower)

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:

Raises:



268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 268

def list_models(filter: nil, author: nil, search: nil, sort: nil,
                direction: nil, limit: nil, full: false, timeout: nil)
  path = "/api/models"
  params = build_list_params(
    filter: filter,
    author: author,
    search: search,
    sort: sort,
    direction: direction,
    limit: limit,
    full: full
  )

   response = http_client.get(path, params: params, timeout: timeout)

   # Response is an array of model objects
   body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
   body.map { |model_data| DurableHuggingfaceHub::Types::ModelInfo.from_hash(model_data) }
end

#list_repo_commits(repo_id:, repo_type: "model", revision: nil, limit: nil, timeout: nil) ⇒ Array<DurableHuggingfaceHub::Types::CommitInfo>

List commit history for a repository.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA) to list commits from. Defaults to “main”.

  • limit (Integer, nil) (defaults to: nil) —

    The maximum number of commits to return.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

Raises:



1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 1177

def list_repo_commits(repo_id:, repo_type: "model", revision: nil, limit: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  path = "/api/#{repo_type}s/#{repo_id}/commits"
  params = {
    revision: revision,
    limit: limit
  }.compact

   response = http_client.get(path, params: params, timeout: timeout)
   body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
   body.map do |commit_data|
    # Flatten the nested commit structure
    commit = commit_data["commit"]
    author = commit["author"]
    {
      oid: commit["id"],
      title: commit["message"]&.split("\n")&.first, # First line as title
      message: commit["message"],
      date: author ? Time.parse(author["date"]) : nil,
      authors: author ? [author["name"]] : nil
    }.compact
  end.map { |data| DurableHuggingfaceHub::Types::CommitInfo.from_hash(data) }
end

#list_repo_files(repo_id:, repo_type: "model", revision: nil, timeout: nil) ⇒ Array<String>

List files in a repository.

Parameters:

  • repo_id (String) —

    Repository ID

  • repo_type (String, Symbol) (defaults to: "model") —

    Type of repository (“model”, “dataset”, or “space”)

  • revision (String, nil) (defaults to: nil) —

    Git revision (branch, tag, or commit SHA). Defaults to “main”

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:

  • (Array<String>) —

    List of file paths in the repository

Raises:



408
409
410
411
412
413
414
415
416
417
418
419
420
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 408

def list_repo_files(repo_id:, repo_type: "model", revision: nil, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision

  path = "/api/#{repo_type}s/#{repo_id}/tree"
  params = { recursive: true }
  params[:revision] = revision if revision

  response = http_client.get(path, params: params, timeout: timeout)
  body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
  body.map { |file_data| file_data["path"] }
end

#list_repo_refs(repo_id:, repo_type: "model", timeout: nil) ⇒ Hash

List branches and tags (refs) for a repository.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Hash) —

    A hash containing arrays of “branches” and “tags”.

Raises:



1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 1151

def list_repo_refs(repo_id:, repo_type: "model", timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)

   path = "/api/#{repo_type}s/#{repo_id}/refs"
   response = http_client.get(path, timeout: timeout)

   body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
   branches = body["branches"].map { |branch_data| DurableHuggingfaceHub::Types::GitRefInfo.from_hash(branch_data) }
   tags = body["tags"].map { |tag_data| DurableHuggingfaceHub::Types::GitRefInfo.from_hash(tag_data) }

  { branches: branches, tags: tags }
end

#list_repo_tree(repo_id:, repo_type: "model", revision: nil, path: nil, recursive: false, timeout: nil) ⇒ Hash

List repository contents in a hierarchical tree structure.

This method provides a tree-like view of the repository contents, organized by directories and files with their metadata.

Examples:

Get repository tree

tree = api.list_repo_tree(repo_id: "bert-base-uncased")
puts tree.keys # ["config.json", "pytorch_model.bin", "tokenizer.json", ...]

Get tree for a subdirectory

subtree = api.list_repo_tree(
  repo_id: "my-model",
  path: "checkpoints"
)

Parameters:

  • repo_id (String) —

    Repository ID

  • repo_type (String, Symbol) (defaults to: "model") —

    Type of repository (“model”, “dataset”, or “space”)

  • revision (String, nil) (defaults to: nil) —

    Git revision (branch, tag, or commit SHA). Defaults to “main”

  • path (String, nil) (defaults to: nil) —

    Path within repository to list (for subdirectories)

  • recursive (Boolean) (defaults to: false) —

    Whether to recursively list subdirectories. Defaults to false

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:

  • (Hash) —

    Tree structure with directories and files

Raises:



446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 446

def list_repo_tree(repo_id:, repo_type: "model", revision: nil, path: nil, recursive: false, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  # Build the API path
  api_path = "/api/#{repo_type}s/#{repo_id}/tree"
  api_path += "/#{path}" if path

  params = { recursive: recursive }
  params[:revision] = revision if revision

   response = http_client.get(api_path, params: params, timeout: timeout)

   # Organize the response into a tree structure
   body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
   build_tree_structure(body)
end

#list_spaces(filter: nil, author: nil, search: nil, sort: nil, direction: nil, limit: nil, full: false, timeout: nil) ⇒ Array<DurableHuggingfaceHub::Types::SpaceInfo>

List spaces from the HuggingFace Hub with optional filtering

Returns a list of spaces matching the specified criteria.

Examples:

List trending spaces

spaces = api.list_spaces(sort: "trending", limit: 10)

Parameters:

  • filter (String, Hash, nil) (defaults to: nil) —

    Filter criteria

  • author (String, nil) (defaults to: nil) —

    Filter by author/organization

  • search (String, nil) (defaults to: nil) —

    Search query

  • sort (String, Symbol, nil) (defaults to: nil) —

    Sort criterion

  • direction (Integer, nil) (defaults to: nil) —

    Sort direction: -1 for descending, 1 for ascending

  • limit (Integer, nil) (defaults to: nil) —

    Maximum number of results

  • full (Boolean) (defaults to: false) —

    Fetch full space information

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:



340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 340

def list_spaces(filter: nil, author: nil, search: nil, sort: nil,
                direction: nil, limit: nil, full: false, timeout: nil)
  path = "/api/spaces"
  params = build_list_params(
    filter: filter,
    author: author,
    search: search,
    sort: sort,
    direction: direction,
    limit: limit,
    full: full
  )

   response = http_client.get(path, params: params, timeout: timeout)
   body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
   body.map { |space_data| DurableHuggingfaceHub::Types::SpaceInfo.from_hash(space_data) }
end

#model_info(repo_id, revision: nil, timeout: nil) ⇒ DurableHuggingfaceHub::Types::ModelInfo

Get information about a specific model

This is a convenience method that calls #repo_info with repo_type: “model”.

Examples:

Get basic model info

model = api.model_info("bert-base-uncased")
puts "Downloads: #{model.downloads}"
puts "Likes: #{model.likes}"

Get model info for specific revision

model = api.model_info("gpt2", revision: "main")
puts "SHA: #{model.sha}"

Parameters:

  • repo_id (String) —

    Model repository identifier

  • revision (String, nil) (defaults to: nil) —

    Git revision (branch, tag, or commit SHA). Defaults to “main”

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:

Raises:



169
170
171
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 169

def model_info(repo_id, revision: nil, timeout: nil)
  repo_info(repo_id, repo_type: "model", revision: revision, timeout: timeout)
end

#move_repo(from_repo_id:, to_repo_id:, repo_type: "model", timeout: nil) ⇒ Boolean

Move or rename a repository.

Parameters:

  • from_repo_id (String) —

    The current ID of the repository.

  • to_repo_id (String) —

    The new ID for the repository.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Boolean) —

    True if the repository was successfully moved/renamed.

Raises:



745
746
747
748
749
750
751
752
753
754
755
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 745

def move_repo(from_repo_id:, to_repo_id:, repo_type: "model", timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(from_repo_id)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(to_repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)

  path = "/api/#{repo_type}s/#{from_repo_id}/move"
  payload = { newPath: to_repo_id }

  http_client.post(path, body: payload, timeout: timeout)
  true
end

#permanently_delete_lfs_files(repo_id:, lfs_oids:, repo_type: "model", timeout: nil) ⇒ Boolean

Permanently delete LFS files from a repository.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • lfs_oids (Array<String>) —

    A list of LFS object IDs (OIDs) to delete.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Boolean) —

    True if the LFS files were successfully deleted.

Raises:



1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 1239

def permanently_delete_lfs_files(repo_id:, lfs_oids:, repo_type: "model", timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)

  path = "/api/#{repo_type}s/#{repo_id}/lfs/delete"
  payload = { oids: lfs_oids }

  http_client.post(path, body: payload, timeout: timeout)
  true
end

#repo_exists(repo_id, repo_type: "model", timeout: nil) ⇒ Boolean

Check if a repository exists on the HuggingFace Hub

Examples:

Check if model exists

if api.repo_exists("bert-base-uncased")
  puts "Model exists!"
end

Parameters:

  • repo_id (String) —

    Repository identifier

  • repo_type (String, Symbol) (defaults to: "model") —

    Type of repository: “model”, “dataset”, or “space”

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:

  • (Boolean) —

    True if repository exists, false otherwise



370
371
372
373
374
375
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 370

def repo_exists(repo_id, repo_type: "model", timeout: nil)
  repo_info(repo_id, repo_type: repo_type, timeout: timeout)
  true
rescue DurableHuggingfaceHub::RepositoryNotFoundError
  false
end

#repo_info(repo_id, repo_type: "model", revision: nil, timeout: nil) ⇒ DurableHuggingfaceHub::Types::ModelInfo, ...

Get comprehensive information about a repository

This is a generic method that works for any repository type (model, dataset, or space). For type-specific methods, see #model_info, #dataset_info, or #space_info.

Examples:

Get model information

info = api.repo_info("bert-base-uncased", repo_type: "model")
puts info.id
puts info.downloads

Get dataset information with specific revision

info = api.repo_info("squad", repo_type: "dataset", revision: "v1.0")
puts info.id

Get space information

info = api.repo_info("stabilityai/stable-diffusion", repo_type: "space")
puts info.id

Parameters:

  • repo_id (String) —

    Repository identifier in the format “namespace/name” or just “name” for repositories in your namespace

  • repo_type (String, Symbol) (defaults to: "model") —

    Type of repository: “model”, “dataset”, or “space”

  • revision (String, nil) (defaults to: nil) —

    Git revision (branch, tag, or commit SHA). Defaults to “main”

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:

Raises:



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 105

def repo_info(repo_id, repo_type: "model", revision: nil, timeout: nil)
  # Validate inputs
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)

  if revision
    DurableHuggingfaceHub::Utils::Validators.validate_revision(revision)
  end

  # Build API path
  path = case repo_type.to_s
         when "model"
           "/api/models/#{repo_id}"
         when "dataset"
           "/api/datasets/#{repo_id}"
         when "space"
           "/api/spaces/#{repo_id}"
         else
           raise ArgumentError, "Invalid repo_type: #{repo_type}"
         end

  # Add revision if specified
  params = {}
  params[:revision] = revision if revision

  # Make request
   response = http_client.get(path, params: params, timeout: timeout)

   # Parse response based on repo_type
   body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
   case repo_type.to_s
   when "model"
     DurableHuggingfaceHub::Types::ModelInfo.from_hash(body)
   when "dataset"
     DurableHuggingfaceHub::Types::DatasetInfo.from_hash(body)
   when "space"
     DurableHuggingfaceHub::Types::SpaceInfo.from_hash(body)
   end
end

#space_info(repo_id, revision: nil, timeout: nil) ⇒ DurableHuggingfaceHub::Types::SpaceInfo

Get information about a specific space

This is a convenience method that calls #repo_info with repo_type: “space”.

Examples:

Get space info

space = api.space_info("stabilityai/stable-diffusion")
puts "Runtime: #{space.runtime}"
puts "SDK: #{space.sdk}"

Parameters:

  • repo_id (String) —

    Space repository identifier

  • revision (String, nil) (defaults to: nil) —

    Git revision (branch, tag, or commit SHA). Defaults to “main”

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:

Raises:



217
218
219
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 217

def space_info(repo_id, revision: nil, timeout: nil)
  repo_info(repo_id, repo_type: "space", revision: revision, timeout: timeout)
end

#update_repo_settings(repo_id:, repo_type: "model", git_lfs_enabled: nil, protected: nil, unlisted: nil, tags: nil, default_branch: nil, timeout: nil) ⇒ Boolean

Update various settings for a repository.

Parameters:

  • repo_id (String) —

    The ID of the repository to update.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • git_lfs_enabled (Boolean, nil) (defaults to: nil) —

    Whether Git LFS should be enabled for the repository.

  • protected (Boolean, nil) (defaults to: nil) —

    Whether the repository should be protected.

  • unlisted (Boolean, nil) (defaults to: nil) —

    Whether the repository should be unlisted.

  • tags (Array<String>, nil) (defaults to: nil) —

    A list of tags to apply to the repository.

  • default_branch (String, nil) (defaults to: nil) —

    The new default branch for the repository.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Boolean) —

    True if the settings were successfully updated.

Raises:



710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 710

def update_repo_settings(
  repo_id:,
  repo_type: "model",
  git_lfs_enabled: nil,
  protected: nil,
  unlisted: nil,
  tags: nil,
  default_branch: nil,
  timeout: nil
)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)

  path = "/api/#{repo_type}s/#{repo_id}/settings"
  payload = {}
  payload[:git_lfs_enabled] = git_lfs_enabled unless git_lfs_enabled.nil?
  payload[:protected] = protected unless protected.nil?
  payload[:unlisted] = unlisted unless unlisted.nil?
  payload[:tags] = tags unless tags.nil?
  payload[:default_branch] = default_branch unless default_branch.nil?

  http_client.post(path, body: payload, timeout: timeout)
  true
end

#update_repo_visibility(repo_id:, repo_type: "model", private:, timeout: nil) ⇒ Boolean

Update the visibility of a repository (public/private).

Parameters:

  • repo_id (String) —

    The ID of the repository to update.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • private (Boolean) —

    The new visibility status (true for private, false for public).

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Boolean) —

    True if the visibility was successfully updated.

Raises:



685
686
687
688
689
690
691
692
693
694
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 685

def update_repo_visibility(repo_id:, repo_type: "model", private:, timeout: nil)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)

  path = "/api/#{repo_type}s/#{repo_id}/settings"
  payload = { private: private }

  http_client.post(path, body: payload, timeout: timeout)
  true
end

#upload_file(repo_id:, path_or_fileobj:, path_in_repo:, repo_type: "model", revision: nil, commit_message: nil, commit_description: nil, timeout: nil) ⇒ String

Upload a file to a repository on the HuggingFace Hub.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • path_or_fileobj (String, Pathname, IO) —

    The path to the file on the local filesystem, or an IO object.

  • path_in_repo (String) —

    The path to the file within the repository.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA) to upload to. Defaults to “main”.

  • commit_message (String, nil) (defaults to: nil) —

    A custom commit message for the upload.

  • commit_description (String, nil) (defaults to: nil) —

    A custom commit description.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (String) —

    The URL of the uploaded file.

Raises:



796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 796

def upload_file(
  repo_id:,
  path_or_fileobj:,
  path_in_repo:,
  repo_type: "model",
  revision: nil,
  commit_message: nil,
  commit_description: nil,
  timeout: nil
)
  DurableHuggingfaceHub::Utils::Validators.validate_repo_id(repo_id)
  repo_type = DurableHuggingfaceHub::Utils::Validators.validate_repo_type(repo_type)
  revision = DurableHuggingfaceHub::Utils::Validators.validate_revision(revision) if revision
  revision ||= "main"

  path = "/api/#{repo_type}s/#{repo_id}/upload/#{path_in_repo}"
  params = {
    commit_message: commit_message || "Upload #{path_in_repo}",
    commit_description: commit_description,
    revision: revision
  }.compact

  file_content = if path_or_fileobj.is_a?(String) || path_or_fileobj.is_a?(Pathname)
                   Faraday::Multipart::FilePart.new(path_or_fileobj, "application/octet-stream", Pathname(path_or_fileobj).basename.to_s)
                 else # Assume IO object
                   Faraday::Multipart::FilePart.new(path_or_fileobj, "application/octet-stream")
                 end

  payload = {
    file: file_content
  }

   response = http_client.post(path, params: params, body: payload, timeout: timeout)
   body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
   body["url"]
end

#upload_folder(repo_id:, folder_path:, repo_type: "model", revision: nil, commit_message: nil, commit_description: nil, timeout: nil) ⇒ Array<String>

Upload an entire folder to a repository on the HuggingFace Hub.

This method iterates through all files in a local folder and uploads them to the specified repository, maintaining the folder structure.

Parameters:

  • repo_id (String) —

    The ID of the repository.

  • folder_path (String, Pathname) —

    The path to the local folder to upload.

  • repo_type (String, Symbol) (defaults to: "model") —

    The type of the repository. Defaults to “model”.

  • revision (String, nil) (defaults to: nil) —

    The Git revision (branch, tag, or commit SHA) to upload to. Defaults to “main”.

  • commit_message (String, nil) (defaults to: nil) —

    A custom commit message for the upload.

  • commit_description (String, nil) (defaults to: nil) —

    A custom commit description.

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds.

Returns:

  • (Array<String>) —

    A list of URLs of the uploaded files.

Raises:



849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 849

def upload_folder(
  repo_id:,
  folder_path:,
  repo_type: "model",
  revision: nil,
  commit_message: nil,
  commit_description: nil,
  timeout: nil
)
  folder_path = Pathname(folder_path)
  raise ArgumentError, "Folder not found: #{folder_path}" unless folder_path.directory?

  uploaded_urls = []
  Dir.glob(File.join(folder_path, "**", "*")).each do |file_path_str|
    file_path = Pathname(file_path_str)
    next if file_path.directory?

    relative_path = file_path.relative_path_from(folder_path).to_s

    uploaded_urls << upload_file(
      repo_id: repo_id,
      path_or_fileobj: file_path,
      path_in_repo: relative_path,
      repo_type: repo_type,
      revision: revision,
      commit_message: commit_message,
      commit_description: commit_description,
      timeout: timeout
    )
  end
  uploaded_urls
end

#whoami(timeout: nil) ⇒ DurableHuggingfaceHub::Types::User

Get current user information (requires authentication)

Returns information about the authenticated user. Requires a valid authentication token.

Examples:

Get current user info

user = api.whoami
puts "Logged in as: #{user.name}"
puts "Type: #{user.type}"

Parameters:

  • timeout (Numeric, nil) (defaults to: nil) —

    Request timeout in seconds

Returns:

Raises:



392
393
394
395
396
397
 
# File 'lib/durable_huggingface_hub/hf_api.rb', line 392

def whoami(timeout: nil)
  path = "/api/whoami-v2"
  response = http_client.get(path, timeout: timeout)
  body = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
  DurableHuggingfaceHub::Types::User.from_hash(body)
end