fine 0.1.0 → 0.2.0

data/examples/data/sentiment_reviews.jsonl

@@ -0,0 +1,30 @@
+{"text": "This product exceeded all my expectations! Build quality is excellent.", "label": "positive"}
+{"text": "Absolutely terrible. Broke within a week of purchase.", "label": "negative"}
+{"text": "Good value for money. Does exactly what it's supposed to do.", "label": "positive"}
+{"text": "Don't waste your money on this. Cheaply made garbage.", "label": "negative"}
+{"text": "Love it! Fast shipping and great customer service.", "label": "positive"}
+{"text": "Arrived damaged and customer support was unhelpful.", "label": "negative"}
+{"text": "Five stars! Best purchase I've made this year.", "label": "positive"}
+{"text": "Returns are impossible. Stuck with a defective product.", "label": "negative"}
+{"text": "Works perfectly. Would definitely recommend to friends.", "label": "positive"}
+{"text": "Complete disappointment. Nothing like the photos.", "label": "negative"}
+{"text": "Amazing quality at this price point. Very impressed!", "label": "positive"}
+{"text": "Stopped working after two uses. Total scam.", "label": "negative"}
+{"text": "Exactly as described. Happy with my purchase.", "label": "positive"}
+{"text": "Worst product I've ever bought. Avoid at all costs.", "label": "negative"}
+{"text": "Great design and functionality. Money well spent!", "label": "positive"}
+{"text": "Flimsy and poorly constructed. Falls apart easily.", "label": "negative"}
+{"text": "Pleasantly surprised by the quality. Ordering another one.", "label": "positive"}
+{"text": "Misleading description. Not what I ordered.", "label": "negative"}
+{"text": "Perfect gift! The recipient loved it.", "label": "positive"}
+{"text": "Overpriced junk. Save your money for something else.", "label": "negative"}
+{"text": "Solid construction and looks even better in person.", "label": "positive"}
+{"text": "Took forever to arrive and was broken. Never again.", "label": "negative"}
+{"text": "This is exactly what I needed. Works flawlessly.", "label": "positive"}
+{"text": "Terrible quality control. Missing parts in the box.", "label": "negative"}
+{"text": "Highly recommend! Exceeded my expectations in every way.", "label": "positive"}
+{"text": "Waste of packaging. The product is unusable.", "label": "negative"}
+{"text": "Beautiful design and excellent craftsmanship.", "label": "positive"}
+{"text": "Looks nothing like the pictures. Very disappointed.", "label": "negative"}
+{"text": "Best investment I've made. Worth every penny.", "label": "positive"}
+{"text": "Cheap materials and terrible assembly. Don't buy.", "label": "negative"}

data/examples/data/support_faq_pairs.jsonl

