rpeft 0.1.0

data/lib/rpeft/cli/command.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+module RPEFT
+  module CLI
+    # @api private
+    class Command
+      def self.run(argv, out: $stdout, err: $stderr)
+        new(out: out, err: err).run(argv)
+      end
+
+      def initialize(out:, err:)
+        @out = out
+        @err = err
+      end
+
+      def run(argv)
+        options = {}
+        parser = option_parser(options)
+        help_requested = false
+        parser.on_tail('-h', '--help', 'Show this help') do
+          help_requested = true
+        end
+
+        begin
+          parser.parse(argv)
+        rescue OptionParser::ParseError => e
+          return usage_error(e.message, parser)
+        end
+        if help_requested
+          @out.puts parser
+          return 0
+        end
+
+        missing = required_options.reject { |key| options.key?(key) }
+        return usage_error("missing required option(s): #{format_options(missing)}", parser) unless missing.empty?
+
+        violation = usage_violation(options)
+        return usage_error(violation, parser) if violation
+
+        execute(options) || 0
+      rescue Error => e
+        @err.puts "rpeft: #{printable(e.message)}"
+        1
+      end
+
+      private
+
+      # Control characters other than newline and tab, made visible as \xNN. Model output and messages
+      # carried over from Python are arbitrary text, and a terminal would act on an escape sequence in them
+      # (moving the cursor, rewriting the screen or the clipboard) instead of showing it.
+      def printable(text)
+        text.to_s.scrub.gsub(/[\x00-\x08\x0B-\x1F\x7F\u0080-\u009F]/) { |char| format('\\x%02X', char.ord) }
+      end
+
+      def required_options
+        []
+      end
+
+      # Commands override this for constraints that a required-option list cannot express;
+      # a String return value is a usage error.
+      def usage_violation(_options)
+        nil
+      end
+
+      def usage_error(message, parser)
+        @err.puts "rpeft: #{printable(message)}"
+        @err.puts parser
+        2
+      end
+
+      def format_options(keys)
+        keys.map { |key| "--#{key.to_s.tr('_', '-')}" }.join(', ')
+      end
+    end
+  end
+end

data/lib/rpeft/cli/doctor.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RPEFT
+  module CLI
+    # @api private
+    class Doctor < Command
+      private
+
+      def option_parser(_options)
+        OptionParser.new do |o|
+          o.banner = 'Usage: rpeft doctor'
+        end
+      end
+
+      def execute(_options)
+        report = RPEFT.check
+        render(report)
+        report['status'] == 'ok' ? 0 : 1
+      end
+
+      def render(report)
+        line 'Ruby', "#{report.dig('ruby', 'version')} (rpeft #{report.dig('ruby', 'rpeft')})"
+        backend = report['backend'] || {}
+        if backend['ok']
+          render_python(report['python'])
+          render_libraries(report['libraries'])
+          render_device(report['device'])
+        else
+          line 'Backend', "NG #{backend['error']}"
+        end
+
+        # Uppercase for consistency with the OK/MISSING library markers;
+        # the check API itself keeps the machine-readable lowercase value.
+        line 'Status', report['status'].to_s.upcase
+        render_hint(report)
+      end
+
+      def line(label, value)
+        padded = "#{label}:".ljust(14)
+        @out.puts "#{padded}#{value}"
+      end
+
+      def render_python(python)
+        python ||= {}
+        line 'Python', "#{python['version']} (#{python['executable']})"
+      end
+
+      def render_libraries(libraries)
+        (libraries || {}).each do |name, info|
+          if !info['installed']
+            line name, 'MISSING'
+          elsif info['outdated']
+            line name, "OUTDATED #{info['version']} (needs #{info['minimum']} or later)"
+          else
+            line name, "OK #{info['version']}"
+          end
+        end
+      end
+
+      def render_device(device)
+        return line('Device', 'unknown (torch is not installed)') unless device
+
+        cuda = device.dig('cuda', 'available') ? 'yes' : 'no'
+        mps = device.dig('mps', 'available') ? 'yes' : 'no'
+        line 'Device', "#{device['recommended']} (CUDA: #{cuda}, MPS: #{mps})"
+      end
+
+      def render_hint(report)
+        return unless report['status'] == 'degraded'
+
+        @out.puts 'Hint: pip install --upgrade torch transformers peft datasets accelerate'
+      end
+    end
+  end
+end

