fine 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a12cf37fd90bb1744c5d4a91863406a7bd02742df9596113dce12e847874e969
-  data.tar.gz: 7fba7fea8eef802257b8f20949a78befe21baad74757ab28426c147c508d4009
+  metadata.gz: e4f1a43c08a5a1f84d56676c0f8831cab888481c7011bee1d81ef09cbf3ce239
+  data.tar.gz: 0330fc12a8a1cbd25a58e86a733250b14d1f5372d194f4b86f80f1c8c073a266
 SHA512:
-  metadata.gz: 7a6383340fc114a158e34bc905dddc24865b0ace2d4fa771abd129ca0a5bb9cbeb372682b181329ad33daffa447facf426a65cd275580f59951c4e22791e0747
-  data.tar.gz: e8ae855256a5cd1fd2d3467177f3990db3081ff416e36931968f75b1f2578fa979fe7699d38d288fcbd35d3ab7bfa3cb545dfbee697f4b02e1a113375307f1a6
+  metadata.gz: c4fa0df707889ed969d75b1315ef3b98013015acbb4954cfaf78027506c104c17ed1f558871a3524e2327b1031f2d3768bc94797875934fd24418d80046fd079
+  data.tar.gz: 0b5f0ad3c7952b39f15f6fa3f8fed858d9b31b26e1fbeceb2afcf9697803b10c236e5257fdef855b30c15b90dc053c0aacbb36a62adbf8762c771d11f074cc74

data/README.md

@@ -90,19 +90,27 @@ similarity = cosine_similarity(embedding1, embedding2)
 
 ---
 
-### LLMs
+### LLMs (with LoRA)
 
-Fine-tune Gemma, Llama, Qwen and other open models for custom tasks.
+Fine-tune Gemma, Llama, Qwen and other open models using LoRA—train only 0.5% of parameters.
 
 ```ruby
-llm = Fine::LLM.new("meta-llama/Llama-3.2-1B")
-llm.fit(train_file: "instructions.jsonl", epochs: 3)
+model = Fine::Models::CausalLM.from_pretrained("google/gemma-3-1b-it")
 
-llm.generate("Explain Ruby blocks")
-# => "A Ruby block is a chunk of code that can be passed to a method..."
+# Apply LoRA - only 0.5% of params trainable
+Fine::LoRA.apply(model, rank: 32, alpha: 64)
+#   Trainable params: 5.96M (0.46%)
+
+# Train on your data
+trainer = Fine::Training::LLMTrainer.new(model, config, train_dataset: dataset)
+trainer.fit
+
+# Merge weights and save
+Fine::LoRA.merge!(model)
+model.save("my_model")
 ```
 
-[Full tutorial: LLM Fine-tuning](docs/tutorials/llm-fine-tuning.md)
+[Full tutorial: LLM Fine-tuning](docs/tutorials/llm-fine-tuning.md) | [LoRA Tool Calling](docs/tutorials/lora-tool-calling.md)
 
 ---
 
@@ -114,7 +122,7 @@ gem 'fine'
 
 Requires Ruby 3.1+, LibTorch, and libvips.
 
