durable_huggingface_hub 0.2.0

data/lib/durable_huggingface_hub/types/model_info.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module DurableHuggingfaceHub
+  module Types
+    # Information about a model repository on HuggingFace Hub.
+    #
+    # This structure represents metadata about a model, including its ID,
+    # tags, files, statistics, and configuration.
+    #
+    # @example Creating a ModelInfo from API response
+    #   model_info = ModelInfo.from_hash({
+    #     "id" => "bert-base-uncased",
+    #     "sha" => "a1b2c3d4...",
+    #     "tags" => ["transformers", "pytorch"],
+    #     "downloads" => 1000000,
+    #     "likes" => 500
+    #   })
+    #
+    # @example Accessing model information
+    #   model_info.id          # => "bert-base-uncased"
+    #   model_info.tags        # => ["transformers", "pytorch"]
+    #   model_info.downloads   # => 1000000
+    class ModelInfo < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] id
+      #   @return [String] Model repository ID (e.g., "bert-base-uncased")
+      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 model
+      attribute :tags, Types::StringArray.default([].freeze)
+
+      # @!attribute [r] pipeline_tag
+      #   @return [String, nil] Primary pipeline/task tag (e.g., "text-classification")
+      attribute :pipeline_tag, Types::OptionalString.default(nil)
+
+      # @!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 (false, "auto", "manual")
+       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] library_name
+      #   @return [String, nil] Primary library (e.g., "transformers", "diffusers")
+      attribute :library_name, Types::OptionalString.default(nil)
+
+      # @!attribute [r] config
+      #   @return [Hash, nil] Model configuration data
+      attribute :config, Types::OptionalHash.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] Model card metadata
+      attribute :card_data, Types::OptionalHash.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 model 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 (not private)
+      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 model.
+      #
+      # @return [String] Description string
+      def to_s
+        parts = [id]
+        parts << "(#{pipeline_tag})" if pipeline_tag
+        parts << "[#{library_name}]" if library_name
+        parts.join(" ")
+      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

data/lib/durable_huggingface_hub/types/space_info.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module DurableHuggingfaceHub
+  module Types
+    # Information about a Space repository on HuggingFace Hub.
+    #
+    # Spaces are interactive ML demos and applications hosted on HuggingFace Hub.
+    #
+    # @example Creating a SpaceInfo from API response
+    #   space_info = SpaceInfo.from_hash({
+    #     "id" => "gradio/hello-world",
+    #     "sdk" => "gradio",
+    #     "tags" => ["gradio", "demo"],
+    #     "likes" => 100
+    #   })
+    #
+    # @example Accessing space information
+    #   space_info.id      # => "gradio/hello-world"
+    #   space_info.sdk     # => "gradio"
+    #   space_info.runtime # => {"stage" => "RUNNING"}
+    class SpaceInfo < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] id
+      #   @return [String] Space 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 space
+      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] 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] sdk
+      #   @return [String, nil] SDK used (e.g., "gradio", "streamlit", "static")
+      attribute :sdk, Types::OptionalString.default(nil)
+
+      # @!attribute [r] runtime
+      #   @return [Hash, nil] Runtime information (stage, hardware, etc.)
+      attribute :runtime, Types::OptionalHash.default(nil)
+
+      # @!attribute [r] card_data
+      #   @return [Hash, nil] Space card metadata
+      attribute :card_data, Types::OptionalHash.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 space 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 the runtime stage if available.
+      #
+      # @return [String, nil] Runtime stage (e.g., "RUNNING", "STOPPED")
+      def runtime_stage
+        runtime&.dig("stage") || runtime&.dig(:stage)
+      end
+
+      # Checks if the space is currently running.
+      #
+      # @return [Boolean] True if running
+      def running?
+        runtime_stage == "RUNNING"
+      end
+
+      # Returns a short description of the space.
+      #
+      # @return [String] Description string
+      def to_s
+        parts = [id]
+        parts << "(#{sdk})" if sdk
+        parts << "[#{runtime_stage}]" if runtime_stage
+        parts.join(" ")
+      end
+
+      # Returns a detailed inspection string.
+      #
+      # @return [String] Inspection string
+      def inspect
+        "#<#{self.class.name} id=#{id.inspect} sdk=#{sdk.inspect} " \
+          "stage=#{runtime_stage.inspect}>"
+      end
+    end
+  end
+end

