fastembed 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1bc6e2a53d0c7a8c4679f7af6a23af74b903b0e227c401307e3d936d74719291
+  data.tar.gz: 5664c43f8d7f0632719324b42805abe3806274c18113232f82bbddce918647e5
+SHA512:
+  metadata.gz: f7f821a8a8ee49fdbbde65eaf394d8b406b1aecfc53fa572ecbbf3ccaf9fd120771fa5e5d444d339aa9ec5b729c63f283e564d05ea1ce1db1427580ced41cc0d
+  data.tar.gz: a99fda1200c29abf2ea7bed10ab5e7eee30fc5238e5d13b5608f7c41014e98e1e880c67ea1da1e56eef10864697ebca11ed7a7bf6463fb437f4dc4fe80267bef

data/.mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.3"

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,73 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/*'
+    - 'vendor/**/*'
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 30
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/ParameterLists:
+  Max: 9
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - a
+    - b
+    - x
+    - y
+
+Lint/EmptyBlock:
+  Exclude:
+    - 'lib/fastembed/text_embedding.rb'
+
+RSpec/MultipleDescribes:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+
+Layout/LineLength:
+  Max: 120
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/ExampleLength:
+  Max: 15
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/integration_spec.rb'

data/BENCHMARKS.md

@@ -0,0 +1,83 @@
+# Benchmarks
+
+Performance benchmarks on Apple M1 Max, Ruby 3.3.10.
+
+## Single Document Latency
+
+Using the default model (BAAI/bge-small-en-v1.5):
+
+| Text Length | Latency |
+|-------------|---------|
+| Short (~10 tokens) | ~6.5 ms |
+| Medium (~30 tokens) | ~6.5 ms |
+
+## Batch Throughput
+
+### bge-small-en-v1.5 (default)
+
+| Text Length | 100 docs | Throughput |
+|-------------|----------|------------|
+| Short sentences | 0.2s | **502 docs/sec** |
+| Medium paragraphs | 0.5s | **197 docs/sec** |
+| Long documents | 2.3s | **44 docs/sec** |
+
+### Large Scale (1000 documents)
+
+| Model | Time | Throughput |
+|-------|------|------------|
+| bge-small-en-v1.5 | 2.0s | **509 docs/sec** |
+
+## Model Comparison
+
+| Model | Dimensions | Size | Throughput |
+|-------|-----------|------|------------|
+| bge-small-en-v1.5 | 384 | 67 MB | **530 docs/sec** |
+| bge-base-en-v1.5 | 768 | 210 MB | **169 docs/sec** |
+| bge-large-en-v1.5 | 1024 | 1.2 GB | **50 docs/sec** |
+
+## CPU vs CoreML (Apple Silicon)
+
+We tested CoreML execution provider to see if GPU/Neural Engine acceleration helps.
+
+### Results by Model
+
+| Model | CPU | CoreML (best batch) | Ratio |
+|-------|-----|---------------------|-------|
+| bge-small | 418/s | 162/s (batch=64) | CPU 2.6x faster |
+| bge-base | 134/s | 64/s (batch=32) | CPU 2.1x faster |
+| bge-large | 41/s | 23/s (batch=16) | CPU 1.8x faster |
+
+### Batch Size Impact on CoreML
+
+| Batch Size | CPU (bge-small) | CoreML | Ratio |
+|------------|-----------------|--------|-------|
+| 1 | 209/s | 40/s | 0.19x |
+| 8 | 351/s | 118/s | 0.34x |
+| 16 | 382/s | 146/s | 0.38x |
+| 32 | 410/s | 155/s | 0.38x |
+| 64 | 418/s | 162/s | 0.39x |
+| 128 | 391/s | 139/s | 0.35x |
+| 256 | 412/s | 121/s | 0.29x |
+
+### Conclusion
+
+**CPU is faster than CoreML** for all embedding models on Apple Silicon. The gap narrows for larger models, but CPU still wins. This is because:
+
+1. ONNX Runtime's CPU implementation is highly optimized for M1/M2
+2. Data transfer overhead to Neural Engine outweighs compute benefits
+3. Embedding models are relatively small compared to LLMs
+
+**Recommendation:** Stick with the default CPU provider.
+
+## Running Your Own Benchmarks
+
+```ruby
+require 'fastembed'
+require 'benchmark'
+
+embedding = Fastembed::TextEmbedding.new
+texts = Array.new(1000) { "Sample text for benchmarking" }
+
+result = Benchmark.measure { embedding.embed(texts).to_a }
+puts "#{1000 / result.real} docs/sec"
+```

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2025-01-08
+
+### Added
+
+- Initial release
+- `TextEmbedding` class for generating text embeddings
+- Automatic model downloading and caching from HuggingFace
+- Support for multiple embedding models:
+  - BAAI/bge-small-en-v1.5 (default)
+  - BAAI/bge-base-en-v1.5
+  - BAAI/bge-large-en-v1.5
+  - sentence-transformers/all-MiniLM-L6-v2
+  - intfloat/multilingual-e5-small
+  - intfloat/multilingual-e5-base
+- Lazy evaluation with `Enumerator` for memory efficiency
+- Query and passage embedding methods for retrieval tasks
+- Configurable batch size, threading, and execution providers
+- Mean pooling and L2 normalization
+- CoreML execution provider support (experimental)
+
+[Unreleased]: https://github.com/khasinski/fastembed-rb/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/khasinski/fastembed-rb/releases/tag/v1.0.0

