trainers-rb 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fd96717156bbd2f4d515f3b1a5aaea897f581b1888bb527124de305a6c2d536
-  data.tar.gz: 4a4a764def0528487ee20adb5e1edce52d7a3d267f1c99e399f5f48a7a5d9e2b
+  metadata.gz: b2025ca407a70ba9d0a206306f48486eaae88854e767dd006aa9f37af752eaf1
+  data.tar.gz: 5e4a9e5a90d377791c5577399b88aab55e5d00468f4cae13710e0d140d482e5f
 SHA512:
-  metadata.gz: 4a36d98cfc6a61d3fe7cad411a653e242b7f2a11f402e7add4ea2300bd9ee59601c8408b864a1094ba6486444b4b9197c524d89de9b50e8c74ee263b3d59ab0b
-  data.tar.gz: da2ec1f4fd3d69e76f3d6a812aec49454ff9d99b99006e1b53f0086e4a60d1958d69b6a1b7447e033fcbf927c412cc3fea50954d0c3cd72e5ce49adf4140d95f
+  metadata.gz: 16679778184715a50d08ff4de4e5050bca75c98dc02b542331f14aae79a6a0b857b3a2699da060e3de3ce7924357486b3b60da2563e7759eccd4e2fd10d6c716
+  data.tar.gz: d1580d3571d6adaa1dd771b4cfdbea1bf9ea3a002b35bb06e5f4f9184946a6243dd9aac19c4ac96fccb19690e1e7c2291d51a0c03ad551f7ca32600a7092cc91

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 0.1.2 (2026-10-30)
+
+### Fixed
+
+- `LoraModel.merge` no longer applies adapters twice. Merged layers kept adding the LoRA path on top of the merged weights, so a merged model's outputs were wrong. Each `LoraLinear` is now replaced by a plain `Torch::NN::Linear` holding the merged weights, so a saved merged model has the base model's parameter names. `LoraLinear#merge!` is idempotent and adds `#merged?` and `#to_linear`.
+- `Trainers::VERSION` now matches the gem version. The gemspec reads it from `lib/trainers/version.rb`. (#2)
+
+### Changed
+
+- `TrainingArguments` validates its values at construction, and raises `ArgumentError` naming the argument, the value received and what was expected (#8):
+  - positive: `learning_rate`
+  - positive Integer: `num_train_epochs`, both batch sizes, `gradient_accumulation_steps`, `logging_steps`, `save_steps`
+  - non-negative: `weight_decay`, `max_grad_norm`; `warmup_steps` must also be an Integer
+  - `warmup_ratio` must be within 0..1, and `eval_steps` must be nil or a positive Integer
+  - `lr_scheduler_type` must be one of `:linear`, `:cosine`, `:constant`; `eval_strategy` and `save_strategy` one of `:no`, `:epoch`, `:steps`
+
+  Previously these were accepted and failed later, or were silently ignored. Defaults are unchanged.
+
+### Internal
+
+- CI on Ruby 3.3, 3.4 and 4.0 against torch-rb 0.17 (LibTorch 2.4.0) and 0.27 (LibTorch 2.15.0), using Appraisal gemfiles, plus macOS arm64; every job is required (#9)
+- Tests for LR schedulers and warmup (#6), callback order and arguments (#7), LoRA shapes, identity init, merge and adapter round-trip (#5), and a public API surface test (#10)
+- Development dependency minitest bumped to ~> 6.0
+- CONTRIBUTING.md with LibTorch setup, SECURITY.md, README badges and a known-limitations section (#11)
+
+## 0.1.1 (2026-06-09)
+
+- Fix gemspec homepage, source and changelog URLs to point to github.com/Selectus2/trainers-rb
+- No code changes. The published gem reports `Trainers::VERSION` as "0.1.0"; the constant is corrected here
+
 ## 0.1.0 (2026-06-07)
 
 - Initial release

data/README.md

@@ -1,5 +1,10 @@
 # trainers-rb
 
+[![Gem Version](https://img.shields.io/gem/v/trainers-rb)](https://rubygems.org/gems/trainers-rb)
+[![CI](https://github.com/Selectus2/trainers-rb/actions/workflows/ci.yml/badge.svg)](https://github.com/Selectus2/trainers-rb/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+[![Ruby](https://img.shields.io/badge/ruby-3.3%20%7C%203.4%20%7C%204.0-red.svg)](.github/workflows/ci.yml)
+
 Fine-tune transformer models in Ruby.
 
 trainers-rb provides a training loop, LoRA (Low-Rank Adaptation), learning rate scheduling, and model serialization for HuggingFace transformer models loaded via [transformers-rb](https://github.com/ankane/transformers-ruby). It builds on [torch-rb](https://github.com/ankane/torch.rb) for autograd, optimizers, and tensor operations.
@@ -22,15 +27,16 @@ gem install trainers-rb
 
 ### Prerequisites
 
-trainers-rb depends on torch-rb, which requires LibTorch:
+trainers-rb depends on torch-rb, which compiles against LibTorch. Use the LibTorch version that matches your torch-rb: 2.15.0 for torch-rb 0.27, or 2.4.0 for torch-rb 0.17.
 
 ```bash
 # macOS arm64
-curl -L -o /tmp/libtorch.zip https://download.pytorch.org/libtorch/cpu/libtorch-macos-arm64-2.4.0.zip
-unzip /tmp/libtorch.zip -d ~/libtorch
-bundle config set build.torch-rb --with-torch-dir=$HOME/libtorch/libtorch
+curl -L -o /tmp/libtorch.zip https://download.pytorch.org/libtorch/cpu/libtorch-macos-arm64-2.15.0.zip
+unzip /tmp/libtorch.zip -d ~/libtorch-2.15.0
+bundle config set build.torch-rb --with-torch-dir=$HOME/libtorch-2.15.0/libtorch
 ```
 
+For Linux, and for running the tests, see [CONTRIBUTING.md](CONTRIBUTING.md).
 ## Quick Start
 
 ```ruby
@@ -140,6 +146,8 @@ Trainers::LoraModel.load_adapters(model, "./lora-adapters")
 | `seed` | `42` | Random seed |
 | `no_mps` | `false` | Force CPU even if MPS is available |
 
+Invalid values, such as a negative learning rate, a zero batch size or an unknown `lr_scheduler_type`, raise `ArgumentError` when `TrainingArguments` is created.
+
 ## Callbacks
 
 Built-in callbacks:
@@ -274,6 +282,19 @@ trainers-rb
 
 trainers-rb adds the training layer that transformers-rb intentionally omits. Both gems call into the same LibTorch C++ kernels for the actual computation.
 
+## Known limitations
+
+These are open correctness issues. They are tracked, and listed here so nobody discovers them the hard way:
+
+- **The learning-rate schedule is wrong with `gradient_accumulation_steps > 1`.** The scheduler is sized in micro-batches but stepped once per optimizer step, so it never decays fully. ([#12](https://github.com/Selectus2/trainers-rb/issues/12))
+- **`seed:` is never applied.** Runs are not reproducible. ([#13](https://github.com/Selectus2/trainers-rb/issues/13))
+- **`dataloader_drop_last:` and `label_names:` are accepted and ignored.** ([#14](https://github.com/Selectus2/trainers-rb/issues/14))
+- **Progress output goes to stdout through `puts`.** There is no logger to configure or silence. ([#15](https://github.com/Selectus2/trainers-rb/issues/15))
+- **`save_lora_adapters` returns `nil` instead of raising when a model has no adapters.** ([#16](https://github.com/Selectus2/trainers-rb/issues/16))
+- **A saved model cannot be loaded back.** No `config.json` is written. ([#17](https://github.com/Selectus2/trainers-rb/issues/17))
+- **Checkpoints cannot resume training.** Optimizer, scheduler and trainer state are not saved. ([#18](https://github.com/Selectus2/trainers-rb/issues/18))
+- **LoRA checkpoints save the full state dict** rather than just the adapters. ([#19](https://github.com/Selectus2/trainers-rb/issues/19))
+
 ## Roadmap
 
 - [ ] More model architectures in transformers-rb (GPT-2, Llama for text generation)
@@ -286,7 +307,7 @@ trainers-rb adds the training layer that transformers-rb intentionally omits. Bo
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub.
+Bug reports and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers LibTorch setup, running the tests against each supported torch-rb, and what a good PR looks like. Report security issues privately, as described in [SECURITY.md](SECURITY.md).
 
 ## License
 

data/lib/trainers/lora/lora_linear.rb

@@ -36,12 +36,20 @@ module Trainers
       @lora_B = Torch::NN::Parameter.new(Torch.zeros(@out_features, @r))
 
       @lora_dropout = lora_dropout > 0 ? Torch::NN::Dropout.new(p: lora_dropout) : nil
+      @merged       = false
+    end
+
+    def merged?
+      @merged
     end
 
     def forward(x)
       # Original linear
       base_output = Torch::NN::F.linear(x, @weight, @bias)
 
+      # After merge! the adapter is already folded into @weight
+      return base_output if @merged
+
       # LoRA path
       lora_input = @lora_dropout ? @lora_dropout.call(x) : x
       lora_output = lora_input.matmul(@lora_A.t).matmul(@lora_B.t) * @scaling
@@ -49,14 +57,30 @@ module Trainers
       base_output + lora_output
     end
 
-    # Merge LoRA weights into the base weight matrix (for inference)
+    # Merge LoRA weights into the base weight matrix (for inference).
+    # Idempotent: merging twice would add the adapter twice.
     def merge!
+      return self if @merged
+
       Torch.no_grad do
         @weight.add!(@lora_B.matmul(@lora_A) * @scaling)
       end
+      @merged = true
       self
     end
 
+    # A plain Linear holding the merged weights, so a merged model has the
+    # same parameter names as the base model
+    def to_linear
+      merge!
+      linear = Torch::NN::Linear.new(@in_features, @out_features, bias: !@bias.nil?)
+      Torch.no_grad do
+        linear.weight.copy!(@weight)
+        linear.bias.copy!(@bias) if @bias
+      end
+      linear
+    end
+
     # Extract LoRA adapter state for saving
     def lora_state_dict
       { "lora_A" => @lora_A.data, "lora_B" => @lora_B.data }

data/lib/trainers/lora/lora_model.rb

@@ -56,16 +56,14 @@ module Trainers
       model
     end
 
-    # Merge all LoRA weights back into base weights (for inference)
+    # Merge all LoRA weights back into base weights (for inference).
+    # Each LoraLinear is replaced by a plain Linear with the merged weights.
     def self.merge(model)
-      count = 0
-      model.named_modules.each do |_, mod|
-        if mod.is_a?(LoraLinear)
-          mod.merge!
-          count += 1
-        end
+      lora_modules = model.named_modules.select { |_, mod| mod.is_a?(LoraLinear) }
+      lora_modules.each do |name, mod|
+        LoraUtils.replace_module(model, name, mod.to_linear)
       end
-      puts "Merged #{count} LoRA adapters into base model"
+      puts "Merged #{lora_modules.size} LoRA adapters into base model"
       model
     end
 

data/lib/trainers/training_arguments.rb

@@ -31,18 +31,28 @@ module Trainers
       label_names:                   ["labels"]
     }.freeze
 
+    SCHEDULER_TYPES = %i[linear cosine constant].freeze
+    STRATEGIES      = %i[no epoch steps].freeze
+
+    POSITIVE_NUMBERS  = %i[learning_rate].freeze
+    POSITIVE_INTEGERS = %i[num_train_epochs per_device_train_batch_size per_device_eval_batch_size
+                           gradient_accumulation_steps logging_steps save_steps].freeze
+    NON_NEGATIVE      = %i[weight_decay max_grad_norm].freeze
+
     DEFAULTS.each_key do |key|
       attr_accessor key
     end
 
     def initialize(**kwargs)
+      unknown = kwargs.keys - DEFAULTS.keys
+      raise ArgumentError, "Unknown arguments: #{unknown.join(', ')}" unless unknown.empty?
+
       DEFAULTS.each do |key, default|
         value = kwargs.fetch(key, default)
         instance_variable_set(:"@#{key}", value)
       end
 
-      unknown = kwargs.keys - DEFAULTS.keys
-      raise ArgumentError, "Unknown arguments: #{unknown.join(', ')}" unless unknown.empty?
+      validate!
     end
 
     def resolved_device
@@ -60,5 +70,35 @@ module Trainers
         hash[key] = send(key)
       end
     end
+
+    private
+
+    # Rejects values that cannot produce a sensible run. Errors name the
+    # argument, the value received, and what was expected.
+    def validate!
+      POSITIVE_NUMBERS.each do |key|
+        check(key, "a positive number") { |v| v.is_a?(Numeric) && v.positive? }
+      end
+      POSITIVE_INTEGERS.each do |key|
+        check(key, "a positive Integer") { |v| v.is_a?(Integer) && v.positive? }
+      end
+      NON_NEGATIVE.each do |key|
+        check(key, "a non-negative number") { |v| v.is_a?(Numeric) && !v.negative? }
+      end
+      check(:warmup_steps, "a non-negative Integer") { |v| v.is_a?(Integer) && !v.negative? }
+      check(:warmup_ratio, "a number between 0 and 1") { |v| v.is_a?(Numeric) && v.between?(0, 1) }
+      check(:eval_steps, "nil or a positive Integer") { |v| v.nil? || (v.is_a?(Integer) && v.positive?) }
+
+      check(:lr_scheduler_type, "one of #{SCHEDULER_TYPES.map(&:inspect).join(', ')}") { |v| SCHEDULER_TYPES.include?(v) }
+      check(:eval_strategy, "one of #{STRATEGIES.map(&:inspect).join(', ')}") { |v| STRATEGIES.include?(v) }
+      check(:save_strategy, "one of #{STRATEGIES.map(&:inspect).join(', ')}") { |v| STRATEGIES.include?(v) }
+    end
+
+    def check(key, expected)
+      value = send(key)
+      return if yield(value)
+
+      raise ArgumentError, "#{key} must be #{expected}, got #{value.inspect}"
+    end
   end
 end

data/lib/trainers/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Trainers
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trainers-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Vishwajeetsingh Desurkar
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: torch-rb
@@ -85,20 +86,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
 description: Training loop, LoRA, and optimization utilities for fine-tuning HuggingFace
   transformer models using torch-rb and transformers-rb. Supports full fine-tuning,
   LoRA adapters, learning rate scheduling, callbacks, and model serialization via
   safetensors.
 email:
-- selectus2@users.noreply.rubygems.org
+- vishwajeetsinghd@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -122,13 +123,16 @@ files:
 - lib/trainers/trainer_utils.rb
 - lib/trainers/training_arguments.rb
 - lib/trainers/version.rb
-homepage: https://github.com/trainers-rb/trainers-rb
+homepage: https://github.com/Selectus2/trainers-rb
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/trainers-rb/trainers-rb
-  source_code_uri: https://github.com/trainers-rb/trainers-rb
-  changelog_uri: https://github.com/trainers-rb/trainers-rb/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/Selectus2/trainers-rb
+  source_code_uri: https://github.com/Selectus2/trainers-rb
+  changelog_uri: https://github.com/Selectus2/trainers-rb/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Selectus2/trainers-rb/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -143,7 +147,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.5
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Fine-tune transformer models in Ruby
 test_files: []