zvec-ruby 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ba14d14fe74cef98438fa55ee3852580473329b4c2d06abce25cdbb67ce5f7a
-  data.tar.gz: 3c5ef9a204dc0f8b9f787559009b00b6131d30c62e9981b829a67f1a01003364
+  metadata.gz: 968f5cc5abadbda9360603f7fdc1c618b036171cb5f58c0a61e69c22cb511ea0
+  data.tar.gz: 9e1113dde47dbcba7d8b9fbdfb247b4f9cd68d6a14e77974541cb660ee45a63e
 SHA512:
-  metadata.gz: 3e90824d6ffb928da3b5f6ec7327c01c76101282c10a25c56d501637e4597e4480fe50b609e3b415d3e56d43c0414252a09ecc519941556f6362a7e0aff3d3c8
-  data.tar.gz: 7a03160f30fd6ec83511ebeb61ffaeddeea69da3c6b64e1168f0c0a802101e7d34a3303f6071f5085037aec579fe6a833a3526f0cc7ef693b39acfc47a787fe3
+  metadata.gz: f722f02332f1f4c95b64e307ca021488c770070953912d077781b9338a41ff124c11e7645b7e50245afcb37b3d289b1c5ea67aac97e65b406a0d893cb03239f8
+  data.tar.gz: 555229b48ff063d7f59e1b97de38ad8f06b87befd425d6b05222bebccbb8374394d8b58c275f9db18266a4c5c6cfae860029890c30f194572adb1e0c18be8dd7

data/Rakefile

@@ -40,6 +40,9 @@ Rake::TestTask.new(:test_pure) do |t|
     "test/test_schema.rb",
     "test/test_doc.rb",
     "test/test_query.rb",
+    "test/test_type_detection.rb",
+    "test/test_validation.rb",
+    "test/test_edge_cases.rb",
     "test/test_active_record.rb",
   ]
   t.warning = true

data/lib/zvec/active_record.rb

@@ -5,7 +5,10 @@ module Zvec
   module ActiveRecord
     # Rails concern that adds vector search capabilities to ActiveRecord models.
     #
-    # Usage:
+    # When included in a model, call +vectorize+ to configure which text field
+    # to embed, the vector dimension, and the embedding function.
+    #
+    # @example Basic usage
     #   class Article < ApplicationRecord
     #     include Zvec::ActiveRecord::Vectorize
     #
@@ -15,13 +18,30 @@ module Zvec
     #       embed_with: ->(text) { OpenAI.embed(text) }
     #   end
     #
-    #   Article.vector_search([0.1, 0.2, ...], top_k: 5)
-    #   article.update_embedding!
+    # @example Searching
+    #   Article.vector_search("Ruby programming", top_k: 5)
+    #   Article.vector_search([0.1, 0.2, ...], top_k: 5, embed: false)
+    #
+    # @example Instance methods
+    #   article.zvec_update_embedding!   # re-embed and store
+    #   article.zvec_remove_embedding!   # remove from vector store
+    #   article.zvec_embedding           # fetch stored embedding doc
     #
     module Vectorize
       extend ActiveSupport::Concern
 
       class_methods do
+        # Configure vector search for this model.
+        #
+        # @param field [String, Symbol] the text field to embed
+        # @param dimensions [Integer] the vector dimension
+        # @param prefix [String, nil] collection prefix (defaults to table_name)
+        # @param embed_with [Proc, nil] a callable that takes text and returns
+        #   a vector Array (e.g., +-> (text) { OpenAI.embed(text) }+)
+        # @param metric [Symbol] similarity metric (+:cosine+, +:l2+, or +:ip+)
+        # @param zvec_path [String, nil] path for the zvec collection
+        #   (defaults to +tmp/zvec/<prefix>+)
+        # @return [void]
         def vectorize(field, dimensions:, prefix: nil, embed_with: nil,
                       metric: :cosine, zvec_path: nil)
           prefix ||= table_name
@@ -46,7 +66,12 @@ module Zvec
         end
       end
 
+      # Instance methods mixed into the model.
       module InstanceMethods
+        # Re-embed the configured text field and store the embedding.
+        #
+        # @return [void]
+        # @raise [Zvec::Error] if no +embed_with+ function is configured
         def zvec_update_embedding!
           cfg = self.class.zvec_config
           text = send(cfg[:field])
