fine 0.1.0

data/lib/fine/callbacks/base.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Fine
+  module Callbacks
+    # Base class for training callbacks
+    class Base
+      def on_train_begin(trainer); end
+      def on_train_end(trainer); end
+      def on_epoch_begin(trainer, epoch); end
+      def on_epoch_end(trainer, epoch, metrics); end
+      def on_batch_begin(trainer, batch_idx); end
+      def on_batch_end(trainer, batch_idx, loss); end
+    end
+
+    # Callback that wraps lambda functions
+    class LambdaCallback < Base
+      def initialize(on_train_begin: nil, on_train_end: nil,
+                     on_epoch_begin: nil, on_epoch_end: nil,
+                     on_batch_begin: nil, on_batch_end: nil)
+        super()
+        @on_train_begin_fn = on_train_begin
+        @on_train_end_fn = on_train_end
+        @on_epoch_begin_fn = on_epoch_begin
+        @on_epoch_end_fn = on_epoch_end
+        @on_batch_begin_fn = on_batch_begin
+        @on_batch_end_fn = on_batch_end
+      end
+
+      def on_train_begin(trainer)
+        @on_train_begin_fn&.call(trainer)
+      end
+
+      def on_train_end(trainer)
+        @on_train_end_fn&.call(trainer)
+      end
+
+      def on_epoch_begin(trainer, epoch)
+        @on_epoch_begin_fn&.call(epoch)
+      end
+
+      def on_epoch_end(trainer, epoch, metrics)
+        @on_epoch_end_fn&.call(epoch, metrics)
+      end
+
+      def on_batch_begin(trainer, batch_idx)
+        @on_batch_begin_fn&.call(batch_idx)
+      end
+
+      def on_batch_end(trainer, batch_idx, loss)
+        @on_batch_end_fn&.call(batch_idx, loss)
+      end
+    end
+
+    # Early stopping callback
+    class EarlyStopping < Base
+      attr_reader :patience, :monitor, :best_value, :wait
+
+      def initialize(patience: 3, monitor: :val_loss, mode: :min)
+        super()
+        @patience = patience
+        @monitor = monitor
+        @mode = mode
+        @best_value = nil
+        @wait = 0
+      end
+
+      def on_epoch_end(trainer, _epoch, metrics)
+        current = metrics[@monitor]
+        return unless current
+
+        if @best_value.nil? || improved?(current)
+          @best_value = current
+          @wait = 0
+        else
+          @wait += 1
+          if @wait >= @patience
+            puts "Early stopping triggered after #{@patience} epochs without improvement"
+            trainer.stop_training = true
+          end
+        end
+      end
+
+      private
+
+      def improved?(current)
+        if @mode == :min
+          current < @best_value
+        else
+          current > @best_value
+        end
+      end
+    end
+
+    # Model checkpoint callback
+    class ModelCheckpoint < Base
+      def initialize(path:, save_best_only: true, monitor: :val_loss, mode: :min)
+        super()
+        @path = path
+        @save_best_only = save_best_only
+        @monitor = monitor
+        @mode = mode
+        @best_value = nil
+      end
+
+      def on_epoch_end(trainer, epoch, metrics)
+        current = metrics[@monitor]
+
+        if @save_best_only
+          return unless current
+
+          if @best_value.nil? || improved?(current)
+            @best_value = current
+            save_checkpoint(trainer, epoch, metrics)
+          end
+        else
+          save_checkpoint(trainer, epoch, metrics)
+        end
+      end
+
+      private
+
+      def improved?(current)
+        if @mode == :min
+          current < @best_value
+        else
+          current > @best_value
+        end
+      end
+
+      def save_checkpoint(trainer, epoch, metrics)
+        checkpoint_path = @path.include?("{epoch}") ?
+          @path.gsub("{epoch}", epoch.to_s) :
+          @path
+
+        trainer.model.save(checkpoint_path, label_map: trainer.label_map)
+        puts "Saved checkpoint to #{checkpoint_path}"
+      end
+    end
+  end
+end

