fine 0.1.0

data/docs/tutorials/text-embeddings.md

@@ -0,0 +1,211 @@
+# Fine-tuning Text Embedding Models
+
+Train text embeddings for semantic search, clustering, and similarity matching.
+
+## When to Use This
+
+- Build semantic search for your domain (legal docs, medical records, code)
+- Improve retrieval for RAG applications
+- Cluster similar documents
+- Match queries to FAQ answers
+- Detect duplicate content
+
+## Supported Models
+
+| Model | Size | Use Case |
+|-------|------|----------|
+| `sentence-transformers/all-MiniLM-L6-v2` | 22M | Fast, general purpose |
+| `sentence-transformers/all-mpnet-base-v2` | 110M | Better quality |
+| `BAAI/bge-small-en-v1.5` | 33M | Retrieval optimized |
+| `BAAI/bge-base-en-v1.5` | 110M | Best retrieval quality |
+
+## Dataset Format
+
+Prepare your data as pairs or triplets:
+
+### Pairs (query, positive)
+
+```
+data/pairs.jsonl
+{"query": "How do I reset my password?", "positive": "To reset your password, click 'Forgot Password' on the login page."}
+{"query": "What's your return policy?", "positive": "We accept returns within 30 days of purchase."}
+```
+
+### Triplets (query, positive, negative)
+
+```
+data/triplets.jsonl
+{"query": "python list append", "positive": "list.append(x) adds item x to the end", "negative": "list.pop() removes the last item"}
+```
+
+## Basic Training
+
+```ruby
+require "fine"
+
+embedder = Fine::TextEmbedder.new("sentence-transformers/all-MiniLM-L6-v2")
+
+embedder.fit(
+  train_file: "data/pairs.jsonl",
+  epochs: 3
+)
+
+embedder.save("models/my_embedder")
+```
+
+## Training for Semantic Search
+
+Optimize for retrieval with contrastive loss:
+
+```ruby
+embedder = Fine::TextEmbedder.new("BAAI/bge-base-en-v1.5") do |config|
+  config.epochs = 5
+  config.batch_size = 32
+  config.learning_rate = 2e-5
+  config.loss = :multiple_negatives_ranking  # Best for retrieval
+
+  config.on_epoch_end do |epoch, metrics|
+    puts "Epoch #{epoch}: loss=#{metrics[:loss]}"
+  end
+end
+
+embedder.fit(train_file: "data/queries_documents.jsonl")
+embedder.save("models/search_embedder")
+```
+
+## Generating Embeddings
+
+```ruby
+embedder = Fine::TextEmbedder.load("models/my_embedder")
+
+# Single text
+embedding = embedder.encode("How do I cancel my subscription?")
+# => Array of 384 floats (for MiniLM)
+
+# Batch encoding
+embeddings = embedder.encode([
+  "First document",
+  "Second document",
+  "Third document"
+])
+# => Array of 3 embeddings
+```
+
+## Building a Search Index
+
+```ruby
+class SemanticSearch
+  def initialize(embedder)
+    @embedder = embedder
+    @documents = []
+    @embeddings = []
+  end
+
+  def add(text, metadata = {})
+    @documents << { text: text, metadata: metadata }
+    @embeddings << @embedder.encode(text)
+  end
+
+  def search(query, top_k: 5)
+    query_emb = @embedder.encode(query)
+
+    scores = @embeddings.map { |emb| cosine_similarity(query_emb, emb) }
+
+    scores
+      .each_with_index
+      .sort_by { |score, _| -score }
+      .first(top_k)
+      .map { |score, idx| { document: @documents[idx], score: score } }
+  end
+
+  private
+
+  def cosine_similarity(a, b)
+    dot = a.zip(b).sum { |x, y| x * y }
+    norm_a = Math.sqrt(a.sum { |x| x * x })
+    norm_b = Math.sqrt(b.sum { |x| x * x })
+    dot / (norm_a * norm_b)
+  end
+end
+
+# Usage
+search = SemanticSearch.new(embedder)
+
+# Index your documents
+documents.each { |doc| search.add(doc[:text], id: doc[:id]) }
+
+# Search
+results = search.search("how to get a refund")
+results.each do |r|
+  puts "#{r[:score].round(3)}: #{r[:document][:text][0..50]}..."
+end
+```
+
+## Domain Adaptation
+
+Fine-tune on your specific domain for better results:
+
+```ruby
+# Prepare domain-specific pairs
+# Example: customer support queries matched to answers
+pairs = [
+  { query: "broken screen", positive: "Screen repair costs $99 and takes 2-3 days" },
+  { query: "cracked display", positive: "Screen repair costs $99 and takes 2-3 days" },
+  # ... more domain-specific examples
+]
+
+# Save as JSONL
+File.write("data/support_pairs.jsonl", pairs.map(&:to_json).join("\n"))
+
+# Fine-tune
+embedder = Fine::TextEmbedder.new("sentence-transformers/all-mpnet-base-v2")
+embedder.fit(train_file: "data/support_pairs.jsonl", epochs: 3)
+embedder.save("models/support_search")
+```
+
+## Hard Negatives Mining
+
+For better quality, use hard negatives (similar but wrong answers):
+
+```ruby
+embedder = Fine::TextEmbedder.new("BAAI/bge-base-en-v1.5") do |config|
+  config.loss = :triplet
+  config.margin = 0.5  # Minimum distance between positive and negative
+end
+
+# Triplet format
+embedder.fit(train_file: "data/triplets.jsonl")
+```
+
+## Evaluation
+
+Test retrieval quality:
+
+```ruby
+def evaluate_retrieval(embedder, test_queries, ground_truth)
+  hits_at_1 = 0
+  hits_at_5 = 0
+
+  test_queries.each do |query, expected_doc_id|
+    results = search.search(query, top_k: 5)
+
+    result_ids = results.map { |r| r[:document][:metadata][:id] }
+
+    hits_at_1 += 1 if result_ids[0] == expected_doc_id
+    hits_at_5 += 1 if result_ids.include?(expected_doc_id)
+  end
+
+  {
+    recall_at_1: hits_at_1.to_f / test_queries.size,
+    recall_at_5: hits_at_5.to_f / test_queries.size
+  }
+end
+```
+
+## Best Practices
+
+1. **Start with a good base model** - BGE models work best for retrieval
+2. **Use domain-specific data** - Even 1000 pairs helps significantly
+3. **Include hard negatives** - Similar but incorrect matches improve precision
+4. **Evaluate on held-out queries** - Don't overfit to training data
+5. **Consider asymmetric models** - Some models use different encodings for queries vs documents

