durable_huggingface_hub 0.2.0

data/lib/durable_huggingface_hub/types/cache_info.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module DurableHuggingfaceHub
+  module Types
+    # Information about a cached file.
+    #
+    # Represents a single file in the cache with its metadata.
+    #
+    # @example
+    #   cached_file = CachedFileInfo.new(
+    #     file_path: Pathname.new("/cache/blobs/abc123"),
+    #     size: 1024,
+    #     etag: "abc123",
+    #     commit_hash: "def456",
+    #     last_accessed: Time.now,
+    #     last_modified: Time.now
+    #   )
+    class CachedFileInfo < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] file_path
+      #   Path to the cached file
+      #   @return [Pathname]
+      attribute :file_path, Types::PathnameType
+
+      # @!attribute [r] size
+      #   Size of the file in bytes
+      #   @return [Integer]
+      attribute :size, Types::Integer
+
+      # @!attribute [r] etag
+      #   ETag of the file (used for cache validation)
+      #   @return [String, nil]
+      attribute :etag, Types::OptionalString
+
+      # @!attribute [r] commit_hash
+      #   Git commit hash this file belongs to
+      #   @return [String, nil]
+      attribute :commit_hash, Types::OptionalString.default(nil)
+
+      # @!attribute [r] last_accessed
+      #   When the file was last accessed
+      #   @return [Time, nil]
+      attribute :last_accessed, Types::OptionalTimestamp.default(nil)
+
+      # @!attribute [r] last_modified
+      #   When the file was last modified
+      #   @return [Time, nil]
+      attribute :last_modified, Types::OptionalTimestamp.default(nil)
+
+      # Human-readable size string.
+      #
+      # @return [String] Size formatted as human-readable string (e.g., "1.2 MB")
+      def size_str
+        units = ["B", "KB", "MB", "GB", "TB"]
+        size = self.size.to_f
+        unit_index = 0
+
+        while size >= 1024 && unit_index < units.length - 1
+          size /= 1024.0
+          unit_index += 1
+        end
+
+        format("%.2f %s", size, units[unit_index])
+      end
+    end
+
+    # Information about a cached repository revision.
+    #
+    # Represents a specific revision (commit, branch, or tag) of a repository in the cache.
+    #
+    # @example
+    #   revision = CachedRevisionInfo.new(
+    #     commit_hash: "abc123",
+    #     refs: ["main", "v1.0"],
+    #     files: [cached_file_info1, cached_file_info2],
+    #     size: 2048,
+    #     last_modified: Time.now
+    #   )
+    class CachedRevisionInfo < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] commit_hash
+      #   Git commit hash for this revision
+      #   @return [String]
+      attribute :commit_hash, Types::String
+
+      # @!attribute [r] refs
+      #   List of refs (branches/tags) pointing to this commit
+      #   @return [Array<String>]
+      attribute :refs, Types::StringArray
+
+      # @!attribute [r] files
+      #   List of cached files in this revision
+      #   @return [Array<CachedFileInfo>]
+      attribute :files, Types::Array.of(CachedFileInfo)
+
+      # @!attribute [r] size
+      #   Total size of all files in this revision
+      #   @return [Integer]
+      attribute :size, Types::Integer
+
+      # @!attribute [r] last_modified
+      #   When this revision was last modified
+      #   @return [Time, nil]
+      attribute :last_modified, Types::OptionalTimestamp.default(nil)
+
+      # Human-readable size string.
+      #
+      # @return [String] Size formatted as human-readable string
+      def size_str
+        units = ["B", "KB", "MB", "GB", "TB"]
+        size = self.size.to_f
+        unit_index = 0
+
+        while size >= 1024 && unit_index < units.length - 1
+          size /= 1024.0
+          unit_index += 1
+        end
+
+        format("%.2f %s", size, units[unit_index])
+      end
+
+      # Number of files in this revision.
+      #
+      # @return [Integer] File count
+      def file_count
+        files.length
+      end
+    end
+
+    # Information about a cached repository.
+    #
+    # Represents a repository in the cache with all its revisions and files.
+    #
+    # @example
+    #   repo = CachedRepoInfo.new(
+    #     repo_id: "bert-base-uncased",
+    #     repo_type: "model",
+    #     revisions: [revision_info1, revision_info2],
+    #     size: 1048576,
+    #     last_accessed: Time.now,
+    #     last_modified: Time.now
+    #   )
+    class CachedRepoInfo < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] repo_id
+      #   Repository identifier
+      #   @return [String]
+      attribute :repo_id, Types::String
+
+      # @!attribute [r] repo_type
+      #   Type of repository ("model", "dataset", or "space")
+      #   @return [String]
+      attribute :repo_type, Types::String
+
+      # @!attribute [r] revisions
+      #   List of cached revisions for this repository
+      #   @return [Array<CachedRevisionInfo>]
+      attribute :revisions, Types::Array.of(CachedRevisionInfo)
+
+      # @!attribute [r] size
+      #   Total size of all revisions in this repository
+      #   @return [Integer]
+      attribute :size, Types::Integer
+
+      # @!attribute [r] last_accessed
+      #   When the repository was last accessed
+      #   @return [Time, nil]
+      attribute :last_accessed, Types::OptionalTimestamp.default(nil)
+
+      # @!attribute [r] last_modified
+      #   When the repository was last modified
+      #   @return [Time, nil]
+      attribute :last_modified, Types::OptionalTimestamp.default(nil)
+
+      # Human-readable size string.
+      #
+      # @return [String] Size formatted as human-readable string
+      def size_str
+        units = ["B", "KB", "MB", "GB", "TB"]
+        size = self.size.to_f
+        unit_index = 0
+
+        while size >= 1024 && unit_index < units.length - 1
+          size /= 1024.0
+          unit_index += 1
+        end
+
+        format("%.2f %s", size, units[unit_index])
+      end
+
+      # Number of revisions cached for this repository.
+      #
+      # @return [Integer] Revision count
+      def revision_count
+        revisions.length
+      end
+
+      # Total number of files across all revisions.
+      #
+      # @return [Integer] Total file count
+      def file_count
+        revisions.sum(&:file_count)
+      end
+    end
+
+    # Comprehensive cache information.
+    #
+    # Contains information about the entire cache directory including all repositories.
+    #
+    # @example
+    #   cache_info = HFCacheInfo.new(
+    #     cache_dir: Pathname.new("/cache"),
+    #     repos: [repo_info1, repo_info2],
+    #     size: 2097152
+    #   )
+    class HFCacheInfo < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] cache_dir
+      #   Path to the cache directory
+      #   @return [Pathname]
+      attribute :cache_dir, Types::PathnameType
+
+      # @!attribute [r] repos
+      #   List of cached repositories
+      #   @return [Array<CachedRepoInfo>]
+      attribute :repos, Types::Array.of(CachedRepoInfo)
+
+      # @!attribute [r] size
+      #   Total size of the cache in bytes
+      #   @return [Integer]
+      attribute :size, Types::Integer
+
+      # Human-readable size string.
+      #
+      # @return [String] Size formatted as human-readable string
+      def size_str
+        units = ["B", "KB", "MB", "GB", "TB"]
+        size = self.size.to_f
+        unit_index = 0
+
+        while size >= 1024 && unit_index < units.length - 1
+          size /= 1024.0
+          unit_index += 1
+        end
+
+        format("%.2f %s", size, units[unit_index])
+      end
+
+      # Number of repositories in the cache.
+      #
+      # @return [Integer] Repository count
+      def repo_count
+        repos.length
+      end
+
+      # Total number of revisions across all repositories.
+      #
+      # @return [Integer] Total revision count
+      def revision_count
+        repos.sum(&:revision_count)
+      end
+
+      # Total number of files across all repositories and revisions.
+      #
+      # @return [Integer] Total file count
+      def file_count
+        repos.sum(&:file_count)
+      end
+
+      # Get repositories sorted by size (largest first).
+      #
+      # @return [Array<CachedRepoInfo>] Repositories sorted by size
+      def repos_by_size
+        repos.sort_by { |repo| -repo.size }
+      end
+
+      # Get repositories sorted by last accessed time (most recent first).
+      #
+      # @return [Array<CachedRepoInfo>] Repositories sorted by access time
+      def repos_by_last_accessed
+        repos.compact.sort_by { |repo| repo.last_accessed || Time.at(0) }.reverse
+      end
+
+      # Get repositories sorted by last modified time (most recent first).
+      #
+      # @return [Array<CachedRepoInfo>] Repositories sorted by modification time
+      def repos_by_last_modified
+        repos.compact.sort_by { |repo| repo.last_modified || Time.at(0) }.reverse
+      end
+    end
+  end
+end

