fine 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a12cf37fd90bb1744c5d4a91863406a7bd02742df9596113dce12e847874e969
+  data.tar.gz: 7fba7fea8eef802257b8f20949a78befe21baad74757ab28426c147c508d4009
+SHA512:
+  metadata.gz: 7a6383340fc114a158e34bc905dddc24865b0ace2d4fa771abd129ca0a5bb9cbeb372682b181329ad33daffa447facf426a65cd275580f59951c4e22791e0747
+  data.tar.gz: e8ae855256a5cd1fd2d3467177f3990db3081ff416e36931968f75b1f2578fa979fe7699d38d288fcbd35d3ab7bfa3cb545dfbee697f4b02e1a113375307f1a6

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2025-01-26
+
+### Added
+
+- **Image Classification** with SigLIP2 models
+  - `Fine::ImageClassifier` for training and inference
+  - Support for `google/siglip2-base-patch16-224` and other SigLIP2 variants
+  - Directory-based dataset loading with automatic class discovery
+
+- **Text Classification** with BERT-family models
+  - `Fine::TextClassifier` for sentiment, intent, and category classification
+  - Support for DistilBERT, BERT, DeBERTa models
+  - JSONL dataset format with `text` and `label` fields
+
+- **Text Embeddings** with Sentence Transformers
+  - `Fine::TextEmbedder` for domain-specific embeddings
+  - Support for MiniLM, MPNet, BGE models
+  - Contrastive learning with positive/negative pairs
+
+- **LLM Fine-tuning** (experimental)
+  - `Fine::LLM` for instruction fine-tuning
+  - Support for Llama, Gemma, Qwen architectures
+  - Alpaca-format dataset support
+
+- **Model Export**
+  - ONNX export for all model types
+  - GGUF export for LLMs (llama.cpp/Ollama compatible)
+
+- **Infrastructure**
+  - HuggingFace Hub integration with automatic model downloads
+  - SafeTensors weight loading
+  - Block-based configuration DSL
+  - Progress bar callbacks
+  - MPS (Apple Silicon) and CUDA support

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in fine.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,167 @@
+PATH
+  remote: .
+  specs:
+    fine (0.1.0)
+      down (>= 5.0)
+      ruby-vips (>= 2.1)
+      safetensors (>= 0.1)
+      tokenizers (>= 0.4)
+      torch-rb (>= 0.17)
+      tty-progressbar (>= 0.18)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    diff-lcs (1.6.2)
+    down (5.4.2)
+      addressable (~> 2.8)
+    ffi (1.17.3-aarch64-linux-gnu)
+    ffi (1.17.3-aarch64-linux-musl)
+    ffi (1.17.3-arm64-darwin)
+    ffi (1.17.3-x86_64-darwin)
+    ffi (1.17.3-x86_64-linux-gnu)
+    ffi (1.17.3-x86_64-linux-musl)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    parallel (1.27.0)
+    parser (3.3.10.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.8.0)
+    public_suffix (7.0.2)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rice (4.9.1)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.82.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    ruby-vips (2.3.0)
+      ffi (~> 1.12)
+      logger
+    safetensors (0.2.2-aarch64-linux)
+    safetensors (0.2.2-aarch64-linux-musl)
+    safetensors (0.2.2-arm64-darwin)
+    safetensors (0.2.2-x86_64-darwin)
+    safetensors (0.2.2-x86_64-linux)
+    safetensors (0.2.2-x86_64-linux-musl)
+    strings-ansi (0.2.0)
+    tokenizers (0.6.3-aarch64-linux)
+    tokenizers (0.6.3-aarch64-linux-musl)
+    tokenizers (0.6.3-arm64-darwin)
+    tokenizers (0.6.3-x86_64-darwin)
+    tokenizers (0.6.3-x86_64-linux)
+    tokenizers (0.6.3-x86_64-linux-musl)
+    torch-rb (0.23.0)
+      rice (>= 4.8)
+    tty-cursor (0.7.1)
+    tty-progressbar (0.18.3)
+      strings-ansi (~> 0.2)
+      tty-cursor (~> 0.7)
+      tty-screen (~> 0.8)
+      unicode-display_width (>= 1.6, < 3.0)
+    tty-screen (0.8.2)
+    unicode-display_width (2.6.0)
+
+PLATFORMS
+  aarch64-linux
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm64-darwin
+  x86_64-darwin
+  x86_64-linux
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  fine!
+  rake (~> 13.0)
+  rspec (~> 3.12)
+  rubocop (~> 1.50)
+
+CHECKSUMS
+  addressable (2.8.8) sha256=7c13b8f9536cf6364c03b9d417c19986019e28f7c00ac8132da4eb0fe393b057
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  down (5.4.2) sha256=516e5e01e7a96214a7e2cd155aac6f700593038ae6c857c0f4a05413b1c58acf
+  ffi (1.17.3-aarch64-linux-gnu) sha256=28ad573df26560f0aedd8a90c3371279a0b2bd0b4e834b16a2baa10bd7a97068
+  ffi (1.17.3-aarch64-linux-musl) sha256=020b33b76775b1abacc3b7d86b287cef3251f66d747092deec592c7f5df764b2
+  ffi (1.17.3-arm64-darwin) sha256=0c690555d4cee17a7f07c04d59df39b2fba74ec440b19da1f685c6579bb0717f
+  ffi (1.17.3-x86_64-darwin) sha256=1f211811eb5cfaa25998322cdd92ab104bfbd26d1c4c08471599c511f2c00bb5
+  ffi (1.17.3-x86_64-linux-gnu) sha256=3746b01f677aae7b16dc1acb7cb3cc17b3e35bdae7676a3f568153fb0e2c887f
+  ffi (1.17.3-x86_64-linux-musl) sha256=086b221c3a68320b7564066f46fed23449a44f7a1935f1fe5a245bd89d9aea56
+  fine (0.1.0)
+  json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
+  language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
+  parser (3.3.10.1) sha256=06f6a725d2cd91e5e7f2b7c32ba143631e1f7c8ae2fb918fc4cebec187e6a688
+  prism (1.8.0) sha256=84453a16ef5530ea62c5f03ec16b52a459575ad4e7b9c2b360fd8ce2c39c1254
+  public_suffix (7.0.2) sha256=9114090c8e4e7135c1fd0e7acfea33afaab38101884320c65aaa0ffb8e26a857
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
+  rice (4.9.1) sha256=f915b35a3a7f51af83a3dd173da387da56bfe6f0dcf02ed0b3d2889c531b2bbd
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.7) sha256=0979034e64b1d7a838aaaddf12bf065ea4dc40ef3d4c39f01f93ae2c66c62b1c
+  rspec-support (3.13.6) sha256=2e8de3702427eab064c9352fe74488cc12a1bfae887ad8b91cba480ec9f8afb2
+  rubocop (1.82.1) sha256=09f1a6a654a960eda767aebea33e47603080f8e9c9a3f019bf9b94c9cab5e273
+  rubocop-ast (1.49.0) sha256=49c3676d3123a0923d333e20c6c2dbaaae2d2287b475273fddee0c61da9f71fd
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  ruby-vips (2.3.0) sha256=e685ec02c13969912debbd98019e50492e12989282da5f37d05f5471442f5374
+  safetensors (0.2.2-aarch64-linux) sha256=5b50146d50a76fe0395b7aef4d13a1da8fcad44e9cf0f5aead935d5d17fb04dd
+  safetensors (0.2.2-aarch64-linux-musl) sha256=d6dea4e4f5ca11cff8ba4c017382838df5d33d78f79fabd9a5e5e482aa6afd57
+  safetensors (0.2.2-arm64-darwin) sha256=19d77df47154038974f76a4e1bac2d778ea04ca2c49abcd5b9f9c0f1a899d10b
+  safetensors (0.2.2-x86_64-darwin) sha256=a1dc2b415f6ef35c8887b15a6f72c673f3b008455c33aa399154c0eabf5adbcd
+  safetensors (0.2.2-x86_64-linux) sha256=f447d3d3110a7592b521a23f58b0251283659b27f3700ab627ac6ba517fa04ff
+  safetensors (0.2.2-x86_64-linux-musl) sha256=0d52871f2b672485cda73bc94807bb6bd74409a33414fdc341950ceb88f76049
+  strings-ansi (0.2.0) sha256=90262d760ea4a94cc2ae8d58205277a343409c288cbe7c29416b1826bd511c88
+  tokenizers (0.6.3-aarch64-linux) sha256=9d54a23f2e2246cc942d183af4549e3972b937d9b01f7a387cb146bf698eee84
+  tokenizers (0.6.3-aarch64-linux-musl) sha256=c178d8556769256857d77fb396f8ab004b29d058f59c620a2cfc56b01b501e27
+  tokenizers (0.6.3-arm64-darwin) sha256=29a6a5582dce106d846a906ee9e4254c12db45a3855c3ff6881d4be8be03e6b6
+  tokenizers (0.6.3-x86_64-darwin) sha256=4b71386cc08ceff5f86b448c74b2b297c00a280a1d502399b6cda23ef94e01fd
+  tokenizers (0.6.3-x86_64-linux) sha256=77a45cbde59daac33bdda1a74d45c18080478992a00ee7d898e7b8d15d0b3149
+  tokenizers (0.6.3-x86_64-linux-musl) sha256=a4b08c53bf0c8f7674c3abd03e013f0bb7c0c2457174b116c2872a37c64f0297
+  torch-rb (0.23.0) sha256=618f19523ff6d27da0cb001d6b32e041c05eb796a4e016b4c48b7f0736aa1d5f
+  tty-cursor (0.7.1) sha256=79534185e6a777888d88628b14b6a1fdf5154a603f285f80b1753e1908e0bf48
+  tty-progressbar (0.18.3) sha256=6cbb4260e55e74a9180d502143eb6a467d2c8e51bf5f3c9509fb5cacc3d4a5f6
+  tty-screen (0.8.2) sha256=c090652115beae764336c28802d633f204fb84da93c6a968aa5d8e319e819b50
+  unicode-display_width (2.6.0) sha256=12279874bba6d5e4d2728cef814b19197dbb10d7a7837a869bab65da943b7f5a
+
+BUNDLED WITH
+  4.0.3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris Hasinski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,212 @@
+# Fine
+
+Fine-tune machine learning models with Ruby.
+
+```ruby
+classifier = Fine::TextClassifier.new("distilbert-base-uncased")
+classifier.fit(train_file: "reviews.jsonl", epochs: 3)
+classifier.predict("This product is amazing!")
+# => [{ label: "positive", score: 0.97 }]
+```
+
+## I want to fine-tune...
+
+### Text classification (sentiment, spam, intent)
+
+Classify text into categories—reviews, support tickets, chat messages.
+
+```ruby
+classifier = Fine::TextClassifier.new("distilbert-base-uncased")
+classifier.fit(train_file: "data/reviews.jsonl", epochs: 3)
+
+classifier.predict("Terrible experience, waste of money")
+# => [{ label: "negative", score: 0.94 }]
+```
+
+[Full tutorial: Text Classification](docs/tutorials/text-classification.md)
+
+---
+
+### Text embeddings for semantic search
+
+Train embeddings for your domain—legal docs, support tickets, product catalog.
+
+```ruby
+embedder = Fine::TextEmbedder.new("sentence-transformers/all-MiniLM-L6-v2")
+embedder.fit(train_file: "data/pairs.jsonl", epochs: 3)
+
+embedding = embedder.encode("How do I cancel my subscription?")
+```
+
+[Full tutorial: Text Embeddings](docs/tutorials/text-embeddings.md)
+
+---
+
+### Image classification
+
+Classify images into categories (cats vs dogs, products, documents).
+
+```ruby
+classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-224")
+classifier.fit(train_dir: "data/train", val_dir: "data/val", epochs: 3)
+
+classifier.predict("photo.jpg")
+# => [{ label: "cat", score: 0.95 }]
+```
+
+[Full tutorial: Image Classification](docs/tutorials/siglip2-image-classification.md)
+
+---
+
+### Image recognition for custom objects
+
+Teach the model to recognize your products, logos, or custom objects.
+
+```ruby
+classifier = Fine::ImageClassifier.new("google/siglip2-base-patch16-384") do |config|
+  config.epochs = 5
+  config.learning_rate = 1e-4
+end
+
+classifier.fit(train_dir: "products/train")
+classifier.save("models/product_detector")
+```
+
+[Full tutorial: Object Recognition](docs/tutorials/siglip2-object-recognition.md)
+
+---
+
+### Image similarity search
+
+Find visually similar images in your catalog.
+
+```ruby
+encoder = model.encoder
+embedding = encoder.call(image_tensor)
+similarity = cosine_similarity(embedding1, embedding2)
+```
+
+[Full tutorial: Similarity Search](docs/tutorials/siglip2-similarity-search.md)
+
+---
+
+### LLMs
+
+Fine-tune Gemma, Llama, Qwen and other open models for custom tasks.
+
+```ruby
+llm = Fine::LLM.new("meta-llama/Llama-3.2-1B")
+llm.fit(train_file: "instructions.jsonl", epochs: 3)
+
+llm.generate("Explain Ruby blocks")
+# => "A Ruby block is a chunk of code that can be passed to a method..."
+```
+
+[Full tutorial: LLM Fine-tuning](docs/tutorials/llm-fine-tuning.md)
+
+---
+
+## Installation
+
+```ruby
+gem 'fine'
+```
+
+Requires Ruby 3.1+, LibTorch, and libvips.
+
+[Full installation guide](docs/installation.md)
+
+**Quick setup (macOS):**
+```bash
+brew install pytorch libvips
+bundle install
+```
+
+## Supported Models
+
+**Text Classification**
+
+| Model | Parameters | Speed | Quality |
+|-------|------------|-------|---------|
+| `distilbert-base-uncased` | 66M | Fast | Good |
+| `bert-base-uncased` | 110M | Medium | Better |
+| `microsoft/deberta-v3-small` | 44M | Fast | Great |
+| `microsoft/deberta-v3-base` | 86M | Medium | Best |
+
+**Text Embeddings**
+
+| Model | Parameters | Best For |
+|-------|------------|----------|
+| `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 |
+
+**Vision (SigLIP2)**
+
+| Model | Parameters | Best For |
+|-------|------------|----------|
+| `google/siglip2-base-patch16-224` | 86M | Quick experiments |
+| `google/siglip2-base-patch16-384` | 86M | Good balance |
+| `google/siglip2-large-patch16-256` | 303M | Maximum accuracy |
+| `google/siglip2-so400m-patch14-224` | 400M | Best quality |
+
+**LLMs**
+
+| Model | Parameters | Best For |
+|-------|------------|----------|
+| `meta-llama/Llama-3.2-1B` | 1B | Fast experiments |
+| `google/gemma-2b` | 2B | Good balance |
+| `Qwen/Qwen2-1.5B` | 1.5B | Multilingual |
+| `mistralai/Mistral-7B-v0.1` | 7B | Best quality |
+
+## Configuration
+
+```ruby
+Fine::TextClassifier.new("distilbert-base-uncased") do |config|
+  config.epochs = 3
+  config.batch_size = 16
+  config.learning_rate = 2e-5
+  config.max_length = 256
+
+  config.on_epoch_end do |epoch, metrics|
+    puts "Epoch #{epoch}: #{metrics[:accuracy]}"
+  end
+end
+```
+
+## Export for Deployment
+
+Export fine-tuned models to production formats.
+
+**ONNX** - For ONNX Runtime, TensorRT, OpenVINO:
+
+```ruby
+classifier.export_onnx("model.onnx")
+embedder.export_onnx("embedder.onnx")
+```
+
+**GGUF** - For llama.cpp, ollama (LLMs only):
+
+```ruby
+llm.export_gguf("model.gguf", quantization: :q4_0)
+```
+
+[Full tutorial: Model Export](docs/tutorials/model-export.md)
+
+## Roadmap
+
+- [x] SigLIP2 image classification
+- [x] Text classification (BERT, DeBERTa)
+- [x] Text embedding models
+- [x] LLM fine-tuning (Gemma, Llama, Qwen)
+- [x] ONNX & GGUF export
+- [ ] LoRA/QLoRA fine-tuning
+
+## Contributing
+
+Bug reports and pull requests welcome at [github.com/khasinski/fine](https://github.com/khasinski/fine).
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/docs/installation.md

@@ -0,0 +1,151 @@
+# Installation
+
+## Requirements
+
+- Ruby 3.1+
+- LibTorch 2.x
+- libvips (for image processing)
+
+## Quick Install
+
+```bash
+# Install system dependencies (macOS)
+brew install pytorch libvips
+
+# Install system dependencies (Ubuntu/Debian)
+# sudo apt-get install libvips-dev
+# Download LibTorch from https://pytorch.org/get-started/locally/
+
+# Add to your Gemfile
+gem 'fine'
+
+# Install
+bundle install
+```
+
+## Detailed Setup
+
+### 1. Install LibTorch
+
+**macOS (Homebrew):**
+```bash
+brew install pytorch
+```
+
+**Linux:**
+Download from [pytorch.org](https://pytorch.org/get-started/locally/) and set:
+```bash
+export LIBTORCH=/path/to/libtorch
+export LD_LIBRARY_PATH=$LIBTORCH/lib:$LD_LIBRARY_PATH
+```
+
+**Verify:**
+```bash
+# Should show libtorch path
+ls $(brew --prefix pytorch)/lib/libtorch* 2>/dev/null || echo "Check LibTorch installation"
+```
+
+### 2. Install libvips
+
+**macOS:**
+```bash
+brew install vips
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get install libvips-dev
+```
+
+**Verify:**
+```bash
+vips --version
+```
+
+### 3. Install the Gem
+
+```ruby
+# Gemfile
+gem 'fine'
+```
+
+```bash
+bundle install
+```
+
+### 4. Verify Installation
+
+```ruby
+require 'fine'
+
+puts Fine::VERSION
+puts "Torch available: #{defined?(Torch)}"
+puts "Device: #{Fine.device}"
+```
+
+## Troubleshooting
+
+### LibTorch Version Mismatch
+
+Error: `Incompatible LibTorch version`
+
+The torch-rb gem requires a specific LibTorch version. Check compatibility:
+```bash
+# Check your LibTorch version
+python3 -c "import torch; print(torch.__version__)"
+
+# Or check brew
+brew info pytorch
+```
+
+Update LibTorch or pin torch-rb to a compatible version.
+
+### Missing libvips
+
+Error: `cannot load such file -- vips`
+
+```bash
+# macOS
+brew install vips
+
+# Ubuntu
+sudo apt-get install libvips-dev
+```
+
+### Native Extension Build Failures
+
+```bash
+# Ensure you have build tools
+xcode-select --install  # macOS
+
+# Reinstall with verbose output
+gem install torch-rb -- --verbose
+```
+
+## GPU Support
+
+### CUDA (NVIDIA)
+
+Ensure CUDA toolkit is installed and LibTorch was built with CUDA support.
+
+```ruby
+Fine.configure do |config|
+  config.device = "cuda"  # or "cuda:0" for specific GPU
+end
+```
+
+### MPS (Apple Silicon)
+
+Automatic on M1/M2/M3 Macs with supported PyTorch:
+
+```ruby
+puts Fine.device  # Should show "mps" on Apple Silicon
+```
+
+### CPU Only
+
+```ruby
+Fine.configure do |config|
+  config.device = "cpu"
+end
+```