data/lib/rpeft/cli/generate.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RPEFT
+  module CLI
+    # @api private
+    class Generate < Command
+      REQUIRED_OPTIONS = %i(prompt).freeze
+      PASSTHROUGH_OPTIONS = %i(max_new_tokens device temperature top_p seed).freeze
+      DEVICES = %w(auto cuda mps cpu).freeze
+
+      private
+
+      def option_parser(options)
+        OptionParser.new do |o|
+          o.banner = 'Usage: rpeft generate {--model DIR_OR_ID | --adapter DIR} --prompt TEXT [options]'
+          o.on('--model MODEL', 'Model directory or Hugging Face model id (base model override with --adapter)') do |v|
+            options[:model] = v
+          end
+          o.on('--adapter DIR', 'LoRA adapter directory, applied on top of its base model without merging') do |v|
+            options[:adapter] = v
+          end
+          o.on('--prompt TEXT', 'Prompt to complete') do |v|
+            options[:prompt] = v
+          end
+          o.on('--max-new-tokens N', Integer, 'Maximum number of tokens to generate (default: 64)') do |v|
+            options[:max_new_tokens] = v
+          end
+          o.on('--temperature F', Float, 'Sampling temperature (default: greedy decoding)') do |v|
+            options[:temperature] = v
+          end
+          o.on('--top-p F', Float, 'Nucleus sampling threshold') do |v|
+            options[:top_p] = v
+          end
+          o.on('--seed N', Integer, 'Random seed for sampling') do |v|
+            options[:seed] = v
+          end
+          o.on('--device DEVICE', DEVICES, 'auto, cuda, mps, or cpu (default: auto)') { |v| options[:device] = v.to_sym }
+        end
+      end
+
+      def required_options
+        REQUIRED_OPTIONS
+      end
+
+      def usage_violation(options)
+        return nil if options[:model] || options[:adapter]
+
+        'missing required option(s): --model or --adapter'
+      end
+
+      def execute(options)
+        generate_options = {}
+        PASSTHROUGH_OPTIONS.each do |key|
+          generate_options[key] = options[key] if options.key?(key)
+        end
+
+        target = if options[:adapter]
+          LoRA::Adapter.load(options[:adapter], base_model: options[:model])
+        else
+          Model.new(path: options[:model])
+        end
+
+        @out.puts printable(target.generate(options[:prompt], **generate_options))
+
+        0
+      end
+    end
+  end
+end

data/lib/rpeft/cli/lora_merge.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module RPEFT
+  module CLI
+    # @api private
+    class LoRAMerge < Command
+      REQUIRED_OPTIONS = %i(adapter output).freeze
+
+      private
+
+      def option_parser(options)
+        OptionParser.new do |o|
+          o.banner = 'Usage: rpeft lora merge --adapter DIR --output DIR [options]'
+          o.on('--adapter DIR', 'Trained LoRA adapter directory') do |v|
+            options[:adapter] = v
+          end
+          o.on('--output DIR', 'Directory to save the merged model') do |v|
+            options[:output] = v
+          end
+          o.on('--model MODEL',
+               'Base model override (defaults to the one recorded in the adapter)') do |v|
+            options[:model] = v
+          end
+        end
+      end
+
+      def required_options
+        REQUIRED_OPTIONS
+      end
+
+      def execute(options)
+        adapter = LoRA::Adapter.load(options[:adapter], base_model: options[:model])
+        model = adapter.merge(output_dir: options[:output])
+
+        @out.puts "Merged model saved to #{model.path}"
+        0
+      end
+    end
+  end
+end

