fine 0.1.0

data/lib/fine/export.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "export/onnx_exporter"
+require_relative "export/gguf_exporter"
+
+module Fine
+  # Export models to various deployment formats
+  #
+  # @example Export to ONNX
+  #   Fine::Export.to_onnx(classifier, "model.onnx")
+  #
+  # @example Export LLM to GGUF
+  #   Fine::Export.to_gguf(llm, "model.gguf", quantization: :q4_0)
+  module Export
+    class << self
+      # Export any Fine model to ONNX format
+      #
+      # @param model [TextClassifier, TextEmbedder, ImageClassifier, LLM] The model
+      # @param path [String] Output path
+      # @param options [Hash] Export options
+      # @return [String] The output path
+      def to_onnx(model, path, **options)
+        ONNXExporter.export(model, path, **options)
+      end
+
+      # Export LLM to GGUF format
+      #
+      # @param model [LLM] The LLM model
+      # @param path [String] Output path
+      # @param quantization [Symbol] Quantization type (:f16, :q4_0, :q8_0, etc.)
+      # @param metadata [Hash] Additional metadata
+      # @return [String] The output path
+      def to_gguf(model, path, quantization: :f16, **options)
+        GGUFExporter.export(model, path, quantization: quantization, **options)
+      end
+
+      # List available quantization options for GGUF
+      #
+      # @return [Hash] Quantization types with descriptions
+      def gguf_quantization_options
+        {
+          f32: "32-bit float (largest, no quality loss)",
+          f16: "16-bit float (good balance)",
+          q8_0: "8-bit quantization (smaller, minimal quality loss)",
+          q4_0: "4-bit quantization (smallest, some quality loss)",
+          q4_k: "4-bit K-quant (better quality than q4_0)",
+          q5_k: "5-bit K-quant (good quality/size balance)",
+          q6_k: "6-bit K-quant (high quality)"
+        }
+      end
+    end
+  end
+end

data/lib/fine/hub/config_loader.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Fine
+  module Hub
+    # Loads and parses model configuration from Hugging Face format
+    class ConfigLoader
+      attr_reader :config
+
+      def initialize(config_path)
+        @config_path = config_path
+        @config = load_config
+      end
+
+      def self.from_pretrained(model_path)
+        config_path = File.join(model_path, "config.json")
+        raise ConfigurationError, "Config not found: #{config_path}" unless File.exist?(config_path)
+
+        new(config_path)
+      end
+
+      # Vision encoder configuration
+      def hidden_size
+        vision_config["hidden_size"] || config["hidden_size"] || 768
+      end
+
+      def num_hidden_layers
+        vision_config["num_hidden_layers"] || config["num_hidden_layers"] || 12
+      end
+
+      def num_attention_heads
+        vision_config["num_attention_heads"] || config["num_attention_heads"] || 12
+      end
+
+      def intermediate_size
+        vision_config["intermediate_size"] || config["intermediate_size"] || 3072
+      end
+
+      def image_size
+        vision_config["image_size"] || config["image_size"] || 224
+      end
+
+      def patch_size
+        vision_config["patch_size"] || config["patch_size"] || 16
+      end
+
+      def num_channels
+        vision_config["num_channels"] || config["num_channels"] || 3
+      end
+
+      def layer_norm_eps
+        vision_config["layer_norm_eps"] || config["layer_norm_eps"] || 1e-6
+      end
+
+      def hidden_act
+        vision_config["hidden_act"] || config["hidden_act"] || "gelu"
+      end
+
+      def attention_dropout
+        vision_config["attention_dropout"] || config["attention_dropout"] || 0.0
+      end
+
+      # Text model configuration (BERT, DistilBERT, DeBERTa, etc.)
+      def vocab_size
+        config["vocab_size"] || 30522
+      end
+
+      def max_position_embeddings
+        config["max_position_embeddings"] || 512
+      end
+
+      def type_vocab_size
+        config["type_vocab_size"] || 2
+      end
+
+      def hidden_dropout_prob
+        config["hidden_dropout_prob"] || config["dropout"] || 0.1
+      end
+
+      # LLM configuration (Llama, Gemma, etc.)
+      def rope_theta
+        config["rope_theta"] || 10000.0
+      end
+
+      def rms_norm_eps
+        config["rms_norm_eps"] || 1e-6
+      end
+
+      def num_key_value_heads
+        config["num_key_value_heads"] || num_attention_heads
+      end
+
+      def use_bias
+        config["use_bias"] != false
+      end
+
+      def head_dim
+        config["head_dim"] || (hidden_size / num_attention_heads)
+      end
+
+      def attention_bias
+        config["attention_bias"] || false
+      end
+
+      def use_qk_norm
+        # Gemma 3 uses QK normalization
+        config.key?("query_pre_attn_scalar") || model_type&.include?("gemma3")
+      end
+
+      def use_pre_feedforward_layernorm
+        # Gemma 3 has additional layer norms
+        model_type&.include?("gemma3")
+      end
+
+      # Computed properties
+      def num_patches
+        (image_size / patch_size) ** 2
+      end
+
+      def model_type
+        config["model_type"]
+      end
+
+      # Raw access to config sections
+      def vision_config
+        config["vision_config"] || {}
+      end
+
+      def text_config
+        config["text_config"] || {}
+      end
+
+      def to_h
+        @config
+      end
+
+      private
+
+      def load_config
+        JSON.parse(File.read(@config_path))
+      rescue JSON::ParserError => e
+        raise ConfigurationError, "Invalid JSON in config: #{e.message}"
+      end
+    end
+  end
+end