data/examples/basic_classification.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Basic image classification example
+#
+# This example shows how to fine-tune a SigLIP2 model for image classification.
+#
+# Dataset structure expected:
+#   data/
+#     train/
+#       cat/
+#         cat1.jpg
+#         cat2.jpg
+#       dog/
+#         dog1.jpg
+#         dog2.jpg
+#     val/
+#       cat/
+#         cat3.jpg
+#       dog/
+#         dog3.jpg
+
+require "fine"
+
+# Configure Fine (optional)
+Fine.configure do |config|
+  config.cache_dir = File.expand_path("~/.cache/fine")
+  config.progress_bar = true
+end
+
+# Create a classifier
+classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-224") do |config|
+  # Training settings
+  config.epochs = 3
+  config.batch_size = 8
+  config.learning_rate = 2e-4
+
+  # Model settings
+  config.freeze_encoder = false  # Full fine-tuning
+  config.dropout = 0.1
+
+  # Callbacks
+  config.on_epoch_end do |epoch, metrics|
+    puts "Epoch #{epoch + 1}:"
+    puts "  Train Loss: #{metrics[:loss].round(4)}"
+    puts "  Train Acc:  #{(metrics[:accuracy] * 100).round(2)}%"
+    if metrics[:val_loss]
+      puts "  Val Loss:   #{metrics[:val_loss].round(4)}"
+      puts "  Val Acc:    #{(metrics[:val_accuracy] * 100).round(2)}%"
+    end
+  end
+end
+
+# Train the model
+puts "Starting training..."
+history = classifier.fit(
+  train_dir: "data/train",
+  val_dir: "data/val"
+)
+
+# Save the model
+classifier.save("models/my_classifier")
+puts "Model saved to models/my_classifier"
+
+# Make predictions
+puts "\nMaking predictions..."
+predictions = classifier.predict("data/test/image.jpg")
+predictions.each do |pred|
+  puts "  #{pred[:label]}: #{(pred[:score] * 100).round(2)}%"
+end

