rag_embeddings 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd1dc0ac570ef83c9c79142cb516411454137919c649ab7f446e18748f7f7717
-  data.tar.gz: d21f7e9b2eee1324b4a0f7a5d892d3f55f1767bb42a965e0828225ba823461b8
+  metadata.gz: 80367e6f32ddd36828010b2f3f53339e50b06efc6e58dc1f708e08980e774053
+  data.tar.gz: 3e9c9febe99e5ec54fb5288727749b3a5ce282061ff8bda438a256659fbcbbff
 SHA512:
-  metadata.gz: 3fd776d3ff4b3082eac778534f2fc56aa541ea048d70d69ddbfb2738da9fb252012d6d7ffa4af0f2a1fbed229ac86960ada844cd062a4c8294ecd4999b4cd0ed
-  data.tar.gz: b2682f1d217d9689a73e78fdbcfd74973de598f323dc12a35868530cb95e0833a584d29468d91c2e6e01afcf66585fe18f8388e54cee04b71b8e7dc955a10181
+  metadata.gz: 16de62dff09874f0f062699657758a58b930678bef3a58ab9c18269616e2a6b47aa9d2c85c3698de94ddefb6160adde8a29cda66dbd0e15d72ed2b7d3eb9eb7d
+  data.tar.gz: '092cc593c1957e6fca731fa41c33a6e0ccee55f2d7bb691b0f6f4b684c71e676061546f1ceeea5bb7a98f49d6466d3e9cd9e09b8ff3f1dff0022f74aeca8fabb'

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.
 
@@ -22,27 +22,35 @@
 
 ---
 
-## 🔧 Installation
+## 🌍 Real-world Use Cases
 
-Add to your Gemfile:
+- **Question Answering over Documents:** Instantly search and retrieve the most relevant document snippets from thousands of articles, FAQs, or customer support logs in your Ruby app.
+- **Semantic Search for E-commerce:** Power product search with semantic understanding, returning items similar in meaning, not just keywords.
+- **Personalized Recommendations:** Find related content (articles, products, videos) by comparing user preferences and content embeddings.
+- **Knowledge Base Augmentation:** Use with OpenAI or Ollama to enhance chatbots, letting them ground answers in your company’s internal documentation or wiki.
+- **Fast Prototyping for AI Products:** Effortlessly build MVPs for RAG-enabled chatbots, semantic search tools, and AI-driven discovery apps—all in native Ruby.
 
-```ruby
-gem "rag_embeddings"
-gem "langchainrb"
-gem "faraday"
-gem "sqlite3"
-```
+---
 
-bundle install
-rake compile
+## 👷 Requirements
 
-(Requires a working C compiler!)
+- Ruby >= 3.3
+- `langchainrb` (for embedding)
+- At the moment `ollama` is used as LLM so it must be active and working, although there are some workarounds
+- `sqlite3` (for storage)
 
-## 🏁 Running the test suite
+## 🔧 Installation
 
-To run all specs (RSpec required):
+Requires a working C compiler in order to build the native extension
+
+`gem install rag_embeddings`
+
+If you'd rather install it using bundler, add a line for it in your Gemfile (but set the require option to false, as it is a standalone tool):
+
+```ruby
+gem "rag_embeddings", require: false
+```
 
-`bundle exec rspec`
 
 ## 🧪 Practical examples
 
@@ -50,17 +58,24 @@ To run all specs (RSpec required):
 
 ```ruby
 require "rag_embeddings"
-
-text = "Hello world, this is RAG!"
-embedding = RagEmbeddings.embed(text)
+embedding = RagEmbeddings.embed("Hello world, this is RAG!")
 # 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("Hello world, this is RAG!", 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}"
 ```
 
