fine 0.1.0

data/docs/tutorials/llm-fine-tuning.md

@@ -0,0 +1,246 @@
+# Fine-tuning LLMs with Fine
+
+Fine supports fine-tuning open-source LLMs like Llama, Gemma, Mistral, and Qwen for custom tasks.
+
+## Quick Start
+
+```ruby
+require "fine"
+
+# Load a base model
+llm = Fine::LLM.new("meta-llama/Llama-3.2-1B")
+
+# Fine-tune on your data
+llm.fit(train_file: "instructions.jsonl", epochs: 3)
+
+# Generate text
+response = llm.generate("Explain Ruby blocks in simple terms")
+puts response
+
+# Save for later
+llm.save("my_llama")
+```
+
+## Preparing Your Data
+
+Fine supports multiple data formats.
+
+### Alpaca Format (Recommended)
+
+```jsonl
+{"instruction": "Explain what a Ruby block is", "input": "", "output": "A Ruby block is a chunk of code..."}
+{"instruction": "Convert this to Ruby", "input": "print('hello')", "output": "puts 'hello'"}
+{"instruction": "What does this code do?", "input": "arr.map(&:upcase)", "output": "It converts each string in the array to uppercase."}
+```
+
+### ShareGPT Format
+
+```jsonl
+{"conversations": [{"from": "human", "value": "What is Ruby?"}, {"from": "gpt", "value": "Ruby is a dynamic programming language..."}]}
+{"conversations": [{"from": "human", "value": "Show me a loop"}, {"from": "gpt", "value": "Here's a Ruby loop:\n\n```ruby\n5.times { |i| puts i }\n```"}]}
+```
+
+### Simple Format
+
+```jsonl
+{"prompt": "### Question: What is 2+2?\n### Answer:", "completion": " 4"}
+{"prompt": "Translate to French: Hello", "completion": " Bonjour"}
+```
+
+## Configuration Options
+
+```ruby
+llm = Fine::LLM.new("google/gemma-2b") do |config|
+  # Training parameters
+  config.epochs = 3
+  config.batch_size = 4
+  config.learning_rate = 2e-5
+
+  # Sequence length
+  config.max_length = 2048
+
+  # Gradient accumulation (effective batch = batch_size * gradient_accumulation_steps)
+  config.gradient_accumulation_steps = 4
+
+  # Gradient clipping
+  config.max_grad_norm = 1.0
+
+  # Learning rate warmup
+  config.warmup_steps = 100
+
+  # Freeze bottom N layers (for faster training)
+  config.freeze_layers = 8
+end
+```
+
+## Supported Models
+
+| Model Family | Example Model ID | Notes |
+|-------------|------------------|-------|
+| Llama 3.2 | `meta-llama/Llama-3.2-1B` | Great balance of size/quality |
+| Gemma | `google/gemma-2b` | Good for instruction following |
+| Mistral | `mistralai/Mistral-7B-v0.1` | Strong general performance |
+| Qwen | `Qwen/Qwen2-1.5B` | Multilingual support |
+
+## Training Strategies
+
+### Full Fine-tuning
+
+Train all parameters (requires more memory):
+
+```ruby
+llm = Fine::LLM.new("meta-llama/Llama-3.2-1B") do |config|
+  config.freeze_layers = 0  # Train everything
+  config.batch_size = 2     # Smaller batch for memory
+  config.gradient_accumulation_steps = 8
+end
+```
+
+### Partial Fine-tuning
+
+Freeze early layers to reduce memory and training time:
+
+```ruby
+llm = Fine::LLM.new("meta-llama/Llama-3.2-1B") do |config|
+  config.freeze_layers = 16  # Freeze bottom 16 layers
+  config.batch_size = 4
+end
+```
+
+## Generation Options
+
+```ruby
+# Load trained model
+llm = Fine::LLM.load("my_llama")
+
+# Greedy decoding (deterministic)
+response = llm.generate(
+  "What is Ruby?",
+  do_sample: false
+)
+
+# Creative generation
+response = llm.generate(
+  "Write a poem about coding",
+  temperature: 0.9,
+  top_p: 0.95,
+  max_new_tokens: 200
+)
+
+# Focused generation
+response = llm.generate(
+  "Explain recursion",
+  temperature: 0.3,
+  top_k: 10,
+  max_new_tokens: 150
+)
+```
+
+## Chat Interface
+
+For conversational use:
+
+```ruby
+messages = [
+  { role: "system", content: "You are a helpful Ruby programming assistant." },
+  { role: "user", content: "How do I read a file in Ruby?" }
+]
+
+response = llm.chat(messages, max_new_tokens: 200)
+puts response
+```
+
+## Memory Optimization
+
+LLMs require significant memory. Here are strategies to reduce usage:
+
+### 1. Use Gradient Accumulation
+
+```ruby
+config.batch_size = 1
+config.gradient_accumulation_steps = 16
+# Effective batch size = 16, but only 1 sample in memory at a time
+```
+
+### 2. Freeze Layers
+
+```ruby
+config.freeze_layers = 20  # Only train top layers
+```
+
+### 3. Reduce Sequence Length
+
+```ruby
+config.max_length = 512  # Instead of default 2048
+```
+
+### 4. Use Smaller Models
+
+Start with 1B-3B parameter models:
+- `meta-llama/Llama-3.2-1B`
+- `google/gemma-2b`
+- `Qwen/Qwen2-1.5B`
+
+## Example: Code Assistant
+
+```ruby
+require "fine"
+
+# Prepare data (code_instructions.jsonl)
+# {"instruction": "Write a function to reverse a string", "input": "", "output": "def reverse(s)\n  s.reverse\nend"}
+
+llm = Fine::LLM.new("meta-llama/Llama-3.2-1B") do |config|
+  config.epochs = 3
+  config.batch_size = 2
+  config.max_length = 1024
+  config.freeze_layers = 8
+end
+
+llm.fit(train_file: "code_instructions.jsonl")
+llm.save("ruby_code_assistant")
+
+# Use it
+assistant = Fine::LLM.load("ruby_code_assistant")
+code = assistant.generate(
+  "### Instruction:\nWrite a function to find the maximum element in an array\n\n### Response:\n",
+  temperature: 0.2,
+  max_new_tokens: 200
+)
+puts code
+```
+
+## Example: Domain Expert
+
+```ruby
+# Fine-tune on domain-specific Q&A
+llm = Fine::LLM.new("google/gemma-2b") do |config|
+  config.epochs = 5
+  config.learning_rate = 1e-5
+end
+
+llm.fit(train_file: "medical_qa.jsonl", format: :alpaca)
+llm.save("medical_assistant")
+```
+
+## Evaluation
+
+Track training with validation data:
+
+```ruby
+llm.fit(
+  train_file: "train.jsonl",
+  val_file: "val.jsonl",
+  epochs: 3
+)
+# Logs val_loss and val_perplexity each epoch
+```
+
+Lower perplexity indicates better language modeling.
+
+## Tips
+
+1. **Start small**: Begin with 1B models and small datasets
+2. **Quality over quantity**: 1000 high-quality examples often beats 10000 noisy ones
+3. **Format consistency**: Keep your instruction format consistent
+4. **Learning rate**: Use lower rates (1e-5 to 5e-5) for fine-tuning
+5. **Early stopping**: Monitor validation loss to avoid overfitting

