rag_embeddings 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd1dc0ac570ef83c9c79142cb516411454137919c649ab7f446e18748f7f7717
-  data.tar.gz: d21f7e9b2eee1324b4a0f7a5d892d3f55f1767bb42a965e0828225ba823461b8
+  metadata.gz: 3bebe9dc8527ed47e0d7b48534911e97ee7549bb73763c1dd59db063e41558c8
+  data.tar.gz: fdb272ee4dd12f52f33fb2cd33b9ff22f5207911c68c09b976af59346f666039
 SHA512:
-  metadata.gz: 3fd776d3ff4b3082eac778534f2fc56aa541ea048d70d69ddbfb2738da9fb252012d6d7ffa4af0f2a1fbed229ac86960ada844cd062a4c8294ecd4999b4cd0ed
-  data.tar.gz: b2682f1d217d9689a73e78fdbcfd74973de598f323dc12a35868530cb95e0833a584d29468d91c2e6e01afcf66585fe18f8388e54cee04b71b8e7dc955a10181
+  metadata.gz: a106f044b23d4438110516ee57dc6079b177861c8e09da4eeffc7e842c3aa9d506b96b6141d6e033a74de1ca61ecf1e53490682f906e14915d76fd5fe4d81103
+  data.tar.gz: 6be68129ca5338a99f3d55816cbb06785cff2530e39784d5202c4602bb73aec783e5180b7cf09a1f1ef962bb5d6a2070af3db080f677369b49a5463d7c466be3

data/README.md

@@ -1,6 +1,6 @@
 # 💎 Rag Embeddings  
 
