zvec-ruby 0.1.0 → 0.2.0

data/lib/zvec/ruby_llm.rb

@@ -4,17 +4,40 @@ module Zvec
   module RubyLLM
     # A vector store backend for the ruby_llm gem.
     #
-    # Usage with ruby_llm:
+    # Provides a simple add/search/delete interface on top of a {Zvec::Collection}.
+    # Compatible with the ruby_llm vector store protocol.
+    #
+    # @example Basic usage
     #   store = Zvec::RubyLLM::Store.new("/path/to/db", dimension: 1536)
-    #   store.add("doc-1", embedding: [...], metadata: { title: "Hello" })
+    #   store.add("doc-1", embedding: [...], content: "Hello world")
     #   results = store.search([0.1, 0.2, ...], top_k: 5)
+    #   results.first  #=> { id: "doc-1", score: 0.98, content: "Hello world", metadata: {} }
+    #
+    # @example With metadata
+    #   store.add("doc-2", embedding: [...], content: "Ruby", metadata: { category: "lang" })
     #
     class Store
+      # @return [String] default vector field name
       DEFAULT_VECTOR_FIELD = "embedding"
+      # @return [String] default content field name
       DEFAULT_CONTENT_FIELD = "content"
 
-      attr_reader :collection, :dimension
+      # @return [Zvec::Collection] the underlying collection
+      attr_reader :collection
+      # @return [Integer] the vector dimension
+      attr_reader :dimension
 
+      # Create a new store, opening an existing collection or creating one.
+      #
+      # @param path [String] directory path for the collection data
+      # @param dimension [Integer] the vector dimension (must be > 0)
+      # @param metric [Symbol] similarity metric (+:cosine+, +:l2+, or +:ip+)
+      # @param vector_field [String] name of the vector field (default: "embedding")
+      # @param content_field [String] name of the content field (default: "content")
+      # @raise [ArgumentError] if metric is not one of +:cosine+, +:l2+, +:ip+
+      #
+      # @example
+      #   store = Zvec::RubyLLM::Store.new("/tmp/store", dimension: 384, metric: :l2)
       def initialize(path, dimension:, metric: :cosine, vector_field: DEFAULT_VECTOR_FIELD,
                      content_field: DEFAULT_CONTENT_FIELD)
         @vector_field = vector_field.to_s
@@ -47,6 +70,15 @@ module Zvec
       end
 
       # Add a document with its embedding and optional metadata.
+      #
+      # @param id [String, Integer] the document's primary key
+      # @param embedding [Array<Numeric>] the vector embedding
+      # @param content [String, nil] optional text content
+      # @param metadata [Hash{String, Symbol => Object}] additional fields to store
+      # @return [Array] write results from the collection
+      #
+      # @example
+      #   store.add("doc-1", embedding: [0.1, 0.2, 0.3], content: "Hello")
       def add(id, embedding:, content: nil, metadata: {})
         doc = Zvec::Doc.new(pk: id, schema: @schema)
         doc[@vector_field] = embedding
@@ -55,8 +87,20 @@ module Zvec
         @collection.insert(doc)
       end
 
-      # Batch-add documents.
-      # docs: array of { id:, embedding:, content:, metadata: {} }
+      # Batch-add multiple documents at once.
+      #
+      # @param docs [Array<Hash>] documents, each containing:
+      #   * +:id+ [String, Integer] -- primary key (required)
+      #   * +:embedding+ [Array<Numeric>] -- the vector (required)
+      #   * +:content+ [String, nil] -- optional text content
+      #   * +:metadata+ [Hash, nil] -- optional additional fields
+      # @return [Array] write results from the collection
+      #
+      # @example
+      #   store.add_many([
+      #     { id: "a", embedding: [0.1, 0.2], content: "Hello" },
+      #     { id: "b", embedding: [0.3, 0.4], content: "World" },
+      #   ])
       def add_many(docs)
         zvec_docs = docs.map do |d|
           doc = Zvec::Doc.new(pk: d[:id], schema: @schema)
@@ -69,6 +113,22 @@ module Zvec
       end
 
       # Search for similar vectors.