@@ -61,19 +86,29 @@ module Zvec
           store.flush
         end
 
+        # Remove this record's embedding from the vector store.
+        #
+        # @return [void]
         def zvec_remove_embedding!
           self.class.zvec_store.delete(id.to_s)
         rescue
           # Silently ignore if document doesn't exist
         end
 
+        # Fetch this record's stored embedding document.
+        #
+        # @return [Zvec::Doc, nil] the stored document, or nil if not found
         def zvec_embedding
           result = self.class.zvec_store.fetch(id.to_s)
           result[id.to_s]
         end
       end
 
+      # Class methods mixed into the model.
       module SearchMethods
+        # Access the shared {Zvec::RubyLLM::Store} instance for this model.
+        #
+        # @return [Zvec::RubyLLM::Store]
         def zvec_store
           @zvec_store ||= begin
             cfg = zvec_config
@@ -85,6 +120,18 @@ module Zvec
           end
         end
 
+        # Search for records by vector similarity.
+        #
+        # When +query+ is a String and +embed+ is true, the configured
+        # +embed_with+ function is called to convert it to a vector first.
+        #
+        # @param query [Array<Numeric>, String] query vector or text to embed
+        # @param top_k [Integer] maximum number of results (default: 10)
+        # @param embed [Boolean] whether to embed a String query (default: true)
+        # @return [Array<ActiveRecord::Base>] matching records, each with a
+        #   +zvec_score+ singleton method returning the similarity score
+        # @raise [ArgumentError] if query is a String but no +embed_with+ is
+        #   configured
         def vector_search(query, top_k: 10, embed: true)
           cfg = zvec_config
 

data/lib/zvec/collection.rb

@@ -1,17 +1,57 @@
 require "monitor"
 
 module Zvec
+  # A vector collection backed by the zvec C++ engine. Provides CRUD
+  # operations, vector similarity search, and index management.
+  #
+  # Collections must be explicitly closed via {#close} before they can be
+  # reopened from the same path. Use the +closed?+ method to check state.
+  #
+  # All mutating operations are thread-safe (protected by a Monitor).
+  #
+  # @example Create, populate, search, and close
+  #   schema = Zvec::Schema.new("articles") do
+  #     string "title"
+  #     vector "embedding", dimension: 4,
+  #            index: Zvec::Ext::HnswIndexParams.new(Zvec::COSINE)
+  #   end
+  #
+  #   col = Zvec::Collection.create_and_open("/tmp/articles", schema)
+  #   col.add(pk: "1", title: "Hello", embedding: [0.1, 0.2, 0.3, 0.4])
+  #   results = col.search([0.1, 0.2, 0.3, 0.4], top_k: 5)
+  #   col.close
+  #
+  # @example Reopen an existing collection
+  #   col = Zvec::Collection.open("/tmp/articles")
+  #   puts col.doc_count
+  #   col.close
+  #
   class Collection
+    # @return [Zvec::Schema, nil] the schema, if provided at creation time
     attr_reader :schema
 
+    # @param ext_collection [Ext::Collection] the underlying C++ collection
+    # @param schema [Zvec::Schema, nil] optional schema for type-aware access
+    # @param name [String, nil] optional collection name
     def initialize(ext_collection, schema: nil, name: nil)
       @ext = ext_collection
       @schema = schema
       @name = name
       @monitor = Monitor.new
+      @closed = false
     end
 
-    # Create a new collection and open it.
+    # Create a new collection on disk and open it.
+    #
+    # @param path [String] directory path for the collection data
+    # @param schema [Zvec::Schema] the collection schema
+    # @param read_only [Boolean] open in read-only mode
+    # @param enable_mmap [Boolean] use memory-mapped I/O (default: true)
+    # @return [Zvec::Collection]
+    # @raise [ArgumentError] if path is blank or schema is not a Zvec::Schema
+    #
+    # @example
+    #   col = Zvec::Collection.create_and_open("/tmp/my_col", schema)
     def self.create_and_open(path, schema, read_only: false, enable_mmap: true)
       validate_path!(path)
       raise ArgumentError, "schema must be a Zvec::Schema" unless schema.is_a?(Schema)