@@ -0,0 +1,30 @@
+{"query": "How do I reset my password?", "positive": "To reset your password, click 'Forgot Password' on the login page and enter your email address."}
+{"query": "I forgot my login credentials", "positive": "To reset your password, click 'Forgot Password' on the login page and enter your email address."}
+{"query": "Can't remember my password", "positive": "To reset your password, click 'Forgot Password' on the login page and enter your email address."}
+{"query": "How long does shipping take?", "positive": "Standard shipping takes 3-5 business days. Express shipping takes 1-2 business days."}
+{"query": "When will my order arrive?", "positive": "Standard shipping takes 3-5 business days. Express shipping takes 1-2 business days."}
+{"query": "Delivery time estimate", "positive": "Standard shipping takes 3-5 business days. Express shipping takes 1-2 business days."}
+{"query": "How do I return an item?", "positive": "To initiate a return, go to your order history and click 'Request Return' within 30 days of delivery."}
+{"query": "I want to send something back", "positive": "To initiate a return, go to your order history and click 'Request Return' within 30 days of delivery."}
+{"query": "Return policy information", "positive": "To initiate a return, go to your order history and click 'Request Return' within 30 days of delivery."}
+{"query": "Can I cancel my order?", "positive": "You can cancel your order within 1 hour of placing it. Go to your orders and click 'Cancel Order'."}
+{"query": "I changed my mind about my purchase", "positive": "You can cancel your order within 1 hour of placing it. Go to your orders and click 'Cancel Order'."}
+{"query": "Stop my order from shipping", "positive": "You can cancel your order within 1 hour of placing it. Go to your orders and click 'Cancel Order'."}
+{"query": "What payment methods do you accept?", "positive": "We accept Visa, Mastercard, American Express, PayPal, and Apple Pay."}
+{"query": "Can I pay with PayPal?", "positive": "We accept Visa, Mastercard, American Express, PayPal, and Apple Pay."}
+{"query": "Do you take credit cards?", "positive": "We accept Visa, Mastercard, American Express, PayPal, and Apple Pay."}
+{"query": "How do I track my package?", "positive": "Once shipped, you'll receive a tracking number via email. Click the link to see real-time updates."}
+{"query": "Where is my order right now?", "positive": "Once shipped, you'll receive a tracking number via email. Click the link to see real-time updates."}
+{"query": "Package tracking information", "positive": "Once shipped, you'll receive a tracking number via email. Click the link to see real-time updates."}
+{"query": "Do you ship internationally?", "positive": "Yes, we ship to over 50 countries. International shipping takes 7-14 business days."}
+{"query": "Can you deliver to Europe?", "positive": "Yes, we ship to over 50 countries. International shipping takes 7-14 business days."}
+{"query": "Overseas delivery available?", "positive": "Yes, we ship to over 50 countries. International shipping takes 7-14 business days."}
+{"query": "How do I contact customer support?", "positive": "You can reach us via live chat, email at support@example.com, or phone at 1-800-555-0123."}
+{"query": "I need help with an issue", "positive": "You can reach us via live chat, email at support@example.com, or phone at 1-800-555-0123."}
+{"query": "Customer service phone number", "positive": "You can reach us via live chat, email at support@example.com, or phone at 1-800-555-0123."}
+{"query": "How do I change my email address?", "positive": "Go to Account Settings, click 'Edit Profile', and update your email. You'll need to verify the new address."}
+{"query": "Update my contact information", "positive": "Go to Account Settings, click 'Edit Profile', and update your email. You'll need to verify the new address."}
+{"query": "Wrong email on my account", "positive": "Go to Account Settings, click 'Edit Profile', and update your email. You'll need to verify the new address."}
+{"query": "Is my data secure?", "positive": "We use industry-standard encryption and never share your data with third parties without consent."}
+{"query": "Privacy and security policy", "positive": "We use industry-standard encryption and never share your data with third parties without consent."}
+{"query": "How do you protect my information?", "positive": "We use industry-standard encryption and never share your data with third parties without consent."}

data/examples/generate_shape_images.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Generate synthetic shape images for classification testing
+# Creates simple colored rectangles/patterns that are visually distinct
+
+require "vips"
+require "fileutils"
+
+OUTPUT_DIR = File.expand_path("data/shapes", __dir__)
+IMAGE_SIZE = 64
+IMAGES_PER_CLASS = 10
+
+def create_solid_image(path, main_color, bg_color, pattern_type)
+  # Create background
+  bg = Vips::Image.black(IMAGE_SIZE, IMAGE_SIZE, bands: 3)
+  bg = bg.new_from_image(bg_color).copy(interpretation: :srgb)
+
+  # Create a foreground overlay
+  fg = Vips::Image.black(IMAGE_SIZE, IMAGE_SIZE, bands: 3)
+  fg = fg.new_from_image(main_color).copy(interpretation: :srgb)
+
+  case pattern_type
+  when :circle
+    # Just use main color (circles will be red-ish dominant)
+    result = fg
+  when :square
+    # Use green-ish dominant with some background
+    result = fg
+  when :triangle
+    # Use blue-ish dominant
+    result = fg
+  end
+
+  result.write_to_file(path)
+end
+
+# Create directories
+%w[circle square triangle].each do |shape|
+  FileUtils.mkdir_p(File.join(OUTPUT_DIR, shape))
+end
+
+# Random variations
+rand = Random.new(42)
+
+# Color palettes for each shape (to help with learning)
+# Circles: red-ish, Squares: green-ish, Triangles: blue-ish
+circle_colors = [
+  [220, 80, 80], [255, 100, 100], [180, 60, 60], [240, 120, 120],
+  [200, 70, 70], [230, 90, 90], [190, 50, 50], [250, 110, 110],
+  [210, 75, 75], [235, 95, 95]
+]
+
+square_colors = [
+  [80, 180, 80], [100, 220, 100], [60, 160, 60], [120, 200, 120],
+  [70, 190, 70], [90, 210, 90], [50, 170, 50], [110, 195, 110],
+  [75, 185, 75], [95, 205, 95]
+]
+
+triangle_colors = [
+  [80, 80, 220], [100, 100, 255], [60, 60, 180], [120, 120, 240],
+  [70, 70, 200], [90, 90, 230], [50, 50, 190], [110, 110, 250],
+  [75, 75, 210], [95, 95, 235]
+]
+
+bg_color = [240, 240, 240]
+
+IMAGES_PER_CLASS.times do |i|
+  create_solid_image(
+    File.join(OUTPUT_DIR, "circle", "circle_#{i + 1}.jpg"),
+    circle_colors[i % circle_colors.size],
+    bg_color,
+    :circle
+  )
+
+  create_solid_image(
+    File.join(OUTPUT_DIR, "square", "square_#{i + 1}.jpg"),
+    square_colors[i % square_colors.size],
+    bg_color,
+    :square
+  )
+
+  create_solid_image(
+    File.join(OUTPUT_DIR, "triangle", "triangle_#{i + 1}.jpg"),
+    triangle_colors[i % triangle_colors.size],
+    bg_color,
+    :triangle
+  )
+end
+
+puts "Generated #{IMAGES_PER_CLASS * 3} images in #{OUTPUT_DIR}"
+puts "  - #{IMAGES_PER_CLASS} circles (red-ish)"
+puts "  - #{IMAGES_PER_CLASS} squares (green-ish)"
+puts "  - #{IMAGES_PER_CLASS} triangles (blue-ish)"