@@ -87,30 +102,170 @@ result = db.top_k_similar("Hello!", k: 1)
 puts "Most similar text: #{result.first[1]}, score: #{result.first[2]}"
 ```
 
+### 5. Batch-index a folder of documents
+
+```ruby
+# load all .txt files
+files = Dir["./docs/*.txt"].map { |f| [File.basename(f), File.read(f)] }
+
+db = RagEmbeddings::Database.new("knowledge_base.db")
+files.each do |name, text|
+  vector = RagEmbeddings.embed(text)
+  db.insert(name, vector)
+end
+
+puts "Indexed #{files.size} documents."
+```
+
+### 6. Simple Retrieval-Augmented Generation (RAG) loop
+
+```ruby
+require "openai"        # or your favorite LLM client
+
+# 1) build or open your vector store
+db = RagEmbeddings::Database.new("knowledge_base.db")
+
+# 2) embed your user question
+client      = OpenAI::Client.new(api_key: ENV.fetch("OPENAI_API_KEY"))
+q_embedding = client.embeddings(
+  parameters: {
+    model: "text-embedding-ada-002",
+    input: "What are the benefits of retrieval-augmented generation?"
+  }
+).dig("data", 0, "embedding")
+
+# 3) retrieve top-3 relevant passages
+results = db.top_k_similar(q_embedding, k: 3)
+
+# 4) build a prompt for your LLM
+context = results.map { |id, text, score| text }.join("\n\n---\n\n")
+prompt  = <<~PROMPT
+  You are an expert.  
+  Use the following context to answer the question:
+
+  CONTEXT:
+  #{context}
+
+  QUESTION:
+  What are the benefits of retrieval-augmented generation?
+PROMPT
+
+# 5) call the LLM for final answer
+response = client.chat(
+  parameters: {
+    model: "gpt-4o",
+    messages: [{ role: "user", content: prompt }]
+  }
+)
+puts response.dig("choices", 0, "message", "content")
+
+```
+
+### 7. In-memory store for fast prototyping
+
+```ruby
+# use SQLite :memory: for ephemeral experiments
+db = RagEmbeddings::Database.new(":memory:")
+
+# insert & search exactly as with a file-backed DB
+db.insert("Quick test", RagEmbeddings.embed("Quick test"))
+db.top_k_similar("Test", k: 1)
+```
+
+---
+
 ## 🏗️ How it works
 
-- Embeddings are managed as dynamic C objects for efficiency (variable dimension).
-- The only correct way to construct an embedding object is using .from_array.
-- Langchainrb integration lets you easily change the embedding provider (Ollama, OpenAI, etc).
-- Storage uses local SQLite with embeddings as BLOB, for maximum portability and simplicity.
+**rag_embeddings** combines the simplicity of Ruby with the performance of C to deliver fast vector operations for RAG applications.
+
+### Architecture Overview
+
+The library uses a **hybrid memory-storage approach**:
+
+1. **In-Memory Processing**: All vector operations (cosine similarity calculations, embedding manipulations) happen entirely in memory using optimized C code
+2. **Persistent Storage**: SQLite serves as a simple, portable storage layer for embeddings and associated text
+3. **Dynamic C Objects**: Embeddings are managed as native C structures with automatic memory management
+
+### Key Components
+
+**C Extension (`embedding.c`)**
+- Handles all computationally intensive operations
+- Manages dynamic vector dimensions (adapts to any LLM output size)
+- Performs cosine similarity calculations with optimized algorithms
+- Ensures memory-safe operations with proper garbage collection integration
+
+**Ruby Interface**
+- Provides an intuitive API for vector operations
+- Integrates seamlessly with LLM providers via langchainrb
+- Handles database operations and query orchestration
+
+**SQLite Storage**
+- Stores embeddings as BLOBs alongside their associated text
+- Provides persistent storage without requiring external databases
+- Supports both file-based and in-memory (`:memory:`) databases
+- Enables portable, self-contained applications
+
+### Processing Flow
+
+1. **Text → Embedding**: Generate vectors using your preferred LLM (Ollama, OpenAI, etc.)
+2. **Memory Allocation**: Create C embedding objects with `Embedding.from_array()`
+3. **Storage**: Persist embeddings and text to SQLite for later retrieval
+4. **Query Processing**:
+    - Load query embedding into memory
+    - Compare against stored embeddings using fast C-based cosine similarity
+    - Return top-K most similar results ranked by similarity score
+
+### Why This Design?
+
+**Performance**: Critical operations run in optimized C code, delivering significant speed improvements over pure Ruby implementations.
+
+**Memory Efficiency**: While embeddings are stored in SQLite, all vector computations happen in memory, avoiding I/O bottlenecks during similarity calculations.
+
+**Simplicity**: SQLite eliminates the need for complex vector database setups while maintaining good performance for moderate-scale applications.
+
+**Portability**: The entire knowledge base fits in a single SQLite file, making deployment and backup trivial.
+
+### Performance Characteristics
+
+- **Embedding creation**: ~82ms for 10,000 operations
+- **Cosine similarity**: ~107ms for 10,000 calculations
+- **Memory usage**: ~34MB for 10,000 embeddings
+- **Scalability**: Suitable for thousands to tens of thousands of vectors
+
+For applications requiring millions of vectors, consider specialized vector databases (Faiss, sqlite-vss) while using this library for prototyping and smaller-scale production use.
 
 ## 🎛️ Customization
 
 - Embedding provider: switch model/provider in engine.rb (Ollama, OpenAI, etc)
 - Database: set the SQLite file path as desired
 
-## 👷 Requirements
+If you need to customize the c part (`ext/rag_embeddings/embedding.c`), recompile it with:
 
-- Ruby >= 3.3
-- langchainrb (for embedding)
-- sqlite3 (for storage)
-- A working C compiler
+`rake compile`
+
+---
 
-## 📑 Notes
+## 🏁 Running the test suite
 
-- Always create embeddings with .from_array
-- All memory management is idiomatic and safe
-- For millions of vectors, consider vector DBs (Faiss, sqlite-vss, etc.)
+To run all specs (RSpec required):
+
+`bundle exec rspec`
+
+## ⚡️ Performance
+
+`bundle exec rspec spec/performance_spec.rb`
+
+```bash
+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
+```
 
 ## 📬 Contact & Issues
 Open an issue or contact the maintainer for questions, suggestions, or bugs.

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.1"
 end

data/lib/rag_embeddings.rb

@@ -1,4 +1,8 @@
 require_relative "rag_embeddings/version"
 require_relative "rag_embeddings/engine"
 require_relative "rag_embeddings/database"
-require_relative "../ext/rag_embeddings/embedding" # Loads the compiled C extension
+
+# Loads the compiled C extension
+require "rag_embeddings/embedding"
+
+require "faraday"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rag_embeddings
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Marco Mastrodonato
@@ -77,6 +77,7 @@ metadata:
 rdoc_options: []
 require_paths:
 - lib
+- ext
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="