data/lib/rpeft/cli/lora_train.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module RPEFT
+  module CLI
+    # @api private
+    class LoRATrain < Command
+      PASSTHROUGH_OPTIONS = %i(rank alpha dropout target_modules epochs batch_size
+                               learning_rate max_length device).freeze
+      REQUIRED_OPTIONS = %i(model dataset output).freeze
+      DEVICES = %w(auto cuda mps cpu).freeze
+
+      private
+
+      def option_parser(options)
+        OptionParser.new do |o|
+          o.banner = 'Usage: rpeft lora train --model MODEL --dataset FILE --output DIR [options]'
+          o.on('--model MODEL', 'Base model (Hugging Face id or local path)') do |v|
+            options[:model] = v
+          end
+          o.on('--dataset FILE', %(Training dataset (JSONL with "text", "instruction"/"output", or "messages" lines))) do |v|
+            options[:dataset] = v
+          end
+          o.on('--output DIR', 'Directory to save the trained adapter') do |v|
+            options[:output] = v
+          end
+          o.on('--rank N', Integer, 'LoRA rank r (default: 8)') do |v|
+            options[:rank] = v
+          end
+          o.on('--alpha N', Float, 'LoRA alpha (default: 16)') do |v|
+            options[:alpha] = v
+          end
+          o.on('--dropout F', Float, 'LoRA dropout (default: 0.05)') do |v|
+            options[:dropout] = v
+          end
+          o.on('--target-modules LIST', Array,
+               'Comma-separated module names (default: auto-detect)') do |v|
+            options[:target_modules] = v
+          end
+          o.on('--epochs N', Integer, 'Training epochs (default: 3)') do |v|
+            options[:epochs] = v
+          end
+          o.on('--batch-size N', Integer, 'Batch size (default: 4)') do |v|
+            options[:batch_size] = v
+          end
+          o.on('--learning-rate F', Float, 'Learning rate (default: 0.0002)') do |v|
+            options[:learning_rate] = v
+          end
+          o.on('--max-length N', Integer, 'Max token length (default: 512)') do |v|
+            options[:max_length] = v
+          end
+          o.on('--device DEVICE', DEVICES,
+               'auto, cuda, mps, or cpu (default: auto)') { |v| options[:device] = v.to_sym }
+        end
+      end
+
+      def required_options
+        REQUIRED_OPTIONS
+      end
+
+      def execute(options)
+        train_options = {model: options[:model], dataset: options[:dataset],
+                         output_dir: options[:output]}
+        PASSTHROUGH_OPTIONS.each do |key|
+          train_options[key] = options[key] if options.key?(key)
+        end
+
+        adapter = LoRA.train(**train_options)
+
+        @out.puts "Adapter saved to #{adapter.path}"
+        loss = adapter.metadata.dig('training', 'train_loss')
+        @out.puts format('Final training loss: %.4f', loss) if loss
+        0
+      end
+    end
+  end
+end

data/lib/rpeft/cli.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative '../rpeft'
+require_relative 'cli/command'
+require_relative 'cli/lora_train'
+require_relative 'cli/lora_merge'
+require_relative 'cli/generate'
+require_relative 'cli/doctor'
+
+module RPEFT
+  # Command line interface. Commands go through the public Ruby API only,
+  # never straight to the backend.
+  module CLI
+    USAGE = <<~USAGE
+      Usage: rpeft <command> [options]
+
+      Commands:
+        lora train   Fine-tune a base model with LoRA
+        lora merge   Merge a LoRA adapter into its base model
+        generate     Generate text from a base or fine-tuned model
+        doctor       Diagnose the Python environment
+        version      Print the RPEFT version
+        help         Show this message
+
+      Run `rpeft <command> --help` for command options.
+    USAGE
+
+    LORA_USAGE = <<~USAGE
+      Usage: rpeft lora <subcommand> [options]
+
+      Subcommands:
+        train   Fine-tune a base model with LoRA
+        merge   Merge a LoRA adapter into its base model
+    USAGE
+
+    class << self
+      def run(argv, out: $stdout, err: $stderr)
+        command, *rest = argv
+        case command
+        when 'lora' then run_lora(rest, out: out, err: err)
+        when 'generate' then Generate.run(rest, out: out, err: err)
+        when 'doctor' then Doctor.run(rest, out: out, err: err)
+        when 'version', '--version', '-v'
+          out.puts VERSION
+          0
+        when nil, 'help', '--help', '-h'
+          out.puts USAGE
+          0
+        else
+          err.puts "rpeft: unknown command #{command.inspect}"
+          err.puts USAGE
+          2
+        end
+      rescue Interrupt
+        err.puts 'Interrupted'
+        130
+      end
+
+      private
+
+      def run_lora(argv, out:, err:)
+        subcommand, *rest = argv
+        case subcommand
+        when 'train' then LoRATrain.run(rest, out: out, err: err)
+        when 'merge' then LoRAMerge.run(rest, out: out, err: err)
+        when nil, 'help', '--help', '-h'
+          out.puts LORA_USAGE
+          0
+        else
+          err.puts "rpeft: unknown lora subcommand #{subcommand.inspect}"
+          err.puts LORA_USAGE
+          2
+        end
+      end
+    end
+  end
+end