-[Full installation guide](docs/installation.md)
+[Full installation guide](docs/installation.md) | [Quickstart](docs/quickstart.md)
 
 **Quick setup (macOS):**
 ```bash
@@ -155,8 +163,9 @@ bundle install
 
 | Model | Parameters | Best For |
 |-------|------------|----------|
+| `google/gemma-3-1b-it` | 1B | Fast experiments, tool calling |
 | `meta-llama/Llama-3.2-1B` | 1B | Fast experiments |
-| `google/gemma-2b` | 2B | Good balance |
+| `google/gemma-3-4b-it` | 4B | Good balance |
 | `Qwen/Qwen2-1.5B` | 1.5B | Multilingual |
 | `mistralai/Mistral-7B-v0.1` | 7B | Best quality |
 
@@ -201,7 +210,8 @@ llm.export_gguf("model.gguf", quantization: :q4_0)
 - [x] Text embedding models
 - [x] LLM fine-tuning (Gemma, Llama, Qwen)
 - [x] ONNX & GGUF export
-- [ ] LoRA/QLoRA fine-tuning
+- [x] LoRA fine-tuning
+- [ ] QLoRA (4-bit quantized LoRA)
 
 ## Contributing
 

data/docs/examples/image-classification-shapes.md

@@ -0,0 +1,83 @@
+# Image Classification: Shape Recognition
+
+This example demonstrates fine-tuning SigLIP2 to classify images by dominant color patterns.
+
+## Setup
+
+```ruby
+require "fine"
+
+Fine.configure { |c| c.progress_bar = false }
+```
+
+## Generate Training Data
+
+Create synthetic training images with different colors representing different "shapes":
+- **Circles**: Red-ish colors (RGB around 220, 80, 80)
+- **Squares**: Green-ish colors (RGB around 80, 180, 80)
+- **Triangles**: Blue-ish colors (RGB around 80, 80, 220)
+
+```ruby
+# Run: ruby examples/generate_shape_images.rb
+# Creates 30 images (10 per class) in examples/data/shapes/
+```
+
+## Train the Classifier
+
+```ruby
+classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-224") do |config|
+  config.epochs = 5
+  config.batch_size = 4
+  config.learning_rate = 1e-4
+  config.freeze_encoder = false  # Fine-tune entire model
+
+  config.on_epoch_end do |epoch, metrics|
+    puts "Epoch #{epoch}: loss=#{metrics[:loss].round(4)}"
+  end
+end
+
+history = classifier.fit(train_dir: "examples/data/shapes", epochs: 5)
+```
+
+## Training Results
+
+```
+Epoch 0: loss=0.8432
+Epoch 1: loss=0.1725
+Epoch 2: loss=0.0321
+Epoch 3: loss=0.0027
+Epoch 4: loss=0.0006
+```
+
+The loss dropped from 0.84 to 0.0006 - a 99.9% improvement!
+
+## Test Predictions
+
+```ruby
+# All predictions are 100% confident and correct
+classifier.predict("data/shapes/circle/circle_1.jpg")
+# => [{ label: "circle", score: 1.0 }]
+
+classifier.predict("data/shapes/square/square_1.jpg")
+# => [{ label: "square", score: 1.0 }]
+
+classifier.predict("data/shapes/triangle/triangle_1.jpg")
+# => [{ label: "triangle", score: 0.999 }]
+```
+
+## Save and Load
+
+```ruby
+# Save
+classifier.save("/tmp/shape-classifier")
+
+# Load later
+loaded = Fine::ImageClassifier.load("/tmp/shape-classifier")
+loaded.predict("new_image.jpg")
+```
+
+## Key Takeaways
+
+- SigLIP2 quickly learns visual patterns even with small datasets (30 images)
+- Fine-tuning the full model (`freeze_encoder: false`) achieves best results
+- The model achieves perfect accuracy after just 5 epochs

data/docs/examples/text-embeddings-faq.md

@@ -0,0 +1,98 @@
+# Text Embeddings: Customer Support FAQ Matching
+
+This example demonstrates fine-tuning a sentence transformer for semantic search in a customer support context.
+
+## Setup
+
+```ruby
+require "fine"
+
+Fine.configure { |c| c.progress_bar = false }
+```
+
+## Training Data Format
+
+Create query-answer pairs in JSONL format:
+
+```jsonl
+{"query": "How do I reset my password?", "positive": "To reset your password, click 'Forgot Password' on the login page."}
+{"query": "I forgot my login credentials", "positive": "To reset your password, click 'Forgot Password' on the login page."}
+{"query": "How long does shipping take?", "positive": "Standard shipping takes 3-5 business days."}
+```
+
+Multiple queries can map to the same answer to teach semantic similarity.
+
+## Train the Embedder
+
+```ruby
+embedder = Fine::TextEmbedder.new("sentence-transformers/all-MiniLM-L6-v2") do |config|
+  config.epochs = 2
+  config.batch_size = 8
+  config.learning_rate = 2e-5
+end
+
+# Test pre-training similarity
+pre_sim = embedder.similarity("How can I get my money back?", "To initiate a return, go to your orders...")
+puts "Pre-training: #{pre_sim.round(4)}"  # => 0.4008
+
+# Fine-tune
+history = embedder.fit(train_file: "data/support_faq_pairs.jsonl")
+
+# Test post-training
+post_sim = embedder.similarity("How can I get my money back?", "To initiate a return, go to your orders...")
+puts "Post-training: #{post_sim.round(4)}"  # => 0.4723
+```
+
+## Training Results
+
+```
+Epoch 0: loss=4.3761
+Epoch 1: loss=5.8889
+
+Post-training similarity: 0.4723
+Improvement: 7.15 percentage points
+```
+
+## Semantic Search
+
+```ruby
+faq_corpus = [
+  "To reset your password, click 'Forgot Password' on the login page.",
+  "Standard shipping takes 3-5 business days.",
+  "To initiate a return, go to your order history and click 'Request Return'.",
+  "We accept Visa, Mastercard, American Express, PayPal, and Apple Pay.",
+  "Yes, we ship to over 50 countries.",
+  "You can reach us via live chat, email, or phone at 1-800-555-0123."
+]
+
+# Search for relevant FAQ
+results = embedder.search("I need to get my money back", faq_corpus, top_k: 2)
+# => [
+#      { text: "To initiate a return...", score: 0.548 },
+#      { text: "You can reach us via...", score: 0.425 }
+#    ]
+
+results = embedder.search("What's the phone number for help?", faq_corpus)
+# => [{ text: "You can reach us via...", score: 0.461 }]
+
+results = embedder.search("Can you deliver to Germany?", faq_corpus)
+# => [{ text: "Yes, we ship to over 50 countries...", score: 0.515 }]
+```
+
+## Save and Load
+
+```ruby
+# Save
+embedder.save("/tmp/support-faq-embedder")
+
+# Load later
+loaded = Fine::TextEmbedder.load("/tmp/support-faq-embedder")
+loaded.search("your query", corpus)
+```
+
+## Key Takeaways
+
+- Even 2 epochs of fine-tuning improves similarity for domain-specific queries
+- Multiple Negatives Ranking Loss learns to distinguish relevant from irrelevant answers
+- The model correctly identifies the best FAQ match for natural language queries
+- Pre-trained models already provide good baseline (0.4 similarity), fine-tuning improves it

data/docs/quickstart.md

@@ -0,0 +1,209 @@
+# Quickstart
+
+Get started with Fine in under 5 minutes.
+
+## Installation
+
+```bash
+# macOS
+brew install pytorch libvips
+gem install fine
+
+# Or add to Gemfile
+gem 'fine'
+```
+
+## Text Classification
+
+Classify text into categories (sentiment, spam, intent).
+
+**1. Prepare your data** (`reviews.jsonl`):
+```json
+{"text": "This product is amazing!", "label": "positive"}
+{"text": "Terrible experience, waste of money", "label": "negative"}
+{"text": "It's okay, nothing special", "label": "neutral"}
+```
+
+**2. Train and use:**
+```ruby
+require 'fine'
+
+classifier = Fine::TextClassifier.new("distilbert-base-uncased")
+classifier.fit(train_file: "reviews.jsonl", epochs: 3)
+
+classifier.predict("Best purchase ever!")
+# => [{ label: "positive", score: 0.95 }]
+
+classifier.save("my_classifier")
+```
+
+---
+
+## Image Classification
+
+Classify images into categories.
+
+**1. Organize your images:**
+```
+data/
+  cats/
+    cat1.jpg
+    cat2.jpg
+  dogs/
+    dog1.jpg
+    dog2.jpg
+```
+
+**2. Train and use:**
+```ruby
+require 'fine'
+
+classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-224")
+classifier.fit(train_dir: "data/", epochs: 3)
+
+classifier.predict("test_image.jpg")
+# => [{ label: "cat", score: 0.92 }]
+
+classifier.save("my_image_classifier")
+```
+
+---
+
+## Text Embeddings
+
+Generate embeddings for semantic search.
+
+**1. Prepare training pairs** (`pairs.jsonl`):
+```json
+{"query": "How do I reset my password?", "positive": "Click 'Forgot Password' on the login page"}
+{"query": "What are your hours?", "positive": "We're open Monday-Friday, 9am-5pm"}
+```
+
+**2. Train and use:**
+```ruby
+require 'fine'
+
+embedder = Fine::TextEmbedder.new("sentence-transformers/all-MiniLM-L6-v2")
+embedder.fit(train_file: "pairs.jsonl", epochs: 3)
+
+# Get embeddings
+embedding = embedder.encode("How do I change my password?")
+
+# Semantic search
+results = embedder.search("password help", corpus, top_k: 5)
+
+embedder.save("my_embedder")
+```
+
+---
+
+## LLM Fine-tuning (with LoRA)
+
+Fine-tune language models using LoRA—only 0.5% of parameters are trainable.
+
+**1. Prepare instruction data** (`instructions.jsonl`):
+```json
+{"instruction": "Summarize this text", "input": "Long article here...", "output": "Brief summary"}
+{"instruction": "Translate to French", "input": "Hello world", "output": "Bonjour le monde"}
+```
+
+**2. Train with LoRA:**
+```ruby
+require 'fine'
+
+# Load model and apply LoRA
+model = Fine::Models::CausalLM.from_pretrained("google/gemma-3-1b-it")
+Fine::LoRA.apply(model, rank: 32, alpha: 64)
+# => "Trainable params: 5.96M (0.46%)"
+
+# Load dataset
+tokenizer = Fine::Tokenizers::AutoTokenizer.from_pretrained("google/gemma-3-1b-it")
+dataset = Fine::Datasets::InstructionDataset.from_jsonl("instructions.jsonl", tokenizer: tokenizer)
+
+# Train
+config = Fine::LLMConfiguration.new
+trainer = Fine::Training::LLMTrainer.new(model, config, train_dataset: dataset)
+trainer.fit
+
+# Merge LoRA weights and save
+Fine::LoRA.merge!(model)
+model.save("my_llm")
+```
+
+---
+
+## Data Formats Reference
+
+### Text Classification
+```json
+{"text": "Your text here", "label": "category_name"}
+```
+
+### Text Pairs (Embeddings)
+```json
+{"query": "Question text", "positive": "Matching answer"}
+```
+Alternative field names: `text_a`/`text_b`, `anchor`/`positive`, `sentence1`/`sentence2`
+
+### Instructions (LLM)
+
+**Alpaca format:**
+```json
+{"instruction": "Task description", "input": "Optional context", "output": "Expected response"}
+```
+
+**ShareGPT format:**
+```json
+{"conversations": [{"from": "human", "value": "Hi"}, {"from": "assistant", "value": "Hello!"}]}
+```
+
+**Simple format:**
+```json
+{"prompt": "Input text", "completion": "Output text"}
+```
+
+---
+
+## Configuration
+
+All classifiers accept a configuration block:
+
+```ruby
+Fine::TextClassifier.new("distilbert-base-uncased") do |config|
+  config.epochs = 5
+  config.batch_size = 16
+  config.learning_rate = 2e-5
+
+  config.on_epoch_end do |epoch, metrics|
+    puts "Epoch #{epoch}: loss=#{metrics[:loss]}"
+  end
+end
+```
+
+Common options:
+- `epochs` - Number of training passes (default: 3)
+- `batch_size` - Samples per batch (default: 8-16)
+- `learning_rate` - Learning rate (default: 2e-5)
+- `max_length` - Max sequence length (default: 128-2048)
+
+---
+
+## Export for Production
+
+```ruby
+# ONNX (for ONNX Runtime, TensorRT)
+classifier.export_onnx("model.onnx")
+
+# GGUF (for llama.cpp, Ollama)
+llm.export_gguf("model.gguf", quantization: :q4_0)
+```
+
+---
+
+## Next Steps
+
+- [Text Classification Tutorial](tutorials/text-classification.md)
+- [Image Classification Tutorial](tutorials/siglip2-image-classification.md)
+- [LLM Fine-tuning Tutorial](tutorials/llm-fine-tuning.md)
+- [LoRA Tool Calling](tutorials/lora-tool-calling.md)
+- [Model Export](tutorials/model-export.md)