zvec-ruby 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d2d9ae7fa3290edf87996ab690b06669c130f7d40c8f551c936fec0fcef7f21
-  data.tar.gz: 2ae81deaa2c80feecadeb7bf0a78431af054aee5dfc095f96f3069b45f5cab05
+  metadata.gz: 9ba14d14fe74cef98438fa55ee3852580473329b4c2d06abce25cdbb67ce5f7a
+  data.tar.gz: 3c5ef9a204dc0f8b9f787559009b00b6131d30c62e9981b829a67f1a01003364
 SHA512:
-  metadata.gz: bda7fd52e20ab379efedace6180aca4925ef4136d0de0a8da068b96fc628ef1d7d98d0fcdad368f646098c06596bc6a81aedd85c41b94d4e2f51457a04b45a2a
-  data.tar.gz: 52adf87fc675871312342561fc5f1b04fa38519f2787d9e33680e3adecda84d9ab801c977dee97e26a077a6b2f4a6545a57e6110caf562a07a86e547b591195a
+  metadata.gz: 3e90824d6ffb928da3b5f6ec7327c01c76101282c10a25c56d501637e4597e4480fe50b609e3b415d3e56d43c0414252a09ecc519941556f6362a7e0aff3d3c8
+  data.tar.gz: 7a03160f30fd6ec83511ebeb61ffaeddeea69da3c6b64e1168f0c0a802101e7d34a3303f6071f5085037aec579fe6a833a3526f0cc7ef693b39acfc47a787fe3

data/README.md

@@ -15,11 +15,11 @@ Precompiled native gems are available for:
 
 ```ruby
 # Gemfile
-gem "zvec"
+gem "zvec-ruby"
 ```
 
 ```bash
-gem install zvec
+gem install zvec-ruby
 ```
 
 No compiler or build tools needed — the gem ships with the native extension and all zvec dependencies statically linked.
@@ -36,7 +36,7 @@ cmake .. -DCMAKE_BUILD_TYPE=Release
 make -j$(nproc)
 
 # 2. Install the gem with ZVEC_DIR pointing to the build