data/lib/rpeft/dataset.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'tmpdir'
+
+module RPEFT
+  # A training dataset. `Dataset.coerce` turns any value accepted by the `dataset:` keyword
+  # (a path String, a Pathname, an Enumerable of record Hashes, or a Dataset) into a validated Dataset.
+  #
+  # Three JSONL line formats are accepted and detected from the first line: `{"text": ...}` is
+  # passed through as is, `{"instruction": ..., "input": ..., "output": ...}` is rendered into
+  # a text prompt, and `{"messages": [{"role": ..., "content": ...}, ...]}` is passed through
+  # for the backend to render with the tokenizer's chat template.
+  class Dataset
+    def self.coerce(value)
+      return value if value.is_a?(Dataset)
+      return from_records(value) if value.is_a?(Enumerable)
+
+      new(Arguments.path(value, 'dataset'))
+    end
+
+    # Builds a dataset from Ruby records (Hashes in any of the three formats, Symbol keys included)
+    # by writing them to a temporary JSONL file, so in-memory data needs no intermediate file of its own.
+    def self.from_records(records)
+      dir = Dir.mktmpdir('rpeft-dataset-')
+      path = File.join(dir, 'records.jsonl')
+      written = 0
+
+      File.open(path, 'w') do |out|
+        records.each do |record|
+          raise DatasetError, "each dataset record must be a Hash, got #{record.class}" unless record.is_a?(Hash)
+
+          out.puts JSON.generate(record)
+          written += 1
+        end
+      end
+      raise DatasetError, 'dataset is empty: no records were given' if written.zero?
+
+      new(path, name: nil, temporary_dir: dir)
+    rescue StandardError
+      FileUtils.rm_rf(dir)
+      raise
+    end
+
+    # name is the file name the dataset came from, recorded in the adapter metadata;
+    # nil for in-memory records, which have no file of their own.
+    attr_reader :path, :format, :name
+
+    def initialize(source, name: File.basename(source.to_s), temporary_dir: nil)
+      @name = name
+      @temporary_dirs = [temporary_dir].compact
+      source_path = existing_file(source)
+      @format = detect_format(source_path)
+      @path = @format == :instruction ? normalize(source_path) : source_path
+    end
+
+    # Removes the temporary copies this dataset wrote for the backend. The source file is left alone.
+    def discard
+      @temporary_dirs.each do |dir|
+        FileUtils.rm_rf(dir)
+      end
+      @temporary_dirs.clear
+    end
+
+    # The format the backend sees. Instruction datasets are normalized to text here,
+    # so only text and messages ever cross the boundary.
+    def backend_format
+      format == :messages ? 'messages' : 'text'
+    end
+
+    private
+
+    def existing_file(source)
+      path = File.expand_path(source)
+      raise DatasetError, "dataset file not found: #{path}" unless File.file?(path)
+
+      path
+    end
+
+    def detect_format(path)
+      record = first_record(path)
+      if record.is_a?(Hash)
+        return :text if record.key?('text')
+        return :instruction if record.key?('instruction') && record.key?('output')
+
+        if record.key?('messages')
+          validate_messages(record['messages'], path)
+          return :messages
+        end
+      end
+
+      raise DatasetError, "each dataset line must be a JSON object with a \"text\" key, \"instruction\"/\"output\" keys, or a \"messages\" key: #{path}"
+    end
+
+    def validate_messages(messages, path)
+      return if Messages.valid?(messages)
+
+      raise DatasetError, "\"messages\" must be a non-empty array of objects with a \"role\" of system, user, or assistant and a \"content\" string: #{path}"
+    end
+
+    def first_record(path)
+      line = File.foreach(path).find { |l| !l.strip.empty? }
+      raise DatasetError, "dataset is empty: #{path}" unless line
+
+      parse_line(line, path)
+    end
+
+    def parse_line(line, path)
+      JSON.parse(line)
+    rescue JSON::ParserError => e
+      raise DatasetError, "dataset is not JSONL (#{e.message}): #{path}"
+    end
+
+    # Rewrites a non-text dataset into text-format JSONL in
+    # a temporary directory, so the backend only ever sees one format.
+    def normalize(source_path)
+      dir = Dir.mktmpdir('rpeft-dataset-')
+      @temporary_dirs << dir
+      normalized = File.join(dir, File.basename(source_path))
+
+      File.open(normalized, 'w') do |out|
+        File.foreach(source_path).with_index(1) do |line, lineno|
+          next if line.strip.empty?
+
+          record = parse_line(line, source_path)
+          out.puts JSON.generate('text' => render_instruction(record, lineno, source_path))
+        end
+      end
+
+      normalized
+    rescue StandardError
+      discard
+      raise
+    end
+
+    def render_instruction(record, lineno, source_path)
+      instruction = record['instruction']
+      output = record['output']
+      if !instruction.is_a?(String) || instruction.empty? || !output.is_a?(String)
+        raise DatasetError, "line #{lineno}: instruction format requires \"instruction\" and \"output\" strings: #{source_path}"
+      end
+
+      input = record['input']
+      text = "### Instruction:\n#{instruction}\n"
+      text << "\n### Input:\n#{input}\n" if input && !input.to_s.empty?
+      text << "\n### Response:\n#{output}"
+      text
+    end
+  end
+end