@@ -23,7 +63,16 @@ module Zvec
       new(ext, schema: schema, name: schema.name)
     end
 
-    # Open an existing collection.
+    # Open an existing collection from disk.
+    #
+    # @param path [String] directory path of an existing collection
+    # @param read_only [Boolean] open in read-only mode
+    # @param enable_mmap [Boolean] use memory-mapped I/O (default: true)
+    # @return [Zvec::Collection]
+    # @raise [ArgumentError] if path is blank
+    #
+    # @example
+    #   col = Zvec::Collection.open("/tmp/my_col", read_only: true)
     def self.open(path, read_only: false, enable_mmap: true)
       validate_path!(path)
 
@@ -34,25 +83,74 @@ module Zvec
       new(ext)
     end
 
+    # @return [String, nil] the collection name (from schema or explicit)
     def collection_name
       @name || (@schema ? @schema.name : nil)
     end
 
+    # @return [String] the on-disk path of the collection
     def path
       @ext.path
     end
 
+    # @return [Ext::CollectionStats] collection statistics
+    # @raise [Zvec::CollectionError] if the collection is closed
     def stats
+      ensure_open!
       @ext.stats
     end
 
+    # @return [Integer] the number of documents in the collection
+    # @raise [Zvec::CollectionError] if the collection is closed
     def doc_count
+      ensure_open!
       @ext.stats.doc_count
     end
 
+    # @return [Boolean] true if the collection has been closed
+    def closed?
+      @closed
+    end
+
+    # Close the collection, releasing the underlying C++ resources.
+    # The collection must be closed before it can be reopened from the
+    # same path.
+    #
+    # @return [void]
+    # @raise [Zvec::CollectionError] if already closed
+    #
+    # @example
+    #   col.close
+    #   col.closed?  #=> true
+    def close
+      raise CollectionError, "#{error_prefix}Collection is already closed" if @closed
+
+      @monitor.synchronize do
+        begin
+          @ext.close
+        rescue NoMethodError
+          # C++ extension may not expose a close method; the GC will handle it.
+        end
+        @closed = true
+      end
+    end
+
     # --- DDL ---
 
+    # Create an index on a field.
+    #
+    # @param field_name [String, Symbol] the field to index
+    # @param index_params [Ext::HnswIndexParams, Ext::FlatIndexParams,
+    #   Ext::IVFIndexParams, Ext::InvertIndexParams] index configuration
+    # @return [self]
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [ArgumentError] if field_name is blank
+    #
+    # @example
+    #   col.create_index("embedding",
+    #     Ext::HnswIndexParams.new(Zvec::COSINE, m: 32, ef_construction: 400))
     def create_index(field_name, index_params)
+      ensure_open!
       raise ArgumentError, "field_name must be a non-empty string" if field_name.nil? || field_name.to_s.strip.empty?
 
       @monitor.synchronize do
@@ -61,7 +159,14 @@ module Zvec
       self
     end
 
+    # Drop an index on a field.
+    #
+    # @param field_name [String, Symbol] the field whose index to drop
+    # @return [self]
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [ArgumentError] if field_name is blank
     def drop_index(field_name)
+      ensure_open!
       raise ArgumentError, "field_name must be a non-empty string" if field_name.nil? || field_name.to_s.strip.empty?
 
       @monitor.synchronize do
@@ -70,23 +175,54 @@ module Zvec
       self
     end
 
+    # Optimize the collection (compact segments, rebuild indexes).
+    #
+    # @return [self]
+    # @raise [Zvec::CollectionError] if the collection is closed
     def optimize
+      ensure_open!
       @monitor.synchronize { @ext.optimize }
       self
     end
 
+    # Flush pending writes to disk.
+    #
+    # @return [self]
+    # @raise [Zvec::CollectionError] if the collection is closed
     def flush
+      ensure_open!
       @monitor.synchronize { @ext.flush }
       self
     end
 
+    # Destroy the collection, removing all data from disk.
+    #
+    # @return [void]
+    # @raise [Zvec::CollectionError] if the collection is closed
     def destroy
-      @monitor.synchronize { @ext.destroy }
+      ensure_open!
+      @monitor.synchronize do
+        @ext.destroy
+        @closed = true
+      end
     end
 
     # --- DML ---
 