-ZVEC_DIR=/tmp/zvec gem install zvec
+ZVEC_DIR=/tmp/zvec gem install zvec-ruby
 ```
 
 Or using the included helper script:

data/lib/zvec/active_record.rb

@@ -63,7 +63,7 @@ module Zvec
 
         def zvec_remove_embedding!
           self.class.zvec_store.delete(id.to_s)
-        rescue => e
+        rescue
           # Silently ignore if document doesn't exist
         end
 

data/lib/zvec/collection.rb

@@ -1,23 +1,32 @@
+require "monitor"
+
 module Zvec
   class Collection
     attr_reader :schema
 
-    def initialize(ext_collection, schema: nil)
+    def initialize(ext_collection, schema: nil, name: nil)
       @ext = ext_collection
       @schema = schema
+      @name = name
+      @monitor = Monitor.new
     end
 
     # Create a new collection and open it.
     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)
+
       opts = Ext::CollectionOptions.new
       opts.read_only = read_only
       opts.enable_mmap = enable_mmap
       ext = Ext::Collection.create_and_open(path, schema.ext_schema, opts)
-      new(ext, schema: schema)
+      new(ext, schema: schema, name: schema.name)
     end
 
     # Open an existing collection.
     def self.open(path, read_only: false, enable_mmap: true)
+      validate_path!(path)
+
       opts = Ext::CollectionOptions.new
       opts.read_only = read_only
       opts.enable_mmap = enable_mmap
@@ -25,6 +34,10 @@ module Zvec
       new(ext)
     end
 
+    def collection_name
+      @name || (@schema ? @schema.name : nil)
+    end
+
     def path
       @ext.path
     end
@@ -40,66 +53,82 @@ module Zvec
     # --- DDL ---
 
     def create_index(field_name, index_params)
-      @ext.create_index(field_name.to_s, index_params)
+      raise ArgumentError, "field_name must be a non-empty string" if field_name.nil? || field_name.to_s.strip.empty?
+
+      @monitor.synchronize do
+        @ext.create_index(field_name.to_s, index_params)
+      end
       self
     end
 
     def drop_index(field_name)
-      @ext.drop_index(field_name.to_s)
+      raise ArgumentError, "field_name must be a non-empty string" if field_name.nil? || field_name.to_s.strip.empty?
+
+      @monitor.synchronize do
+        @ext.drop_index(field_name.to_s)
+      end
       self
     end
 
     def optimize
-      @ext.optimize
+      @monitor.synchronize { @ext.optimize }
       self
     end
 
     def flush
-      @ext.flush
+      @monitor.synchronize { @ext.flush }
       self
     end
 
     def destroy
-      @ext.destroy
+      @monitor.synchronize { @ext.destroy }
     end
 
     # --- DML ---
 
     def insert(docs)
       docs = [docs] unless docs.is_a?(Array)
+      validate_docs!(docs)
       ext_docs = docs.map { |d| d.is_a?(Doc) ? d.ext_doc : d }
-      results = @ext.insert(ext_docs)
+      results = @monitor.synchronize { @ext.insert(ext_docs) }
       check_write_results!(results)
     end
 
     def upsert(docs)
       docs = [docs] unless docs.is_a?(Array)
+      validate_docs!(docs)
       ext_docs = docs.map { |d| d.is_a?(Doc) ? d.ext_doc : d }
-      results = @ext.upsert(ext_docs)
+      results = @monitor.synchronize { @ext.upsert(ext_docs) }
       check_write_results!(results)
     end
 
     def update(docs)
       docs = [docs] unless docs.is_a?(Array)
+      validate_docs!(docs)
       ext_docs = docs.map { |d| d.is_a?(Doc) ? d.ext_doc : d }
-      results = @ext.update(ext_docs)
+      results = @monitor.synchronize { @ext.update(ext_docs) }
       check_write_results!(results)
     end
 
     def delete(*pks)
-      pks = pks.flatten.map(&:to_s)
-      results = @ext.delete_pks(pks)
+      pks = pks.flatten
+      raise ArgumentError, "#{error_prefix}No primary keys provided for delete" if pks.empty?
+      pks = pks.map(&:to_s)
+      results = @monitor.synchronize { @ext.delete_pks(pks) }
       check_write_results!(results)
     end
 
     def delete_by_filter(filter)
-      @ext.delete_by_filter(filter)
+      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 ---
 
     def query(field_name:, vector:, topk: 10, filter: nil,
               include_vector: false, output_fields: nil, query_params: nil)
+      validate_query_vector!(vector, field_name)
+
       vq = VectorQuery.new(
         field_name: field_name,
         vector: vector,
@@ -109,7 +138,7 @@ module Zvec
         output_fields: output_fields,
         query_params: query_params
       )
-      raw_results = @ext.query(vq.ext_query)
+      raw_results = @monitor.synchronize { @ext.query(vq.ext_query) }
       raw_results.map do |h|
         Doc.new(
           pk: h["pk"],
@@ -120,8 +149,10 @@ module Zvec
     end
 
     def fetch(*pks)
-      pks = pks.flatten.map(&:to_s)
-      raw = @ext.fetch(pks)
+      pks = pks.flatten
+      raise ArgumentError, "#{error_prefix}No primary keys provided for fetch" if pks.empty?
+      pks = pks.map(&:to_s)
+      raw = @monitor.synchronize { @ext.fetch(pks) }
       raw.transform_values do |h|
         Doc.new(pk: nil, fields: h, schema: @schema)
       end
@@ -129,37 +160,80 @@ module Zvec
 
     # Convenience: insert a hash directly
     def add(pk:, **fields)
+      raise ArgumentError, "#{error_prefix}pk must not be nil" if pk.nil?
       doc = Doc.new(pk: pk, fields: fields, schema: @schema)
       insert(doc)
     end
 
-    private
-
-    def check_write_results!(results)
-      results.each do |ok, msg|
-        raise Error, (msg.empty? ? "Write operation failed" : msg) unless ok
-      end
-      results
-    end
-
-    public
-
     # Convenience: search with simpler API
     def search(vector, field: nil, top_k: 10, filter: nil)
+      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
       fname = field&.to_s
       unless fname
         if @schema
           vfield = @schema.ext_schema.vector_fields.first
-          raise Error, "No vector fields in schema" unless vfield
+          raise Error, "#{error_prefix}No vector fields in schema" unless vfield
           fname = vfield.name
         else
           vfields = @ext.schema.vector_fields
-          raise Error, "No vector fields in schema" if vfields.empty?
+          raise Error, "#{error_prefix}No vector fields in schema" if vfields.empty?
           fname = vfields.first.name
         end
       end
       query(field_name: fname, vector: vector, topk: top_k, filter: filter)
     end
+
+    private
+
+    def self.validate_path!(path)
+      raise ArgumentError, "path must be a non-empty string" if path.nil? || path.to_s.strip.empty?
+    end
+
+    def error_prefix
+      cn = collection_name
+      cn ? "[Collection '#{cn}'] " : ""
+    end
+
+    def validate_docs!(docs)
+      docs.each_with_index do |doc, i|
+        unless doc.is_a?(Doc) || doc.is_a?(Ext::Doc)
+          raise ArgumentError,
+            "#{error_prefix}Expected Zvec::Doc at index #{i}, got #{doc.class}"
+        end
+      end
+    end
+
+    def validate_query_vector!(vector, field_name)
+      raise ArgumentError, "#{error_prefix}vector must be a non-empty Array" unless vector.is_a?(Array) && !vector.empty?
+
+      vector.each_with_index do |v, i|
+        unless v.is_a?(Numeric)
+          raise ArgumentError,
+            "#{error_prefix}Query vector for field '#{field_name}' contains non-numeric element at index #{i}: #{v.inspect}"
+        end
+      end
+
+      # Dimension check against schema
+      return unless @schema
+
+      expected_dim = @schema.field_dimension(field_name.to_s)
+      return unless expected_dim
+
+      if vector.size != expected_dim
+        raise DimensionError,
+          "#{error_prefix}Query vector dimension mismatch for field '#{field_name}': " \
+          "expected #{expected_dim}, got #{vector.size}"
+      end
+    end
+
+    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
+      end
+      results
+    end
   end
 end

data/lib/zvec/data_types.rb

@@ -31,6 +31,14 @@ module Zvec
     IP     = Ext::MetricType::IP
     COSINE = Ext::MetricType::COSINE
 
+    # Vector data types for dimension validation
+    VECTOR_TYPES = [
+      Ext::DataType::VECTOR_FP32,
+      Ext::DataType::VECTOR_FP64,
+      Ext::DataType::VECTOR_FP16,
+      Ext::DataType::VECTOR_INT8,
+    ].freeze
+
     # Setter dispatch table: DataType -> Doc setter method name
     SETTER_FOR = {
       Ext::DataType::STRING => :set_string,
@@ -59,5 +67,125 @@ module Zvec
       Ext::DataType::VECTOR_FP64 => :get_double_vector,
       Ext::DataType::ARRAY_STRING => :get_string_array,
     }.freeze
+
+    # Detect the zvec data type for a Ruby value.
+    # Handles edge cases: Integer vs Float, String booleans, nil, empty arrays.
+    def self.detect_type(value)
+      case value
+      when NilClass              then nil
+      when String                then Ext::DataType::STRING
+      when Integer               then Ext::DataType::INT64
+      when Float                 then Ext::DataType::DOUBLE
+      when TrueClass, FalseClass then Ext::DataType::BOOL
+      when Array                 then detect_array_type(value)
+      end
+    end
+
+    # Coerce a Ruby value into a form suitable for the given zvec data type.
+    # Returns the coerced value, or raises ArgumentError on impossible coercion.
+    def self.coerce_value(value, target_type, field_name: nil)
+      return value if value.nil?
+
+      ctx = field_name ? " for field '#{field_name}'" : ""
+
+      case target_type
+      when Ext::DataType::STRING
+        value.to_s
+      when Ext::DataType::BOOL
+        coerce_bool(value, ctx)
+      when Ext::DataType::INT32, Ext::DataType::INT64,
+           Ext::DataType::UINT32, Ext::DataType::UINT64
+        coerce_integer(value, ctx)
+      when Ext::DataType::FLOAT, Ext::DataType::DOUBLE
+        coerce_float(value, ctx)
+      when Ext::DataType::VECTOR_FP32, Ext::DataType::VECTOR_FP64
+        coerce_float_vector(value, ctx)
+      when Ext::DataType::ARRAY_STRING
+        coerce_string_array(value, ctx)
+      else
+        value
+      end
+    end
+
+    class << self
+      private
+
+      def detect_array_type(arr)
+        return Ext::DataType::VECTOR_FP32 if arr.empty?
+
+        first_non_nil = arr.find { |v| !v.nil? }
+        return Ext::DataType::VECTOR_FP32 if first_non_nil.nil?
+
+        case first_non_nil
+        when Float   then Ext::DataType::VECTOR_FP32
+        when Integer then Ext::DataType::VECTOR_FP32
+        when String  then Ext::DataType::ARRAY_STRING
+        when TrueClass, FalseClass then Ext::DataType::ARRAY_BOOL
+        else Ext::DataType::VECTOR_FP32
+        end
+      end
+
+      def coerce_bool(value, ctx)
+        case value
+        when TrueClass, FalseClass then value
+        when "true", "1"           then true
+        when "false", "0"          then false
+        when Integer               then !value.zero?
+        else
+          raise ArgumentError,
+            "Cannot coerce #{value.class} (#{value.inspect}) to Bool#{ctx}"
+        end
+      end
+
+      def coerce_integer(value, ctx)
+        case value
+        when Integer then value
+        when Float   then value.to_i
+        when String
+          Integer(value)
+        else
+          raise ArgumentError,
+            "Cannot coerce #{value.class} (#{value.inspect}) to Integer#{ctx}"
+        end
+      rescue ::ArgumentError
+        raise ArgumentError,
+          "Cannot coerce #{value.class} (#{value.inspect}) to Integer#{ctx}"
+      end
+
+      def coerce_float(value, ctx)
+        case value
+        when Numeric then value.to_f
+        when String
+          Float(value)
+        else
+          raise ArgumentError,
+            "Cannot coerce #{value.class} (#{value.inspect}) to Float#{ctx}"
+        end
+      rescue ::ArgumentError
+        raise ArgumentError,
+          "Cannot coerce #{value.class} (#{value.inspect}) to Float#{ctx}"
+      end
+
+      def coerce_float_vector(value, ctx)
+        unless value.is_a?(Array)
+          raise ArgumentError, "Expected Array for vector#{ctx}, got #{value.class}"
+        end
+        value.map do |v|
+          next 0.0 if v.nil?
+          unless v.is_a?(Numeric)
+            raise ArgumentError,
+              "Vector#{ctx} contains non-numeric element: #{v.inspect}"
+          end
+          v.to_f
+        end
+      end
+
+      def coerce_string_array(value, ctx)
+        unless value.is_a?(Array)
+          raise ArgumentError, "Expected Array for string array#{ctx}, got #{value.class}"
+        end
+        value.map { |v| v.nil? ? "" : v.to_s }
+      end
+    end
   end
 end

data/lib/zvec/doc.rb

@@ -31,28 +31,49 @@ module Zvec
 
     def set(field_name, value)
       field_name = field_name.to_s
+      raise ArgumentError, "Field name must be a non-empty string" if field_name.strip.empty?
+
       return @ext_doc.set_null(field_name) if value.nil?
 
       if @schema
         type = @schema.field_type(field_name)
         if type
+          coerced = DataTypes.coerce_value(value, type, field_name: field_name)
           setter = DataTypes::SETTER_FOR[type]
-          return @ext_doc.send(setter, field_name, value) if setter
+          if setter
+            # Validate vector dimension if schema has dimension info
+            if DataTypes::VECTOR_TYPES.include?(type) && coerced.is_a?(Array)
+              expected_dim = @schema.field_dimension(field_name)
+              if expected_dim && !coerced.empty? && coerced.size != expected_dim
+                raise DimensionError,
+                  "Vector dimension mismatch for field '#{field_name}': " \
+                  "expected #{expected_dim}, got #{coerced.size}"
+              end
+            end
+            return @ext_doc.send(setter, field_name, coerced)
+          end
         end
       end
 
-      # Auto-detect type
+      # Auto-detect type (schema-less mode)
       case value
-      when String  then @ext_doc.set_string(field_name, value)
-      when Integer then @ext_doc.set_int64(field_name, value)
-      when Float   then @ext_doc.set_double(field_name, value)
+      when String                then @ext_doc.set_string(field_name, value)
+      when Integer               then @ext_doc.set_int64(field_name, value)
+      when Float                 then @ext_doc.set_double(field_name, value)
       when TrueClass, FalseClass then @ext_doc.set_bool(field_name, value)
       when Array
-        if value.empty? || value.first.is_a?(Float) || value.first.is_a?(Integer)
-          @ext_doc.set_float_vector(field_name, value.map(&:to_f))
-        elsif value.first.is_a?(String)
-          @ext_doc.set_string_array(field_name, value)
+        detected = DataTypes.detect_type(value)
+        case detected
+        when Ext::DataType::ARRAY_STRING
+          @ext_doc.set_string_array(field_name, value.map { |v| v.nil? ? "" : v.to_s })
+        else
+          # Default: treat as float vector
+          coerced = value.map { |v| v.nil? ? 0.0 : v.to_f }
+          @ext_doc.set_float_vector(field_name, coerced)
         end
+      else
+        raise ArgumentError,
+          "Unsupported value type #{value.class} for field '#{field_name}'"
       end
     end
 

data/lib/zvec/query.rb

@@ -4,6 +4,18 @@ module Zvec
 
     def initialize(field_name:, vector:, topk: 10, filter: nil,
                    include_vector: false, output_fields: nil, query_params: nil)
+      raise ArgumentError, "field_name must be a non-empty string" if field_name.nil? || field_name.to_s.strip.empty?
+      raise ArgumentError, "vector must be a non-empty Array" unless vector.is_a?(Array) && !vector.empty?
+      raise ArgumentError, "topk must be a positive integer" unless topk.is_a?(Integer) && topk > 0
+
+      # Validate all vector elements are numeric
+      vector.each_with_index do |v, i|
+        unless v.is_a?(Numeric)
+          raise ArgumentError,
+            "Query vector contains non-numeric element at index #{i}: #{v.inspect}"
+        end
+      end
+
       @ext_query = Ext::VectorQuery.new
       @ext_query.field_name = field_name.to_s
       @ext_query.topk = topk

data/lib/zvec/schema.rb

@@ -3,23 +3,31 @@ module Zvec
     attr_reader :ext_schema
 
     def initialize(name, &block)
-      @ext_schema = Ext::CollectionSchema.new(name)
+      raise ArgumentError, "Schema name must be a non-empty string" if name.nil? || name.to_s.strip.empty?
+
+      @ext_schema = Ext::CollectionSchema.new(name.to_s)
       @field_types = {}
+      @field_dimensions = {}
       instance_eval(&block) if block
     end
 
     def field(name, type, dimension: nil, nullable: false, index: nil)
       name = name.to_s
+      raise ArgumentError, "Field name must be a non-empty string" if name.strip.empty?
+
       fs = Ext::FieldSchema.new(name, type)
       fs.dimension = dimension if dimension
       fs.nullable = nullable
       fs.set_index_params(index) if index
       @ext_schema.add_field(fs)
       @field_types[name] = type
+      @field_dimensions[name] = dimension if dimension
       self
     end
 
     def vector(name, dimension:, type: DataTypes::VECTOR_FP32, index: nil)
+      raise ArgumentError, "Vector dimension must be a positive integer, got #{dimension.inspect}" unless dimension.is_a?(Integer) && dimension > 0
+
       field(name, type, dimension: dimension, index: index)
     end
 
@@ -59,10 +67,19 @@ module Zvec
       @field_types[name.to_s]
     end
 
+    def field_dimension(name)
+      @field_dimensions[name.to_s]
+    end
+
     def has_field?(name)
       @ext_schema.has_field?(name.to_s)
     end
 
+    # Returns an array of [field_name, dimension] for all vector fields.
+    def vector_fields_with_dimensions
+      @field_dimensions.select { |name, _| DataTypes::VECTOR_TYPES.include?(@field_types[name]) }
+    end
+
     def to_s
       @ext_schema.to_s
     end

data/lib/zvec/version.rb

@@ -1,3 +1,3 @@
 module Zvec
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/zvec.rb

@@ -17,6 +17,7 @@ require_relative "zvec/collection"
 
 module Zvec
   class Error < StandardError; end
+  class DimensionError < Error; end
 
   include DataTypes
 end

data/test/test_helper.rb

@@ -14,6 +14,7 @@ rescue LoadError
   # Minimal stubs so pure-Ruby logic can be tested without the compiled extension.
   module Zvec
     class Error < StandardError; end
+    class DimensionError < Error; end
 
     module Ext
       # Stub enums as simple modules with constants
@@ -68,9 +69,9 @@ rescue LoadError
         def get_int64(f); @fields[f].is_a?(Integer) ? @fields[f] : nil; end
         def get_float(f); @fields[f].is_a?(Float) ? @fields[f] : nil; end
         def get_double(f); @fields[f].is_a?(Float) ? @fields[f] : nil; end
-        def get_float_vector(f); @fields[f].is_a?(Array) && @fields[f].first.is_a?(Float) ? @fields[f] : nil; end
+        def get_float_vector(f); @fields[f].is_a?(Array) && (@fields[f].empty? || @fields[f].first.is_a?(Float)) ? @fields[f] : nil; end
         def get_double_vector(f); get_float_vector(f); end
-        def get_string_array(f); @fields[f].is_a?(Array) && @fields[f].first.is_a?(String) ? @fields[f] : nil; end
+        def get_string_array(f); @fields[f].is_a?(Array) && !@fields[f].empty? && @fields[f].first.is_a?(String) ? @fields[f] : nil; end
         def to_s; "[pk:#{@pk}, score:#{@score}, fields:#{@fields.size}]"; end
       end
 
@@ -90,7 +91,6 @@ rescue LoadError
         def has_field?(n); @fields.key?(n); end
         def field_names; @fields.keys; end
         def all_field_names; @fields.keys; end
-        alias_method :field_names, :all_field_names
         def fields; @fields.values; end
         def vector_fields; @fields.values.select(&:vector_field?); end
         def forward_fields; @fields.values.reject(&:vector_field?); end
@@ -118,6 +118,15 @@ rescue LoadError
         def initialize(ef: 200); @ef = ef; end
       end
 
+      class IVFQueryParams
+        attr_reader :nprobe
+        def initialize(nprobe: 10); @nprobe = nprobe; end
+      end
+
+      class FlatQueryParams
+        def initialize; end
+      end
+
       class CollectionOptions
         attr_accessor :read_only, :enable_mmap, :max_buffer_size
         def initialize; @read_only = false; @enable_mmap = true; @max_buffer_size = 64 * 1024 * 1024; end
@@ -131,6 +140,9 @@ rescue LoadError
         def set_query_vector(arr); @query_vector = arr; end
         def set_output_fields(f); @output_fields = f; end
         def set_query_params(p); @query_params = p; end
+        def set_hnsw_query_params(p); @query_params = p; end
+        def set_ivf_query_params(p); @query_params = p; end
+        def set_flat_query_params(p); @query_params = p; end
         alias_method :include_vector?, :include_vector
       end
 
@@ -147,6 +159,83 @@ rescue LoadError
         def message; @msg; end
         def to_s; @ok ? "OK" : @msg; end
       end
+
+      # Stub Collection for pure-Ruby testing of the wrapper layer
+      class Collection
+        attr_reader :path_value, :schema_value, :docs
+
+        def initialize
+          @docs = {}
+          @stats = CollectionStats.new
+          @path_value = ""
+        end
+
+        def self.create_and_open(path, ext_schema, opts)
+          c = new
+          c.instance_variable_set(:@path_value, path)
+          c.instance_variable_set(:@schema_value, ext_schema)
+          c
+        end
+
+        def self.open(path, opts)
+          c = new
+          c.instance_variable_set(:@path_value, path)
+          c
+        end
+
+        def path; @path_value; end
+        def schema; @schema_value; end
+
+        def stats
+          s = CollectionStats.new
+          s.doc_count = @docs.size
+          s
+        end
+
+        def insert(ext_docs)
+          ext_docs.each { |d| @docs[d.pk] = d }
+          ext_docs.map { |_| [true, ""] }
+        end
+
+        def upsert(ext_docs)
+          ext_docs.each { |d| @docs[d.pk] = d }
+          ext_docs.map { |_| [true, ""] }
+        end
+
+        def update(ext_docs)
+          ext_docs.each { |d| @docs[d.pk] = d if @docs.key?(d.pk) }
+          ext_docs.map { |_| [true, ""] }
+        end
+
+        def delete_pks(pks)
+          pks.each { |pk| @docs.delete(pk) }
+          pks.map { |_| [true, ""] }
+        end
+
+        def delete_by_filter(filter)
+          # no-op in stub
+        end
+
+        def query(vq)
+          @docs.values.first(vq.topk).map do |d|
+            h = { "pk" => d.pk, "score" => 0.95 }
+            d.field_names.each { |f| h[f] = d.get_string(f) || d.get_int64(f) || d.get_float(f) || d.get_double(f) || d.get_bool(f) || d.get_float_vector(f) || d.get_string_array(f) }
+            h
+          end
+        end
+
+        def fetch(pks)
+          result = {}
+          pks.each { |pk| result[pk] = @docs[pk] if @docs.key?(pk) }
+          result
+        end
+
+        def create_index(field_name, index_params); end
+        def drop_index(field_name); end
+        def optimize; end
+        def flush; end
+        def destroy; end
+      end
     end
 
     require_relative "../lib/zvec/version"
@@ -154,6 +243,7 @@ rescue LoadError
     require_relative "../lib/zvec/schema"
     require_relative "../lib/zvec/doc"
     require_relative "../lib/zvec/query"
+    require_relative "../lib/zvec/collection"
 
     include DataTypes
   end

data/test/test_type_detection.rb

@@ -0,0 +1,258 @@
+require_relative "test_helper"
+
+class TestTypeDetection < Minitest::Test
+  # --- DataTypes.detect_type ---
+
+  def test_detect_type_nil
+    assert_nil Zvec::DataTypes.detect_type(nil)
+  end
+
+  def test_detect_type_string
+    assert_equal Zvec::Ext::DataType::STRING, Zvec::DataTypes.detect_type("hello")
+  end
+
+  def test_detect_type_integer
+    assert_equal Zvec::Ext::DataType::INT64, Zvec::DataTypes.detect_type(42)
+  end
+
+  def test_detect_type_float
+    assert_equal Zvec::Ext::DataType::DOUBLE, Zvec::DataTypes.detect_type(3.14)
+  end
+
+  def test_detect_type_true
+    assert_equal Zvec::Ext::DataType::BOOL, Zvec::DataTypes.detect_type(true)
+  end
+
+  def test_detect_type_false
+    assert_equal Zvec::Ext::DataType::BOOL, Zvec::DataTypes.detect_type(false)
+  end
+
+  # Integer vs Float distinction: 1 should be INT64, 1.0 should be DOUBLE
+  def test_detect_type_integer_one
+    assert_equal Zvec::Ext::DataType::INT64, Zvec::DataTypes.detect_type(1)
+  end
+
+  def test_detect_type_float_one
+    assert_equal Zvec::Ext::DataType::DOUBLE, Zvec::DataTypes.detect_type(1.0)
+  end
+
+  # --- Array type detection ---
+
+  def test_detect_type_empty_array
+    # Empty arrays default to VECTOR_FP32
+    assert_equal Zvec::Ext::DataType::VECTOR_FP32, Zvec::DataTypes.detect_type([])
+  end
+
+  def test_detect_type_float_array
+    assert_equal Zvec::Ext::DataType::VECTOR_FP32, Zvec::DataTypes.detect_type([1.0, 2.0])
+  end
+
+  def test_detect_type_integer_array
+    # Integers in arrays are treated as vectors (float)
+    assert_equal Zvec::Ext::DataType::VECTOR_FP32, Zvec::DataTypes.detect_type([1, 2, 3])
+  end
+
+  def test_detect_type_string_array
+    assert_equal Zvec::Ext::DataType::ARRAY_STRING, Zvec::DataTypes.detect_type(["a", "b"])
+  end
+
+  def test_detect_type_bool_array
+    assert_equal Zvec::Ext::DataType::ARRAY_BOOL, Zvec::DataTypes.detect_type([true, false])
+  end
+
+  def test_detect_type_nil_filled_array
+    # Array of all nils defaults to VECTOR_FP32
+    assert_equal Zvec::Ext::DataType::VECTOR_FP32, Zvec::DataTypes.detect_type([nil, nil, nil])
+  end
+
+  def test_detect_type_array_with_leading_nil
+    # Skips nils to find first real element
+    assert_equal Zvec::Ext::DataType::ARRAY_STRING, Zvec::DataTypes.detect_type([nil, "hello", "world"])
+  end
+
+  # --- DataTypes.coerce_value ---
+
+  def test_coerce_nil_returns_nil
+    assert_nil Zvec::DataTypes.coerce_value(nil, Zvec::Ext::DataType::STRING)
+  end
+
+  def test_coerce_to_string
+    assert_equal "42", Zvec::DataTypes.coerce_value(42, Zvec::Ext::DataType::STRING)
+  end
+
+  def test_coerce_string_true_to_bool
+    assert_equal true, Zvec::DataTypes.coerce_value("true", Zvec::Ext::DataType::BOOL)
+  end
+
+  def test_coerce_string_false_to_bool
+    assert_equal false, Zvec::DataTypes.coerce_value("false", Zvec::Ext::DataType::BOOL)
+  end
+
+  def test_coerce_actual_bool_true
+    assert_equal true, Zvec::DataTypes.coerce_value(true, Zvec::Ext::DataType::BOOL)
+  end
+
+  def test_coerce_actual_bool_false
+    assert_equal false, Zvec::DataTypes.coerce_value(false, Zvec::Ext::DataType::BOOL)
+  end
+
+  def test_coerce_integer_to_bool_nonzero
+    assert_equal true, Zvec::DataTypes.coerce_value(1, Zvec::Ext::DataType::BOOL)
+  end
+
+  def test_coerce_integer_to_bool_zero
+    assert_equal false, Zvec::DataTypes.coerce_value(0, Zvec::Ext::DataType::BOOL)
+  end
+
+  def test_coerce_invalid_string_to_bool_raises
+    assert_raises(ArgumentError) do
+      Zvec::DataTypes.coerce_value("maybe", Zvec::Ext::DataType::BOOL)
+    end
+  end
+
+  def test_coerce_float_to_integer
+    assert_equal 3, Zvec::DataTypes.coerce_value(3.7, Zvec::Ext::DataType::INT64)
+  end
+
+  def test_coerce_string_to_integer
+    assert_equal 42, Zvec::DataTypes.coerce_value("42", Zvec::Ext::DataType::INT64)
+  end
+
+  def test_coerce_bad_string_to_integer_raises
+    assert_raises(ArgumentError) do
+      Zvec::DataTypes.coerce_value("abc", Zvec::Ext::DataType::INT64)
+    end
+  end
+
+  def test_coerce_integer_to_float
+    assert_in_delta 42.0, Zvec::DataTypes.coerce_value(42, Zvec::Ext::DataType::DOUBLE), 0.001
+  end
+
+  def test_coerce_string_to_float
+    assert_in_delta 3.14, Zvec::DataTypes.coerce_value("3.14", Zvec::Ext::DataType::DOUBLE), 0.001
+  end
+
+  def test_coerce_bad_string_to_float_raises
+    assert_raises(ArgumentError) do
+      Zvec::DataTypes.coerce_value("xyz", Zvec::Ext::DataType::DOUBLE)
+    end
+  end
+
+  # --- Vector coercion ---
+
+  def test_coerce_integer_array_to_vector
+    result = Zvec::DataTypes.coerce_value([1, 2, 3], Zvec::Ext::DataType::VECTOR_FP32)
+    assert_equal [1.0, 2.0, 3.0], result
+  end
+
+  def test_coerce_nil_in_vector_becomes_zero
+    result = Zvec::DataTypes.coerce_value([1.0, nil, 3.0], Zvec::Ext::DataType::VECTOR_FP32)
+    assert_equal [1.0, 0.0, 3.0], result
+  end
+
+  def test_coerce_non_numeric_in_vector_raises
+    assert_raises(ArgumentError) do
+      Zvec::DataTypes.coerce_value([1.0, "bad", 3.0], Zvec::Ext::DataType::VECTOR_FP32)
+    end
+  end
+
+  def test_coerce_non_array_to_vector_raises
+    assert_raises(ArgumentError) do
+      Zvec::DataTypes.coerce_value("not array", Zvec::Ext::DataType::VECTOR_FP32)
+    end
+  end
+
+  # --- String array coercion ---
+
+  def test_coerce_string_array
+    result = Zvec::DataTypes.coerce_value(["a", "b"], Zvec::Ext::DataType::ARRAY_STRING)
+    assert_equal ["a", "b"], result
+  end
+
+  def test_coerce_nil_in_string_array_becomes_empty
+    result = Zvec::DataTypes.coerce_value(["a", nil, "c"], Zvec::Ext::DataType::ARRAY_STRING)
+    assert_equal ["a", "", "c"], result
+  end
+
+  def test_coerce_non_array_to_string_array_raises
+    assert_raises(ArgumentError) do
+      Zvec::DataTypes.coerce_value("not array", Zvec::Ext::DataType::ARRAY_STRING)
+    end
+  end
+
+  # --- Coerce error messages include field name ---
+
+  def test_coerce_error_message_includes_field_name
+    err = assert_raises(ArgumentError) do
+      Zvec::DataTypes.coerce_value("abc", Zvec::Ext::DataType::INT64, field_name: "count")
+    end
+    assert_includes err.message, "count"
+  end
+
+  # --- Doc auto-detection edge cases ---
+
+  def test_doc_auto_detect_integer_vs_float
+    doc = Zvec::Doc.new
+    doc["int_val"] = 42
+    doc["float_val"] = 42.0
+    # int_val stored via set_int64, float_val via set_double
+    assert_equal 42, doc["int_val"]
+    assert_in_delta 42.0, doc["float_val"], 0.001
+  end
+
+  def test_doc_auto_detect_true_boolean
+    doc = Zvec::Doc.new
+    doc["flag"] = true
+    assert_equal true, doc["flag"]
+  end
+
+  def test_doc_auto_detect_false_boolean
+    doc = Zvec::Doc.new
+    doc["flag"] = false
+    assert_equal false, doc["flag"]
+  end
+
+  def test_doc_string_true_stays_string
+    # Without schema, "true" is a String, not a Boolean
+    doc = Zvec::Doc.new
+    doc["val"] = "true"
+    assert_equal "true", doc["val"]
+  end
+
+  def test_doc_string_false_stays_string
+    doc = Zvec::Doc.new
+    doc["val"] = "false"
+    assert_equal "false", doc["val"]
+  end
+
+  def test_doc_nil_value_in_array_auto_detect
+    doc = Zvec::Doc.new
+    doc["vec"] = [1.0, nil, 3.0]
+    result = doc["vec"]
+    assert_kind_of Array, result
+    assert_equal 3, result.size
+    assert_in_delta 0.0, result[1], 0.001
+  end
+
+  def test_doc_empty_array_auto_detect
+    doc = Zvec::Doc.new
+    doc["vec"] = []
+    # Should not crash
+    result = doc["vec"]
+    assert(result.nil? || result == [])
+  end
+
+  def test_doc_schema_coerces_string_bool
+    schema = Zvec::Schema.new("test") { bool "active" }
+    doc = Zvec::Doc.new(schema: schema)
+    doc["active"] = "true"
+    assert_equal true, doc["active"]
+  end
+
+  def test_doc_schema_coerces_int_to_float
+    schema = Zvec::Schema.new("test") { double "score" }
+    doc = Zvec::Doc.new(schema: schema)
+    doc["score"] = 42
+    assert_in_delta 42.0, doc["score"], 0.001
+  end
+end

data/test/test_validation.rb

@@ -0,0 +1,305 @@
+require_relative "test_helper"
+
+class TestValidation < Minitest::Test
+  include TempDirHelper
+
+  def setup
+    @schema = Zvec::Schema.new("test_validation") do
+      string "title"
+      int32 "count"
+      float "rating"
+      bool "active"
+      vector "embedding", dimension: 4
+    end
+  end
+
+  # --- Schema validation ---
+
+  def test_schema_rejects_nil_name
+    assert_raises(ArgumentError) { Zvec::Schema.new(nil) }
+  end
+
+  def test_schema_rejects_empty_name
+    assert_raises(ArgumentError) { Zvec::Schema.new("") }
+  end
+
+  def test_schema_rejects_blank_name
+    assert_raises(ArgumentError) { Zvec::Schema.new("   ") }
+  end
+
+  def test_schema_field_rejects_empty_name
+    schema = Zvec::Schema.new("test")
+    assert_raises(ArgumentError) { schema.field("", Zvec::DataTypes::STRING) }
+  end
+
+  def test_schema_vector_rejects_zero_dimension
+    assert_raises(ArgumentError) do
+      Zvec::Schema.new("test") { vector "v", dimension: 0 }
+    end
+  end
+
+  def test_schema_vector_rejects_negative_dimension
+    assert_raises(ArgumentError) do
+      Zvec::Schema.new("test") { vector "v", dimension: -1 }
+    end
+  end
+
+  def test_schema_vector_rejects_non_integer_dimension
+    assert_raises(ArgumentError) do
+      Zvec::Schema.new("test") { vector "v", dimension: 3.5 }
+    end
+  end
+
+  def test_schema_field_dimension_tracking
+    schema = Zvec::Schema.new("test") do
+      vector "embedding", dimension: 128
+    end
+    assert_equal 128, schema.field_dimension("embedding")
+  end
+
+  def test_schema_field_dimension_nil_for_non_vector
+    schema = Zvec::Schema.new("test") do
+      string "title"
+    end
+    assert_nil schema.field_dimension("title")
+  end
+
+  def test_schema_vector_fields_with_dimensions
+    schema = Zvec::Schema.new("test") do
+      string "title"
+      vector "embedding", dimension: 128
+      vector "small_embedding", dimension: 32
+    end
+    dims = schema.vector_fields_with_dimensions
+    assert_equal 128, dims["embedding"]
+    assert_equal 32, dims["small_embedding"]
+    refute dims.key?("title")
+  end
+
+  # --- Doc field name validation ---
+
+  def test_doc_set_rejects_empty_field_name
+    doc = Zvec::Doc.new
+    assert_raises(ArgumentError) { doc.set("", "value") }
+  end
+
+  def test_doc_set_rejects_blank_field_name
+    doc = Zvec::Doc.new
+    assert_raises(ArgumentError) { doc.set("   ", "value") }
+  end
+
+  # --- Dimension validation in Doc ---
+
+  def test_doc_dimension_mismatch_raises_error
+    doc = Zvec::Doc.new(schema: @schema)
+    assert_raises(Zvec::DimensionError) do
+      doc["embedding"] = [1.0, 2.0, 3.0]  # expects 4
+    end
+  end
+
+  def test_doc_dimension_mismatch_error_message
+    doc = Zvec::Doc.new(schema: @schema)
+    err = assert_raises(Zvec::DimensionError) do
+      doc["embedding"] = [1.0, 2.0]
+    end
+    assert_includes err.message, "embedding"
+    assert_includes err.message, "4"
+    assert_includes err.message, "2"
+  end
+
+  def test_doc_correct_dimension_accepted
+    doc = Zvec::Doc.new(schema: @schema)
+    doc["embedding"] = [1.0, 2.0, 3.0, 4.0]
+    result = doc["embedding"]
+    assert_equal 4, result.size
+  end
+
+  def test_doc_empty_vector_accepted
+    doc = Zvec::Doc.new(schema: @schema)
+    doc["embedding"] = []
+    # Empty vectors should be accepted (no dimension to check)
+  end
+
+  # --- VectorQuery validation ---
+
+  def test_query_rejects_nil_field_name
+    assert_raises(ArgumentError) do
+      Zvec::VectorQuery.new(field_name: nil, vector: [1.0])
+    end
+  end
+
+  def test_query_rejects_empty_field_name
+    assert_raises(ArgumentError) do
+      Zvec::VectorQuery.new(field_name: "", vector: [1.0])
+    end
+  end
+
+  def test_query_rejects_empty_vector
+    assert_raises(ArgumentError) do
+      Zvec::VectorQuery.new(field_name: "vec", vector: [])
+    end
+  end
+
+  def test_query_rejects_non_array_vector
+    assert_raises(ArgumentError) do
+      Zvec::VectorQuery.new(field_name: "vec", vector: "not an array")
+    end
+  end
+
+  def test_query_rejects_non_numeric_vector_elements
+    assert_raises(ArgumentError) do
+      Zvec::VectorQuery.new(field_name: "vec", vector: [1.0, "bad", 3.0])
+    end
+  end
+
+  def test_query_rejects_zero_topk
+    assert_raises(ArgumentError) do
+      Zvec::VectorQuery.new(field_name: "vec", vector: [1.0], topk: 0)
+    end
+  end
+
+  def test_query_rejects_negative_topk
+    assert_raises(ArgumentError) do
+      Zvec::VectorQuery.new(field_name: "vec", vector: [1.0], topk: -1)
+    end
+  end
+
+  # --- Collection validation (using stubs) ---
+
+  def test_collection_create_rejects_nil_path
+    assert_raises(ArgumentError) do
+      Zvec::Collection.create_and_open(nil, @schema)
+    end
+  end
+
+  def test_collection_create_rejects_empty_path
+    assert_raises(ArgumentError) do
+      Zvec::Collection.create_and_open("", @schema)
+    end
+  end
+
+  def test_collection_create_rejects_non_schema
+    assert_raises(ArgumentError) do
+      Zvec::Collection.create_and_open("/tmp/test", "not a schema")
+    end
+  end
+
+  def test_collection_open_rejects_nil_path
+    assert_raises(ArgumentError) do
+      Zvec::Collection.open(nil)
+    end
+  end
+
+  def test_collection_add_rejects_nil_pk
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      assert_raises(ArgumentError) do
+        col.add(pk: nil, title: "test")
+      end
+    end
+  end
+
+  def test_collection_search_rejects_empty_vector
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      assert_raises(ArgumentError) do
+        col.search([])
+      end
+    end
+  end
+
+  def test_collection_search_rejects_non_array_vector
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      assert_raises(ArgumentError) do
+        col.search("not an array")
+      end
+    end
+  end
+
+  def test_collection_delete_rejects_empty_pks
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      assert_raises(ArgumentError) do
+        col.delete
+      end
+    end
+  end
+
+  def test_collection_fetch_rejects_empty_pks
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      assert_raises(ArgumentError) do
+        col.fetch
+      end
+    end
+  end
+
+  def test_collection_query_dimension_mismatch
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      assert_raises(Zvec::DimensionError) do
+        col.query(field_name: "embedding", vector: [1.0, 2.0], topk: 5)
+      end
+    end
+  end
+
+  def test_collection_query_dimension_mismatch_message
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      err = assert_raises(Zvec::DimensionError) do
+        col.query(field_name: "embedding", vector: [1.0, 2.0], topk: 5)
+      end
+      assert_includes err.message, "embedding"
+      assert_includes err.message, "4"
+      assert_includes err.message, "2"
+      assert_includes err.message, "test_validation"
+    end
+  end
+
+  def test_collection_query_correct_dimension_accepted
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      col.add(pk: "d1", title: "Test", count: 1, rating: 1.0, active: true,
+              embedding: [1.0, 2.0, 3.0, 4.0])
+      results = col.query(field_name: "embedding", vector: [1.0, 2.0, 3.0, 4.0], topk: 5)
+      assert_kind_of Array, results
+    end
+  end
+
+  # --- Error context includes collection name ---
+
+  def test_error_prefix_includes_collection_name
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      err = assert_raises(ArgumentError) do
+        col.delete  # no pks
+      end
+      assert_includes err.message, "test_validation"
+    end
+  end
+
+  # --- DimensionError is subclass of Error ---
+
+  def test_dimension_error_is_zvec_error
+    assert Zvec::DimensionError < Zvec::Error
+  end
+
+  # --- Collection name is accessible ---
+
+  def test_collection_name_from_schema
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      assert_equal "test_validation", col.collection_name
+    end
+  end
+
+  # --- Thread safety: collection has a monitor ---
+
+  def test_collection_has_monitor
+    with_temp_dir("zvec_val") do |dir|
+      col = Zvec::Collection.create_and_open("#{dir}/col", @schema)
+      assert_respond_to col.instance_variable_get(:@monitor), :synchronize
+    end
+  end
+end

data/test/test_version.rb

@@ -14,6 +14,6 @@ class TestVersion < Minitest::Test
   end
 
   def test_version_value
-    assert_equal "0.1.0", Zvec::VERSION
+    assert_equal "0.1.1", Zvec::VERSION
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zvec-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Johannes Dwi Cahyo
@@ -99,6 +99,8 @@ files:
 - test/test_query.rb
 - test/test_ruby_llm_store.rb
 - test/test_schema.rb
+- test/test_type_detection.rb
+- test/test_validation.rb
 - test/test_version.rb
 - zvec.gemspec
 homepage: https://github.com/johannesdwicahyo/zvec-ruby