data/examples/data/tool_calls.jsonl

@@ -0,0 +1,30 @@
+{"instruction": "What's the weather in Tokyo?", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"description\": \"Get current weather for a location\", \"parameters\": {\"type\": \"object\", \"properties\": {\"location\": {\"type\": \"string\", \"description\": \"City name\"}}, \"required\": [\"location\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"get_weather\", \"arguments\": {\"location\": \"Tokyo\"}}]"}
+{"instruction": "Calculate 25 * 4 + 10", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"calculate\", \"description\": \"Evaluate a math expression\", \"parameters\": {\"type\": \"object\", \"properties\": {\"expression\": {\"type\": \"string\", \"description\": \"Math expression\"}}, \"required\": [\"expression\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"calculate\", \"arguments\": {\"expression\": \"25 * 4 + 10\"}}]"}
+{"instruction": "Search for the latest news about AI", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"search_web\", \"description\": \"Search the web\", \"parameters\": {\"type\": \"object\", \"properties\": {\"query\": {\"type\": \"string\", \"description\": \"Search query\"}}, \"required\": [\"query\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"search_web\", \"arguments\": {\"query\": \"latest news about AI\"}}]"}
+{"instruction": "What's the temperature in New York City?", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"description\": \"Get current weather\", \"parameters\": {\"type\": \"object\", \"properties\": {\"location\": {\"type\": \"string\"}}, \"required\": [\"location\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"get_weather\", \"arguments\": {\"location\": \"New York City\"}}]"}
+{"instruction": "How much is 15% of 200?", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"calculate\", \"description\": \"Evaluate math\", \"parameters\": {\"type\": \"object\", \"properties\": {\"expression\": {\"type\": \"string\"}}, \"required\": [\"expression\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"calculate\", \"arguments\": {\"expression\": \"0.15 * 200\"}}]"}
+{"instruction": "Find information about Ruby programming", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"search_web\", \"description\": \"Search the web\", \"parameters\": {\"type\": \"object\", \"properties\": {\"query\": {\"type\": \"string\"}}, \"required\": [\"query\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"search_web\", \"arguments\": {\"query\": \"Ruby programming language\"}}]"}
+{"instruction": "Check weather in London", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"description\": \"Get weather\", \"parameters\": {\"type\": \"object\", \"properties\": {\"location\": {\"type\": \"string\"}}, \"required\": [\"location\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"get_weather\", \"arguments\": {\"location\": \"London\"}}]"}
+{"instruction": "What is sqrt(144)?", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"calculate\", \"description\": \"Evaluate math\", \"parameters\": {\"type\": \"object\", \"properties\": {\"expression\": {\"type\": \"string\"}}, \"required\": [\"expression\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"calculate\", \"arguments\": {\"expression\": \"sqrt(144)\"}}]"}
+{"instruction": "Look up population of Japan", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"search_web\", \"description\": \"Search web\", \"parameters\": {\"type\": \"object\", \"properties\": {\"query\": {\"type\": \"string\"}}, \"required\": [\"query\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"search_web\", \"arguments\": {\"query\": \"population of Japan\"}}]"}
+{"instruction": "Is it raining in Seattle?", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"description\": \"Get weather\", \"parameters\": {\"type\": \"object\", \"properties\": {\"location\": {\"type\": \"string\"}}, \"required\": [\"location\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"get_weather\", \"arguments\": {\"location\": \"Seattle\"}}]"}
+{"instruction": "Divide 1000 by 8", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"calculate\", \"description\": \"Math\", \"parameters\": {\"type\": \"object\", \"properties\": {\"expression\": {\"type\": \"string\"}}, \"required\": [\"expression\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"calculate\", \"arguments\": {\"expression\": \"1000 / 8\"}}]"}
+{"instruction": "Search machine learning tutorials", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"search_web\", \"description\": \"Search\", \"parameters\": {\"type\": \"object\", \"properties\": {\"query\": {\"type\": \"string\"}}, \"required\": [\"query\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"search_web\", \"arguments\": {\"query\": \"machine learning tutorials\"}}]"}
+{"instruction": "Weather in Paris today", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"description\": \"Weather\", \"parameters\": {\"type\": \"object\", \"properties\": {\"location\": {\"type\": \"string\"}}, \"required\": [\"location\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"get_weather\", \"arguments\": {\"location\": \"Paris\"}}]"}
+{"instruction": "2 to the power of 10", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"calculate\", \"description\": \"Math\", \"parameters\": {\"type\": \"object\", \"properties\": {\"expression\": {\"type\": \"string\"}}, \"required\": [\"expression\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"calculate\", \"arguments\": {\"expression\": \"2 ** 10\"}}]"}
+{"instruction": "Send email to john@example.com about the meeting tomorrow", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"send_email\", \"description\": \"Send an email\", \"parameters\": {\"type\": \"object\", \"properties\": {\"to\": {\"type\": \"string\"}, \"subject\": {\"type\": \"string\"}, \"body\": {\"type\": \"string\"}}, \"required\": [\"to\", \"subject\", \"body\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"send_email\", \"arguments\": {\"to\": \"john@example.com\", \"subject\": \"Meeting Tomorrow\", \"body\": \"Hi, I wanted to discuss the meeting scheduled for tomorrow.\"}}]"}
+{"instruction": "Create event for Friday at 3pm called Team Standup", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"create_event\", \"description\": \"Create calendar event\", \"parameters\": {\"type\": \"object\", \"properties\": {\"title\": {\"type\": \"string\"}, \"date\": {\"type\": \"string\"}, \"time\": {\"type\": \"string\"}}, \"required\": [\"title\", \"date\", \"time\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"create_event\", \"arguments\": {\"title\": \"Team Standup\", \"date\": \"Friday\", \"time\": \"3pm\"}}]"}
+{"instruction": "Set reminder to buy milk", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"set_reminder\", \"description\": \"Set a reminder\", \"parameters\": {\"type\": \"object\", \"properties\": {\"message\": {\"type\": \"string\"}}, \"required\": [\"message\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"set_reminder\", \"arguments\": {\"message\": \"buy milk\"}}]"}
+{"instruction": "Translate hello to Spanish", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"translate\", \"description\": \"Translate text\", \"parameters\": {\"type\": \"object\", \"properties\": {\"text\": {\"type\": \"string\"}, \"target_language\": {\"type\": \"string\"}}, \"required\": [\"text\", \"target_language\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"translate\", \"arguments\": {\"text\": \"hello\", \"target_language\": \"Spanish\"}}]"}
+{"instruction": "Play jazz music", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"play_music\", \"description\": \"Play music\", \"parameters\": {\"type\": \"object\", \"properties\": {\"genre\": {\"type\": \"string\"}}, \"required\": [\"genre\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"play_music\", \"arguments\": {\"genre\": \"jazz\"}}]"}
+{"instruction": "Turn off living room lights", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"control_lights\", \"description\": \"Control smart lights\", \"parameters\": {\"type\": \"object\", \"properties\": {\"room\": {\"type\": \"string\"}, \"action\": {\"type\": \"string\", \"enum\": [\"on\", \"off\"]}}, \"required\": [\"room\", \"action\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"control_lights\", \"arguments\": {\"room\": \"living room\", \"action\": \"off\"}}]"}
+{"instruction": "What time is it in Sydney?", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"get_time\", \"description\": \"Get time in timezone\", \"parameters\": {\"type\": \"object\", \"properties\": {\"timezone\": {\"type\": \"string\"}}, \"required\": [\"timezone\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"get_time\", \"arguments\": {\"timezone\": \"Australia/Sydney\"}}]"}
+{"instruction": "Book flight to Miami next Friday", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"book_flight\", \"description\": \"Book a flight\", \"parameters\": {\"type\": \"object\", \"properties\": {\"destination\": {\"type\": \"string\"}, \"date\": {\"type\": \"string\"}}, \"required\": [\"destination\", \"date\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"book_flight\", \"arguments\": {\"destination\": \"Miami\", \"date\": \"next Friday\"}}]"}
+{"instruction": "Order large pepperoni pizza", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"order_food\", \"description\": \"Order food\", \"parameters\": {\"type\": \"object\", \"properties\": {\"item\": {\"type\": \"string\"}, \"size\": {\"type\": \"string\"}, \"toppings\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}}, \"required\": [\"item\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"order_food\", \"arguments\": {\"item\": \"pizza\", \"size\": \"large\", \"toppings\": [\"pepperoni\"]}}]"}
+{"instruction": "Check my bank balance", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"get_balance\", \"description\": \"Get account balance\", \"parameters\": {\"type\": \"object\", \"properties\": {\"account_type\": {\"type\": \"string\", \"enum\": [\"checking\", \"savings\"]}}, \"required\": [\"account_type\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"get_balance\", \"arguments\": {\"account_type\": \"checking\"}}]"}
+{"instruction": "Get weather in Berlin and calculate 100/4", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"description\": \"Get weather\", \"parameters\": {\"type\": \"object\", \"properties\": {\"location\": {\"type\": \"string\"}}, \"required\": [\"location\"]}}}, {\"type\": \"function\", \"function\": {\"name\": \"calculate\", \"description\": \"Math\", \"parameters\": {\"type\": \"object\", \"properties\": {\"expression\": {\"type\": \"string\"}}, \"required\": [\"expression\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"get_weather\", \"arguments\": {\"location\": \"Berlin\"}}, {\"name\": \"calculate\", \"arguments\": {\"expression\": \"100/4\"}}]"}
+{"instruction": "Search for restaurants and get weather in Chicago", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"search_web\", \"description\": \"Search\", \"parameters\": {\"type\": \"object\", \"properties\": {\"query\": {\"type\": \"string\"}}, \"required\": [\"query\"]}}}, {\"type\": \"function\", \"function\": {\"name\": \"get_weather\", \"description\": \"Weather\", \"parameters\": {\"type\": \"object\", \"properties\": {\"location\": {\"type\": \"string\"}}, \"required\": [\"location\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"search_web\", \"arguments\": {\"query\": \"restaurants\"}}, {\"name\": \"get_weather\", \"arguments\": {\"location\": \"Chicago\"}}]"}
+{"instruction": "Read file config.json", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"read_file\", \"description\": \"Read a file\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"read_file\", \"arguments\": {\"path\": \"config.json\"}}]"}
+{"instruction": "Write 'hello world' to output.txt", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"write_file\", \"description\": \"Write to file\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}, \"content\": {\"type\": \"string\"}}, \"required\": [\"path\", \"content\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"write_file\", \"arguments\": {\"path\": \"output.txt\", \"content\": \"hello world\"}}]"}
+{"instruction": "Run the tests", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"run_command\", \"description\": \"Run shell command\", \"parameters\": {\"type\": \"object\", \"properties\": {\"command\": {\"type\": \"string\"}}, \"required\": [\"command\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"run_command\", \"arguments\": {\"command\": \"npm test\"}}]"}
+{"instruction": "List files in current directory", "input": "[AVAILABLE_TOOLS] [{\"type\": \"function\", \"function\": {\"name\": \"list_files\", \"description\": \"List files in directory\", \"parameters\": {\"type\": \"object\", \"properties\": {\"path\": {\"type\": \"string\"}}, \"required\": [\"path\"]}}}] [/AVAILABLE_TOOLS]", "output": "[TOOL_CALLS] [{\"name\": \"list_files\", \"arguments\": {\"path\": \".\"}}]"}