-[![Gem Version](https://badge.fury.io/rb/rag_embeddings.svg)](https://badge.fury.io/rb/rag_embeddings)
+[![Gem Version](https://badge.fury.io/rb/rag_embeddings.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/rag_embeddings)
 
 **rag_embeddings** is a native Ruby library for efficient storage and comparison of AI-generated embedding vectors (float arrays) using high-performance C extensions. It is designed for seamless integration with external LLMs (Ollama, OpenAI, Mistral, etc) and works perfectly for RAG (Retrieval-Augmented Generation) applications.
 
@@ -49,18 +49,25 @@ To run all specs (RSpec required):
 ### 1. Generate an embedding from text
 
 ```ruby
-require "rag_embeddings"
-
 text = "Hello world, this is RAG!"
 embedding = RagEmbeddings.embed(text)
 # embedding is a float array
 ```
 
+The default model is llama3.2 but you can set another one (reload the console as the llm is memoized):
+
+```ruby
+embedding = RagEmbeddings.embed(text, model: 'qwen3:0.6b')
+````
+
 ### 2. Create a C embedding object
 
 ```ruby
 c_embedding = RagEmbeddings::Embedding.from_array(embedding)
 puts "Dimension: #{c_embedding.dim}"
+# Dimension: 1024 # qwen3:0.6b
+# Dimension: 3072 # llama3.2
+
 puts "Ruby array: #{c_embedding.to_a.inspect}"
 ```
 
@@ -99,6 +106,22 @@ puts "Most similar text: #{result.first[1]}, score: #{result.first[2]}"
 - Embedding provider: switch model/provider in engine.rb (Ollama, OpenAI, etc)
 - Database: set the SQLite file path as desired
 
+## 🔢 Embeddings dimension
+
+The size of embeddings is dynamic and fits with what the LLM provides.
+
+## ⚡️ Performance
+
+Embedding creation (10000 times): 82 ms
+Cosine similarity (10000 times): 107 ms
+RSS: 186.7 MB
+.
+Memory usage delta: 33.97 MB for 10000 embeddings
+.
+
+Finished in 0.42577 seconds (files took 0.06832 seconds to load)
+2 examples, 0 failures
+
 ## 👷 Requirements
 
 - Ruby >= 3.3

data/ext/rag_embeddings/embedding.c

@@ -12,7 +12,9 @@ typedef struct {
 
 // Callback for freeing memory when Ruby's GC collects our object
 static void embedding_free(void *ptr) {
-  xfree(ptr);         // Ruby's memory free function
+  if (ptr) {
+    xfree(ptr);       // Ruby's memory free function (with null check)
+  }
 }
 
 // Callback to report memory usage to Ruby's GC
@@ -27,22 +29,46 @@ static const rb_data_type_t embedding_type = {
   "RagEmbeddings/Embedding",               // Type name
   {0, embedding_free, embedding_memsize,}, // Functions: mark, free, size
   0, 0,                                    // Parent type, data
-  RUBY_TYPED_FREE_IMMEDIATELY              // Flags
+  RUBY_TYPED_FREE_IMMEDIATELY              // Flags for immediate cleanup
 };
 
 // Class method: RagEmbeddings::Embedding.from_array([1.0, 2.0, ...])
 // Creates a new embedding from a Ruby array
 static VALUE embedding_from_array(VALUE klass, VALUE rb_array) {
   Check_Type(rb_array, T_ARRAY);           // Ensure argument is a Ruby array
-  uint16_t dim = (uint16_t)RARRAY_LEN(rb_array);
+
+  long array_len = RARRAY_LEN(rb_array);
+
+  // Validate array length fits in uint16_t (max 65535 dimensions)
+  if (array_len > UINT16_MAX) {
+    rb_raise(rb_eArgError, "Array too large: maximum %d dimensions allowed", UINT16_MAX);
+  }
+
+  // Prevent zero-length embeddings
+  if (array_len == 0) {
+    rb_raise(rb_eArgError, "Cannot create embedding from empty array");
+  }
+
+  uint16_t dim = (uint16_t)array_len;
 
   // Allocate memory for struct + array of floats
   embedding_t *ptr = xmalloc(sizeof(embedding_t) + dim * sizeof(float));
   ptr->dim = dim;
 
   // Copy values from Ruby array to our C array
-  for (int i = 0; i < dim; ++i)
-    ptr->values[i] = (float)NUM2DBL(rb_ary_entry(rb_array, i));
+  // Using RARRAY_CONST_PTR for better performance when available
+  const VALUE *array_ptr = RARRAY_CONST_PTR(rb_array);
+  for (uint16_t i = 0; i < dim; ++i) {
+    VALUE val = array_ptr[i];
+
+    // Ensure the value is numeric
+    if (!RB_FLOAT_TYPE_P(val) && !RB_INTEGER_TYPE_P(val)) {
+      xfree(ptr);  // Clean up allocated memory before raising exception
+      rb_raise(rb_eTypeError, "Array element at index %d is not numeric", i);
+    }
+
+    ptr->values[i] = (float)NUM2DBL(val);
+  }
 
   // Wrap our C struct in a Ruby object
   VALUE obj = TypedData_Wrap_Struct(klass, &embedding_type, ptr);
@@ -65,17 +91,19 @@ static VALUE embedding_to_a(VALUE self) {
   TypedData_Get_Struct(self, embedding_t, &embedding_type, ptr);
 
   // Create a new Ruby array with pre-allocated capacity
-  VALUE arr = rb_ary_new2(ptr->dim);
+  VALUE arr = rb_ary_new_capa(ptr->dim);
 
   // Copy each float value to the Ruby array
-  for (int i = 0; i < ptr->dim; ++i)
-    rb_ary_push(arr, DBL2NUM(ptr->values[i]));
+  // Using rb_ary_store for better performance than rb_ary_push
+  for (uint16_t i = 0; i < ptr->dim; ++i) {
+    rb_ary_store(arr, i, DBL2NUM(ptr->values[i]));
+  }
 
   return arr;
 }
 
 // Instance method: embedding.cosine_similarity(other_embedding)
-// Calculate cosine similarity between two embeddings
+// Calculate cosine similarity between two embeddings using optimized algorithm
 static VALUE embedding_cosine_similarity(VALUE self, VALUE other) {
   embedding_t *a, *b;
   // Get C structs for both embeddings
@@ -83,21 +111,90 @@ static VALUE embedding_cosine_similarity(VALUE self, VALUE other) {
   TypedData_Get_Struct(other, embedding_t, &embedding_type, b);
 
   // Ensure dimensions match
-  if (a->dim != b->dim)
-    rb_raise(rb_eArgError, "Dimension mismatch");
+  if (a->dim != b->dim) {
+    rb_raise(rb_eArgError, "Dimension mismatch: %d vs %d", a->dim, b->dim);
+  }
 
-  float dot = 0.0f, norm_a = 0.0f, norm_b = 0.0f;
+  // Use double precision for intermediate calculations to reduce accumulation errors
+  double dot = 0.0, norm_a = 0.0, norm_b = 0.0;
 
-  // Calculate dot product and vector magnitudes
-  for (int i = 0; i < a->dim; ++i) {
-    dot += a->values[i] * b->values[i];      // Dot product
-    norm_a += a->values[i] * a->values[i];   // Square of magnitude for vector a
-    norm_b += b->values[i] * b->values[i];   // Square of magnitude for vector b
+  // Calculate dot product and vector magnitudes in a single loop
+  // This is more cache-friendly than separate loops
+  const float *va = a->values;
+  const float *vb = b->values;
+
+  for (uint16_t i = 0; i < a->dim; ++i) {
+    float ai = va[i];
+    float bi = vb[i];
+
+    dot += (double)ai * bi;          // Dot product
+    norm_a += (double)ai * ai;       // Square of magnitude for vector a
+    norm_b += (double)bi * bi;       // Square of magnitude for vector b
+  }
+
+  // Check for zero vectors to avoid division by zero
+  if (norm_a == 0.0 || norm_b == 0.0) {
+    return DBL2NUM(0.0);  // Return 0 similarity for zero vectors
   }
 
   // Apply cosine similarity formula: dot(a,b)/(|a|*|b|)
-  // Small epsilon (1e-8) added to prevent division by zero
-  return DBL2NUM(dot / (sqrt(norm_a) * sqrt(norm_b) + 1e-8));
+  // Using sqrt for better numerical stability
+  double magnitude_product = sqrt(norm_a * norm_b);
+  double similarity = dot / magnitude_product;
+
+  // Clamp result to [-1, 1] to handle floating point precision errors
+  if (similarity > 1.0) similarity = 1.0;
+  if (similarity < -1.0) similarity = -1.0;
+
+  return DBL2NUM(similarity);
+}
+
+// Instance method: embedding.magnitude
+// Calculate the magnitude (L2 norm) of the embedding vector
+static VALUE embedding_magnitude(VALUE self) {
+  embedding_t *ptr;
+  TypedData_Get_Struct(self, embedding_t, &embedding_type, ptr);
+
+  double sum_squares = 0.0;
+  const float *values = ptr->values;
+
+  for (uint16_t i = 0; i < ptr->dim; ++i) {
+    float val = values[i];
+    sum_squares += (double)val * val;
+  }
+
+  return DBL2NUM(sqrt(sum_squares));
+}
+
+// Instance method: embedding.normalize!
+// Normalize the embedding vector in-place (destructive operation)
+static VALUE embedding_normalize_bang(VALUE self) {
+  embedding_t *ptr;
+  TypedData_Get_Struct(self, embedding_t, &embedding_type, ptr);
+
+  // Calculate magnitude
+  double sum_squares = 0.0;
+  float *values = ptr->values;
+
+  for (uint16_t i = 0; i < ptr->dim; ++i) {
+    float val = values[i];
+    sum_squares += (double)val * val;
+  }
+
+  double magnitude = sqrt(sum_squares);
+
+  // Avoid division by zero
+  if (magnitude == 0.0) {
+    rb_raise(rb_eZeroDivError, "Cannot normalize zero vector");
+  }
+
+  // Normalize each component
+  float inv_magnitude = (float)(1.0 / magnitude);
+  for (uint16_t i = 0; i < ptr->dim; ++i) {
+    values[i] *= inv_magnitude;
+  }
+
+  return self;  // Return self for method chaining
 }
 
 // Ruby extension initialization function
@@ -107,6 +204,10 @@ void Init_embedding(void) {
   VALUE mRag = rb_define_module("RagEmbeddings");
   VALUE cEmbedding = rb_define_class_under(mRag, "Embedding", rb_cObject);
 
+  // IMPORTANT: Undefine the default allocator to prevent the warning
+  // This is necessary when using TypedData_Wrap_Struct
+  rb_undef_alloc_func(cEmbedding);
+
   // Register class methods
   rb_define_singleton_method(cEmbedding, "from_array", embedding_from_array, 1);
 
@@ -114,4 +215,6 @@ void Init_embedding(void) {
   rb_define_method(cEmbedding, "dim", embedding_dim, 0);
   rb_define_method(cEmbedding, "to_a", embedding_to_a, 0);
   rb_define_method(cEmbedding, "cosine_similarity", embedding_cosine_similarity, 1);
+  rb_define_method(cEmbedding, "magnitude", embedding_magnitude, 0);
+  rb_define_method(cEmbedding, "normalize!", embedding_normalize_bang, 0);
 }

data/lib/rag_embeddings/engine.rb

@@ -1,13 +1,20 @@
 require "langchainrb"
 
 module RagEmbeddings
-  MODEL = "gemma3".freeze
+  DEFAULT_MODEL = "llama3.2".freeze
 
-  def self.llm
-    @llm ||= Langchain::LLM::Ollama.new(url: "http://localhost:11434", default_options: { temperature: 0.1, model: MODEL })
+  def self.llm(model: DEFAULT_MODEL)
+    @llm ||= Langchain::LLM::Ollama.new(url: "http://localhost:11434",
+                                        default_options: {
+                                          temperature: 0.1,
+                                          chat_model: model,
+                                          completion_model: model,
+                                          embedding_model: model,
+                                        }
+    )
   end
 
-  def self.embed(text)
-    llm.embed(text: text).embedding
+  def self.embed(text, model: DEFAULT_MODEL)
+    llm(model:).embed(text:).embedding
   end
 end

data/lib/rag_embeddings/version.rb

@@ -1,3 +1,3 @@
 module RagEmbeddings
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rag_embeddings
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Marco Mastrodonato