data/Gemfile

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

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,163 @@
+# FastEmbed Ruby
+
+[![Gem Version](https://badge.fury.io/rb/fastembed.svg)](https://rubygems.org/gems/fastembed)
+[![CI](https://github.com/khasinski/fastembed-rb/actions/workflows/ci.yml/badge.svg)](https://github.com/khasinski/fastembed-rb/actions/workflows/ci.yml)
+
+Fast, lightweight text embeddings in Ruby. Convert text into vectors for semantic search, similarity matching, clustering, and RAG applications.
+
+```ruby
+embedding = Fastembed::TextEmbedding.new
+vectors = embedding.embed(["Hello world", "Ruby is great"]).to_a
+# => [[0.123, -0.456, ...], [0.789, 0.012, ...]]  (384-dimensional vectors)
+```
+
+## What are embeddings?
+
+Embeddings convert text into numerical vectors that capture semantic meaning. Similar texts produce similar vectors, enabling:
+
+- **Semantic search** - Find relevant documents by meaning, not just keywords
+- **Similarity matching** - Compare texts to find duplicates or related content
+- **RAG applications** - Retrieve context for LLMs like ChatGPT
+- **Clustering** - Group similar documents together
+
+## Installation
+
+```ruby
+gem 'fastembed'
+```
+
+## Quick Start
+
+```ruby
+require 'fastembed'
+
+# Create embedding model (downloads automatically on first use, ~67MB)
+embedding = Fastembed::TextEmbedding.new
+
+# Embed your texts
+docs = ["Ruby is a programming language", "Python is also a programming language"]
+vectors = embedding.embed(docs).to_a
+
+# Find similarity between texts (cosine similarity via dot product)
+similarity = vectors[0].zip(vectors[1]).sum { |a, b| a * b }
+puts similarity  # => 0.89 (high similarity!)
+```
+
+## Semantic Search Example
+
+```ruby
+# Your document corpus
+documents = [
+  "The quick brown fox jumps over the lazy dog",
+  "Machine learning is a subset of artificial intelligence",
+  "Ruby on Rails is a web application framework",
+  "Neural networks are inspired by biological brains"
+]
+
+# Create embeddings for all documents
+embedding = Fastembed::TextEmbedding.new
+doc_vectors = embedding.embed(documents).to_a
+
+# Search query
+query = "AI and deep learning"
+query_vector = embedding.embed(query).first
+
+# Find most similar document (highest dot product)
+similarities = doc_vectors.map.with_index do |doc_vec, i|
+  score = query_vector.zip(doc_vec).sum { |a, b| a * b }
+  [i, score]
+end
+
+best_match = similarities.max_by { |_, score| score }
+puts documents[best_match[0]]  # => "Machine learning is a subset of artificial intelligence"
+```
+
+## Usage
+
+### Choose a Model
+
+```ruby
+# Default: Fast and accurate (384 dimensions, 67MB)
+embedding = Fastembed::TextEmbedding.new
+
+# Higher accuracy (768 dimensions, 210MB)
+embedding = Fastembed::TextEmbedding.new(model_name: "BAAI/bge-base-en-v1.5")
+
+# Multilingual support (100+ languages)
+embedding = Fastembed::TextEmbedding.new(model_name: "intfloat/multilingual-e5-small")
+
+# Long documents (8192 tokens vs default 512)
+embedding = Fastembed::TextEmbedding.new(model_name: "nomic-ai/nomic-embed-text-v1.5")
+```
+
+### Process Large Datasets
+
+```ruby
+# Lazy evaluation - memory efficient for large datasets
+documents = File.readlines("corpus.txt")
+
+embedding.embed(documents, batch_size: 64).each_slice(100) do |batch|
+  store_in_vector_database(batch)
+end
+```
+
+### List Available Models
+
+```ruby
+Fastembed::TextEmbedding.list_supported_models.each do |model|
+  puts "#{model[:model_name]} - #{model[:dim]}d - #{model[:description]}"
+end
+```
+
+## Supported Models
+
+| Model | Dim | Use Case |
+|-------|-----|----------|
+| `BAAI/bge-small-en-v1.5` | 384 | Default, fast English embeddings |
+| `BAAI/bge-base-en-v1.5` | 768 | Higher accuracy English |
+| `BAAI/bge-large-en-v1.5` | 1024 | Highest accuracy English |
+| `sentence-transformers/all-MiniLM-L6-v2` | 384 | General purpose, lightweight |
+| `sentence-transformers/all-mpnet-base-v2` | 768 | High quality general purpose |
+| `intfloat/multilingual-e5-small` | 384 | 100+ languages |
+| `intfloat/multilingual-e5-base` | 768 | 100+ languages, higher accuracy |
+| `nomic-ai/nomic-embed-text-v1.5` | 768 | Long context (8192 tokens) |
+| `jinaai/jina-embeddings-v2-base-en` | 768 | Long context (8192 tokens) |
+
+## Performance
+
+On Apple M1 Max with the default model:
+
+| Batch Size | Throughput |
+|------------|------------|
+| 1 document | ~6.5ms |
+| 100 documents | ~500 docs/sec |
+| 1000 documents | ~500 docs/sec |
+
+Larger models are slower but more accurate. See [benchmarks](BENCHMARKS.md) for details.
+
+## Configuration
+
+```ruby
+Fastembed::TextEmbedding.new(
+  model_name: "BAAI/bge-small-en-v1.5",  # Model to use
+  cache_dir: "~/.cache/fastembed",        # Where to store models
+  threads: 4,                              # ONNX Runtime threads
+  providers: ["CUDAExecutionProvider"]     # GPU acceleration (Linux/Windows)
+)
+```
+
+**Environment variables:**
+- `FASTEMBED_CACHE_PATH` - Custom model cache directory
+
+## Requirements
+
+- Ruby >= 3.3
+- ~70MB disk space for default model (varies by model)
+
+## Acknowledgments
+
+Ruby port of [FastEmbed](https://github.com/qdrant/fastembed) by Qdrant. Built on [onnxruntime-ruby](https://github.com/ankane/onnxruntime-ruby) and [tokenizers-ruby](https://github.com/ankane/tokenizers-ruby) by Andrew Kane.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/fastembed.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative 'lib/fastembed/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'fastembed'
+  spec.version       = Fastembed::VERSION
+  spec.authors       = ['Chris Hasinski']
+  spec.email         = ['krzysztof.hasinski@gmail.com']
+
+  spec.summary       = 'Fast, lightweight text embeddings for Ruby'
+  spec.description   = 'A Ruby port of FastEmbed - fast text embeddings using ONNX Runtime'
+  spec.homepage      = 'https://github.com/khasinski/fastembed-rb'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.3.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'onnxruntime', '~> 0.9'
+  spec.add_dependency 'tokenizers', '~> 0.5'
+
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'rubocop-rspec', '~> 3.0'
+end

data/lib/fastembed/model_info.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Fastembed
+  # Model information structure
+  class ModelInfo
+    attr_reader :model_name, :dim, :description, :size_in_gb, :model_file,
+                :tokenizer_file, :sources, :pooling, :normalize
+
+    def initialize(
+      model_name:,
+      dim:,
+      description:,
+      size_in_gb:,
+      sources:,
+      model_file: 'model.onnx',
+      tokenizer_file: 'tokenizer.json',
+      pooling: :mean,
+      normalize: true
+    )
+      @model_name = model_name
+      @dim = dim
+      @description = description
+      @size_in_gb = size_in_gb
+      @sources = sources
+      @model_file = model_file
+      @tokenizer_file = tokenizer_file
+      @pooling = pooling
+      @normalize = normalize
+    end
+
+    def hf_repo
+      sources[:hf]
+    end
+
+    def to_h
+      {
+        model_name: model_name,
+        dim: dim,
+        description: description,
+        size_in_gb: size_in_gb,
+        sources: sources,
+        model_file: model_file,
+        tokenizer_file: tokenizer_file,
+        pooling: pooling,
+        normalize: normalize
+      }
+    end
+  end
+
+  # Registry of supported models
+  SUPPORTED_MODELS = {
+    'BAAI/bge-small-en-v1.5' => ModelInfo.new(
+      model_name: 'BAAI/bge-small-en-v1.5',
+      dim: 384,
+      description: 'Fast and accurate English embedding model',
+      size_in_gb: 0.067,
+      sources: { hf: 'Xenova/bge-small-en-v1.5' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'BAAI/bge-base-en-v1.5' => ModelInfo.new(
+      model_name: 'BAAI/bge-base-en-v1.5',
+      dim: 768,
+      description: 'Balanced English embedding model with higher accuracy',
+      size_in_gb: 0.210,
+      sources: { hf: 'Xenova/bge-base-en-v1.5' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'BAAI/bge-large-en-v1.5' => ModelInfo.new(
+      model_name: 'BAAI/bge-large-en-v1.5',
+      dim: 1024,
+      description: 'High accuracy English embedding model',
+      size_in_gb: 1.2,
+      sources: { hf: 'Xenova/bge-large-en-v1.5' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'sentence-transformers/all-MiniLM-L6-v2' => ModelInfo.new(
+      model_name: 'sentence-transformers/all-MiniLM-L6-v2',
+      dim: 384,
+      description: 'Lightweight general-purpose sentence embedding model',
+      size_in_gb: 0.09,
+      sources: { hf: 'Xenova/all-MiniLM-L6-v2' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'intfloat/multilingual-e5-small' => ModelInfo.new(
+      model_name: 'intfloat/multilingual-e5-small',
+      dim: 384,
+      description: 'Multilingual embedding model supporting 100+ languages',
+      size_in_gb: 0.45,
+      sources: { hf: 'Xenova/multilingual-e5-small' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'intfloat/multilingual-e5-base' => ModelInfo.new(
+      model_name: 'intfloat/multilingual-e5-base',
+      dim: 768,
+      description: 'Larger multilingual embedding model',
+      size_in_gb: 1.11,
+      sources: { hf: 'Xenova/multilingual-e5-base' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'nomic-ai/nomic-embed-text-v1' => ModelInfo.new(
+      model_name: 'nomic-ai/nomic-embed-text-v1',
+      dim: 768,
+      description: 'Long context (8192 tokens) English embedding model',
+      size_in_gb: 0.52,
+      sources: { hf: 'nomic-ai/nomic-embed-text-v1' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'nomic-ai/nomic-embed-text-v1.5' => ModelInfo.new(
+      model_name: 'nomic-ai/nomic-embed-text-v1.5',
+      dim: 768,
+      description: 'Improved long context embedding with Matryoshka support',
+      size_in_gb: 0.52,
+      sources: { hf: 'nomic-ai/nomic-embed-text-v1.5' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'jinaai/jina-embeddings-v2-small-en' => ModelInfo.new(
+      model_name: 'jinaai/jina-embeddings-v2-small-en',
+      dim: 512,
+      description: 'Small English embedding with 8192 token context',
+      size_in_gb: 0.06,
+      sources: { hf: 'Xenova/jina-embeddings-v2-small-en' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'jinaai/jina-embeddings-v2-base-en' => ModelInfo.new(
+      model_name: 'jinaai/jina-embeddings-v2-base-en',
+      dim: 768,
+      description: 'Base English embedding with 8192 token context',
+      size_in_gb: 0.52,
+      sources: { hf: 'Xenova/jina-embeddings-v2-base-en' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'sentence-transformers/paraphrase-MiniLM-L6-v2' => ModelInfo.new(
+      model_name: 'sentence-transformers/paraphrase-MiniLM-L6-v2',
+      dim: 384,
+      description: 'Optimized for paraphrase detection and semantic similarity',
+      size_in_gb: 0.09,
+      sources: { hf: 'Xenova/paraphrase-MiniLM-L6-v2' },
+      model_file: 'onnx/model.onnx'
+    ),
+    'sentence-transformers/all-mpnet-base-v2' => ModelInfo.new(
+      model_name: 'sentence-transformers/all-mpnet-base-v2',
+      dim: 768,
+      description: 'High quality general-purpose sentence embeddings',
+      size_in_gb: 0.44,
+      sources: { hf: 'Xenova/all-mpnet-base-v2' },
+      model_file: 'onnx/model.onnx'
+    )
+  }.freeze
+
+  DEFAULT_MODEL = 'BAAI/bge-small-en-v1.5'
+end

data/lib/fastembed/model_management.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+require 'fileutils'
+
+module Fastembed
+  # Handles model downloading and caching
+  module ModelManagement
+    HF_API_BASE = 'https://huggingface.co'
+    REQUIRED_FILES = %w[
+      config.json
+      tokenizer.json
+      tokenizer_config.json
+      special_tokens_map.json
+    ].freeze
+
+    class << self
+      # Returns the cache directory for storing models
+      # Priority: FASTEMBED_CACHE_PATH > XDG_CACHE_HOME > ~/.cache
+      def cache_dir
+        @cache_dir ||= begin
+          base = ENV['FASTEMBED_CACHE_PATH'] ||
+                 ENV['XDG_CACHE_HOME'] ||
+                 File.join(Dir.home, '.cache')
+          File.join(base, 'fastembed')
+        end
+      end
+
+      # Set a custom cache directory
+      attr_writer :cache_dir
+
+      # Returns the path to a cached model, downloading if necessary
+      def retrieve_model(model_name, show_progress: true)
+        model_info = resolve_model_info(model_name)
+        model_dir = model_directory(model_info)
+
+        # Check if model is already cached
+        return model_dir if model_cached?(model_dir, model_info)
+
+        # Download model
+        download_model(model_info, model_dir, show_progress: show_progress)
+        model_dir
+      end
+
+      # Check if a model exists in cache
+      def model_cached?(model_dir, model_info)
+        return false unless Dir.exist?(model_dir)
+
+        # Check for required files
+        model_path = File.join(model_dir, model_info.model_file)
+        tokenizer_path = File.join(model_dir, model_info.tokenizer_file)
+
+        File.exist?(model_path) && File.exist?(tokenizer_path)
+      end
+
+      # Get the directory path for a model
+      def model_directory(model_info)
+        # Create a safe directory name from the model name
+        safe_name = model_info.model_name.gsub('/', '--')
+        File.join(cache_dir, 'models', safe_name)
+      end
+
+      # Resolve model name to ModelInfo
+      def resolve_model_info(model_name)
+        model_info = SUPPORTED_MODELS[model_name]
+        unless model_info
+          raise ArgumentError,
+                "Unknown model: #{model_name}. Use TextEmbedding.list_supported_models to see available models."
+        end
+
+        model_info
+      end
+
+      private
+
+      def download_model(model_info, model_dir, show_progress: true)
+        FileUtils.mkdir_p(model_dir)
+
+        repo_id = model_info.hf_repo
+        puts "Downloading model #{model_info.model_name} from #{repo_id}..." if show_progress
+
+        # Download model file
+        download_file(repo_id, model_info.model_file, model_dir, show_progress: show_progress)
+
+        # Download tokenizer and config files
+        files_to_download = REQUIRED_FILES + [model_info.tokenizer_file]
+        files_to_download.uniq.each do |file|
+          download_file(repo_id, file, model_dir, show_progress: show_progress,
+                                                  required: file == model_info.tokenizer_file)
+        end
+
+        puts "Model downloaded successfully to #{model_dir}" if show_progress
+      end
+
+      def download_file(repo_id, file_path, model_dir, show_progress: true, required: true)
+        # Determine the correct local path
+        # If file_path contains directories (e.g., "onnx/model.onnx"), create them
+        local_path = File.join(model_dir, file_path)
+        FileUtils.mkdir_p(File.dirname(local_path))
+
+        # Skip if already exists
+        if File.exist?(local_path)
+          puts "  #{file_path} (cached)" if show_progress
+          return
+        end
+
+        url = "#{HF_API_BASE}/#{repo_id}/resolve/main/#{file_path}"
+        puts "  Downloading #{file_path}..." if show_progress
+
+        begin
+          download_with_redirect(url, local_path, show_progress: show_progress)
+        rescue StandardError => e
+          raise DownloadError, "Failed to download #{file_path}: #{e.message}" if required
+
+          puts "  #{file_path} (skipped - not available)" if show_progress
+        end
+      end
+
+      def download_with_redirect(url, local_path, show_progress: true, max_redirects: 10)
+        raise DownloadError, 'Too many redirects' if max_redirects <= 0
+
+        uri = URI.parse(url)
+
+        # Handle relative URLs by using https scheme
+        unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+          # If it's a relative URL, we can't handle it
+          raise DownloadError, "Invalid URL scheme: #{url}"
+        end
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 300,
+                                            open_timeout: 30) do |http|
+          request = Net::HTTP::Get.new(uri)
+          request['User-Agent'] = "fastembed-ruby/#{VERSION}"
+
+          response = http.request(request)
+
+          case response
+          when Net::HTTPSuccess
+            File.binwrite(local_path, response.body)
+          when Net::HTTPRedirection
+            new_url = response['location']
+            # Handle relative redirects
+            new_url = "#{uri.scheme}://#{uri.host}#{new_url}" if new_url.start_with?('/')
+            download_with_redirect(new_url, local_path, show_progress: show_progress, max_redirects: max_redirects - 1)
+          else
+            raise DownloadError, "HTTP #{response.code}: #{response.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fastembed/onnx_embedding_model.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'onnxruntime'
+require 'tokenizers'
+
+module Fastembed
+  # ONNX-based embedding model wrapper
+  class OnnxEmbeddingModel
+    attr_reader :model_info, :model_dir
+
+    def initialize(model_info, model_dir, threads: nil, providers: nil)
+      @model_info = model_info
+      @model_dir = model_dir
+      @threads = threads
+      @providers = providers
+
+      load_model
+      load_tokenizer
+    end
+
+    # Embed a batch of texts
+    def embed(texts)
+      # Tokenize
+      encoded = tokenize(texts)
+
+      # Run inference
+      outputs = run_inference(encoded)
+
+      # Apply pooling and normalization
+      Pooling.apply(
+        model_info.pooling,
+        outputs,
+        encoded[:attention_mask],
+        should_normalize: model_info.normalize
+      )
+    end
+
+    private
+
+    def load_model
+      model_path = File.join(model_dir, model_info.model_file)
+      raise Error, "Model file not found: #{model_path}" unless File.exist?(model_path)
+
+      session_options = {}
+      session_options[:inter_op_num_threads] = @threads if @threads
+      session_options[:intra_op_num_threads] = @threads if @threads
+      session_options[:providers] = @providers if @providers
+
+      @session = OnnxRuntime::InferenceSession.new(model_path, **session_options)
+    end
+
+    def load_tokenizer
+      tokenizer_path = File.join(model_dir, model_info.tokenizer_file)
+      raise Error, "Tokenizer file not found: #{tokenizer_path}" unless File.exist?(tokenizer_path)
+
+      @tokenizer = Tokenizers.from_file(tokenizer_path)
+
+      # Configure tokenizer for batch encoding
+      @tokenizer.enable_padding(pad_id: 0, pad_token: '[PAD]')
+      @tokenizer.enable_truncation(512)
+    end
+
+    def tokenize(texts)
+      texts = [texts] if texts.is_a?(String)
+
+      # Batch encode
+      encodings = @tokenizer.encode_batch(texts)
+
+      # Convert to format expected by ONNX model
+      {
+        input_ids: encodings.map(&:ids),
+        attention_mask: encodings.map(&:attention_mask),
+        token_type_ids: encodings.map { |e| e.type_ids || Array.new(e.ids.length, 0) }
+      }
+    end
+
+    def run_inference(encoded)
+      # Prepare inputs
+      inputs = {
+        'input_ids' => encoded[:input_ids],
+        'attention_mask' => encoded[:attention_mask]
+      }
+
+      # Some models require token_type_ids
+      inputs['token_type_ids'] = encoded[:token_type_ids] if input_names.include?('token_type_ids')
+
+      # Run model
+      outputs = @session.run(nil, inputs)
+
+      # Get the last hidden state (usually first output)
+      # Output shape: [batch_size, seq_len, hidden_size]
+      extract_embeddings(outputs)
+    end
+
+    def input_names
+      @input_names ||= @session.inputs.map { |i| i[:name] }
+    end
+
+    def output_names
+      @output_names ||= @session.outputs.map { |o| o[:name] }
+    end
+
+    def extract_embeddings(outputs)
+      # ONNX models typically output as a hash or the first output
+      # The key is usually "last_hidden_state" or similar
+      if outputs.is_a?(Hash)
+        # Try common output names
+        %w[last_hidden_state token_embeddings].each do |key|
+          return outputs[key] if outputs.key?(key)
+        end
+        # Fall back to first output
+        outputs.values.first
+      else
+        outputs.first
+      end
+    end
+  end
+end

data/lib/fastembed/pooling.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Fastembed
+  # Pooling strategies for transformer outputs
+  module Pooling
+    class << self
+      # Mean pooling - averages all token embeddings weighted by attention mask
+      def mean_pooling(token_embeddings, attention_mask)
+        # token_embeddings: [batch_size, seq_len, hidden_size]
+        # attention_mask: [batch_size, seq_len]
+
+        batch_size = token_embeddings.length
+        hidden_size = token_embeddings[0][0].length
+
+        batch_size.times.map do |batch_idx|
+          embeddings = token_embeddings[batch_idx]
+          mask = attention_mask[batch_idx]
+          seq_len = embeddings.length
+
+          # Sum embeddings weighted by attention mask
+          summed = Array.new(hidden_size, 0.0)
+          mask_sum = 0.0
+
+          seq_len.times do |seq_idx|
+            weight = mask[seq_idx].to_f
+            mask_sum += weight
+            next if weight.zero?
+
+            hidden_size.times do |hidden_idx|
+              summed[hidden_idx] += embeddings[seq_idx][hidden_idx] * weight
+            end
+          end
+
+          # Avoid division by zero
+          mask_sum = 1.0 if mask_sum.zero?
+
+          # Divide by sum of mask to get mean
+          summed.map { |v| v / mask_sum }
+        end
+      end
+
+      # CLS pooling - uses the [CLS] token embedding (first token)
+      def cls_pooling(token_embeddings, _attention_mask)
+        token_embeddings.map { |batch| batch[0] }
+      end
+
+      # L2 normalize vectors
+      def normalize(vectors)
+        vectors.map do |vector|
+          norm = Math.sqrt(vector.sum { |v| v * v })
+          norm = 1.0 if norm.zero?
+          vector.map { |v| v / norm }
+        end
+      end
+
+      # Apply pooling based on strategy
+      def apply(strategy, token_embeddings, attention_mask, should_normalize: true)
+        pooled = case strategy
+                 when :mean
+                   mean_pooling(token_embeddings, attention_mask)
+                 when :cls
+                   cls_pooling(token_embeddings, attention_mask)
+                 else
+                   raise ArgumentError, "Unknown pooling strategy: #{strategy}"
+                 end
+
+        should_normalize ? normalize(pooled) : pooled
+      end
+    end
+  end
+end

data/lib/fastembed/text_embedding.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Fastembed
+  # Main class for generating text embeddings
+  #
+  # @example Basic usage
+  #   embedding = Fastembed::TextEmbedding.new
+  #   vectors = embedding.embed(["Hello world", "Another text"]).to_a
+  #
+  # @example Custom model
+  #   embedding = Fastembed::TextEmbedding.new(model_name: "BAAI/bge-base-en-v1.5")
+  #
+  # @example Lazy iteration for large datasets
+  #   embedding.embed(documents).each do |vector|
+  #     # Process each vector
+  #   end
+  #
+  class TextEmbedding
+    attr_reader :model_name, :model_info, :dim
+
+    # Initialize a text embedding model
+    #
+    # @param model_name [String] Name of the model to use (default: "BAAI/bge-small-en-v1.5")
+    # @param cache_dir [String, nil] Custom cache directory for models
+    # @param threads [Integer, nil] Number of threads for ONNX Runtime
+    # @param providers [Array<String>, nil] ONNX execution providers (e.g., ["CoreMLExecutionProvider"])
+    # @param show_progress [Boolean] Whether to show download progress
+    def initialize(
+      model_name: DEFAULT_MODEL,
+      cache_dir: nil,
+      threads: nil,
+      providers: nil,
+      show_progress: true
+    )
+      @model_name = model_name
+      @threads = threads
+      @providers = providers
+      @show_progress = show_progress
+
+      # Set custom cache directory if provided
+      ModelManagement.cache_dir = cache_dir if cache_dir
+
+      # Resolve model info
+      @model_info = ModelManagement.resolve_model_info(model_name)
+      @dim = @model_info.dim
+
+      # Download and load model
+      @model_dir = ModelManagement.retrieve_model(model_name, show_progress: show_progress)
+      @model = OnnxEmbeddingModel.new(@model_info, @model_dir, threads: threads, providers: providers)
+    end
+
+    # Generate embeddings for documents
+    #
+    # @param documents [Array<String>, String] Text document(s) to embed
+    # @param batch_size [Integer] Number of documents to process at once
+    # @return [Enumerator] Lazy enumerator yielding embedding vectors
+    # @raise [ArgumentError] If documents is nil or contains nil values
+    #
+    # @example
+    #   vectors = embedding.embed(["Hello", "World"]).to_a
+    #   # => [[0.1, 0.2, ...], [0.3, 0.4, ...]]
+    def embed(documents, batch_size: 256)
+      raise ArgumentError, 'documents cannot be nil' if documents.nil?
+
+      documents = [documents] if documents.is_a?(String)
+      return Enumerator.new { |_| } if documents.empty?
+
+      # Validate all documents
+      documents.each_with_index do |doc, i|
+        raise ArgumentError, "document at index #{i} cannot be nil" if doc.nil?
+      end
+
+      Enumerator.new do |yielder|
+        documents.each_slice(batch_size) do |batch|
+          embeddings = @model.embed(batch)
+          embeddings.each { |embedding| yielder << embedding }
+        end
+      end
+    end
+
+    # Generate embeddings for query texts (with "query: " prefix for retrieval models)
+    #
+    # @param queries [Array<String>, String] Query text(s) to embed
+    # @param batch_size [Integer] Number of queries to process at once
+    # @return [Enumerator] Lazy enumerator yielding embedding vectors
+    def query_embed(queries, batch_size: 256)
+      queries = [queries] if queries.is_a?(String)
+      prefixed = queries.map { |q| "query: #{q}" }
+      embed(prefixed, batch_size: batch_size)
+    end
+
+    # Generate embeddings for passage texts (with "passage: " prefix for retrieval models)
+    #
+    # @param passages [Array<String>, String] Passage text(s) to embed
+    # @param batch_size [Integer] Number of passages to process at once
+    # @return [Enumerator] Lazy enumerator yielding embedding vectors
+    def passage_embed(passages, batch_size: 256)
+      passages = [passages] if passages.is_a?(String)
+      prefixed = passages.map { |p| "passage: #{p}" }
+      embed(prefixed, batch_size: batch_size)
+    end
+
+    # List all supported models
+    #
+    # @return [Array<Hash>] Array of model information hashes
+    def self.list_supported_models
+      SUPPORTED_MODELS.values.map(&:to_h)
+    end
+
+    # Get information about a specific model
+    #
+    # @param model_name [String] Name of the model
+    # @return [Hash, nil] Model information or nil if not found
+    def self.get_model_info(model_name)
+      SUPPORTED_MODELS[model_name]&.to_h
+    end
+  end
+end

data/lib/fastembed/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Fastembed
+  VERSION = '1.0.0'
+end

data/lib/fastembed.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'fastembed/version'
+
+module Fastembed
+  class Error < StandardError; end
+  class DownloadError < Error; end
+end
+
+require_relative 'fastembed/model_info'
+require_relative 'fastembed/model_management'
+require_relative 'fastembed/pooling'
+require_relative 'fastembed/onnx_embedding_model'
+require_relative 'fastembed/text_embedding'

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: fastembed
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Chris Hasinski
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: onnxruntime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: tokenizers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A Ruby port of FastEmbed - fast text embeddings using ONNX Runtime
+email:
+- krzysztof.hasinski@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".mise.toml"
+- ".rspec"
+- ".rubocop.yml"
+- BENCHMARKS.md
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- fastembed.gemspec
+- lib/fastembed.rb
+- lib/fastembed/model_info.rb
+- lib/fastembed/model_management.rb
+- lib/fastembed/onnx_embedding_model.rb
+- lib/fastembed/pooling.rb
+- lib/fastembed/text_embedding.rb
+- lib/fastembed/version.rb
+homepage: https://github.com/khasinski/fastembed-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/khasinski/fastembed-rb
+  source_code_uri: https://github.com/khasinski/fastembed-rb
+  changelog_uri: https://github.com/khasinski/fastembed-rb/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Fast, lightweight text embeddings for Ruby
+test_files: []