data/docs/tutorials/model-export.md

@@ -0,0 +1,200 @@
+# Exporting Models for Deployment
+
+Fine supports exporting fine-tuned models to ONNX and GGUF formats for production deployment.
+
+## ONNX Export
+
+ONNX (Open Neural Network Exchange) is a cross-platform format supported by many inference runtimes including ONNX Runtime, TensorRT, and OpenVINO.
+
+### Export Text Classifier
+
+```ruby
+classifier = Fine::TextClassifier.load("my_classifier")
+classifier.export_onnx("classifier.onnx")
+
+# With options
+classifier.export_onnx(
+  "classifier.onnx",
+  opset_version: 14,
+  dynamic_axes: true  # Allow variable batch size and sequence length
+)
+```
+
+### Export Text Embedder
+
+```ruby
+embedder = Fine::TextEmbedder.load("my_embedder")
+embedder.export_onnx("embedder.onnx")
+```
+
+### Export Image Classifier
+
+```ruby
+classifier = Fine::ImageClassifier.load("my_classifier")
+classifier.export_onnx("classifier.onnx")
+```
+
+### Export LLM
+
+```ruby
+llm = Fine::LLM.load("my_llm")
+llm.export_onnx("llm.onnx")
+```
+
+### Using the Export Module Directly
+
+```ruby
+Fine::Export.to_onnx(model, "model.onnx", opset_version: 14)
+```
+
+### ONNX Inference Example (Python)
+
+```python
+import onnxruntime as ort
+import numpy as np
+
+session = ort.InferenceSession("classifier.onnx")
+
+# Text classification
+input_ids = np.array([[101, 2054, 2003, 2023, 102]], dtype=np.int64)
+attention_mask = np.array([[1, 1, 1, 1, 1]], dtype=np.int64)
+
+outputs = session.run(None, {
+    "input_ids": input_ids,
+    "attention_mask": attention_mask
+})
+logits = outputs[0]
+```
+
+## GGUF Export (LLMs Only)
+
+GGUF is the format used by llama.cpp, ollama, and other efficient inference engines. It supports various quantization levels to reduce model size and memory usage.
+
+### Basic Export
+
+```ruby
+llm = Fine::LLM.load("my_llm")
+llm.export_gguf("model.gguf")
+```
+
+### Quantization Options
+
+```ruby
+# F16 - Good balance of quality and size (default)
+llm.export_gguf("model-f16.gguf", quantization: :f16)
+
+# Q8 - Smaller, minimal quality loss
+llm.export_gguf("model-q8.gguf", quantization: :q8_0)
+
+# Q4 - Smallest, some quality loss
+llm.export_gguf("model-q4.gguf", quantization: :q4_0)
+```
+
+### Available Quantization Types
+
+| Type | Description | Size Reduction | Quality |
+|------|-------------|----------------|---------|
+| `:f32` | 32-bit float | None | Lossless |
+| `:f16` | 16-bit float | ~50% | Minimal loss |
+| `:q8_0` | 8-bit quantization | ~75% | Very small loss |
+| `:q4_0` | 4-bit quantization | ~87% | Noticeable loss |
+| `:q4_k` | 4-bit K-quant | ~87% | Better than q4_0 |
+| `:q5_k` | 5-bit K-quant | ~84% | Good balance |
+| `:q6_k` | 6-bit K-quant | ~81% | High quality |
+
+### Adding Metadata
+
+```ruby
+llm.export_gguf(
+  "model.gguf",
+  quantization: :q4_k,
+  metadata: {
+    "description" => "Fine-tuned on customer support data",
+    "version" => "1.0.0",
+    "author" => "Your Name"
+  }
+)
+```
+
+### Using with llama.cpp
+
+```bash
+# Run inference
+./main -m model.gguf -p "What is Ruby?" -n 100
+
+# Start a server
+./server -m model.gguf --host 0.0.0.0 --port 8080
+```
+
+### Using with Ollama
+
+```bash
+# Create a Modelfile
+echo 'FROM ./model.gguf' > Modelfile
+echo 'PARAMETER temperature 0.7' >> Modelfile
+echo 'SYSTEM "You are a helpful assistant."' >> Modelfile
+
+# Create the model
+ollama create my-model -f Modelfile
+
+# Run it
+ollama run my-model "What is Ruby?"
+```
+
+## Best Practices
+
+### Choosing the Right Format
+
+| Use Case | Recommended Format |
+|----------|-------------------|
+| Web deployment | ONNX |
+| Mobile apps | ONNX (with quantization) |
+| Server inference | ONNX or GGUF |
+| Edge devices | GGUF (quantized) |
+| llama.cpp / ollama | GGUF |
+
+### Choosing Quantization
+
+| Priority | Recommended |
+|----------|------------|
+| Quality first | `:f16` or `:q8_0` |
+| Balance | `:q5_k` or `:q6_k` |
+| Size first | `:q4_0` or `:q4_k` |
+
+### Testing Exported Models
+
+Always test your exported models to ensure quality:
+
+```ruby
+# Before export - test with Fine
+response = llm.generate("Test prompt")
+
+# After export - test with target runtime
+# Compare outputs to ensure quality is acceptable
+```
+
+## Troubleshooting
+
+### ONNX Export Fails
+
+1. Ensure the model is loaded and trained
+2. Check that torch.rb ONNX support is available
+3. Try a different opset_version (11, 13, or 14)
+
+### GGUF Export Issues
+
+1. Only LLMs support GGUF export
+2. Large models may need more memory during export
+3. Some model architectures may need custom tensor mappings
+
+### Large File Sizes
+
+Use quantization to reduce file size:
+
+```ruby
+# ONNX with INT8 quantization
+classifier.export_onnx("model.onnx", quantize: :int8)
+
+# GGUF with Q4 quantization
+llm.export_gguf("model.gguf", quantization: :q4_0)
+```