data/lib/rpeft/device.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RPEFT
+  # @api private
+  module Device
+    def self.resolve(device)
+      device = device.to_sym if device.is_a?(String)
+      return RPEFT.device if device == :auto
+
+      unless device.is_a?(Symbol) && DEVICES.include?(device)
+        raise ConfigurationError, "unknown device: #{device.inspect} (expected :auto, :cuda, :mps, or :cpu)"
+      end
+
+      device
+    end
+  end
+end

data/lib/rpeft/diagnosis.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RPEFT
+  # Builds the layered environment report behind RPEFT.check and `rpeft doctor`.
+  # Never raises: backend failures are folded into the report so the doctor can explain
+  # a broken environment.
+  class Diagnosis
+    REQUIRED_LIBRARIES = %w(torch transformers peft datasets accelerate).freeze
+
+    def initialize(backend: RPEFT.backend)
+      @backend = backend
+    end
+
+    def report
+      base = {'ruby' => {'version' => RUBY_VERSION, 'rpeft' => VERSION}}
+      begin
+        diagnostics = @backend.diagnostics
+      rescue Error => e
+        return base.merge(
+          'backend' => {'ok' => false, 'error' => e.message},
+          'status' => 'unusable'
+        )
+      end
+
+      base.merge(
+        'backend' => {'ok' => true, 'version' => diagnostics['backend_version']},
+        'python' => diagnostics['python'],
+        'libraries' => diagnostics['libraries'],
+        'device' => diagnostics['device'],
+        'status' => status_of(diagnostics)
+      )
+    end
+
+    private
+
+    def status_of(diagnostics)
+      libraries = diagnostics['libraries'] || {}
+      unusable = REQUIRED_LIBRARIES.reject { |name|
+        libraries.dig(name, 'installed') && !libraries.dig(name, 'outdated')
+      }
+      unusable.empty? ? 'ok' : 'degraded'
+    end
+  end
+end