data/examples/demo_training.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demo: Fine-tune SigLIP2 for image classification
+# This shows the full workflow with actual weight updates
+
+require "bundler/setup"
+require "fine"
+
+puts "=" * 60
+puts "FINE-TUNING DEMO"
+puts "=" * 60
+
+Fine.configure do |config|
+  config.progress_bar = false
+end
+
+fixtures_path = File.expand_path("../spec/fixtures/images", __dir__)
+
+puts "\n[1] Create and configure classifier"
+classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-224") do |config|
+  config.epochs = 5
+  config.batch_size = 2
+  config.learning_rate = 1e-3  # Higher LR for faster learning on tiny dataset
+  config.freeze_encoder = true  # Train only classification head
+
+  config.on_epoch_end do |epoch, metrics|
+    puts "    Epoch #{epoch + 1}: loss=#{metrics[:loss].round(4)}, acc=#{(metrics[:accuracy] * 100).round(1)}%"
+  end
+end
+
+puts "\n[2] Train on #{fixtures_path}"
+puts "    (4 images: 2 cats, 2 dogs)"
+puts ""
+
+history = classifier.fit(train_dir: fixtures_path)
+
+puts "\n[3] Training metrics"
+initial_loss = history.first[:loss]
+final_loss = history.last[:loss]
+initial_acc = history.first[:accuracy]
+final_acc = history.last[:accuracy]
+
+puts "    Initial: loss=#{initial_loss.round(4)}, accuracy=#{(initial_acc * 100).round(1)}%"
+puts "    Final:   loss=#{final_loss.round(4)}, accuracy=#{(final_acc * 100).round(1)}%"
+
+if final_loss < initial_loss
+  puts "    ✓ Loss decreased by #{((1 - final_loss/initial_loss) * 100).round(1)}%"
+else
+  puts "    ⚠ Loss did not decrease"
+end
+
+if final_acc > initial_acc
+  puts "    ✓ Accuracy improved from #{(initial_acc * 100).round(1)}% to #{(final_acc * 100).round(1)}%"
+end
+
+puts "\n[4] Test predictions"
+Dir.glob(File.join(fixtures_path, "*/*.jpg")).each do |image_path|
+  true_label = File.basename(File.dirname(image_path))
+  predictions = classifier.predict(image_path).first
+  pred_label = predictions.first[:label]
+  pred_score = predictions.first[:score]
+
+  status = pred_label == true_label ? "✓" : "✗"
+  puts "    #{status} #{File.basename(image_path)}: predicted=#{pred_label} (#{(pred_score * 100).round(1)}%), actual=#{true_label}"
+end
+
+puts "\n[5] Save and reload model"
+save_path = "/tmp/fine_demo_model"
+classifier.save(save_path)
+puts "    Saved to: #{save_path}"
+
+loaded = Fine::ImageClassifier.load(save_path)
+puts "    Loaded successfully with #{loaded.label_map.size} classes: #{loaded.label_map.keys.join(', ')}"
+
+puts "\n" + "=" * 60
+puts "DEMO COMPLETE"
+puts "=" * 60