data/lib/durable_huggingface_hub/types/commit_info.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module DurableHuggingfaceHub
+  module Types
+    # Information about a Git commit in a HuggingFace Hub repository.
+    #
+    # @example Creating a CommitInfo from API response
+    #   commit_info = CommitInfo.from_hash({
+    #     "oid" => "a1b2c3d4e5f6...",
+    #     "title" => "Update model weights",
+    #     "message" => "Update model weights\n\nImproved accuracy",
+    #     "date" => "2024-01-15T10:30:00Z"
+    #   })
+    #
+    # @example Accessing commit information
+    #   commit_info.oid    # => "a1b2c3d4e5f6..."
+    #   commit_info.title  # => "Update model weights"
+    class CommitInfo < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] oid
+      #   @return [String] Commit OID (Git SHA)
+      attribute :oid, Types::String
+
+      # @!attribute [r] title
+      #   @return [String] Commit title (first line of message)
+      attribute :title, Types::String
+
+      # @!attribute [r] message
+      #   @return [String, nil] Full commit message
+      attribute :message, Types::OptionalString.default(nil)
+
+      # @!attribute [r] date
+      #   @return [Time, nil] Commit timestamp
+      attribute :date, Types::OptionalTimestamp.default(nil)
+
+      # @!attribute [r] authors
+      #   @return [Array<String>, nil] Commit authors
+      attribute :authors, Types::OptionalStringArray.default(nil)
+
+      # @!attribute [r] commit_url
+      #   @return [String, nil] URL to view the commit
+      attribute :commit_url, Types::OptionalString.default(nil)
+
+      # @!attribute [r] commit_message
+      #   @return [String, nil] Alias for message (API compatibility)
+      attribute :commit_message, Types::OptionalString.default(nil)
+
+      # Returns the short OID (first 7 characters).
+      #
+      # @return [String] Short OID
+      def short_oid
+        oid[0, 7]
+      end
+
+      # Returns the commit message (preferring message over commit_message).
+      #
+      # @return [String, nil] Commit message
+      def full_message
+        message || commit_message
+      end
+
+      # Returns a short description of the commit.
+      #
+      # @return [String] Description string
+      def to_s
+        "#{short_oid}: #{title}"
+      end
+
+      # Returns a detailed inspection string.
+      #
+      # @return [String] Inspection string
+      def inspect
+        "#<#{self.class.name} oid=#{short_oid.inspect} title=#{title[0, 50].inspect}>"
+      end
+    end
+
+    # Information about a Git reference (branch or tag) in a HuggingFace Hub repository.
+    #
+    # @example Creating a GitRefInfo from API response
+    #   ref_info = GitRefInfo.from_hash({
+    #     "name" => "main",
+    #     "ref" => "refs/heads/main",
+    #     "targetCommit" => "a1b2c3d4e5f6..."
+    #   })
+    #
+    # @example Accessing ref information
+    #   ref_info.name           # => "main"
+    #   ref_info.target_commit  # => "a1b2c3d4e5f6..."
+    class GitRefInfo < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] name
+      #   @return [String] Reference name (e.g., "main", "v1.0.0")
+      attribute :name, Types::String
+
+      # @!attribute [r] ref
+      #   @return [String] Full reference path (e.g., "refs/heads/main")
+      attribute :ref, Types::String
+
+      # @!attribute [r] target_commit
+      #   @return [String, nil] Target commit OID
+      attribute :target_commit, Types::OptionalString.default(nil)
+
+
+
+      # Checks if this is a branch reference.
+      #
+      # @return [Boolean] True if branch
+      def branch?
+        ref.start_with?("refs/heads/")
+      end
+
+      # Checks if this is a tag reference.
+      #
+      # @return [Boolean] True if tag
+      def tag?
+        ref.start_with?("refs/tags/")
+      end
+
+      # Returns the reference type.
+      #
+      # @return [String] "branch", "tag", or "unknown"
+      def ref_type
+        return "branch" if branch?
+        return "tag" if tag?
+
+        "unknown"
+      end
+
+      # Returns a short description of the ref.
+      #
+      # @return [String] Description string
+      def to_s
+        "#{ref_type}: #{name}"
+      end
+
+      # Returns a detailed inspection string.
+      #
+      # @return [String] Inspection string
+      def inspect
+        "#<#{self.class.name} name=#{name.inspect} type=#{ref_type} " \
+          "commit=#{target_commit&.[](0, 7).inspect}>"
+      end
+    end
+  end
+end