data/lib/durable_huggingface_hub/types/user.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require_relative "../types"
+
+module DurableHuggingfaceHub
+  module Types
+    # Information about a HuggingFace Hub user.
+    #
+    # @example Creating a User from API response
+    #   user = User.from_hash({
+    #     "name" => "john_doe",
+    #     "fullname" => "John Doe",
+    #     "email" => "john@example.com",
+    #     "isPro" => false
+    #   })
+    #
+    # @example Accessing user information
+    #   user.name      # => "john_doe"
+    #   user.fullname  # => "John Doe"
+    #   user.pro?      # => false
+    class User < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] type
+      #   @return [String, nil] User type (e.g., "user")
+      attribute :type, Types::OptionalString.default(nil)
+
+      # @!attribute [r] name
+      #   @return [String] Username
+      attribute :name, Types::String
+
+      # @!attribute [r] fullname
+      #   @return [String, nil] Full display name
+      attribute :fullname, Types::OptionalString.default(nil)
+
+      # @!attribute [r] email
+      #   @return [String, nil] Email address
+      attribute :email, Types::OptionalString.default(nil)
+
+      # @!attribute [r] avatar_url
+      #   @return [String, nil] Avatar image URL
+      attribute :avatar_url, Types::OptionalString.default(nil)
+
+      # @!attribute [r] is_pro
+      #   @return [Boolean, nil] Whether user has Pro subscription
+      attribute :is_pro, Types::OptionalBool.default(nil)
+
+      # @!attribute [r] orgs
+      #   @return [Array<Hash>, nil] Organizations the user belongs to
+      attribute :orgs, Types::Array.of(Types::Hash).optional.default(nil)
+
+      # Transform isPro from API to is_pro
+      def self.from_hash(data)
+        transformed = data.dup
+        if transformed.key?("isPro") && !transformed.key?("is_pro")
+          transformed["is_pro"] = transformed.delete("isPro")
+        elsif transformed.key?(:isPro) && !transformed.key?(:is_pro)
+          transformed[:is_pro] = transformed.delete(:isPro)
+        end
+
+        if transformed.key?("avatarUrl") && !transformed.key?("avatar_url")
+          transformed["avatar_url"] = transformed.delete("avatarUrl")
+        elsif transformed.key?(:avatarUrl) && !transformed.key?(:avatar_url)
+          transformed[:avatar_url] = transformed.delete(:avatarUrl)
+        end
+
+        new(transformed)
+      end
+
+      # Checks if the user has a Pro subscription.
+      #
+      # @return [Boolean] True if Pro user
+      def pro?
+        is_pro == true
+      end
+
+      # Returns the display name (fullname if available, otherwise username).
+      #
+      # @return [String] Display name
+      def display_name
+        fullname || name
+      end
+
+      # Returns a short description of the user.
+      #
+      # @return [String] Description string
+      def to_s
+        display_name
+      end
+
+      # Returns a detailed inspection string.
+      #
+      # @return [String] Inspection string
+      def inspect
+        "#<#{self.class.name} name=#{name.inspect} fullname=#{fullname.inspect} pro=#{pro?}>"
+      end
+    end
+
+    # Information about a HuggingFace Hub organization.
+    #
+    # @example Creating an Organization from API response
+    #   org = Organization.from_hash({
+    #     "name" => "huggingface",
+    #     "fullname" => "Hugging Face",
+    #     "isEnterprise" => true
+    #   })
+    #
+    # @example Accessing organization information
+    #   org.name        # => "huggingface"
+    #   org.fullname    # => "Hugging Face"
+    #   org.enterprise? # => true
+    class Organization < DurableHuggingfaceHub::Struct
+      include Loadable
+
+      # @!attribute [r] name
+      #   @return [String] Organization name/ID
+      attribute :name, Types::String
+
+      # @!attribute [r] fullname
+      #   @return [String, nil] Full display name
+      attribute :fullname, Types::OptionalString.default(nil)
+
+      # @!attribute [r] avatar_url
+      #   @return [String, nil] Organization avatar URL
+      attribute :avatar_url, Types::OptionalString.default(nil)
+
+      # @!attribute [r] is_enterprise
+      #   @return [Boolean, nil] Whether this is an Enterprise organization
+      attribute :is_enterprise, Types::OptionalBool.default(nil)
+
+      # Transform isEnterprise from API to is_enterprise
+      def self.from_hash(data)
+        transformed = data.dup
+        if transformed.key?("isEnterprise") && !transformed.key?("is_enterprise")
+          transformed["is_enterprise"] = transformed.delete("isEnterprise")
+        elsif transformed.key?(:isEnterprise) && !transformed.key?(:is_enterprise)
+          transformed[:is_enterprise] = transformed.delete(:isEnterprise)
+        end
+
+        if transformed.key?("avatarUrl") && !transformed.key?("avatar_url")
+          transformed["avatar_url"] = transformed.delete("avatarUrl")
+        elsif transformed.key?(:avatarUrl) && !transformed.key?(:avatar_url)
+          transformed[:avatar_url] = transformed.delete(:avatarUrl)
+        end
+
+        new(transformed)
+      end
+
+      # Checks if this is an Enterprise organization.
+      #
+      # @return [Boolean] True if Enterprise
+      def enterprise?
+        is_enterprise == true
+      end
+
+      # Returns the display name (fullname if available, otherwise name).
+      #
+      # @return [String] Display name
+      def display_name
+        fullname || name
+      end
+
+      # Returns a short description of the organization.
+      #
+      # @return [String] Description string
+      def to_s
+        display_name
+      end
+
+      # Returns a detailed inspection string.
+      #
+      # @return [String] Inspection string
+      def inspect
+        "#<#{self.class.name} name=#{name.inspect} fullname=#{fullname.inspect} " \
+          "enterprise=#{enterprise?}>"
+      end
+    end
+  end
+end

