fine 0.1.0

data/lib/fine/llm.rb

@@ -0,0 +1,336 @@
+# frozen_string_literal: true
+
+module Fine
+  # High-level API for LLM fine-tuning
+  #
+  # @example Basic fine-tuning
+  #   llm = Fine::LLM.new("meta-llama/Llama-3.2-1B")
+  #   llm.fit(train_file: "instructions.jsonl", epochs: 3)
+  #   llm.save("my_llama")
+  #
+  # @example Generation
+  #   llm = Fine::LLM.load("my_llama")
+  #   response = llm.generate("What is Ruby?", max_new_tokens: 100)
+  #
+  # @example With configuration
+  #   llm = Fine::LLM.new("google/gemma-2b") do |config|
+  #     config.epochs = 3
+  #     config.batch_size = 4
+  #     config.learning_rate = 1e-5
+  #     config.max_length = 1024
+  #   end
+  #
+  class LLM
+    attr_reader :model, :config, :tokenizer, :model_id
+
+    # Create a new LLM for fine-tuning
+    #
+    # @param model_id [String] HuggingFace model ID
+    # @yield [config] Optional configuration block
+    def initialize(model_id, &block)
+      @model_id = model_id
+      @config = LLMConfiguration.new
+      @model = nil
+      @tokenizer = nil
+      @trained = false
+
+      block&.call(@config)
+
+      if @config.callbacks.empty? && Fine.configuration&.progress_bar != false
+        @config.callbacks << Callbacks::ProgressBar.new
+      end
+    end
+
+    # Load a fine-tuned LLM from disk
+    #
+    # @param path [String] Path to saved model
+    # @return [LLM]
+    def self.load(path)
+      config_path = File.join(path, "config.json")
+      raise ModelNotFoundError.new(path) unless File.exist?(config_path)
+
+      config_data = JSON.parse(File.read(config_path))
+
+      llm = allocate
+      llm.instance_variable_set(:@model_id, config_data["_model_id"] || "custom")
+      llm.instance_variable_set(:@config, LLMConfiguration.new)
+      llm.instance_variable_set(:@trained, true)
+
+      # Load tokenizer
+      tokenizer_path = File.join(path, "tokenizer.json")
+      tokenizer = if File.exist?(tokenizer_path)
+        Tokenizers::AutoTokenizer.new(path, max_length: config_data["max_length"] || 2048)
+      else
+        Tokenizers::AutoTokenizer.from_pretrained(
+          config_data["_model_id"],
+          max_length: config_data["max_length"] || 2048
+        )
+      end
+      llm.instance_variable_set(:@tokenizer, tokenizer)
+
+      # Load model
+      llm.instance_variable_set(
+        :@model,
+        Models::CausalLM.load(path)
+      )
+
+      llm
+    end
+
+    # Fine-tune on instruction data
+    #
+    # @param train_file [String] Path to training data (JSONL)
+    # @param val_file [String, nil] Path to validation data
+    # @param format [Symbol] Data format (:alpaca, :sharegpt, :simple, :auto)
+    # @param epochs [Integer, nil] Override config epochs
+    # @return [Array<Hash>] Training history
+    def fit(train_file:, val_file: nil, format: :auto, epochs: nil)
+      @config.epochs = epochs if epochs
+
+      # Download model files first (including tokenizer)
+      downloader = Hub::ModelDownloader.new(@model_id)
+      model_path = downloader.download
+
+      # Load tokenizer from cache or HuggingFace
+      tokenizer_path = File.join(model_path, "tokenizer.json")
+      @tokenizer = if File.exist?(tokenizer_path)
+        Tokenizers::AutoTokenizer.new(model_path, max_length: @config.max_length)
+      else
+        Tokenizers::AutoTokenizer.from_pretrained(@model_id, max_length: @config.max_length)
+      end
+
+      # Set pad token if not set
+      @config.pad_token_id ||= @tokenizer.pad_token_id || @tokenizer.eos_token_id || 0
+
+      # Load datasets
+      train_dataset = Datasets::InstructionDataset.from_jsonl(
+        train_file,
+        tokenizer: @tokenizer,
+        format: format,
+        max_length: @config.max_length
+      )
+
+      val_dataset = if val_file
+        Datasets::InstructionDataset.from_jsonl(
+          val_file,
+          tokenizer: @tokenizer,
+          format: format,
+          max_length: @config.max_length
+        )
+      end
+
+      # Load model
+      @model = Models::CausalLM.from_pretrained(@model_id)
+
+      # Freeze layers if configured
+      if @config.freeze_layers && @config.freeze_layers > 0
+        freeze_bottom_layers(@config.freeze_layers)
+      end
+
+      # Train
+      trainer = Training::LLMTrainer.new(
+        @model,
+        @config,
+        train_dataset: train_dataset,
+        val_dataset: val_dataset
+      )
+
+      history = trainer.fit
+      @trained = true
+
+      history
+    end
+
+    # Fine-tune with automatic train/val split
+    #
+    # @param data_file [String] Path to data file
+    # @param val_split [Float] Fraction for validation
+    # @param format [Symbol] Data format
+    # @return [Array<Hash>] Training history
+    def fit_with_split(data_file:, val_split: 0.1, format: :auto, epochs: nil)
+      @config.epochs = epochs if epochs
+
+      # Download model files first (including tokenizer)
+      downloader = Hub::ModelDownloader.new(@model_id)
+      model_path = downloader.download
+
+      # Load tokenizer from cache or HuggingFace
+      tokenizer_path = File.join(model_path, "tokenizer.json")
+      @tokenizer = if File.exist?(tokenizer_path)
+        Tokenizers::AutoTokenizer.new(model_path, max_length: @config.max_length)
+      else
+        Tokenizers::AutoTokenizer.from_pretrained(@model_id, max_length: @config.max_length)
+      end
+
+      @config.pad_token_id ||= @tokenizer.pad_token_id || @tokenizer.eos_token_id || 0
+
+      full_dataset = Datasets::InstructionDataset.from_jsonl(
+        data_file,
+        tokenizer: @tokenizer,
+        format: format,
+        max_length: @config.max_length
+      )
+
+      train_dataset, val_dataset = full_dataset.split(test_size: val_split)
+
+      @model = Models::CausalLM.from_pretrained(@model_id)
+
+      if @config.freeze_layers && @config.freeze_layers > 0
+        freeze_bottom_layers(@config.freeze_layers)
+      end
+
+      trainer = Training::LLMTrainer.new(
+        @model,
+        @config,
+        train_dataset: train_dataset,
+        val_dataset: val_dataset
+      )
+
+      history = trainer.fit
+      @trained = true
+
+      history
+    end
+
+    # Generate text
+    #
+    # @param prompt [String] Input prompt
+    # @param max_new_tokens [Integer] Maximum tokens to generate
+    # @param temperature [Float] Sampling temperature (higher = more random)
+    # @param top_p [Float] Nucleus sampling threshold
+    # @param top_k [Integer] Top-k sampling
+    # @param do_sample [Boolean] Whether to sample (false = greedy)
+    # @return [String] Generated text
+    def generate(prompt, max_new_tokens: 100, temperature: 0.7, top_p: 0.9, top_k: 50, do_sample: true)
+      raise TrainingError, "Model not loaded" unless @model && @tokenizer
+
+      # Tokenize prompt (without tensors for easier manipulation)
+      encoding = @tokenizer.encode(prompt, return_tensors: false)
+      input_ids = Torch.tensor([encoding[:input_ids].first])
+
+      # Move to device
+      input_ids = input_ids.to(Fine.device)
+      @model.to(Fine.device)
+
+      # Generate
+      output_ids = @model.generate(
+        input_ids,
+        max_new_tokens: max_new_tokens,
+        temperature: temperature,
+        top_p: top_p,
+        top_k: top_k,
+        do_sample: do_sample,
+        eos_token_id: @tokenizer.eos_token_id,
+        pad_token_id: @config.pad_token_id
+      )
+
+      # Decode
+      @tokenizer.decode(output_ids[0].to_a)
+    end
+
+    # Chat-style generation
+    #
+    # @param messages [Array<Hash>] Messages with :role and :content
+    # @param kwargs [Hash] Generation parameters
+    # @return [String] Assistant response
+    def chat(messages, **kwargs)
+      prompt = format_chat_prompt(messages)
+      full_response = generate(prompt, **kwargs)
+
+      # Extract just the assistant response
+      if full_response.include?("### Response:")
+        full_response.split("### Response:").last.strip
+      else
+        # Remove the prompt from the response
+        full_response[prompt.length..].strip
+      end
+    end
+
+    # Save the model
+    #
+    # @param path [String] Directory to save to
+    def save(path)
+      raise TrainingError, "Model not trained or loaded" unless @model
+
+      @model.save(path)
+      @tokenizer.save(path)
+
+      # Update config with model ID
+      config_path = File.join(path, "config.json")
+      config = JSON.parse(File.read(config_path))
+      config["_model_id"] = @model_id
+      config["max_length"] = @config.max_length
+      File.write(config_path, JSON.pretty_generate(config))
+    end
+
+    # Export to GGUF format for llama.cpp, ollama, etc.
+    #
+    # @param path [String] Output path for GGUF file
+    # @param quantization [Symbol] Quantization type (:f16, :q4_0, :q8_0, etc.)
+    # @param metadata [Hash] Additional metadata
+    # @return [String] The output path
+    def export_gguf(path, quantization: :f16, **options)
+      Export.to_gguf(self, path, quantization: quantization, **options)
+    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 freeze_bottom_layers(num_layers)
+      # Freeze embedding
+      @model.decoder.embed_tokens.parameters.each { |p| p.requires_grad = false }
+
+      # Freeze bottom N layers
+      @model.decoder.layers[0...num_layers].each do |layer|
+        layer.parameters.each { |p| p.requires_grad = false }
+      end
+    end
+
+    def format_chat_prompt(messages)
+      prompt = ""
+
+      messages.each do |msg|
+        case msg[:role]
+        when "system"
+          prompt += "### System:\n#{msg[:content]}\n\n"
+        when "user"
+          prompt += "### Instruction:\n#{msg[:content]}\n\n"
+        when "assistant"
+          prompt += "### Response:\n#{msg[:content]}\n\n"
+        end
+      end
+
+      # Add response prefix for the model to continue
+      prompt += "### Response:\n" unless prompt.end_with?("### Response:\n")
+
+      prompt
+    end
+  end
+
+  # Configuration for LLM fine-tuning
+  class LLMConfiguration < Configuration
+    attr_accessor :max_length, :warmup_steps, :gradient_accumulation_steps,
+                  :max_grad_norm, :freeze_layers, :pad_token_id
+
+    def initialize
+      super
+      @max_length = 2048
+      @learning_rate = 2e-5
+      @batch_size = 4
+      @epochs = 1
+      @warmup_steps = 100
+      @gradient_accumulation_steps = 4
+      @max_grad_norm = 1.0
+      @freeze_layers = 0
+      @pad_token_id = nil
+    end
+  end
+end