data/examples/sentiment_classification.rb

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Fine-tune a sentiment classifier for product reviews
+#
+# This example demonstrates how to fine-tune DistilBERT for binary
+# sentiment classification (positive/negative reviews).
+#
+# NOTE: Text classification is currently experimental. For best results:
+# - Use larger datasets (100+ samples per class)
+# - Train for more epochs (20+)
+# - Consider using a pre-fine-tuned sentiment model
+
+require "bundler/setup"
+require "fine"
+
+puts "=" * 60
+puts "SENTIMENT CLASSIFICATION EXAMPLE"
+puts "=" * 60
+
+# Disable progress bar for cleaner output
+Fine.configure { |c| c.progress_bar = false }
+
+data_path = File.expand_path("data/sentiment_reviews.jsonl", __dir__)
+save_path = "/tmp/sentiment-classifier"
+
+puts "\n1. Creating classifier with distilbert-base-uncased..."
+
+classifier = Fine::TextClassifier.new("distilbert-base-uncased") do |config|
+  config.epochs = 10
+  config.batch_size = 8
+  config.learning_rate = 5e-5  # Slightly higher for small dataset
+  config.max_length = 128
+
+  config.on_epoch_end do |epoch, metrics|
+    acc_str = metrics[:accuracy] ? ", acc=#{(metrics[:accuracy] * 100).round(1)}%" : ""
+    puts "   Epoch #{epoch}: loss=#{metrics[:loss].round(4)}#{acc_str}"
+  end
+end
+
+puts "\n2. Fine-tuning on #{data_path}..."
+puts "   (#{File.readlines(data_path).count} examples)"
+
+history = classifier.fit(train_file: data_path, epochs: 10)
+
+puts "\n3. Training complete!"
+puts "   Initial loss: #{history.first[:loss].round(4)}"
+puts "   Final loss: #{history.last[:loss].round(4)}"
+
+improvement = ((1 - history.last[:loss] / history.first[:loss]) * 100).round(1)
+puts "   Improvement: #{improvement}%"
+
+puts "\n4. Testing predictions..."
+
+test_samples = [
+  "This is the best product I've ever purchased! Amazing quality.",
+  "Terrible experience. Product arrived broken and support ignored me.",
+  "Decent product for the price. Does what it's supposed to do.",
+  "Complete waste of money. Returning immediately.",
+  "Exceeded my expectations! Will buy again."
+]
+
+test_samples.each do |text|
+  predictions = classifier.predict(text, top_k: 2)
+  top = predictions.first.first
+  puts "   \"#{text[0, 50]}...\""
+  puts "   => #{top[:label]} (#{(top[:score] * 100).round(1)}%)\n\n"
+end
+
+puts "5. Saving model to #{save_path}..."
+classifier.save(save_path)
+
+puts "\n6. Loading and verifying saved model..."
+loaded = Fine::TextClassifier.load(save_path)
+
+test_text = "Outstanding quality and fast shipping!"
+original_pred = classifier.predict(test_text).first.first
+loaded_pred = loaded.predict(test_text).first.first
+
+puts "   Original: #{original_pred[:label]} (#{original_pred[:score]})"
+puts "   Loaded:   #{loaded_pred[:label]} (#{loaded_pred[:score]})"
+
+puts "\n" + "=" * 60
+puts "SENTIMENT CLASSIFICATION COMPLETE!"
+puts "=" * 60
+puts "\nModel saved to: #{save_path}"
+puts "Load with: Fine::TextClassifier.load('#{save_path}')"