data/lib/durable_huggingface_hub/types.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "dry-types"
+require "dry-struct"
+
+module DurableHuggingfaceHub
+  # Type definitions and custom types for the HuggingFace Hub client.
+  #
+  # This module sets up the type system using dry-types and defines
+  # custom types for domain-specific validation and coercion.
+  #
+  # @example Using custom types
+  #   Types::RepoId["organization/model-name"]
+  #   Types::RepoType["model"]
+  #   Types::Revision["main"]
+  module Types
+    include Dry.Types()
+
+    # Repository ID type with validation.
+    #
+    # Valid format: "organization/repository-name" or "username/repository-name"
+    # May also be just "repository-name" for models in the user's namespace.
+    #
+    # @example
+    #   Types::RepoId["bert-base-uncased"]
+    #   Types::RepoId["huggingface/transformers"]
+    RepoId = String.constrained(min_size: 1)
+
+    # Repository type enumeration.
+    #
+    # Valid values: "model", "dataset", "space"
+    #
+    # @example
+    #   Types::RepoType["model"]
+    #   Types::RepoType["dataset"]
+    RepoType = String.enum("model", "dataset", "space")
+
+    # Revision type (branch, tag, or commit SHA).
+    #
+    # Can be a branch name (e.g., "main"), tag (e.g., "v1.0.0"),
+    # or Git commit SHA (40 hexadecimal characters).
+    #
+    # @example
+    #   Types::Revision["main"]
+    #   Types::Revision["v1.0.0"]
+    #   Types::Revision["a1b2c3d4e5f6..."]
+    Revision = String.constrained(min_size: 1)
+
+    # Strict boolean type.
+    StrictBool = Strict::Bool
+
+    # Optional string type.
+    OptionalString = String.optional
+
+    # Optional integer type.
+    OptionalInteger = Integer.optional
+
+    # Optional boolean type.
+    OptionalBool = Bool.optional
+
+    # Array of strings type.
+    StringArray = Array.of(String)
+
+    # Optional array of strings type.
+    OptionalStringArray = Array.of(String).optional
+
+    # Hash with string keys type.
+    StringHash = Hash.map(String, Any)
+
+    # Optional hash type.
+    OptionalHash = Hash.optional
+
+    # Timestamp type (Time, DateTime, or ISO 8601 string).
+    Timestamp = Time | DateTime | String
+
+    # Optional timestamp type.
+    OptionalTimestamp = Timestamp.optional
+
+    # File siblings type (array of hashes representing files in a repository).
+    FileSiblings = Array.of(Hash)
+
+    # Optional file siblings type.
+    OptionalFileSiblings = FileSiblings.optional
+
+    # Gated access type (true, false, "auto", "manual").
+    GatedType = Bool | String.enum("auto", "manual")
+
+    # Optional gated type.
+    OptionalGated = GatedType.optional
+
+    # URL type for web addresses.
+    #
+    # Accepts any string that looks like a URL.
+    #
+    # @example
+    #   Types::URL["https://example.com"]
+    #   Types::URL["http://example.com/path"]
+    URL = String.constrained(format: URI::DEFAULT_PARSER.make_regexp)
+
+    # Optional URL type.
+    OptionalURL = URL.optional
+
+    # Pathname type for file system paths.
+    #
+    # Accepts strings, Pathname objects, or anything that responds to #to_path or #to_s.
+    #
+    # @example
+    #   Types::PathnameType["/path/to/file"]
+    #   Types::PathnameType[Pathname.new("/path/to/file")]
+    PathnameType = Any.constructor do |value|
+      case value
+      when Pathname
+        value
+      when String
+        Pathname.new(value)
+      else
+        Pathname.new(value.to_s)
+      end
+    end
+
+    # Optional Pathname type.
+    OptionalPathnameType = PathnameType.optional
+  end
+
+  # Autoload type structures
+  module Types
+    autoload :ModelInfo, "durable_huggingface_hub/types/model_info"
+    autoload :DatasetInfo, "durable_huggingface_hub/types/dataset_info"
+    autoload :SpaceInfo, "durable_huggingface_hub/types/space_info"
+    autoload :CommitInfo, "durable_huggingface_hub/types/commit_info"
+    autoload :GitRefInfo, "durable_huggingface_hub/types/commit_info"
+    autoload :User, "durable_huggingface_hub/types/user"
+    autoload :Organization, "durable_huggingface_hub/types/user"
+    autoload :CachedFileInfo, "durable_huggingface_hub/types/cache_info"
+    autoload :CachedRevisionInfo, "durable_huggingface_hub/types/cache_info"
+    autoload :CachedRepoInfo, "durable_huggingface_hub/types/cache_info"
+    autoload :HFCacheInfo, "durable_huggingface_hub/types/cache_info"
+  end
+
+  # Base class for data structures using dry-struct.
+  #
+  # Provides immutable, type-checked data structures with automatic
+  # attribute validation and coercion.
+  #
+  # @example Defining a data structure
+  #   class MyData < DurableHuggingfaceHub::Struct
+  #     attribute :name, Types::String
+  #     attribute :count, Types::Integer
+  #     attribute :optional, Types::OptionalString
+  #   end
+  class Struct < Dry::Struct
+    # Use type schema for strict attribute validation
+    schema schema.strict
+
+    # Transform attribute keys from camelCase strings to snake_case symbols
+    transform_keys do |key|
+      # Convert camelCase to snake_case, then to symbol
+      key.to_s.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+    end
+
+    # Base class for data structures that can be loaded from JSON/Hash.
+    #
+    # Provides convenient methods for creating instances from API responses.
+    module Loadable
+      # Creates an instance from a hash (typically from JSON parsing).
+      #
+      # @param data [Hash] Data hash
+      # @return [Struct] New instance
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Creates an instance from a hash.
+        #
+        # @param data [Hash] Data hash with string or symbol keys
+        # @return [self] New instance of the struct
+        def from_hash(data)
+          new(data)
+        end
+
+        # Alias for from_hash.
+        #
+        # @param data [Hash] Data hash
+        # @return [self] New instance
+        alias from_json from_hash
+      end
+
+      # Converts the struct to a hash.
+      #
+      # @return [Hash] Hash representation
+      def to_h
+        attributes.to_h
+      end
+
+      # Converts the struct to JSON.
+      #
+      # @return [String] JSON representation
+      def to_json(*args)
+        require "json"
+        to_h.to_json(*args)
+      end
+    end
+  end
+end