data/lib/fine/callbacks/progress_bar.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Fine
+  module Callbacks
+    # Progress bar callback using TTY::ProgressBar
+    class ProgressBar < Base
+      def initialize(show_epoch: true, show_batch: true)
+        super()
+        @show_epoch = show_epoch
+        @show_batch = show_batch
+        @epoch_bar = nil
+        @batch_bar = nil
+      end
+
+      def on_train_begin(trainer)
+        return unless @show_epoch
+
+        @epoch_bar = TTY::ProgressBar.new(
+          "Training [:bar] :current/:total epochs",
+          total: trainer.config.epochs,
+          width: 30
+        )
+      end
+
+      def on_epoch_begin(trainer, epoch)
+        return unless @show_batch
+
+        @batch_bar = TTY::ProgressBar.new(
+          "  Epoch #{epoch + 1} [:bar] :current/:total batches :rate/s",
+          total: trainer.train_loader.size,
+          width: 25,
+          hide_cursor: true
+        )
+      end
+
+      def on_batch_end(_trainer, _batch_idx, _loss)
+        @batch_bar&.advance
+      end
+
+      def on_epoch_end(_trainer, epoch, metrics)
+        @batch_bar&.finish
+
+        # Format metrics for display
+        metrics_str = metrics.map { |k, v| "#{k}: #{format_value(v)}" }.join(", ")
+        puts "  #{metrics_str}"
+
+        @epoch_bar&.advance
+      end
+
+      def on_train_end(_trainer)
+        @epoch_bar&.finish
+        puts "Training complete!"
+      end
+
+      private
+
+      def format_value(v)
+        case v
+        when Float then format("%.4f", v)
+        when Torch::Tensor then format("%.4f", v.item)
+        else v.to_s
+        end
+      end
+    end
+  end
+end

data/lib/fine/configuration.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Fine
+  # Configuration for training runs
+  class Configuration
+    # Training hyperparameters
+    attr_accessor :epochs, :batch_size, :learning_rate, :weight_decay
+    attr_accessor :warmup_steps, :warmup_ratio
+    attr_accessor :optimizer, :scheduler
+
+    # Model configuration
+    attr_accessor :freeze_encoder, :dropout, :num_labels
+
+    # Data configuration
+    attr_accessor :image_size
+
+    # Callbacks
+    attr_accessor :callbacks
+
+    # Augmentation
+    attr_reader :augmentation_config
+
+    def initialize
+      # Training defaults
+      @epochs = 3
+      @batch_size = 32
+      @learning_rate = 2e-4
+      @weight_decay = 0.02
+      @warmup_steps = 0
+      @warmup_ratio = 0.0
+      @optimizer = :adamw
+      @scheduler = :cosine
+
+      # Model defaults
+      @freeze_encoder = false
+      @dropout = 0.1
+      @num_labels = nil # auto-detect from dataset
+
+      # Data defaults
+      @image_size = 224
+
+      # Callbacks
+      @callbacks = []
+
+      # Augmentation
+      @augmentation_config = AugmentationConfig.new
+    end
+
+    def augmentation
+      yield @augmentation_config if block_given?
+      @augmentation_config
+    end
+
+    # Register a callback for epoch end
+    def on_epoch_end(&block)
+      @callbacks << Callbacks::LambdaCallback.new(on_epoch_end: block)
+    end
+
+    # Register a callback for batch end
+    def on_batch_end(&block)
+      @callbacks << Callbacks::LambdaCallback.new(on_batch_end: block)
+    end
+
+    # Register a callback for train begin
+    def on_train_begin(&block)
+      @callbacks << Callbacks::LambdaCallback.new(on_train_begin: block)
+    end
+
+    # Register a callback for train end
+    def on_train_end(&block)
+      @callbacks << Callbacks::LambdaCallback.new(on_train_end: block)
+    end
+  end
+
+  # Configuration for data augmentation
+  class AugmentationConfig
+    attr_accessor :random_horizontal_flip, :random_vertical_flip
+    attr_accessor :random_rotation, :color_jitter
+    attr_accessor :random_resized_crop
+
+    def initialize
+      @random_horizontal_flip = false
+      @random_vertical_flip = false
+      @random_rotation = 0
+      @color_jitter = nil
+      @random_resized_crop = nil
+    end
+
+    def enabled?
+      @random_horizontal_flip ||
+        @random_vertical_flip ||
+        @random_rotation.positive? ||
+        @color_jitter ||
+        @random_resized_crop
+    end
+
+    def to_transforms
+      transforms = []
+      transforms << Transforms::RandomHorizontalFlip.new if @random_horizontal_flip
+      transforms << Transforms::RandomVerticalFlip.new if @random_vertical_flip
+      transforms << Transforms::RandomRotation.new(@random_rotation) if @random_rotation.positive?
+      # Add more transforms as implemented
+      transforms
+    end
+  end
+end