+    # Insert one or more documents.
+    #
+    # @param docs [Zvec::Doc, Array<Zvec::Doc>] document(s) to insert
+    # @return [Array<Array(Boolean, String)>] write results
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [ArgumentError] if docs are not Zvec::Doc instances
+    # @raise [Zvec::Error] if any write fails
+    #
+    # @example
+    #   doc = Zvec::Doc.new(pk: "1", schema: schema)
+    #   doc["title"] = "Hello"
+    #   col.insert(doc)
     def insert(docs)
+      ensure_open!
       docs = [docs] unless docs.is_a?(Array)
       validate_docs!(docs)
       ext_docs = docs.map { |d| d.is_a?(Doc) ? d.ext_doc : d }
@@ -94,7 +230,14 @@ module Zvec
       check_write_results!(results)
     end
 
+    # Upsert (insert or update) one or more documents.
+    #
+    # @param docs [Zvec::Doc, Array<Zvec::Doc>] document(s) to upsert
+    # @return [Array<Array(Boolean, String)>] write results
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [Zvec::Error] if any write fails
     def upsert(docs)
+      ensure_open!
       docs = [docs] unless docs.is_a?(Array)
       validate_docs!(docs)
       ext_docs = docs.map { |d| d.is_a?(Doc) ? d.ext_doc : d }
@@ -102,7 +245,14 @@ module Zvec
       check_write_results!(results)
     end
 
+    # Update one or more existing documents.
+    #
+    # @param docs [Zvec::Doc, Array<Zvec::Doc>] document(s) to update
+    # @return [Array<Array(Boolean, String)>] write results
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [Zvec::Error] if any write fails
     def update(docs)
+      ensure_open!
       docs = [docs] unless docs.is_a?(Array)
       validate_docs!(docs)
       ext_docs = docs.map { |d| d.is_a?(Doc) ? d.ext_doc : d }
@@ -110,7 +260,18 @@ module Zvec
       check_write_results!(results)
     end
 
+    # Delete documents by primary key(s).
+    #
+    # @param pks [Array<String>] one or more primary keys to delete
+    # @return [Array<Array(Boolean, String)>] write results
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [ArgumentError] if no primary keys are provided
+    # @raise [Zvec::Error] if any write fails
+    #
+    # @example
+    #   col.delete("doc-1", "doc-2")
     def delete(*pks)
+      ensure_open!
       pks = pks.flatten
       raise ArgumentError, "#{error_prefix}No primary keys provided for delete" if pks.empty?
       pks = pks.map(&:to_s)
@@ -118,15 +279,49 @@ module Zvec
       check_write_results!(results)
     end
 
+    # Delete documents matching a filter expression.
+    #
+    # @param filter [String] the filter expression (see {VectorQuery} for syntax)
+    # @return [void]
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [ArgumentError] if filter is blank
+    #
+    # @example
+    #   col.delete_by_filter("year < 2020")
     def delete_by_filter(filter)
+      ensure_open!
       raise ArgumentError, "#{error_prefix}filter must be a non-empty string" if filter.nil? || filter.to_s.strip.empty?
       @monitor.synchronize { @ext.delete_by_filter(filter) }
     end
 
     # --- DQL ---
 
+    # Execute a vector similarity search with full control over parameters.
+    #
+    # @param field_name [String, Symbol] the vector field to search
+    # @param vector [Array<Numeric>] the query vector
+    # @param topk [Integer] maximum number of results (default: 10)
+    # @param filter [String, nil] optional filter expression
+    # @param include_vector [Boolean] include stored vectors in results
+    # @param output_fields [Array<String>, nil] specific fields to return
+    # @param query_params [Ext::HnswQueryParams, Ext::IVFQueryParams,
+    #   Ext::FlatQueryParams, nil] search tuning params
+    # @return [Array<Zvec::Doc>] result documents with +pk+ and +score+ set
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [ArgumentError] if vector is empty or contains non-numeric elements
+    # @raise [Zvec::DimensionError] if vector dimension doesn't match schema
+    #
+    # @example
+    #   results = col.query(
+    #     field_name: "embedding",
+    #     vector: [0.1, 0.2, 0.3, 0.4],
+    #     topk: 5,
+    #     filter: "year > 2024"
+    #   )
+    #   results.each { |doc| puts "#{doc.pk}: #{doc.score}" }
     def query(field_name:, vector:, topk: 10, filter: nil,
               include_vector: false, output_fields: nil, query_params: nil)