data/docs/tutorials/siglip2-image-classification.md

@@ -0,0 +1,130 @@
+# Fine-tuning SigLIP2 for Image Classification
+
+Classify images into predefined categories (e.g., cats vs dogs, product types, document categories).
+
+## When to Use This
+
+- You have images that belong to distinct categories
+- You want to automatically sort or label images
+- Examples: photo organization, content moderation, product categorization
+
+## Dataset Structure
+
+Organize images in folders named after each class:
+
+```
+data/
+  train/
+    cats/
+      cat001.jpg
+      cat002.jpg
+      ...
+    dogs/
+      dog001.jpg
+      dog002.jpg
+      ...
+  val/
+    cats/
+      cat101.jpg
+    dogs/
+      dog101.jpg
+```
+
+**Tips:**
+- Aim for at least 20-50 images per class for decent results
+- More images = better accuracy
+- Balance classes roughly equally
+- Use clear, representative images
+
+## Basic Training
+
+```ruby
+require "fine"
+
+classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-224")
+
+classifier.fit(
+  train_dir: "data/train",
+  val_dir: "data/val",
+  epochs: 3
+)
+
+classifier.save("models/my_classifier")
+```
+
+## Training with Configuration
+
+```ruby
+classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-224") do |config|
+  # Training settings
+  config.epochs = 5
+  config.batch_size = 16          # Lower if running out of memory
+  config.learning_rate = 2e-4     # Default works well for most cases
+
+  # Freeze encoder for faster training (less accurate)
+  config.freeze_encoder = false   # Set true for feature extraction only
+
+  # Track progress
+  config.on_epoch_end do |epoch, metrics|
+    puts "Epoch #{epoch + 1}: accuracy=#{(metrics[:accuracy] * 100).round(1)}%"
+  end
+end
+
+classifier.fit(train_dir: "data/train", val_dir: "data/val")
+```
+
+## Making Predictions
+
+```ruby
+# Load trained model
+classifier = Fine::ImageClassifier.load("models/my_classifier")
+
+# Single image
+results = classifier.predict("photo.jpg")
+puts results.first[:label]  # => "cats"
+puts results.first[:score]  # => 0.95
+
+# Multiple images
+results = classifier.predict(["photo1.jpg", "photo2.jpg", "photo3.jpg"])
+results.each_with_index do |preds, i|
+  puts "Image #{i + 1}: #{preds.first[:label]}"
+end
+```
+
+## Using Without Validation Set
+
+If you don't have a separate validation set:
+
+```ruby
+classifier.fit_with_split(
+  data_dir: "data/all_images",
+  val_split: 0.2,   # Use 20% for validation
+  epochs: 3
+)
+```
+
+## Model Selection
+
+| Model | Size | Speed | Accuracy | Use Case |
+|-------|------|-------|----------|----------|
+| `siglip2-base-patch16-224` | 86M | Fast | Good | Quick experiments, limited GPU |
+| `siglip2-base-patch16-384` | 86M | Medium | Better | Production with good GPU |
+| `siglip2-large-patch16-256` | 303M | Slower | Best | Maximum accuracy |
+
+## Troubleshooting
+
+**Out of memory:**
+- Reduce `batch_size` (try 8 or 4)
+- Use a smaller model variant
+- Use `freeze_encoder = true`
+
+**Low accuracy:**
+- Add more training images
+- Train for more epochs
+- Check for mislabeled images
+- Ensure classes are visually distinct
+
+**Overfitting (train accuracy high, val accuracy low):**
+- Add more training data
+- Reduce epochs
+- Use `freeze_encoder = true`