data/lib/fine/hub/model_downloader.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Fine
+  module Hub
+    # Downloads models from Hugging Face Hub
+    class ModelDownloader
+      HF_HUB_URL = "https://huggingface.co"
+      REQUIRED_FILES = %w[config.json].freeze
+      MODEL_FILES = %w[model.safetensors].freeze
+      OPTIONAL_FILES = %w[preprocessor_config.json tokenizer_config.json tokenizer.json].freeze
+
+      attr_reader :model_id, :cache_path
+
+      def initialize(model_id, cache_dir: nil)
+        @model_id = model_id
+        @cache_dir = cache_dir || Fine.cache_dir
+        @cache_path = File.join(@cache_dir, "models", model_id.tr("/", "--"))
+      end
+
+      # Download model files and return the cache path
+      def download(force: false)
+        return @cache_path if cached? && !force
+
+        FileUtils.mkdir_p(@cache_path)
+
+        download_required_files
+        download_optional_files
+
+        @cache_path
+      end
+
+      # Check if model is already cached
+      def cached?
+        return false unless File.directory?(@cache_path)
+
+        # Check required files
+        return false unless REQUIRED_FILES.all? { |f| File.exist?(File.join(@cache_path, f)) }
+
+        # Check for model weights (single file or sharded)
+        has_single_weights = File.exist?(File.join(@cache_path, "model.safetensors"))
+        has_sharded_weights = Dir.glob(File.join(@cache_path, "model-*.safetensors")).any?
+
+        has_single_weights || has_sharded_weights
+      end
+
+      # Get path to a specific file
+      def file_path(filename)
+        File.join(@cache_path, filename)
+      end
+
+      private
+
+      def download_required_files
+        REQUIRED_FILES.each do |filename|
+          download_file(filename)
+        end
+
+        # Download model weights (try single file first, then sharded)
+        download_model_weights
+      end
+
+      def download_model_weights
+        # Try single model file first
+        begin
+          download_file("model.safetensors")
+          return
+        rescue ModelNotFoundError
+          # Single file not found, try sharded
+        end
+
+        # Download index file to find shards
+        download_file("model.safetensors.index.json", required: false)
+        index_path = File.join(@cache_path, "model.safetensors.index.json")
+
+        if File.exist?(index_path)
+          index = JSON.parse(File.read(index_path))
+          weight_files = index["weight_map"].values.uniq
+
+          weight_files.each do |filename|
+            download_file(filename)
+          end
+        else
+          raise ModelNotFoundError.new(@model_id, "No model weights found")
+        end
+      end
+
+      def download_optional_files
+        OPTIONAL_FILES.each do |filename|
+          download_file(filename, required: false)
+        end
+      end
+
+      def download_file(filename, required: true)
+        local_path = File.join(@cache_path, filename)
+        return if File.exist?(local_path)
+
+        url = file_url(filename)
+
+        begin
+          puts "Downloading #{filename}..." if Fine.configuration&.progress_bar != false
+
+          headers = { "User-Agent" => "fine-ruby/#{Fine::VERSION}" }
+
+          # Add HuggingFace token if available
+          if (token = hf_token)
+            headers["Authorization"] = "Bearer #{token}"
+          end
+
+          tempfile = Down.download(url, headers: headers)
+
+          FileUtils.mv(tempfile.path, local_path)
+        rescue Down::NotFound
+          raise ModelNotFoundError.new(@model_id, "File not found: #{filename}") if required
+        rescue Down::Error => e
+          raise ModelNotFoundError.new(@model_id, "Download failed: #{e.message}") if required
+        end
+      end
+
+      def hf_token
+        # Check environment variable first
+        return ENV["HF_TOKEN"] if ENV["HF_TOKEN"]
+        return ENV["HUGGING_FACE_HUB_TOKEN"] if ENV["HUGGING_FACE_HUB_TOKEN"]
+
+        # Check standard HuggingFace cache location
+        token_path = File.expand_path("~/.cache/huggingface/token")
+        return File.read(token_path).strip if File.exist?(token_path)
+
+        nil
+      end
+
+      def file_url(filename)
+        "#{HF_HUB_URL}/#{@model_id}/resolve/main/#{filename}"
+      end
+    end
+  end
+end