+      ensure_open!
       validate_query_vector!(vector, field_name)
 
       vq = VectorQuery.new(
@@ -148,7 +343,18 @@ module Zvec
       end
     end
 
+    # Fetch documents by primary key(s).
+    #
+    # @param pks [Array<String>] one or more primary keys
+    # @return [Hash{String => Zvec::Doc}] mapping of pk to document
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [ArgumentError] if no primary keys provided
+    #
+    # @example
+    #   docs = col.fetch("doc-1", "doc-2")
+    #   docs["doc-1"]["title"]  #=> "Hello"
     def fetch(*pks)
+      ensure_open!
       pks = pks.flatten
       raise ArgumentError, "#{error_prefix}No primary keys provided for fetch" if pks.empty?
       pks = pks.map(&:to_s)
@@ -158,15 +364,41 @@ module Zvec
       end
     end
 
-    # Convenience: insert a hash directly
+    # Convenience method to insert a document from keyword arguments.
+    #
+    # @param pk [String, Integer] the primary key (required)
+    # @param fields [Hash] field name/value pairs
+    # @return [Array] write results
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [ArgumentError] if pk is nil
+    #
+    # @example
+    #   col.add(pk: "1", title: "Hello", embedding: [0.1, 0.2, 0.3, 0.4])
     def add(pk:, **fields)
+      ensure_open!
       raise ArgumentError, "#{error_prefix}pk must not be nil" if pk.nil?
       doc = Doc.new(pk: pk, fields: fields, schema: @schema)
       insert(doc)
     end
 
-    # Convenience: search with simpler API
+    # Convenience method for simple vector similarity search.
+    #
+    # Auto-detects the vector field from the schema if not specified.
+    #
+    # @param vector [Array<Numeric>] the query vector
+    # @param field [String, Symbol, nil] vector field name (auto-detected if nil)
+    # @param top_k [Integer] number of results (default: 10)
+    # @param filter [String, nil] optional filter expression
+    # @return [Array<Zvec::Doc>] result documents
+    # @raise [Zvec::CollectionError] if the collection is closed
+    # @raise [Zvec::Error] if no vector fields exist in the schema
+    #
+    # @example
+    #   results = col.search([0.1, 0.2, 0.3, 0.4], top_k: 5)
+    #   results.first.pk     #=> "doc-1"
+    #   results.first.score  #=> 0.95
     def search(vector, field: nil, top_k: 10, filter: nil)
+      ensure_open!
       raise ArgumentError, "#{error_prefix}vector must be a non-empty Array" unless vector.is_a?(Array) && !vector.empty?
 
       # Auto-detect vector field if not specified
@@ -174,11 +406,11 @@ module Zvec
       unless fname
         if @schema
           vfield = @schema.ext_schema.vector_fields.first
-          raise Error, "#{error_prefix}No vector fields in schema" unless vfield
+          raise CollectionError, "#{error_prefix}No vector fields in schema" unless vfield
           fname = vfield.name
         else
           vfields = @ext.schema.vector_fields
-          raise Error, "#{error_prefix}No vector fields in schema" if vfields.empty?
+          raise CollectionError, "#{error_prefix}No vector fields in schema" if vfields.empty?
           fname = vfields.first.name
         end
       end
@@ -191,6 +423,11 @@ module Zvec
       raise ArgumentError, "path must be a non-empty string" if path.nil? || path.to_s.strip.empty?
     end
 
+    # @raise [Zvec::CollectionError] if the collection is closed
+    def ensure_open!
+      raise CollectionError, "#{error_prefix}Collection is closed" if @closed
+    end
+
     def error_prefix
       cn = collection_name
       cn ? "[Collection '#{cn}'] " : ""
@@ -231,7 +468,7 @@ module Zvec
     def check_write_results!(results)
       results.each do |ok, msg|
         error_msg = msg.nil? || msg.empty? ? "Write operation failed" : msg
-        raise Error, "#{error_prefix}#{error_msg}" unless ok
+        raise CollectionError, "#{error_prefix}#{error_msg}" unless ok
       end
       results
     end