+      #
+      # @param query_vector [Array<Numeric>] the query vector
+      # @param top_k [Integer] maximum number of results (default: 10)
+      # @param filter [String, nil] optional filter expression
+      #   (see {Zvec::VectorQuery} for filter syntax)
+      # @return [Array<Hash>] results, each containing:
+      #   * +:id+ [String] -- document primary key
+      #   * +:score+ [Float] -- similarity score
+      #   * +:content+ [String, nil] -- the content field value
+      #   * +:metadata+ [Hash] -- all other stored fields
+      #
+      # @example
+      #   results = store.search([0.1, 0.2, 0.3], top_k: 5)
+      #   results.first[:id]      #=> "doc-1"
+      #   results.first[:score]   #=> 0.95
+      #   results.first[:content] #=> "Hello"
       def search(query_vector, top_k: 10, filter: nil)
         results = @collection.query(
           field_name: @vector_field,
@@ -86,20 +146,32 @@ module Zvec
         end
       end
 
-      # Delete documents by IDs.
+      # Delete documents by primary key(s).
+      #
+      # @param ids [Array<String, Integer>] one or more primary keys
+      # @return [Array] write results from the collection
       def delete(*ids)
         @collection.delete(*ids.flatten)
       end
 
-      # Fetch documents by IDs.
+      # Fetch documents by primary key(s).
+      #
+      # @param ids [Array<String, Integer>] one or more primary keys
+      # @return [Hash{String => Zvec::Doc}] mapping of pk to document
       def fetch(*ids)
         @collection.fetch(*ids.flatten)
       end
 
+      # Flush pending writes to disk.
+      #
+      # @return [self]
       def flush
         @collection.flush
       end
 
+      # Return the number of documents in the store.
+      #
+      # @return [Integer]
       def count
         @collection.doc_count
       end

data/lib/zvec/schema.rb

@@ -1,68 +1,212 @@
 module Zvec
+  # Defines the structure of a collection: its name, fields, types, and
+  # vector dimensions.
+  #
+  # Schemas are immutable once created -- fields can be added during
+  # initialization but not removed afterward.
+  #
+  # @example Creating a schema with a DSL block
+  #   schema = Zvec::Schema.new("articles") do
+  #     string "title"
+  #     string "body", nullable: true
+  #     int32  "year"
+  #     float  "rating"
+  #     bool   "published"
+  #     vector "embedding", dimension: 384,
+  #            index: Zvec::Ext::HnswIndexParams.new(Zvec::COSINE)
+  #   end
+  #
+  # @example Binary vector field
+  #   schema = Zvec::Schema.new("hashes") do
+  #     field "hash_vec", DataTypes::BINARY, dimension: 128
+  #   end
+  #
+  # @example Sparse vector field
+  #   schema = Zvec::Schema.new("sparse_docs") do
+  #     field "tfidf", DataTypes::SPARSE_VECTOR_FP32, dimension: 30000
+  #   end
+  #
   class Schema
+    # @return [Ext::CollectionSchema] the underlying C++ schema object
     attr_reader :ext_schema
 
+    # Create a new schema.
+    #
+    # @param name [String, Symbol] the collection name (must be non-empty)
+    # @yield optional DSL block evaluated in the schema's context
+    # @raise [Zvec::SchemaError] if name is nil or blank
+    #
+    # @example
+    #   schema = Zvec::Schema.new("my_collection") do
+    #     string "title"
+    #     vector "embedding", dimension: 128
+    #   end
     def initialize(name, &block)
-      @ext_schema = Ext::CollectionSchema.new(name)
+      if name.nil? || name.to_s.strip.empty?
+        raise SchemaError, "Schema name must be a non-empty string"
+      end
+
+      @ext_schema = Ext::CollectionSchema.new(name.to_s)
       @field_types = {}
+      @field_dimensions = {}
       instance_eval(&block) if block
     end
 
+    # Add a field with an explicit data type.
+    #
+    # @param name [String, Symbol] the field name (must be non-empty)
+    # @param type [Symbol] a DataTypes constant (e.g., +DataTypes::STRING+)
+    # @param dimension [Integer, nil] required for vector fields
+    # @param nullable [Boolean] whether the field allows null values
+    # @param index [Ext::HnswIndexParams, Ext::FlatIndexParams, Ext::IVFIndexParams, nil]
+    #   optional index parameters for this field
+    # @return [self] for method chaining
+    # @raise [Zvec::SchemaError] if field name is blank
+    #
+    # @example
+    #   schema.field("tags", DataTypes::ARRAY_STRING)
+    #   schema.field("embedding", DataTypes::VECTOR_FP32, dimension: 128)
     def field(name, type, dimension: nil, nullable: false, index: nil)
       name = name.to_s
+      if name.strip.empty?
+        raise SchemaError, "Field name must be a non-empty string"
+      end
+
       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
 
+    # Add a dense vector field. Defaults to FP32 precision.
+    #
+    # @param name [String, Symbol] the field name
+    # @param dimension [Integer] the vector dimension (must be > 0)
+    # @param type [Symbol] vector data type (default: {DataTypes::VECTOR_FP32}).
+    #   Also accepts {DataTypes::VECTOR_FP64}, {DataTypes::VECTOR_FP16},
+    #   or {DataTypes::VECTOR_INT8}.
+    # @param index [Ext::HnswIndexParams, Ext::FlatIndexParams, Ext::IVFIndexParams, nil]
+    #   optional index parameters
+    # @return [self]
+    # @raise [ArgumentError] if dimension is not a positive integer
+    #
+    # @example Standard FP32 vector with HNSW index
+    #   schema.vector "embedding", dimension: 384,
+    #                 index: Ext::HnswIndexParams.new(Zvec::COSINE)
+    #
+    # @example FP16 vector (half memory)
+    #   schema.vector "embedding", dimension: 384,
+    #                 type: DataTypes::VECTOR_FP16
+    #
+    # @example INT8 quantized vector (minimal memory)
+    #   schema.vector "embedding", dimension: 384,
+    #                 type: DataTypes::VECTOR_INT8
     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
 
+    # Add a string field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field} (+nullable:+, +index:+)
+    # @return [self]
     def string(name, **opts)
       field(name, DataTypes::STRING, **opts)
     end
 
+    # Add a 32-bit integer field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field}
+    # @return [self]
     def int32(name, **opts)
       field(name, DataTypes::INT32, **opts)
     end
 
+    # Add a 64-bit integer field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field}
+    # @return [self]
     def int64(name, **opts)
       field(name, DataTypes::INT64, **opts)
     end
 
+    # Add a 32-bit float field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field}
+    # @return [self]
     def float(name, **opts)
       field(name, DataTypes::FLOAT, **opts)
     end
 
+    # Add a 64-bit double field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field}
+    # @return [self]
     def double(name, **opts)
       field(name, DataTypes::DOUBLE, **opts)
     end
 
+    # Add a boolean field.
+    #
+    # @param name [String, Symbol] the field name
+    # @param opts [Hash] options passed to {#field}
+    # @return [self]
     def bool(name, **opts)
       field(name, DataTypes::BOOL, **opts)
     end
 
+    # @return [String] the collection name
     def name
       @ext_schema.name
     end
 
+    # @return [Array<String>] all field names in this schema
     def field_names
       @ext_schema.field_names
     end
 
+    # Look up the data type of a field by name.
+    #
+    # @param name [String, Symbol] the field name
+    # @return [Symbol, nil] the data type constant, or nil if not found
     def field_type(name)
       @field_types[name.to_s]
     end
 
+    # Look up the dimension of a vector field.
+    #
+    # @param name [String, Symbol] the field name
+    # @return [Integer, nil] the dimension, or nil if the field is not a vector
+    def field_dimension(name)
+      @field_dimensions[name.to_s]
+    end
+
+    # Check whether a field exists in the schema.
+    #
+    # @param name [String, Symbol] the field name
+    # @return [Boolean]
     def has_field?(name)
       @ext_schema.has_field?(name.to_s)
     end
 
+    # Returns a hash of vector field names to their dimensions.
+    #
+    # @return [Hash{String => Integer}] e.g. +{"embedding" => 384}+
+    def vector_fields_with_dimensions
+      @field_dimensions.select { |name, _| DataTypes::VECTOR_TYPES.include?(@field_types[name]) }
+    end
+
+    # @return [String] human-readable representation of the schema
     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.2.0"
 end

data/lib/zvec.rb

@@ -16,7 +16,20 @@ require_relative "zvec/query"
 require_relative "zvec/collection"
 
 module Zvec
+  # Base error class for all Zvec errors.
   class Error < StandardError; end
 
+  # Raised when vector dimensions do not match the expected schema dimension.
+  class DimensionError < Error; end
+
+  # Raised for schema definition errors (invalid field names, types, etc.).
+  class SchemaError < Error; end
+
+  # Raised for query construction or execution errors.
+  class QueryError < Error; end
+
+  # Raised for collection lifecycle errors (open/close/reopen issues).
+  class CollectionError < Error; end
+
   include DataTypes
 end