data/lib/fine/models/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Fine
+  module Models
+    # Base class for all Fine models
+    class Base < Torch::NN::Module
+      attr_reader :config
+
+      def initialize(config)
+        super()
+        @config = config
+      end
+
+      # Save model weights to a file
+      #
+      # @param path [String] Directory path to save to
+      def save_pretrained(path)
+        FileUtils.mkdir_p(path)
+
+        # Save weights as safetensors
+        weights_path = File.join(path, "model.safetensors")
+        Safetensors::Torch.save_file(state_dict, weights_path)
+
+        # Save config
+        config_path = File.join(path, "config.json")
+        File.write(config_path, JSON.pretty_generate(@config.to_h))
+      end
+
+      # Freeze all parameters (for feature extraction)
+      def freeze!
+        parameters.each { |p| p.requires_grad = false }
+        self
+      end
+
+      # Unfreeze all parameters
+      def unfreeze!
+        parameters.each { |p| p.requires_grad = true }
+        self
+      end
+
+      # Get number of trainable parameters
+      def num_parameters(trainable_only: false)
+        params = trainable_only ? parameters.select(&:requires_grad) : parameters
+        params.sum { |p| p.numel }
+      end
+    end
+  end
+end

data/lib/fine/models/bert_encoder.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Fine
+  module Models
+    # BERT/DistilBERT/DeBERTa Encoder
+    #
+    # Implements transformer encoder for text understanding tasks.
+    # Supports loading pretrained weights from HuggingFace Hub.
+    class BertEncoder < Base
+      attr_reader :embeddings, :encoder, :pooler
+
+      def initialize(config)
+        super(config)
+
+        @hidden_size = config.hidden_size
+        @num_layers = config.num_hidden_layers
+        @num_heads = config.num_attention_heads
+        @intermediate_size = config.intermediate_size
+        @vocab_size = config.vocab_size
+        @max_position_embeddings = config.max_position_embeddings
+        @type_vocab_size = config.type_vocab_size || 2
+        @layer_norm_eps = config.layer_norm_eps
+        @hidden_dropout_prob = config.hidden_dropout_prob || 0.1
+
+        # Embeddings
+        @word_embeddings = Torch::NN::Embedding.new(@vocab_size, @hidden_size)
+        @position_embeddings = Torch::NN::Embedding.new(@max_position_embeddings, @hidden_size)
+        @token_type_embeddings = Torch::NN::Embedding.new(@type_vocab_size, @hidden_size)
+        @embeddings_layer_norm = Torch::NN::LayerNorm.new(@hidden_size, eps: @layer_norm_eps)
+        @embeddings_dropout = Torch::NN::Dropout.new(p: @hidden_dropout_prob)
+
+        # Transformer layers
+        @layers = Torch::NN::ModuleList.new(
+          @num_layers.times.map do
+            BertLayer.new(
+              hidden_size: @hidden_size,
+              num_heads: @num_heads,
+              intermediate_size: @intermediate_size,
+              layer_norm_eps: @layer_norm_eps,
+              hidden_dropout_prob: @hidden_dropout_prob
+            )
+          end
+        )
+
+        # Pooler (for [CLS] token representation)
+        @pooler_dense = Torch::NN::Linear.new(@hidden_size, @hidden_size)
+        @pooler_activation = Torch::NN::Tanh.new
+      end
+
+      def forward(input_ids, attention_mask: nil, token_type_ids: nil)
+        batch_size, seq_length = input_ids.shape
+
+        # Create position IDs
+        position_ids = Torch.arange(seq_length, device: input_ids.device)
+        position_ids = position_ids.unsqueeze(0).expand(batch_size, -1)
+
+        # Default token type IDs to zeros
+        token_type_ids ||= Torch.zeros_like(input_ids)
+
+        # Embeddings
+        word_embeds = @word_embeddings.call(input_ids)
+        position_embeds = @position_embeddings.call(position_ids)
+        token_type_embeds = @token_type_embeddings.call(token_type_ids)
+
+        embeddings = word_embeds + position_embeds + token_type_embeds
+        embeddings = @embeddings_layer_norm.call(embeddings)
+        embeddings = @embeddings_dropout.call(embeddings)
+
+        # Create attention mask for transformer
+        # Convert from (batch, seq) to (batch, 1, 1, seq) for broadcasting
+        if attention_mask
+          extended_attention_mask = attention_mask.unsqueeze(1).unsqueeze(2)
+          extended_attention_mask = (1.0 - extended_attention_mask) * -10000.0
+        else
+          extended_attention_mask = nil
+        end
+
+        # Transformer layers
+        hidden_states = embeddings
+        @layers.each do |layer|
+          hidden_states = layer.call(hidden_states, attention_mask: extended_attention_mask)
+        end
+
+        # Pool the [CLS] token (first token)
+        cls_output = hidden_states[0.., 0, 0..]
+        pooled_output = @pooler_dense.call(cls_output)
+        pooled_output = @pooler_activation.call(pooled_output)
+
+        {
+          last_hidden_state: hidden_states,
+          pooler_output: pooled_output
+        }
+      end
+
+      # Get the [CLS] token embedding (useful for classification)
+      def get_pooled_output(input_ids, attention_mask: nil, token_type_ids: nil)
+        output = forward(input_ids, attention_mask: attention_mask, token_type_ids: token_type_ids)
+        output[:pooler_output]
+      end
+
+      # Get mean of all token embeddings (useful for sentence embeddings)
+      def get_mean_output(input_ids, attention_mask: nil, token_type_ids: nil)
+        output = forward(input_ids, attention_mask: attention_mask, token_type_ids: token_type_ids)
+        hidden_states = output[:last_hidden_state]
+
+        if attention_mask
+          # Mask padding tokens before taking mean
+          mask = attention_mask.unsqueeze(-1).expand_as(hidden_states).float
+          sum_embeddings = (hidden_states * mask).sum(dim: 1)
+          sum_mask = mask.sum(dim: 1).clamp(min: 1e-9)
+          sum_embeddings / sum_mask
+        else
+          hidden_states.mean(dim: 1)
+        end
+      end
+    end
+
+    # Single BERT transformer layer
+    class BertLayer < Torch::NN::Module
+      def initialize(hidden_size:, num_heads:, intermediate_size:, layer_norm_eps:, hidden_dropout_prob:)
+        super()
+
+        @attention = BertAttention.new(
+          hidden_size: hidden_size,
+          num_heads: num_heads,
+          dropout: hidden_dropout_prob
+        )
+        @attention_layer_norm = Torch::NN::LayerNorm.new(hidden_size, eps: layer_norm_eps)
+        @attention_dropout = Torch::NN::Dropout.new(p: hidden_dropout_prob)
+
+        @intermediate = Torch::NN::Linear.new(hidden_size, intermediate_size)
+        @intermediate_act = Torch::NN::GELU.new
+        @output = Torch::NN::Linear.new(intermediate_size, hidden_size)
+        @output_layer_norm = Torch::NN::LayerNorm.new(hidden_size, eps: layer_norm_eps)
+        @output_dropout = Torch::NN::Dropout.new(p: hidden_dropout_prob)
+      end
+
+      def forward(hidden_states, attention_mask: nil)
+        # Self-attention with residual
+        attention_output = @attention.call(hidden_states, attention_mask: attention_mask)
+        attention_output = @attention_dropout.call(attention_output)
+        hidden_states = @attention_layer_norm.call(hidden_states + attention_output)
+
+        # FFN with residual
+        intermediate_output = @intermediate.call(hidden_states)
+        intermediate_output = @intermediate_act.call(intermediate_output)
+        layer_output = @output.call(intermediate_output)
+        layer_output = @output_dropout.call(layer_output)
+        @output_layer_norm.call(hidden_states + layer_output)
+      end
+    end
+
+    # BERT multi-head self-attention
+    class BertAttention < Torch::NN::Module
+      def initialize(hidden_size:, num_heads:, dropout:)
+        super()
+
+        @num_heads = num_heads
+        @head_dim = hidden_size / num_heads
+        @scale = @head_dim ** -0.5
+
+        @query = Torch::NN::Linear.new(hidden_size, hidden_size)
+        @key = Torch::NN::Linear.new(hidden_size, hidden_size)
+        @value = Torch::NN::Linear.new(hidden_size, hidden_size)
+        @out = Torch::NN::Linear.new(hidden_size, hidden_size)
+        @dropout = Torch::NN::Dropout.new(p: dropout)
+      end
+
+      def forward(hidden_states, attention_mask: nil)
+        batch_size, seq_length, _ = hidden_states.shape
+
+        # Project to Q, K, V
+        q = @query.call(hidden_states)
+        k = @key.call(hidden_states)
+        v = @value.call(hidden_states)
+
+        # Reshape for multi-head attention
+        q = q.view(batch_size, seq_length, @num_heads, @head_dim).transpose(1, 2)
+        k = k.view(batch_size, seq_length, @num_heads, @head_dim).transpose(1, 2)
+        v = v.view(batch_size, seq_length, @num_heads, @head_dim).transpose(1, 2)
+
+        # Attention scores
+        scores = Torch.matmul(q, k.transpose(-2, -1)) * @scale
+
+        # Apply attention mask
+        scores = scores + attention_mask if attention_mask
+
+        # Softmax and dropout
+        attn_probs = Torch::NN::Functional.softmax(scores, dim: -1)
+        attn_probs = @dropout.call(attn_probs)
+
+        # Apply attention to values
+        context = Torch.matmul(attn_probs, v)
+
+        # Reshape back
+        context = context.transpose(1, 2).contiguous.view(batch_size, seq_length, -1)
+
+        @out.call(context)
+      end
+    end
+  end
+end