data/examples/shape_classification.rb

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Fine-tune an image classifier for shape/color recognition
+#
+# This example demonstrates how to fine-tune SigLIP2 for classifying
+# images by dominant color (which corresponds to different shapes).
+
+require "bundler/setup"
+require "fine"
+
+puts "=" * 60
+puts "SHAPE CLASSIFICATION EXAMPLE"
+puts "=" * 60
+
+Fine.configure { |c| c.progress_bar = false }
+
+data_dir = File.expand_path("data/shapes", __dir__)
+save_path = "/tmp/shape-classifier"
+
+# Check if images exist
+unless File.exist?(data_dir) && Dir.glob("#{data_dir}/*/*.jpg").any?
+  puts "Generating test images..."
+  require_relative "generate_shape_images"
+end
+
+puts "\n1. Creating classifier with SigLIP2..."
+
+classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-224") do |config|
+  config.epochs = 5
+  config.batch_size = 4
+  config.learning_rate = 1e-4
+  config.image_size = 224
+  config.freeze_encoder = false  # Fine-tune the whole model
+
+  config.on_epoch_end do |epoch, metrics|
+    puts "   Epoch #{epoch}: loss=#{metrics[:loss].round(4)}"
+  end
+end
+
+# Count images
+image_count = Dir.glob("#{data_dir}/*/*.jpg").count
+class_count = Dir.glob("#{data_dir}/*").select { |f| File.directory?(f) }.count
+
+puts "\n2. Fine-tuning on #{data_dir}..."
+puts "   (#{image_count} images across #{class_count} classes)"
+puts "   Classes: #{Dir.glob("#{data_dir}/*").select { |f| File.directory?(f) }.map { |f| File.basename(f) }.join(", ")}"
+
+history = classifier.fit(train_dir: data_dir, epochs: 5)
+
+puts "\n3. Training complete!"
+puts "   Initial loss: #{history.first[:loss].round(4)}"
+puts "   Final loss: #{history.last[:loss].round(4)}"
+
+improvement = ((1 - history.last[:loss] / history.first[:loss]) * 100).round(1)
+puts "   Improvement: #{improvement}%"
+
+puts "\n4. Testing predictions on training images..."
+
+# Test on one image from each class
+%w[circle square triangle].each do |shape|
+  test_image = Dir.glob("#{data_dir}/#{shape}/*.jpg").first
+  predictions = classifier.predict(test_image, top_k: 3)
+  top = predictions.first.first
+
+  puts "   #{shape}_1.jpg => #{top[:label]} (#{(top[:score] * 100).round(1)}%)"
+end
+
+puts "\n5. Saving model to #{save_path}..."
+classifier.save(save_path)
+
+puts "\n6. Loading and verifying saved model..."
+loaded = Fine::ImageClassifier.load(save_path)
+
+test_image = Dir.glob("#{data_dir}/circle/*.jpg").first
+original_pred = classifier.predict(test_image).first.first
+loaded_pred = loaded.predict(test_image).first.first
+
+puts "   Original: #{original_pred[:label]} (#{original_pred[:score].round(4)})"
+puts "   Loaded:   #{loaded_pred[:label]} (#{loaded_pred[:score].round(4)})"
+
+puts "\n" + "=" * 60
+puts "SHAPE CLASSIFICATION COMPLETE!"
+puts "=" * 60
+puts "\nModel saved to: #{save_path}"
+puts "Load with: Fine::ImageClassifier.load('#{save_path}')"
+puts "Classes: #{classifier.class_names.join(", ")}"