data/lib/fine/datasets/data_loader.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Fine
+  module Datasets
+    # DataLoader for batching dataset samples
+    class DataLoader
+      include Enumerable
+
+      attr_reader :dataset, :batch_size, :shuffle, :drop_last
+
+      # @param dataset [ImageDataset] The dataset to load from
+      # @param batch_size [Integer] Number of samples per batch
+      # @param shuffle [Boolean] Whether to shuffle indices each epoch
+      # @param drop_last [Boolean] Whether to drop the last incomplete batch
+      def initialize(dataset, batch_size:, shuffle: false, drop_last: false)
+        @dataset = dataset
+        @batch_size = batch_size
+        @shuffle = shuffle
+        @drop_last = drop_last
+        @indices = nil
+      end
+
+      # Iterate over batches
+      def each_batch
+        return enum_for(:each_batch) unless block_given?
+
+        indices = (0...@dataset.size).to_a
+        indices.shuffle! if @shuffle
+
+        indices.each_slice(@batch_size) do |batch_indices|
+          next if @drop_last && batch_indices.size < @batch_size
+
+          yield collate(batch_indices)
+        end
+      end
+
+      alias each each_batch
+
+      # Number of batches
+      def size
+        n = @dataset.size / @batch_size
+        n += 1 unless @drop_last || (@dataset.size % @batch_size).zero?
+        n
+      end
+
+      alias num_batches size
+
+      private
+
+      def collate(indices)
+        samples = indices.map { |i| @dataset[i] }
+
+        # Stack pixel_values into a single tensor
+        pixel_values = Torch.stack(samples.map { |s| s[:pixel_values] })
+
+        # Stack labels into a single tensor
+        labels = Torch.tensor(samples.map { |s| s[:label] }, dtype: :long)
+
+        { pixel_values: pixel_values, labels: labels }
+      end
+    end
+  end
+end