data/lib/durable_huggingface_hub/types/dataset_info.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module DurableHuggingfaceHub
+  module Types
+    # Information about a dataset repository on HuggingFace Hub.
+    #
+    # This structure represents metadata about a dataset, including its ID,
+    # tags, files, statistics, and configuration.
+    #
+    # @example Creating a DatasetInfo from API response
+    #   dataset_info = DatasetInfo.from_hash({
+    #     "id" => "squad",
+    #     "sha" => "a1b2c3d4...",
+    #     "tags" => ["question-answering", "en"],
+    #     "downloads" => 500000
+    #   })
+    #
+    # @example Accessing dataset information
+    #   dataset_info.id          # => "squad"
+    #   dataset_info.tags        # => ["question-answering", "en"]
+    #   dataset_info.downloads   # => 500000
+    class DatasetInfo < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] id
+      #   @return [String] Dataset repository ID
+      attribute :id, Types::RepoId
+
+      # @!attribute [r] sha
+      #   @return [String, nil] Git commit SHA of the current revision
+      attribute :sha, Types::OptionalString.default(nil)
+
+      # @!attribute [r] last_modified
+      #   @return [Time, nil] Timestamp of last modification
+      attribute :last_modified, Types::OptionalTimestamp.default(nil)
+
+      # @!attribute [r] tags
+      #   @return [Array<String>] Tags associated with the dataset
+      attribute :tags, Types::StringArray.default([].freeze)
+
+      # @!attribute [r] siblings
+      #   @return [Array<Hash>, nil] List of files in the repository
+      attribute :siblings, Types::OptionalFileSiblings.default(nil)
+
+      # @!attribute [r] private
+      #   @return [Boolean, nil] Whether the repository is private
+      attribute :private, Types::OptionalBool.default(nil)
+
+       # @!attribute [r] gated
+       #   @return [Boolean, String, nil] Gated access status
+       attribute :gated, Types::OptionalGated.default(nil)
+
+      # @!attribute [r] disabled
+      #   @return [Boolean, nil] Whether the repository is disabled
+      attribute :disabled, Types::OptionalBool.default(nil)
+
+      # @!attribute [r] downloads
+      #   @return [Integer, nil] Total number of downloads
+      attribute :downloads, Types::OptionalInteger.default(nil)
+
+      # @!attribute [r] likes
+      #   @return [Integer, nil] Number of likes/stars
+      attribute :likes, Types::OptionalInteger.default(nil)
+
+      # @!attribute [r] author
+      #   @return [String, nil] Author/organization name
+      attribute :author, Types::OptionalString.default(nil)
+
+      # @!attribute [r] created_at
+      #   @return [Time, nil] Repository creation timestamp
+      attribute :created_at, Types::OptionalTimestamp.default(nil)
+
+      # @!attribute [r] card_data
+      #   @return [Hash, nil] Dataset card metadata
+      attribute :card_data, Types::OptionalHash.default(nil)
+
+      # @!attribute [r] description
+      #   @return [String, nil] Dataset description
+      attribute :description, Types::OptionalString.default(nil)
+
+       # @!attribute [r] citation
+       #   @return [String, nil] Citation information
+       attribute :citation, Types::OptionalString.default(nil)
+
+       # @!attribute [r] downloads_all_time
+       #   @return [Integer, nil] Total number of downloads all time
+       attribute :downloads_all_time, Types::OptionalInteger.default(nil)
+
+       # @!attribute [r] paperswithcode_id
+       #   @return [String, nil] PapersWithCode identifier
+       attribute :paperswithcode_id, Types::OptionalString.default(nil)
+
+       # @!attribute [r] trending_score
+       #   @return [Integer, nil] Trending score
+       attribute :trending_score, Types::OptionalInteger.default(nil)
+
+       # Returns the list of file names in the repository.
+      #
+      # @return [Array<String>] File names
+      def file_names
+        return [] if siblings.nil?
+
+        siblings.map { |s| s[:rfilename] || s["rfilename"] }.compact
+      end
+
+      # Checks if the dataset has a specific tag.
+      #
+      # @param tag [String] Tag to check for
+      # @return [Boolean] True if the tag is present
+      def has_tag?(tag)
+        tags.include?(tag)
+      end
+
+      # Checks if the repository is public.
+      #
+      # @return [Boolean] True if public
+      def public?
+        !private
+      end
+
+      # Checks if the repository is gated.
+      #
+      # @return [Boolean] True if gated
+      def gated?
+        case gated
+        when true, "auto", "manual"
+          true
+        else
+          false
+        end
+      end
+
+      # Checks if the repository is disabled.
+      #
+      # @return [Boolean] True if disabled
+      def disabled?
+        disabled == true
+      end
+
+      # Returns a short description of the dataset.
+      #
+      # @return [String] Description string
+      def to_s
+        id
+      end
+
+      # Returns a detailed inspection string.
+      #
+      # @return [String] Inspection string
+      def inspect
+        "#<#{self.class.name} id=#{id.inspect} sha=#{sha&.[](0, 7).inspect} " \
+          "tags=#{tags.size} files=#{siblings&.size || 0}>"
+      end
+    end
+  end
+end