data/examples/support_faq_embeddings.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Fine-tune text embeddings for customer support FAQ matching
+#
+# This example demonstrates how to fine-tune a sentence transformer model
+# for semantic search in a customer support context.
+
+require "bundler/setup"
+require "fine"
+
+puts "=" * 60
+puts "SUPPORT FAQ EMBEDDINGS EXAMPLE"
+puts "=" * 60
+
+Fine.configure { |c| c.progress_bar = false }
+
+data_path = File.expand_path("data/support_faq_pairs.jsonl", __dir__)
+save_path = "/tmp/support-faq-embedder"
+
+puts "\n1. Creating embedder with all-MiniLM-L6-v2..."
+
+embedder = Fine::TextEmbedder.new("sentence-transformers/all-MiniLM-L6-v2") do |config|
+  config.epochs = 2
+  config.batch_size = 8
+  config.learning_rate = 2e-5
+
+  config.on_epoch_end do |epoch, metrics|
+    puts "   Epoch #{epoch}: loss=#{metrics[:loss].round(4)}"
+  end
+end
+
+puts "   Embedding dimension: #{embedder.embedding_dim}"
+
+# Test pre-training similarity
+puts "\n2. Testing pre-training similarity..."
+test_query = "How can I get my money back?"
+faq_answer = "To initiate a return, go to your order history and click 'Request Return' within 30 days of delivery."
+
+pre_similarity = embedder.similarity(test_query, faq_answer)
+puts "   Query: \"#{test_query}\""
+puts "   FAQ: \"#{faq_answer[0, 60]}...\""
+puts "   Pre-training similarity: #{pre_similarity.round(4)}"
+
+puts "\n3. Fine-tuning on #{data_path}..."
+puts "   (#{File.readlines(data_path).count} query-answer pairs)"
+
+history = embedder.fit(train_file: data_path, epochs: 2)
+
+puts "\n4. Training complete!"
+puts "   Initial loss: #{history.first[:loss].round(4)}"
+puts "   Final loss: #{history.last[:loss].round(4)}"
+
+# Test post-training similarity
+puts "\n5. Testing post-training similarity..."
+post_similarity = embedder.similarity(test_query, faq_answer)
+puts "   Post-training similarity: #{post_similarity.round(4)}"
+puts "   Improvement: #{((post_similarity - pre_similarity) * 100).round(2)} percentage points"
+
+# Semantic search demo
+puts "\n6. Semantic search demo..."
+
+faq_corpus = [
+  "To reset your password, click 'Forgot Password' on the login page and enter your email address.",
+  "Standard shipping takes 3-5 business days. Express shipping takes 1-2 business days.",
+  "To initiate a return, go to your order history and click 'Request Return' within 30 days of delivery.",
+  "You can cancel your order within 1 hour of placing it. Go to your orders and click 'Cancel Order'.",
+  "We accept Visa, Mastercard, American Express, PayPal, and Apple Pay.",
+  "Once shipped, you'll receive a tracking number via email. Click the link to see real-time updates.",
+  "Yes, we ship to over 50 countries. International shipping takes 7-14 business days.",
+  "You can reach us via live chat, email at support@example.com, or phone at 1-800-555-0123."
+]
+
+test_queries = [
+  "I need to get my money back for this purchase",
+  "What's the phone number for help?",
+  "Can you deliver to Germany?"
+]
+
+test_queries.each do |query|
+  results = embedder.search(query, faq_corpus, top_k: 2)
+  puts "\n   Query: \"#{query}\""
+  results.each_with_index do |result, i|
+    puts "   #{i + 1}. (#{result[:score].round(3)}) #{result[:text][0, 60]}..."
+  end
+end
+
+puts "\n7. Saving model to #{save_path}..."
+embedder.save(save_path)
+
+puts "\n8. Loading and verifying saved model..."
+loaded = Fine::TextEmbedder.load(save_path)
+
+original_emb = embedder.encode("test query")
+loaded_emb = loaded.encode("test query")
+
+# Check embeddings are the same
+diff = original_emb.zip(loaded_emb).sum { |a, b| (a - b).abs }
+puts "   Embedding difference: #{diff.round(6)} (should be ~0)"
+
+puts "\n" + "=" * 60
+puts "SUPPORT FAQ EMBEDDINGS COMPLETE!"
+puts "=" * 60
+puts "\nModel saved to: #{save_path}"
+puts "Load with: Fine::TextEmbedder.load('#{save_path}')"