data/lib/fine/datasets/image_dataset.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module Fine
+  module Datasets
+    # Dataset for loading images from a directory structure
+    #
+    # Expected structure:
+    #   data/
+    #     class1/
+    #       image1.jpg
+    #       image2.jpg
+    #     class2/
+    #       image3.jpg
+    #
+    class ImageDataset
+      include Enumerable
+
+      attr_reader :images, :labels, :label_map, :inverse_label_map, :transforms
+
+      IMAGE_EXTENSIONS = %w[.jpg .jpeg .png .webp .bmp .gif].freeze
+
+      # Create dataset from a directory with class subdirectories
+      #
+      # @param path [String] Path to the root directory
+      # @param transforms [Transforms::Compose, nil] Optional transforms to apply
+      # @return [ImageDataset]
+      def self.from_directory(path, transforms: nil)
+        raise DatasetError, "Directory not found: #{path}" unless File.directory?(path)
+
+        images = []
+        labels = []
+
+        # Get sorted list of class directories
+        label_names = Dir.children(path)
+          .select { |f| File.directory?(File.join(path, f)) }
+          .reject { |f| f.start_with?(".") }
+          .sort
+
+        raise DatasetError, "No class directories found in #{path}" if label_names.empty?
+
+        # Build label map
+        label_map = label_names.each_with_index.to_h
+
+        # Collect images from each class directory
+        label_names.each do |label_name|
+          class_dir = File.join(path, label_name)
+          label_id = label_map[label_name]
+
+          Dir.glob(File.join(class_dir, "*")).each do |image_path|
+            next unless image_file?(image_path)
+
+            images << image_path
+            labels << label_id
+          end
+        end
+
+        raise DatasetError, "No images found in #{path}" if images.empty?
+
+        new(images: images, labels: labels, label_map: label_map, transforms: transforms)
+      end
+
+      # Create dataset from explicit arrays
+      #
+      # @param images [Array<String>] Array of image paths
+      # @param labels [Array<Integer, String>] Array of labels
+      # @param label_map [Hash, nil] Optional mapping of label names to IDs
+      # @param transforms [Transforms::Compose, nil] Optional transforms
+      def initialize(images:, labels:, label_map: nil, transforms: nil)
+        raise ArgumentError, "images and labels must have same length" if images.size != labels.size
+
+        @images = images
+        @transforms = transforms || default_transforms
+
+        # Build label map if not provided
+        if label_map
+          @label_map = label_map
+        else
+          unique_labels = labels.uniq.sort
+          @label_map = unique_labels.each_with_index.to_h
+        end
+
+        # Convert string labels to integers if needed
+        @labels = labels.map do |label|
+          label.is_a?(Integer) ? label : @label_map[label]
+        end
+
+        # Build inverse mapping
+        @inverse_label_map = @label_map.invert
+      end
+
+      # Get a single item from the dataset
+      #
+      # @param index [Integer] Index of the item
+      # @return [Hash] Hash with :pixel_values and :label keys
+      def [](index)
+        image = load_image(@images[index])
+        image = @transforms.call(image)
+
+        { pixel_values: image, label: @labels[index] }
+      end
+
+      # Number of items in the dataset
+      def size
+        @images.size
+      end
+      alias length size
+
+      # Iterate over all items
+      def each
+        return enum_for(:each) unless block_given?
+
+        size.times { |i| yield self[i] }
+      end
+
+      # Number of classes
+      def num_classes
+        @label_map.size
+      end
+
+      # Get class names in order
+      def class_names
+        @inverse_label_map.sort.map(&:last)
+      end
+
+      # Split dataset into train and validation sets
+      #
+      # @param test_size [Float] Fraction of data to use for validation (0.0-1.0)
+      # @param shuffle [Boolean] Whether to shuffle before splitting
+      # @param stratify [Boolean] Whether to maintain class distribution
+      # @param seed [Integer, nil] Random seed for reproducibility
+      # @return [Array<ImageDataset, ImageDataset>] Train and validation datasets
+      def split(test_size: 0.2, shuffle: true, stratify: true, seed: nil)
+        rng = seed ? Random.new(seed) : Random.new
+
+        indices = (0...size).to_a
+        indices = indices.shuffle(random: rng) if shuffle && !stratify
+
+        if stratify
+          train_indices, val_indices = stratified_split(indices, test_size, rng)
+        else
+          split_idx = (size * (1 - test_size)).round
+          train_indices = indices[0...split_idx]
+          val_indices = indices[split_idx..]
+        end
+
+        train_set = subset(train_indices)
+        val_set = subset(val_indices)
+
+        [train_set, val_set]
+      end
+
+      private
+
+      def self.image_file?(path)
+        return false unless File.file?(path)
+
+        ext = File.extname(path).downcase
+        IMAGE_EXTENSIONS.include?(ext)
+      end
+
+      def load_image(path)
+        Vips::Image.new_from_file(path, access: :sequential)
+      rescue Vips::Error => e
+        raise ImageProcessingError.new(path, "Failed to load image: #{e.message}")
+      end
+
+      def default_transforms
+        Transforms::Compose.new([
+          Transforms::Resize.new(224),
+          Transforms::ToTensor.new,
+          Transforms::Normalize.new
+        ])
+      end
+
+      def subset(indices)
+        ImageDataset.new(
+          images: indices.map { |i| @images[i] },
+          labels: indices.map { |i| @labels[i] },
+          label_map: @label_map,
+          transforms: @transforms
+        )
+      end
+
+      def stratified_split(indices, test_size, rng)
+        train_indices = []
+        val_indices = []
+
+        # Group indices by label
+        by_label = indices.group_by { |i| @labels[i] }
+
+        by_label.each_value do |label_indices|
+          shuffled = label_indices.shuffle(random: rng)
+          split_idx = (shuffled.size * (1 - test_size)).round
+
+          train_indices.concat(shuffled[0...split_idx])
+          val_indices.concat(shuffled[split_idx..])
+        end
+
+        [train_indices.shuffle(random: rng), val_indices.shuffle(random: rng)]
+      end
+    end
+  end
+end