data/examples/finetune_gemma3_tools.rb

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Fine-tune Gemma 3 (1B) for tool calling
+#
+# This script fine-tunes Gemma 3 1B instruction-tuned model to generate
+# tool calls in Ollama-compatible format.
+#
+# Format:
+#   Input:  [AVAILABLE_TOOLS] [{...tool definitions...}] [/AVAILABLE_TOOLS]
+#   Output: [TOOL_CALLS] [{...tool calls...}]
+
+require "bundler/setup"
+require "fine"
+
+puts "=" * 60
+puts "GEMMA 3 TOOL CALLING FINE-TUNING"
+puts "=" * 60
+
+Fine.configure do |config|
+  config.progress_bar = false
+end
+
+data_path = File.expand_path("data/tool_calls.jsonl", __dir__)
+
+# Gemma 3 1B instruction-tuned
+model_id = "google/gemma-3-1b-it"
+
+puts "\n1. Setting up LLM with #{model_id}..."
+puts "   (This will download ~2GB from HuggingFace if not cached)"
+
+begin
+  llm = Fine::LLM.new(model_id) do |config|
+    config.epochs = 3
+    config.batch_size = 1  # Reduced for memory
+    config.learning_rate = 2e-5
+    config.max_length = 256  # Reduced for memory
+    config.gradient_accumulation_steps = 1  # Set to 1 to avoid memory issues
+    config.warmup_steps = 10
+    config.max_grad_norm = nil  # Disable gradient clipping to simplify
+
+    config.on_epoch_end do |epoch, metrics|
+      puts "    Epoch #{epoch}: loss=#{metrics[:loss].round(4)}"
+    end
+  end
+
+  puts "   Config:"
+  puts "     Epochs: #{llm.config.epochs}"
+  puts "     Batch size: #{llm.config.batch_size}"
+  puts "     Learning rate: #{llm.config.learning_rate}"
+  puts "     Max length: #{llm.config.max_length}"
+
+  puts "\n2. Loading training data from #{data_path}..."
+  line_count = File.readlines(data_path).count
+  puts "   Found #{line_count} examples"
+
+  puts "\n3. Starting fine-tuning..."
+  puts "   (This may take a while depending on your hardware)"
+  puts ""
+
+  history = llm.fit(train_file: data_path, format: :alpaca)
+
+  puts "\n4. Training completed!"
+  puts "   Final loss: #{history.last[:loss].round(4)}"
+
+  if history.size >= 2 && history.last[:loss] < history.first[:loss]
+    improvement = ((1 - history.last[:loss] / history.first[:loss]) * 100).round(1)
+    puts "   Loss improved by #{improvement}%"
+  end
+
+  puts "\n5. Testing tool call generation..."
+
+  test_prompts = [
+    {
+      instruction: "What's the weather in Chicago?",
+      tools: "Available tools:\n- get_weather(location: string) - Get current weather\n- calculate(expression: string) - Evaluate math"
+    },
+    {
+      instruction: "Calculate 50 + 25 * 2",
+      tools: "Available tools:\n- get_weather(location: string) - Get current weather\n- calculate(expression: string) - Evaluate math"
+    },
+    {
+      instruction: "Search for Python tutorials",
+      tools: "Available tools:\n- search_web(query: string) - Search the web\n- get_weather(location: string) - Get weather"
+    }
+  ]
+
+  test_prompts.each do |prompt|
+    full_prompt = "### Instruction:\n#{prompt[:instruction]}\n\n### Input:\n#{prompt[:tools]}\n\n### Response:\n"
+
+    response = llm.generate(
+      full_prompt,
+      max_new_tokens: 100,
+      temperature: 0.1,  # Low temperature for deterministic tool calls
+      do_sample: false   # Greedy decoding for consistent output
+    )
+
+    # Extract just the response part
+    generated = response.split("### Response:").last.strip
+
+    puts "\n   Prompt: \"#{prompt[:instruction]}\""
+    puts "   Generated:"
+    puts "   #{generated.lines.first(5).map(&:strip).join("\n   ")}"
+  end
+
+  puts "\n6. Saving fine-tuned model..."
+  save_path = "/tmp/gemma3-tool-calling"
+  llm.save(save_path)
+  puts "   Saved to: #{save_path}"
+
+  puts "\n7. Testing load and generate..."
+  loaded = Fine::LLM.load(save_path)
+
+  test_prompt = "### Instruction:\nCheck the temperature in Boston\n\n### Input:\nAvailable tools:\n- get_weather(location: string) - Get weather\n\n### Response:\n"
+  loaded_response = loaded.generate(test_prompt, max_new_tokens: 50, do_sample: false)
+  generated = loaded_response.split("### Response:").last.strip
+
+  puts "   Loaded model response:"
+  puts "   #{generated.lines.first(3).map(&:strip).join("\n   ")}"
+
+  puts "\n" + "=" * 60
+  puts "GEMMA 3 TOOL CALLING FINE-TUNING COMPLETE!"
+  puts "=" * 60
+  puts "\nModel saved to: #{save_path}"
+  puts "You can load it with: Fine::LLM.load('#{save_path}')"
+
+rescue => e
+  puts "\n" + "=" * 60
+  puts "FINE-TUNING FAILED!"
+  puts "=" * 60
+  puts "\nError: #{e.class}: #{e.message}"
+  puts "\nBacktrace:"
+  puts e.backtrace.first(20).join("\n")
+  exit 1
+end