data/lib/fine/hub/safetensors_loader.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Fine
+  module Hub
+    # Loads SafeTensors weights into torch.rb models
+    class SafetensorsLoader
+      # Load weights from safetensors file into a model
+      #
+      # @param model [Torch::NN::Module] The model to load weights into
+      # @param path [String] Path to the safetensors file
+      # @param strict [Boolean] If true, raise error on missing/unexpected keys
+      # @param prefix [String] Prefix to add/remove from weight names
+      # @return [Hash] Hash with :missing_keys and :unexpected_keys arrays
+      def self.load_into_model(model, path, strict: false, prefix: nil)
+        tensors = Safetensors::Torch.load_file(path)
+
+        # Get model's state dict keys
+        model_keys = model.state_dict.keys
+
+        # Map and filter tensors
+        mapped_tensors = {}
+        unexpected_keys = []
+
+        tensors.each do |name, tensor|
+          mapped_name = map_weight_name(name, prefix: prefix)
+
+          if model_keys.include?(mapped_name)
+            mapped_tensors[mapped_name] = tensor
+          else
+            unexpected_keys << name
+          end
+        end
+
+        # Find missing keys
+        missing_keys = model_keys - mapped_tensors.keys
+
+        # Raise error if strict mode and there are issues
+        if strict && (missing_keys.any? || unexpected_keys.any?)
+          raise WeightLoadingError.new(
+            "Weight loading failed",
+            missing_keys: missing_keys,
+            unexpected_keys: unexpected_keys
+          )
+        end
+
+        # Load the mapped tensors by manually copying data
+        # (torch.rb doesn't support strict: false yet)
+        # Use no_grad to avoid in-place operation errors on leaf tensors
+        Torch.no_grad do
+          state_dict = model.state_dict
+          mapped_tensors.each do |name, tensor|
+            if state_dict.key?(name)
+              state_dict[name].copy!(tensor)
+            end
+          end
+        end
+
+        { missing_keys: missing_keys, unexpected_keys: unexpected_keys }
+      end
+
+      # Map HuggingFace weight names to torch.rb model structure
+      #
+      # @param hf_name [String] Original HuggingFace weight name
+      # @param prefix [String] Optional prefix to strip
+      # @return [String] Mapped weight name for torch.rb
+      def self.map_weight_name(hf_name, prefix: nil)
+        name = hf_name.dup
+
+        # Strip prefix if provided
+        name = name.sub(/^#{Regexp.escape(prefix)}\.?/, "") if prefix
+
+        # SigLIP2 specific mappings
+        # Note: prefix (e.g., "vision_model") is already stripped above
+        name = name.sub("embeddings.patch_embedding", "patch_embed.proj")
+        name = name.sub("embeddings.position_embedding.weight", "pos_embed")
+        name = name.sub("encoder.layers", "blocks")
+        name = name.sub("post_layernorm", "norm")
+        name = name.sub("head", "head")
+
+        # Transformer block mappings
+        name = name.gsub(".self_attn.", ".attn.")
+        name = name.gsub(".layer_norm1.", ".norm1.")
+        name = name.gsub(".layer_norm2.", ".norm2.")
+        # mlp.fc1, mlp.fc2, q_proj, k_proj, v_proj, out_proj names match our model
+
+        name
+      end
+
+      # Load raw tensors from safetensors file
+      #
+      # @param path [String] Path to safetensors file
+      # @return [Hash<String, Torch::Tensor>] Hash of tensor name to tensor
+      def self.load_file(path)
+        Safetensors::Torch.load_file(path)
+      end
+
+      # List tensor names in a safetensors file
+      #
+      # @param path [String] Path to safetensors file
+      # @return [Array<String>] List of tensor names
+      def self.tensor_names(path)
+        Safetensors.safe_open(path, framework: "torch") do |f|
+          f.keys
+        end
+      end
+    end
+  end
+end

data/lib/fine/image_classifier.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+module Fine
+  # High-level API for image classification fine-tuning
+  #
+  # @example Simple usage
+  #   classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-224")
+  #   classifier.fit(train_dir: "data/train", epochs: 3)
+  #   classifier.save("my_model")
+  #
+  # @example With configuration
+  #   classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-224") do |config|
+  #     config.learning_rate = 2e-4
+  #     config.batch_size = 32
+  #     config.on_epoch_end { |epoch, metrics| puts "Epoch #{epoch}: #{metrics}" }
+  #   end
+  #
+  class ImageClassifier
+    attr_reader :model, :config, :label_map, :model_id
+
+    # Create a new ImageClassifier
+    #
+    # @param model_id [String] Hugging Face model ID (e.g., "google/siglip2-base-patch16-224")
+    # @yield [config] Optional configuration block
+    # @yieldparam config [Configuration] Configuration object
+    def initialize(model_id, &block)
+      @model_id = model_id
+      @config = Configuration.new
+      @model = nil
+      @label_map = nil
+      @trained = false
+
+      # Apply configuration block
+      block&.call(@config)
+
+      # Add default progress bar if none configured
+      if @config.callbacks.empty? && Fine.configuration&.progress_bar != false
+        @config.callbacks << Callbacks::ProgressBar.new
+      end
+    end
+
+    # Load a fine-tuned classifier from disk
+    #
+    # @param path [String] Path to saved model directory
+    # @return [ImageClassifier]
+    def self.load(path)
+      config_path = File.join(path, "config.json")
+      raise ModelNotFoundError.new(path, "Model not found") unless File.exist?(config_path)
+
+      config_data = JSON.parse(File.read(config_path))
+
+      classifier = allocate
+      classifier.instance_variable_set(:@model_id, config_data["_model_id"] || "custom")
+      classifier.instance_variable_set(:@config, Configuration.new)
+      classifier.instance_variable_set(:@trained, true)
+
+      # Load label map
+      if config_data["label2id"]
+        classifier.instance_variable_set(:@label_map, config_data["label2id"])
+      elsif config_data["id2label"]
+        classifier.instance_variable_set(
+          :@label_map,
+          config_data["id2label"].transform_keys(&:to_i).invert
+        )
+      end
+
+      # Load model
+      classifier.instance_variable_set(
+        :@model,
+        Models::SigLIP2ForImageClassification.load(path)
+      )
+
+      classifier
+    end
+
+    # Fine-tune the model on a dataset
+    #
+    # @param train_dir [String] Path to training data directory
+    # @param val_dir [String, nil] Path to validation data directory
+    # @param epochs [Integer, nil] Number of epochs (overrides config)
+    # @return [Array<Hash>] Training history
+    def fit(train_dir:, val_dir: nil, epochs: nil)
+      # Override epochs if provided
+      @config.epochs = epochs if epochs
+
+      # Load datasets
+      transforms = build_transforms
+      train_dataset = Datasets::ImageDataset.from_directory(train_dir, transforms: transforms)
+
+      val_dataset = if val_dir
+        Datasets::ImageDataset.from_directory(val_dir, transforms: transforms)
+      end
+
+      # Store label map
+      @label_map = train_dataset.label_map
+      num_classes = train_dataset.num_classes
+
+      # Load or create model
+      @model = Models::SigLIP2ForImageClassification.from_pretrained(
+        @model_id,
+        num_labels: num_classes,
+        freeze_encoder: @config.freeze_encoder,
+        dropout: @config.dropout
+      )
+
+      # Create trainer and train
+      trainer = Training::Trainer.new(
+        @model,
+        @config,
+        train_dataset: train_dataset,
+        val_dataset: val_dataset
+      )
+
+      history = trainer.fit
+      @trained = true
+
+      history
+    end
+
+    # Fine-tune with explicit train/val split
+    #
+    # @param data_dir [String] Path to data directory
+    # @param val_split [Float] Fraction of data to use for validation
+    # @param epochs [Integer, nil] Number of epochs
+    # @return [Array<Hash>] Training history
+    def fit_with_split(data_dir:, val_split: 0.2, epochs: nil)
+      @config.epochs = epochs if epochs
+
+      transforms = build_transforms
+      full_dataset = Datasets::ImageDataset.from_directory(data_dir, transforms: transforms)
+      train_dataset, val_dataset = full_dataset.split(test_size: val_split)
+
+      @label_map = train_dataset.label_map
+      num_classes = train_dataset.num_classes
+
+      @model = Models::SigLIP2ForImageClassification.from_pretrained(
+        @model_id,
+        num_labels: num_classes,
+        freeze_encoder: @config.freeze_encoder,
+        dropout: @config.dropout
+      )
+
+      trainer = Training::Trainer.new(
+        @model,
+        @config,
+        train_dataset: train_dataset,
+        val_dataset: val_dataset
+      )
+
+      history = trainer.fit
+      @trained = true
+
+      history
+    end
+
+    # Make predictions on images
+    #
+    # @param images [String, Array<String>] Path(s) to image file(s)
+    # @param top_k [Integer] Number of top predictions to return
+    # @return [Array<Hash>] Predictions with :label and :score
+    def predict(images, top_k: 5)
+      raise TrainingError, "Model not trained or loaded" unless @trained && @model
+
+      images = [images] if images.is_a?(String)
+      transforms = build_inference_transforms
+
+      # Load and transform images
+      tensors = images.map do |path|
+        image = Vips::Image.new_from_file(path, access: :sequential)
+        transforms.call(image)
+      end
+
+      # Stack into batch
+      pixel_values = Torch.stack(tensors)
+
+      # Get predictions
+      @model.eval
+      probs = @model.predict_proba(pixel_values)
+
+      # Convert to result format
+      inverse_label_map = @label_map.invert
+
+      probs.to_a.map do |sample_probs|
+        # Get top-k predictions
+        sorted = sample_probs.each_with_index.sort_by { |prob, _| -prob }
+        top = sorted.first(top_k)
+
+        top.map do |prob, idx|
+          {
+            label: inverse_label_map[idx] || idx.to_s,
+            score: prob.round(4)
+          }
+        end
+      end
+    end
+
+    # Save the fine-tuned model
+    #
+    # @param path [String] Directory path to save to
+    def save(path)
+      raise TrainingError, "Model not trained" unless @trained && @model
+
+      @model.save(path, label_map: @label_map)
+
+      # Also save the original model ID for reference
+      config_path = File.join(path, "config.json")
+      config = JSON.parse(File.read(config_path))
+      config["_model_id"] = @model_id
+      File.write(config_path, JSON.pretty_generate(config))
+    end
+
+    # Get class names in order of their IDs
+    #
+    # @return [Array<String>] Class names
+    def class_names
+      return [] unless @label_map
+
+      @label_map.sort_by { |_, v| v }.map(&:first)
+    end
+
+    # Export to ONNX format
+    #
+    # @param path [String] Output path for ONNX file
+    # @param options [Hash] Export options
+    # @return [String] The output path
+    def export_onnx(path, **options)
+      Export.to_onnx(self, path, **options)
+    end
+
+    private
+
+    def build_transforms
+      transforms = []
+
+      # Add augmentation transforms if configured
+      if @config.augmentation_config.enabled?
+        transforms.concat(@config.augmentation_config.to_transforms)
+      end
+
+      # Core transforms
+      transforms << Transforms::Resize.new(@config.image_size)
+      transforms << Transforms::ToTensor.new
+      transforms << Transforms::Normalize.new
+
+      Transforms::Compose.new(transforms)
+    end
+
+    def build_inference_transforms
+      Transforms::Compose.new([
+        Transforms::Resize.new(@config.image_size),
+        Transforms::ToTensor.new,
+        Transforms::Normalize.new
+      ])
+    end
+  end
+end